DynamicForm 动态表单

动态表单组件，用于快速构建基于配置的表单界面。

TIP

除了完整的动态表单组件，我们也提供了独立的 EzFormItem 组件，可以用于构建自定义表单布局。

基础用法

组件类型

表单校验

自定义插槽

属性

属性名	说明	类型	是否必须	默认值
model-value	初始表单数据	Record	否	-
items	表单配置项	FormItemConfig[]	是	[]
cols	栅格布局列数	number	否	1
gutter	栅格间距	number	否	20
formProps	el-form 属性	Partial	否	-

FormItemConfig

属性名	说明	类型	是否必须	默认值
prop	字段名	string	是	-
label	标签	string	否	-
type	组件类型	FormItemType | string	否	-
defaultValue	默认值	any	否	-
rules	验证规则	FormItemRule	否	-
required	是否必填	boolean	否	false
requiredMessage	必填提示信息	string	否	-
span	占用栅格列数	number	否	-
hidden	是否隐藏	boolean	否	false
disabled	是否禁用	boolean	否	false
placeholder	占位符	string	否	-
options	选项配置	FormItemOption[]	否	-
attrs	组件属性（透传给具体组件）	Record	否	-
component	自定义组件	Component	否	-
itemAttrs	额外的 el-form-item 属性	Record	否	-
show	联动显示条件	Function	否	-
disabledWhen	联动禁用条件	Function	否	-

数据初始化优先级

• model-value：外部传入的初始数据，优先级最高
• defaultValue：配置项的默认值，仅在 model-value 中不存在该字段时生效

数据流设计

本组件采用单向数据流 + 方法控制的设计：

• model-value 仅用于初始化，不做双向绑定
• 使用 getFormData() 按需获取表单数据（如提交时）
• 使用 setFormData() 显式设置数据（会自动清除校验提示）
• 这种设计确保了数据流清晰、性能最优，适合复杂表单场景

注意事项

自本版本起，组件已移除对 model-value 的自动监听与双向同步（不再自动 emit update:modelValue）。

• 当需要从外部更新表单数据，请使用组件实例方法 setFormData(data, merge?: boolean)。
• 若需获取最新表单数据，请使用 getFormData()（例如在提交或父级需要读取时）。
• 如果原来依赖 v-model 双向绑定的用法，请改为使用 ref 调用上述方法来同步数据。

此变更可避免高频双向同步带来的性能开销，推荐在复杂场景下使用方法控制数据流。

FormItemType

名称	说明
INPUT	输入框
TEXTAREA	多行文本
NUMBER	数字输入
PASSWORD	密码输入
SELECT	下拉选择（封装组件）
RADIO	单选框（封装组件）
CHECKBOX	多选框（封装组件）
DATE	日期选择
DATETIME	日期时间
DATERANGE	日期范围
DATETIMERANGE	日期时间范围
TIME	时间选择
TIMERANGE	时间范围
UPLOAD_IMAGES	图片上传（封装组件）
SWITCH	开关
TREE_SELECT	树形选择
CASCADER	级联选择
TREE	树形控件
SLIDER	滑块
RATE	评分

方法

方法名	说明	类型
validate	验证表单	Function
validateField	验证指定字段	Function
clearValidate	清空验证	Function
resetFields	重置表单（重置为初始数据）	Function
getFormData	获取表单数据（按需调用）	Function
setFormData	设置表单数据（会清除校验，支持合并或完全替换）	Function

插槽

插槽名	说明	参数
[prop]	自定义表单项内容	{ item: FormItemConfig, value: any, formData: Record }
label-[prop]	自定义表单项标签	{ item: FormItemConfig }