主题
ProDescriptions 描述列表
ProDescriptions 描述列表 的基础用法、公开 API 与示例。
基础示例
示例使用本地演示数据；上传、校验和提交不会连接业务后端。
引入方式
ts
import { ProDescriptions } from "@/components/pro/descriptions";Props
| 参数 | 说明 | 类型 | 默认值 | 必填 |
|---|---|---|---|---|
| border | 是否显示边框。 | boolean | - | 否 |
| data | 描述列表数据，如果传入该配置项且有数据，则不会执行 api 请求 | object | {} | 否 |
| requestApi | 请求数据的 api | (data?: Recordable) => Promise<unknown> | undefined | 否 |
| defaultRequestParams | 默认请求参数 | Recordable | {} | 否 |
| transformData | 对请求成功的数据进行处理 | (data: Recordable, result?: unknown) => unknown | - | 否 |
| columns | 描述列表列配置 | LooseDescriptionColumn[] | [] | 否 |
| descriptionsItemProps | 描述列表 DescriptionItem 全局配置 | Partial<DescriptionItemProps> | {} | 否 |
| card | 是否使用卡片背景 | boolean | false | 否 |
| editable | 描述列表整体是否为编辑态 | boolean | false | 否 |
| editButton | 是否显示编辑按钮 | boolean | false | 否 |
| editText | 编辑按钮文案 | [string, string] | ["编辑", "退出编辑"] | 否 |
| formProps | ProForm Props | DescriptionColumn["formProps"] | {} | 否 |
| showReset | 是否显示重置按钮 | boolean | true | 否 |
| submitText | 提交按钮文字 | string | "提交" | 否 |
| resetText | 重置按钮文字 | string | "重置" | 否 |
| submitLoading | 提交按钮 loading | boolean | false | 否 |
| footerAlign | 底部按钮对齐方式 | "left" | "center" | "right" | "left" | 否 |
| footerStyle | 底部按钮组样式 | CSSProperties | {} | 否 |
| validate | 是否使用内置的表单校验功能 | boolean | true | 否 |
| modelValue | 组件双向绑定值。 | Recordable | () => reactive({}) | 否 |
Events
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| register | 注册事件 | proDescriptionsInstance: unknown |
| formChange | 表单值改变事件 | value: unknown, prop: string, model: Recordable, column: FormItemColumnProps |
| edited | 进入编辑态事件 | - |
| editedCancel | 退出编辑态事件 | - |
| submit | 提交按钮事件 | model: Recordable, closeEdited: () => void |
| reset | 重置按钮事件 | model: Recordable, closeEdited: () => void |
| update:modelValue | 双向绑定值更新时触发。 | value: Recordable |
Slots
| 插槽名 | 说明 | 参数 |
|---|---|---|
| default | 默认内容插槽。 | - |
动态插槽(${column.prop}-label) | 动态转发当前组件收到的同名插槽。 | label |
Expose
| 名称 | 说明 | 类型 |
|---|---|---|
| model | 暴露 model 给外部调用。 | - |
| optionsMap | 暴露 optionsMap 给外部调用。 | - |
| proFormInstances | 暴露 proFormInstances 给外部调用。 | - |
| setValues | 暴露 setValues 给外部调用。 | - |
| setProps | 动态设置组件属性。 | - |
| setColumn | 动态设置列配置。 | - |
| addColumn | 动态新增列配置。 | - |
| delColumn | 动态删除列配置。 | - |
| openEdited | 暴露 openEdited 给外部调用。 | - |
| closeEdited | 暴露 closeEdited 给外部调用。 | - |
| handleReset | 暴露 handleReset 给外部调用。 | - |
| handleSubmit | 暴露 handleSubmit 给外部调用。 | - |
| getProFormInstances | 暴露 getProFormInstances 给外部调用。 | - |
| getElFormInstance | 获取查询表单实例。 | (prop: string) => {<br> const proFormInstance = proFormInstances.value[prop];<br> return proFormInstance!.elFormInstance;<br> } |
| getElFormItemInstance | 获取查询表单项实例。 | (prop: string) => {<br> const proFormInstance = proFormInstances.value[prop];<br> return proFormInstance!.proFormMainInstance?.getElFormItemInstance(prop);<br> } |
| getElInstance | 获取内部组件实例。 | (prop: string) => {<br> const proFormInstance = proFormInstances.value[prop];<br> return proFormInstance!.proFormMainInstance?.getElInstance(prop);<br> } |
Module API
| 名称 | 说明 | 类型 |
|---|---|---|
| ProDescriptions | 导出 ProDescriptions 供业务侧复用。 | useInstall(index) |
Types
ProDescriptionsProp
PropDescriptions 组件的 Props
| 字段 | 说明 | 类型 | 默认值 | 必填 |
|---|---|---|---|---|
| border | 是否显示边框。 | boolean | - | 否 |
| data | 描述列表数据，如果传入该配置项且有数据，则不会执行 api 请求 | object | - | 否 |
| requestApi | 请求数据的 api | (data?: Recordable) => Promise<unknown> | - | 否 |
| defaultRequestParams | 默认请求参数 | Recordable | - | 否 |
| transformData | 对请求成功的数据进行处理 | (data: Recordable, result?: unknown) => unknown | - | 否 |
| columns | 描述列表列配置 | LooseDescriptionColumn[] | - | 否 |
| descriptionsItemProps | 描述列表 DescriptionItem 全局配置 | Partial<DescriptionItemProps> | - | 否 |
| card | 是否使用卡片背景 | boolean | - | 否 |
| editable | 描述列表整体是否为编辑态 | boolean | false | 否 |
| editButton | 是否显示编辑按钮 | boolean | true | 否 |
| editText | 编辑按钮文案 | [string, string] | '["编辑", "退出编辑"]' | 否 |
| formProps | ProForm Props | DescriptionColumn["formProps"] | - | 否 |
| showReset | 是否显示重置按钮 | boolean | true | 否 |
| submitText | 提交按钮文字 | string | '提交' | 否 |
| resetText | 重置按钮文字 | string | '重置' | 否 |
| submitLoading | 提交按钮 loading | boolean | false | 否 |
| footerAlign | 底部按钮对齐方式 | "left" | "center" | "right" | 'right' | 否 |
| footerStyle | 底部按钮组样式 | CSSProperties | - | 否 |
| validate | 是否使用内置的表单校验功能 | boolean | true | 否 |
LooseDescriptionColumn
组件边界使用的宽松描述列配置，擦除具体业务数据模型。
| 字段 | 说明 | 类型 | 默认值 | 必填 |
|---|---|---|---|---|
| renderLabel | 标签渲染回调，组件内部按实际列配置收窄后调用。 | unknown | - | 否 |
| render | 内容渲染回调，组件内部按实际列配置收窄后调用。 | unknown | - | 否 |
| renderHTML | HTML 渲染回调，组件内部按实际列配置收窄后调用。 | unknown | - | 否 |
| formatValue | 值格式化回调，组件内部按实际列配置收窄后调用。 | unknown | - | 否 |
| elSlots | 组件插槽回调，组件内部按实际列配置收窄后调用。 | unknown | - | 否 |
| elProps | 展示组件属性，组件内部按实际列配置收窄后调用。 | unknown | - | 否 |
| transformOption | 字典选项转换回调，组件内部按实际列配置收窄后调用。 | unknown | - | 否 |
DescriptionColumn
描述列表配置项
| 字段 | 说明 | 类型 | 默认值 | 必填 |
|---|---|---|---|---|
| prop | 唯一键 | FormItemColumnProps["prop"] | - | 否 |
| label | 标签 | MaybeRefOrGetter<string> | - | 否 |
| span | 列的数量 | MaybeRef<number> | ((editable: boolean) => number) | - | 否 |
| rowSpan | 单元格应该跨越的行数 | MaybeRef<number> | ((editable: boolean) => number) | - | 否 |
| width | 列的宽度 | MaybeRef<string | number> | ((editable: boolean) => string | number) | - | 否 |
| minWidth | 列的最小宽度 | MaybeRef<string | number> | ((editable: boolean) => string | number) | - | 否 |
| labelWidth | 列标签宽 | MaybeRef<string | number> | ((editable: boolean) => string | number) | - | 否 |
| hidden | 是否隐藏 | MaybeRefOrGetter<boolean> | false | 否 |
| options | 字典枚举数据 | FormItemColumnProps["options"] | - | 否 |
| optionCache | 是否缓存字典数据 | boolean | true | 否 |
| optionsProp | 指定 Options 的 key，如果设置了则优先从缓存获取对于 key 的 Options 数据 | string | - | 否 |
| optionField | 字典指定 label && value && children 的 key 值 | FormItemColumnProps["optionField"] | '{ label: "label", value: "value", children: "children", disabled: "disabled" }' | 否 |
| transformOption | 自定义当前 option 选项 | (value: unknown, options: ElOption[], data: Recordable) => ElOption | - | 否 |
| order | 排序（从大到小） | number | - | 否 |
| renderLabel | 自定义 label 渲染 | BivariantCallback<[scope: DescriptionsRenderParams<T>], RenderTypes> | - | 否 |
| render | 自定义内容渲染 | BivariantCallback<[scope: DescriptionsRenderParams<T>], RenderTypes> | - | 否 |
| renderHTML | 自定义内容渲染（HTML 格式） | BivariantCallback<[scope: DescriptionsRenderParams<T>], string> | - | 否 |
| formatValue | 自定义内容 | BivariantCallback<[value: unknown, scope: DescriptionsRenderParams<T>], string | number> | - | 否 |
| editable | 是否为编辑态 | boolean | false | 否 |
| formProps | ProForm Props | MaybeRefOrGetter<<br> Omit<<br> ProFormNamespace.Props,<br> | "columns"<br> | "flexLayout"<br> | "showLabel"<br> | "showFooter"<br> | "rowProps"<br> | "colProps"<br> | "showReset"<br> | "submitText"<br> | "resetText"<br> | "submitLoading"<br> | "footerAlign"<br> | "preventNativeSubmit"<br> ><br> > | - | 否 |
| formColumn | ProFormItem Props，等于 ProForm 的单个 column | MaybeRefOrGetter<Omit<FormItemColumnProps, "prop" | "label" | "options" | "optionField">> | - | 否 |
| elSlots | el 组件的插槽 | {<br> [slotName: string]: BivariantCallback<[data: DescriptionsRenderParams<T> & Recordable], RenderTypes>;<br> } | - | 否 |
ProDescriptionsEmits
ProDescriptions 事件
| 字段 | 说明 | 类型 | 默认值 | 必填 |
|---|---|---|---|---|
| register | 注册事件 | [proDescriptionsInstance: unknown] | - | 是 |
| formChange | 表单值改变事件 | [value: unknown, prop: string, model: Recordable, column: FormItemColumnProps] | - | 是 |
| edited | 进入编辑态事件 | [] | - | 是 |
| editedCancel | 退出编辑态事件 | [] | - | 是 |
| submit | 提交按钮事件 | [model: Recordable, closeEdited: () => void] | - | 是 |
| reset | 重置按钮事件 | [model: Recordable, closeEdited: () => void] | - | 是 |
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 | - | 否 |
API 根据当前组件源码生成；同步版本与验证记录见维护说明。