Form 表单组件
动态表单组件，支持通过配置快速生成表单，提供开箱即用的表单解决方案。
基础用法
通过配置 formItems 数组，快速生成表单。支持所有 Element Plus 表单组件类型。
插槽使用
可配置化
除了使用模板插槽和在 WForm 标签上监听事件，还可以在 formItems 配置对象中直接定义插槽和事件处理器，这种方式称为"可配置化"。
⚠️ 注意：可配置化插槽在 VitePress demo 块中可能无法正常工作（VitePress 在编译时无法正确序列化函数类型的 props）。如果需要查看效果，建议在本地 demo 查看。
插槽
可配置化插槽支持两种类型：
- FormItem 插槽：在配置对象的
slots字段中定义，用于自定义el-form-item的插槽（如label、error等） - 动态组件插槽：在
compProps.slots字段中定义，用于自定义动态组件的插槽（如prefix、suffix等）
优先级：可配置化插槽优先级高于模板插槽，如果同时定义了可配置化插槽和模板插槽，会优先使用可配置化插槽。
事件
可配置化事件支持在 compProps 中定义动态组件的事件处理器。
- 动态组件事件：在
compProps中定义，事件名以on开头（如onBlur、onFocus、onInput等） - 优先级：可配置化事件优先级高于
WForm标签上的事件，如果同时定义了可配置化事件和标签事件，会优先使用可配置化事件
条件渲染
使用 vIf 或 vShow 实现表单项的条件显示。两者都支持布尔值或接收表单数据的函数，函数可以通过参数访问表单数据，也可以通过闭包访问外部值。
vIf：条件渲染（v-if），条件为false时不会渲染 DOMvShow：显示/隐藏（v-show），条件为false时隐藏但保留 DOM
操作按钮
布局配置
Inline 模式下的展开/收起功能
展开/收起功能仅在 inline 模式下可用，通过 actionConfig.buttons 包含 'expand' 来启用。适用于字段较多、需要默认隐藏部分字段的场景。
基础展开/收起功能
通过 expand 配置展开规则，支持三种方式：count（按数量）、include（白名单）、exclude（黑名单）。
使用 count 配置（按数量展开）
使用 include 配置（白名单）
使用 exclude 配置（黑名单）
分栏布局 + 展开/收起功能
鼠标悬停自动展开
通过 autoExpandOnHover: true 启用鼠标悬停自动展开功能。注意：此功能仅支持自动展开，不支持自动收起。如果手动点击展开/收起按钮，则会锁定状态，不再受鼠标移入影响。
展开/收起自动滚动
通过 scrollOnToggle: true 启用展开/收起后自动滚动功能。可以通过 scrollIntoViewOptions 配置滚动行为，支持自定义滚动位置（block）、滚动方式（behavior）等选项。
选项加载器
选项加载器用于动态加载选项数据，通过 compProps.optionsLoader 配置加载函数，结合 useLoadOptions 组合式函数进行调用。支持同步和异步两种方式，适用于级联选择、接口请求等场景。
API
属性
支持 ElForm 所有的属性。
拓展属性：
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| formItems | 表单项配置数组，详见 FormItem 配置 | FormItems | [] |
| rowProps | 行布局属性，详见 rowProps 配置 | RowProps | {} |
| actionConfig | 操作按钮配置，详见 actionConfig 配置 | FormActionConfig | {} |
| expanded | 展开/折叠状态（双向绑定，仅在 inline 模式下且 actionConfig.buttons 包含 'expand' 时可用） | boolean | false |
FormItem 配置
formItems 数组中每一项的配置类型。
基础配置
支持 ElFormItem 所有的属性。
拓展属性：
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| prop | 表单字段名（必填） | string | - |
| compType | 组件类型（必填） | FormItemComp | - |
| compProps | 组件属性配置，根据组件类型自动推断。 对于支持 options 的组件（如 select、cascader、radio、checkbox 等），支持两种配置方式： 1. 静态数组： options: [{ label: '选项1', value: '1' }]2. 动态加载： compProps.optionsLoader + useLoadOptionscompProps 还支持：- compProps.slots：动态组件插槽配置（如 prefix、suffix 等），使用 h() 函数创建 VNode详见 选项加载器 和 可配置化 | FormItemCompProps<C> | - |
| slots | FormItem 插槽配置，用于自定义 el-form-item 的插槽（如 label、error 等），使用 h() 函数创建 VNode。详见 可配置化 - 插槽 | FormItemSlotsConfig | - |
| vIf | 条件渲染（v-if），支持布尔值或接收表单数据的函数。函数可以依赖表单内部值或外部状态 | boolean | ((data: Record<string, any>) => boolean) | true |
| vShow | 显示/隐藏（v-show），支持布尔值或接收表单数据的函数。函数可以依赖表单内部值或外部状态 | boolean | ((data: Record<string, any>) => boolean) | true |
| colProps | 列布局属性，详见 ElCol 组件属性 | ColProps | - |
支持的组件类型
compType 字段支持以下组件类型：
| 组件类型 | 说明 | 默认值 | 文档链接 |
|---|---|---|---|
input | 输入框（支持 type: 'textarea' 实现文本域） | { placeholder: '请输入${label}'（动态），clearable: true } | Element Plus Input |
input-number | 数字输入框 | { placeholder: '请输入', clearable: true } | Element Plus InputNumber |
input-tag | 标签输入 | { placeholder: '请输入${label}'（动态），clearable: true } | Element Plus InputTag |
select | 选择器 | { placeholder: '请选择${label}'（动态），clearable: true, filterable: true } | Element Plus Select |
select-v2 | 虚拟列表选择器 | { placeholder: '请选择${label}'（动态），clearable: true, filterable: true } | Element Plus SelectV2 |
autocomplete | 自动完成 | { placeholder: '请输入${label}'（动态），clearable: true } | Element Plus Autocomplete |
cascader | 级联选择器 | { placeholder: '请选择${label}'（动态），clearable: true, filterable: true } | Element Plus Cascader |
tree-select | 树形选择器 | { placeholder: '请选择${label}'（动态），clearable: true, filterable: true } | Element Plus TreeSelect |
date-picker | 日期选择器 | { placeholder: '请选择${label}'（动态），clearable: true } | Element Plus DatePicker |
date-picker-panel | 日期选择面板 | - | Element Plus DatePickerPanel |
time-picker | 时间选择器 | { placeholder: '请选择${label}'（动态），clearable: true } | Element Plus TimePicker |
time-select | 时间选择 | { placeholder: '请选择${label}'（动态），clearable: true } | Element Plus TimeSelect |
switch | 开关 | - | Element Plus Switch |
checkbox | 复选框（单个） | - | Element Plus Checkbox |
checkbox-group | 复选框组（配合 options 属性） | - | Element Plus CheckboxGroup |
radio-group | 单选框组（配合 options 属性） | - | Element Plus RadioGroup |
rate | 评分 | - | Element Plus Rate |
slider | 滑块 | - | Element Plus Slider |
color-picker | 颜色选择器 | - | Element Plus ColorPicker |
color-picker-panel | 颜色选择面板 | - | Element Plus ColorPickerPanel |
transfer | 穿梭框 | - | Element Plus Transfer |
mention | 提及 | { placeholder: '请输入${label}'（动态），clearable: true } | Element Plus Mention |
custom | 自定义组件（通过插槽实现） | - | - |
w-check-tag | 可选标签（支持单选/多选，配合 options 属性） | - | Element Plus Kit CheckTag |
Options 配置
对于支持 options 的组件（如 select、cascader、radio、checkbox 等），支持两种配置方式：
1. 静态数组（compProps.options）
直接使用数组配置选项，适用于选项固定的场景。
| 类型 | 说明 |
|---|---|
FormItemCompProps<T>['options'] | 对应组件的 options 属性类型（如 ElSelect 的 Array<SelectOption>、ElCascader 的 Array<CascaderOption> 等） |
2. 动态加载（compProps.optionsLoader）
| 类型 | 说明 |
|---|---|
(formData: Record<string, unknown>) => any[] | Promise<any[]> | 支持同步和异步函数，通过闭包访问外部依赖，结合 useLoadOptions 组合式函数进行自定义调用 |
rowProps 配置
支持 ElRow 所有的属性。
拓展属性：
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| span | 默认列数（用于 colProps.span 的默认值） | number | - |
actionConfig 配置
actionConfig 用于自定义表单底部的操作按钮。
拓展属性：
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| vIf | 是否显示操作区域（支持函数动态判断） | boolean | ((data?: Record<string, any>) => boolean) | inline 为 true 时默认为 true，inline 为 false 时默认为 false |
| vShow | 显示/隐藏操作区域（支持函数动态判断，使用 v-show） | boolean | ((data?: Record<string, any>) => boolean) | true |
| buttons | 按钮列表，详见 buttons 配置 | FormActionButtons[] | inline 为 true 时默认为 ['search', 'reset']，inline 为 false 时默认为 ['submit', 'cancel'] |
| expand | 默认展开规则（仅在 buttons 包含 'expand' 时生效），详见 expand 配置 | FormExpandRule | - |
buttons 配置
buttons 支持预设按钮字符串或自定义按钮对象。
预设按钮：
| 按钮类型 | 说明 | 默认样式 |
|---|---|---|
'submit' | 确认按钮 | 主要按钮（type: 'primary'） |
'reset' | 重置按钮 | 默认按钮（带刷新图标） |
'search' | 搜索按钮 | 主要按钮（type: 'primary'，带搜索图标） |
'cancel' | 取消按钮 | 默认按钮 |
'expand' | 展开/折叠按钮 | 链接按钮（link: true，仅在 inline 模式下可用） |
自定义按钮：
支持 ElButton 所有的属性。
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
eventName | 事件名称（必填） | string | - |
label | 按钮文字 | string | - |
expand 配置
expand 用于配置展开/折叠规则，支持三种配置方式：
| 配置方式 | 说明 | 类型 | 示例 |
|---|---|---|---|
| count | 按字段数量展开（从第一个开始） | { count: number } & FormExpandRuleBase | { count: 3 } |
| include | 指定展示的字段（白名单，字段 prop 数组） | { include: string[] } & FormExpandRuleBase | { include: ['field1', 'field2'] } |
| exclude | 指定折叠的字段（黑名单，字段 prop 数组） | { exclude: string[] } & FormExpandRuleBase | { exclude: ['field3', 'field4'] } |
配置优先级：exclude > include > count
FormExpandRuleBase 基础配置：
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| autoExpandOnHover | 是否启用鼠标悬停自动展开功能 | boolean | false |
| scrollOnToggle | 是否在展开/收起后自动滚动到表单中心 | boolean | false |
| scrollIntoViewOptions | 自定义滚动选项（仅在 scrollOnToggle 为 true 时生效），详见 scrollIntoViewOptions 文档 | ScrollIntoViewOptions | { behavior: 'smooth', block: 'center', inline: 'nearest' } |
事件
支持 ElForm 所有的事件。
拓展事件：
| 事件名 | 说明 | 类型 |
|---|---|---|
| change | 表单项值变化事件 | <T extends Record<string, any>, K extends keyof T>(extendedParams: FormItemEventExtendedParams, value: T[K]) => void |
| action | 操作按钮点击事件 | (eventName: string, data?: unknown) => void |
| search | 搜索按钮点击事件 | () => void |
| reset | 重置按钮点击事件 | (resetData: Record<string, unknown>) => void |
| submit | 提交按钮点击事件 | () => void |
| cancel | 取消按钮点击事件 | () => void |
| expand | 展开状态变化事件 | (value: boolean) => void |
@{EventName} | 动态组件事件（如 @input、@focus、@blur 等） | (extendedParams: FormItemEventExtendedParams, ...args: any[]) => void |
注意：
- 动态组件的事件（例如
change、input、focus、blur等）的第一个参数固定为extendedParams（包含prop、index、formItem），后续参数为原始事件参数 - 预设事件（
@submit、@cancel、@search、@reset、@expand）是为了方便使用而提供的。当点击这些预设按钮时，组件会先触发对应的事件，然后还会统一触发一次@action事件 - 不建议同时监听
@action和预设事件，因为会导致重复处理。如果必须混用，则不能在@action事件中处理eventName为这 5 个预设按钮名称（submit、cancel、search、reset、expand）的逻辑
插槽
| 插槽名 | 说明 | 作用域参数 |
|---|---|---|
{prop} | 自定义组件插槽，当 compType 为 custom 时使用 | FormItemSlotScope |
form-item-{prop} | 表单项插槽，用于自定义表单项内容 | FormItemSlotScope |
{prop}-{slotName} | 动态组件插槽，如 username-prefix、email-suffix | FormItemSlotScope |
action | 自定义操作按钮区域 | - |
插槽作用域参数 FormItemSlotScope：
| 参数 | 说明 | 类型 |
|---|---|---|
value | 当前表单项组件的值 | any |
form | 表单数据对象 | Record<string, any> |
formItem | 表单项配置对象 | FormItem |
方法
支持 ElForm 所有的方法。
拓展方法：
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
expanded | 获取当前展开状态（getter） | - | boolean |
toggleExpand | 切换或设置展开/折叠状态 | (value?: boolean) | - |
组合式函数
useLoadOptions
useLoadOptions 组合式函数用于动态加载选项数据，结合 compProps.optionsLoader 使用。
函数签名：
typescript
function useLoadOptions(
formItems: FormItems,
formData: Record<string, any>
): {
loadOptions: (props?: string | string[]) => Promise<void>
loading: Ref<boolean>
getOptions: (props?: string | string[]) => any[] | Array<{prop: string, options: any[]}>
}返回值：
| 参数 | 说明 | 类型 |
|---|---|---|
loadOptions | 加载选项的函数 | (props?: string | string[]) => Promise<void> |
loading | 加载状态（响应式） | Ref<boolean> |
getOptions | 获取选项的函数 | (props?: string | string[]) => any[] | Array<{prop: string, options: any[]}> |
loadOptions 使用方式：
loadOptions('fieldName')- 加载单个字段的选项loadOptions(['field1', 'field2'])- 加载多个字段的选项loadOptions()- 加载所有有optionsLoader的字段
getOptions 使用方式：
getOptions('fieldName')- 获取单个字段的选项，返回any[]getOptions(['field1', 'field2'])- 获取多个字段的选项，返回Array<{prop: string, options: any[]}>getOptions()- 获取所有字段的选项，返回Array<{prop: string, options: any[]}>
使用示例： 详见 选项加载器 章节。