主题
ProFormItem 表单项
ProFormItem 表单项 的基础用法、公开 API 与示例。
基础示例
示例使用本地演示数据；上传、校验和提交不会连接业务后端。
引入方式
ts
import { Tree, ProFormItem } from "@/components/pro/form-item";Props
| 参数 | 说明 | 类型 | 默认值 | 必填 |
|---|---|---|---|---|
| prop | ElFormItem 的 prop 属性，当表单数据 model 为对象时，prop 也是 model 的 key | string | "" | 否 |
| label | 标签，ElFormItem 的 label 属性 | MaybeRef<string | number> | BivariantCallback<[model: T], string | number> | "" | 否 |
| showLabel | 是否显示 label | MaybeRefOrGetter<boolean> | true | 否 |
| width | 表单组件宽度 | MaybeRefOrGetter<string | number> | "" | 否 |
| el | 使用的表单组件名 | MaybeRefOrGetter<FormElType> | "ElInput" | 否 |
| elProps | 表单组件的 Props，即会透传到表单组件 | MaybeRefOrGetter<FormElProps> | BivariantCallback<[model: T], FormElProps> | {} | 否 |
| elSlots | 表单组件的插槽 | {<br> [slotName: string]: BivariantCallback<[data: FormItemRenderParams<T> & Recordable], RenderTypes>;<br> } | {} | 否 |
| options | 字典枚举数据 | | string[]<br> | MaybeRef<ElOption[] | object[]><br> | Promise<ElOption[] | object[]><br> | BivariantCallback<<br> [optionsParams: OptionsParams<T>],<br> | ElOption[]<br> | object[]<br> | Record<string, ElOption[] | object[]><br> | Promise<ElOption[] | object[] | Record<string, ElOption[] | object[]>><br> > | [] | 否 |
| optionField | 字典指定 label && value && children 的 key 值 | ElOptionField | () => defaultOptionField | 否 |
| formItemProps | ElFormItem props | MaybeRefOrGetter<ElFormItemProps> | {} | 否 |
| clearable | 是否显示清除按钮 | boolean | true | 否 |
| tooltip | Label 右侧 ElToolTip 提示 | | MaybeRefOrGetter<string><br> | ({<br> icon?: Component; // ElTooTip 绑定的元素图标<br> render?: () => RenderTypes; // 自定义 ElTooTip 绑定的元素，将会覆盖图标，传入 ElTooTip 的 default 插槽里<br> contentRender?: () => RenderTypes; // 自定义 ElTooTip 的内容，传入 ElTooTip 的 content 插槽里<br> } & Partial<ElTooltipProps>) | undefined | 否 |
| valueFormat | 表单绑定的值格式，场景：select 下拉 value 为 "1"，而 value 值是 1 导致无法匹配，可以设置为 valueFormat: "string" 解决 | "string" | "number" | "boolean" | ((value: unknown) => unknown) | undefined | 否 |
| returnFullPath | 对于 el-tree-select 组件，是否返回完整路径 当设置为 true 时，选择子节点会返回从根节点到选中节点的完整路径数组 例如：选择 "马来一期" 会返回 ["马来项目", "马来一期"] | boolean | false | 否 |
| editable | 是否为编辑态 | MaybeRefOrGetter<boolean> | true | 否 |
| renderLabel | 自定义 label 标题 | BivariantCallback<[scope: FormItemRenderParams<T>], RenderTypes> | undefined | 否 |
| renderLabelHTML | 自定义 Label 内容渲染（返回 HTML），优先级低于 render，高于插槽 | BivariantCallback<[scope: FormItemRenderParams<T>], string> | - | 否 |
| render | 自定义渲染 el-form-item 下的表单组件 | BivariantCallback<[scope: FormItemRenderParams<T>], RenderTypes> | undefined | 否 |
| parse | 解析 model 中的值为组件需要的格式（在读取时调用） 使用场景：后端返回逗号分隔的字符串 "1,2,3"，需要解析为数组 ['1','2','3'] 供 el-select 多选使用 示例：parse: (value) => typeof value === 'string' ? value.split(',') : value | (value: unknown) => unknown | undefined | 否 |
| format | 格式化最终表单提交的值（在设置到 model 之前调用） 使用场景：el-select 多选返回数组 ['1','2','3']，需要格式化为逗号分隔的字符串 "1,2,3" 提交给后端 示例：format: (value) => Array.isArray(value) ? value.join(',') : value 注意：parse 和 format 通常配对使用，形成双向转换 | (value: unknown) => unknown | undefined | 否 |
| modelValue | 组件双向绑定值。 | BaseValueType | - | 否 |
Events
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| update:modelValue | 双向绑定值更新时触发。 | value: BaseValueType |
| change | 表单值改变事件 | value: unknown, model: Record<string, unknown>, column: FormItemColumnProps, oldValue: unknown |
Slots
| 插槽名 | 说明 | 参数 |
|---|---|---|
动态插槽(${prop}-label) | 动态转发当前组件收到的同名插槽。 | - |
Expose
| 名称 | 说明 | 类型 |
|---|---|---|
| elFormItemInstance | 暴露 elFormItemInstance 给外部调用。 | - |
| elInstance | 暴露 elInstance 给外部调用。 | - |
Module API
| 名称 | 说明 | 类型 |
|---|---|---|
| ProFormItem | 导出 ProFormItem 供业务侧复用。 | useInstall(index) |
Types
FormItemColumnProps
ProFormItem 的 props
| 字段 | 说明 | 类型 | 默认值 | 必填 |
|---|---|---|---|---|
| prop | ElFormItem 的 prop 属性，当表单数据 model 为对象时，prop 也是 model 的 key | string | - | 否 |
| label | 标签，ElFormItem 的 label 属性 | MaybeRef<string | number> | BivariantCallback<[model: T], string | number> | - | 否 |
| showLabel | 是否显示 label | MaybeRefOrGetter<boolean> | true | 否 |
| width | 表单组件宽度 | MaybeRefOrGetter<string | number> | - | 否 |
| el | 使用的表单组件名 | MaybeRefOrGetter<FormElType> | 'ElInput' | 否 |
| elProps | 表单组件的 Props，即会透传到表单组件 | MaybeRefOrGetter<FormElProps> | BivariantCallback<[model: T], FormElProps> | - | 否 |
| elSlots | 表单组件的插槽 | {<br> [slotName: string]: BivariantCallback<[data: FormItemRenderParams<T> & Recordable], RenderTypes>;<br> } | - | 否 |
| options | 字典枚举数据 | | string[]<br> | MaybeRef<ElOption[] | object[]><br> | Promise<ElOption[] | object[]><br> | BivariantCallback<<br> [optionsParams: OptionsParams<T>],<br> | ElOption[]<br> | object[]<br> | Record<string, ElOption[] | object[]><br> | Promise<ElOption[] | object[] | Record<string, ElOption[] | object[]>><br> > | - | 否 |
| optionField | 字典指定 label && value && children 的 key 值 | ElOptionField | '{ label: "label", value: "value", children: "children", disabled: "disabled" }' | 否 |
| formItemProps | ElFormItem props | MaybeRefOrGetter<ElFormItemProps> | - | 否 |
| clearable | 是否显示清除按钮 | boolean | true | 否 |
| tooltip | Label 右侧 ElToolTip 提示 | | MaybeRefOrGetter<string><br> | ({<br> icon?: Component; // ElTooTip 绑定的元素图标<br> render?: () => RenderTypes; // 自定义 ElTooTip 绑定的元素，将会覆盖图标，传入 ElTooTip 的 default 插槽里<br> contentRender?: () => RenderTypes; // 自定义 ElTooTip 的内容，传入 ElTooTip 的 content 插槽里<br> } & Partial<ElTooltipProps>) | - | 否 |
| valueFormat | 表单绑定的值格式，场景：select 下拉 value 为 "1"，而 value 值是 1 导致无法匹配，可以设置为 valueFormat: "string" 解决 | "string" | "number" | "boolean" | ((value: unknown) => unknown) | - | 否 |
| returnFullPath | 对于 el-tree-select 组件，是否返回完整路径 当设置为 true 时，选择子节点会返回从根节点到选中节点的完整路径数组 例如：选择 "马来一期" 会返回 ["马来项目", "马来一期"] | boolean | false | 否 |
| editable | 是否为编辑态 | MaybeRefOrGetter<boolean> | true | 否 |
| renderLabel | 自定义 label 标题 | BivariantCallback<[scope: FormItemRenderParams<T>], RenderTypes> | - | 否 |
| renderLabelHTML | 自定义 Label 内容渲染（返回 HTML），优先级低于 render，高于插槽 | BivariantCallback<[scope: FormItemRenderParams<T>], string> | - | 否 |
| render | 自定义渲染 el-form-item 下的表单组件 | BivariantCallback<[scope: FormItemRenderParams<T>], RenderTypes> | - | 否 |
| parse | 解析 model 中的值为组件需要的格式（在读取时调用） 使用场景：后端返回逗号分隔的字符串 "1,2,3"，需要解析为数组 ['1','2','3'] 供 el-select 多选使用 示例：parse: (value) => typeof value === 'string' ? value.split(',') : value | (value: unknown) => unknown | - | 否 |
| format | 格式化最终表单提交的值（在设置到 model 之前调用） 使用场景：el-select 多选返回数组 ['1','2','3']，需要格式化为逗号分隔的字符串 "1,2,3" 提交给后端 示例：format: (value) => Array.isArray(value) ? value.join(',') : value 注意：parse 和 format 通常配对使用，形成双向转换 | (value: unknown) => unknown | - | 否 |
FormItemRenderParams
render 或插槽参数类型
| 字段 | 说明 | 类型 | 默认值 | 必填 |
|---|---|---|---|---|
| value | 当前值 | unknown | - | 是 |
| model | 当前表单数据 | T | - | 是 |
| label | 当前描述列表标签 | string | number | - | 是 |
| options | 字典枚举 | ElOption[] | - | 是 |
| elProps | el 组件的 props | Recordable | - | 是 |
| formItemProps | el-form-item 的 props | Partial<FormItemProps> | - | 是 |
| update | 更新当前 prop 的表单值函数 | (value: unknown) => void | - | 是 |
| column | 当前列配置 | FormItemColumnProps<T> | - | 是 |
ElOption
字典数据类型
| 字段 | 说明 | 类型 | 默认值 | 必填 |
|---|---|---|---|---|
| label | 选项框显示的文字 | string | - | 否 |
| value | 选项框值 | string | number | boolean | object | null | - | 否 |
| disabled | 是否禁用此选项 | boolean | - | 否 |
| children | 为树形选择时，可以通过 children 属性指定子选项 | ElOption[] | - | 否 |
OptionsParams
options 为函数的参数类型
| 字段 | 说明 | 类型 | 默认值 | 必填 |
|---|---|---|---|---|
| model | 表单数据 | T | - | 否 |
| optionsMap | 字典枚举数据缓存，key 为 prop，value 为 options | Map<string, MaybeRef<ElOption[]>> | - | 否 |
| prop | 当前列配置 | string | - | 否 |
ElOptionField
自定义字典的 key
| 字段 | 说明 | 类型 | 默认值 | 必填 |
|---|---|---|---|---|
| label | 配置 label。 | string | - | 否 |
| value | 组件值。 | string | - | 否 |
| disabled | 是否禁用组件。 | string | - | 否 |
| children | 配置 children。 | string | - | 否 |
ProFormItemEmits
导出 ProFormItemEmits 供业务侧复用。
| 字段 | 说明 | 类型 | 默认值 | 必填 |
|---|---|---|---|---|
| change | 表单值改变事件 | [value: unknown, model: Record<string, unknown>, column: FormItemColumnProps, oldValue: unknown] | - | 是 |
API 根据当前组件源码生成；同步版本与验证记录见维护说明。