element-plus-lab

Element Plus Lab

基于 Element Plus 的业务组件与组合式 API：Promise 化对话框/抽屉、schema 驱动的查询表单与整表构建（ElFormQuery / ElFormBuilder + ElFormRenderer + ElFormLayout）、业务页 ElCruPage，以及步骤条、页面头等基础物料。

• 文档站点：element-plus-lab-docs（组件说明、示例与 vibe-coding/plans/form 方案文）
• 源码：GitHub

安装

pnpm add element-plus-lab

请一并安装对等依赖：

pnpm add vue element-plus portal-vue @vueuse/core

部分组件依赖 @element-plus/icons-vue，使用到对应图标时请自行安装。

使用

注册 Vue 组件

所有通过 withInstall 导出的 .vue 组件 有两种用法。

方式一：一次性注册（推荐）

import { createApp } from 'vue'
import ElementPlusLab from 'element-plus-lab'

const app = createApp(App)
app.use(ElementPlusLab)

ElementPlusLab.install 会依次注册：

组件	说明
ElLabConfigProvider	子树内默认 网格（断点/列数/间距），供 ElFormQuery / ElFormLayout 继承
ElFormGroup	可折叠表单分组
ElFormLayout / ElFormLayoutItem	表单栅格布局层
ElFormRenderer	字段 schema 渲染（内置控件 + registerControl）
ElCruPage	页头 ElSimplePageHeader + ElFormBuilder 等业务页组合
ElFormBuilder	整表 schema、分组/自定义块、portal 操作区与 dependencies / visible(tab) 等
ElFormQuery	查询表单（网格、折叠 dense、${uid}-actions 操作区）
ElSimplePageHeader	轻量页头（返回、标题或选项卡）
ElSimpleSteps	轻量步骤条

方式二：按需 app.use(单个组件)

import { createApp } from 'vue'
import { ElFormQuery } from 'element-plus-lab'

const app = createApp(App)
app.use(ElFormQuery)

Hooks（useDialog / useDrawer / useForm / useFormDialog / useFormDrawer）无需注册，在脚本中直接 import 使用即可。

useDialog / useDrawer

在应用根布局（如 App.vue）挂载 portal-vue 目标，名称需与实现一致：

<template>
  <router-view />
  <portal-target name="ell-dialog" multiple />
  <portal-target name="ell-drawer" multiple />
</template>

示例：

import { useDialog, type EllOverlayResult } from 'element-plus-lab'

const { openDialog } = useDialog()

async function open() {
  try {
    await openDialog({ title: '确认', content: '确定要执行此操作吗？' })
  } catch (error: unknown) {
    const result = error as EllOverlayResult
    console.log('关闭原因:', result.reason) // 'cancel' | 'close' | 'ok'
  }
}

更多能力（自定义头/内容/底栏、beforeClose、keepInstance、useFormDialog / useFormDrawer 等）见文档站对应章节。

与 @element-plus-lab/utils 的边界

• @element-plus-lab/utils：工具函数与类型的定义处；本仓库内 packages/components、packages/utils 实现层对 utils 符号一律使用 @element-plus-lab/utils，勿从主包「绕路」导入仅来自 utils 的运行时实现。
• element-plus-lab 主包：不再默认批量再导出 utils 的运行时函数；若个别 API 必须给「只装主包」的 npm 用户使用，须在 index.ts 单独 export、在本文档说明，并更新 changeset。
• 类型：主包保留 export type { … } from '@element-plus-lab/utils' 的白名单，外部可 import type { … } from 'element-plus-lab'；其中 EllOverlayResult / EllOverlayCloseReason 已承诺从主包导出，与 useDialog / useDrawer 文档、业务示例保持一致。

导出一览（节选）

下表便于检索；完整符号以 index.ts 为准。

类别	名称	说明
类型	EllOverlayResult、EllOverlayCloseReason	浮层 Promise reject 分支的关闭结果（reason / data）
类型	EllFormSchema 及 EllFieldSchema、EllGroupSchema、EllCustomSchema 等	表单 schema 与 parseSchema 分块相关类型；运行时 parseSchema、布局/grid 工具等仍在 @element-plus-lab/utils
类型	ConfigProviderState、EllGridLayoutConfig、EllGridPresetName 等	ElLabConfigProvider / 网格配置
运行时	registerControl、formatPreviewByControlType、formatDateTimeLikePreview	表单控件注册与预览文案
运行时	FORM_RENDERER_ENHANCE_CONTEXT_KEY	ElFormBuilder / ElFormQuery 向 ElFormRenderer 注入 model / schema / getSchemaByField（事件 payload 增强）
组合式	useDialog、useDrawer	<el-dialog> / <el-drawer> 的 Promise 化封装
组合式	useForm	基于 ElFormBuilder 的 Form 组件与 submit / validate / setSchema 等便捷能力
组合式	useFormDialog、useFormDrawer	在 useDialog / useDrawer 上接入 ElFormBuilder
组件	ElLabConfigProvider	注入默认 grid
组件	ElFormLayout、ElFormLayoutItem	表单栅格
组件	ElFormQuery、ElFormBuilder、ElFormRenderer	查询 / 构建 / 渲染链路
组件	ElCruPage	创建·编辑·详情类页面组合
组件	ElFormGroup、ElSimplePageHeader、ElSimpleSteps	分组、页头、步骤条
注入	CONFIG_PROVIDER_INJECTION_KEY、useConfigProvider	与 ElLabConfigProvider 配套
插件	ElementPlusLab（default export）	一次性注册上表所列 Vue 组件