ElFormRenderer

ElFormRenderer 根据单条 EllFieldSchema 渲染一个业务控件：v-model 绑定字段值，controlType 在内部注册表中解析为具体 Vue 组件（默认 input）。ElFormQuery、ElFormBuilder 均在表单项内使用它；也可在 el-form-item 中单独使用。

与上层表单的关系

注册表（可选）： 挂载在 ElFormBuilder / ElFormQuery 子树内时，会 inject FORM_BUILDER_FIELD_REGISTRY_KEY 并注册 控件 ref（getControlRef）；mode: 'preview' 时不注册。
增强上下文（可选）： FORM_RENDERER_ENHANCE_CONTEXT_KEY 提供 model / schema / getSchemaByField，供 schema.options 异步函数、事件 payload 等使用；独立使用渲染器而未 provide 时，相关能力退化但仍可编辑。
校验路径： 单独用时请在 el-form-item 上设置 prop，并与 el-form model 路径一致。

基础用法

v-model + schema；schema.field 应与模型字段对应（亦可通过 field-registry-key / formItemConfig.prop 与 ElFormQuery 对齐，见 props 说明）。

渲染模式 `mode`

值	行为
`edit`（默认）	挂载 `EllControlItem.component`，双向绑定
`disabled`	与 `edit` 相同组件；若整表只读，合并 `dependencies.disabled`：仅当依赖显式返回 `false` 时本字段可编辑（与 `ElFormBuilder` 一致）
`preview`	优先 `previewComponent`；否则 `formatPreview` 或内置按类型的纯文本

注册自定义控件

全局注册表为进程内单例：在应用启动（或任意早于首次解析该 controlType 的模块）调用 registerControl 即可。同一 type 再次注册会覆盖，可用于项目级替换内置实现。

`registerControl(type, item)`

import type { EllControlItem } from 'element-plus-lab'
import { registerControl } from 'element-plus-lab'

EllControlItem 常用字段：

字段	说明
`component`	编辑态根组件（如 Element Plus 控件）
`modelProp`	v-model 绑定 prop，默认 `modelValue`
`modelEvent`	更新事件，默认 `update:modelValue`
`defaultProps`	默认透传 props（可被 `schema.controlConfig` 覆盖）
`formatPreview`	`(value, schema) => string`，`mode: 'preview'` 且无 `previewComponent` 时使用
`previewComponent`	可选；接收 `model-value` / `schema`，自定义预览 UI

约定：

组件须支持 modelProp / modelEvent 与 ElFormRenderer 的合成（多数 EP 组件为 modelValue + update:modelValue）。
schema.controlConfig、dependencies 动态 controlConfig 会合并进绑定；不要在 controlConfig 里塞 modelValue（实现侧会剔除）。
未知 controlType 会回落到 input，避免白屏。
select 等内置类型的 options 由渲染器单独解析；自定义类型请在控件内自行消费 controlConfig。

查询与覆盖

getRegisteredControl(type)：读取当前注册项（主要用于调试）。
内置类型在首次 resolveControl 时懒加载注册；自定义可与内置同名覆盖（慎用）。

内置 `controlType` 一览

与 FormQuery · Schema 一致，当前内置包括：

input、textarea、input-number、switch、checkbox、select、date-picker、datetime-picker、daterange-picker、time-picker、time-select。

`schema` 与事件

controlConfig： 透传到具体控件（合并 defaultProps、依赖动态配置）。
events： 驼峰事件名，会转为 onXxx 监听；与 controlConfig 中的监听器合并时以后者覆盖。
在 ElFormBuilder / ElFormQuery 下，部分事件会注入 EllFormRendererEventPayload（见主包 export type 白名单）。

Props

属性名	说明	类型	默认值
modelValue（`v-model`）	字段值	`unknown`	-
schema	单字段 `EllFieldSchema`	`EllFieldSchema`	（必填）
mode	`edit` / `disabled` / `preview`	`EllFormRenderMode`	`edit`
fieldRegistryKey	与 `el-form-item` `prop` 一致的注册键；不传则用 `schema.field`	`string`	-
dependencyEval	由 `ElFormBuilder` 传入时复用依赖求值，避免重复计算	`EllFieldDependencyEval`	-

类型说明

import type {
  ElFormRendererProps,
  EllControlItem,
  EllFormRenderMode,
} from 'element-plus-lab'
import { registerControl } from 'element-plus-lab'

EllControlItem 形状（节选）

import type { EllFieldSchema } from 'element-plus-lab'
import type { Component } from 'vue'

export interface EllControlItem {
  component: Component
  defaultProps?: Record<string, unknown>
  modelProp?: string
  modelEvent?: string
  previewComponent?: Component
  formatPreview?: (value: unknown, schema: EllFieldSchema) => string
}

完整 ElFormRendererProps 与 defineModel 细节以发布包 d.ts 为准。

贡献者

jenemy

页面历史

最后编辑于大约 5 小时前

查看完整历史

ElFormRenderer ​

基础用法 ​

渲染模式 mode ​

注册自定义控件 ​

registerControl(type, item) ​

推荐注册时机 ​

查询与覆盖 ​

内置 controlType 一览 ​

schema 与事件 ​

Props ​

类型说明 ​

相关 ​

贡献者