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 组件 |