ProFormSteps 步骤表单

ProFormSteps 步骤表单 的基础用法、公开 API 与示例。

基础示例

示例使用本地演示数据；上传、校验和提交不会连接业务后端。

<script setup lang="ts">
import { ref, } from "vue";
import { ProFormSteps } from "@/components/pro/form-steps";

const columns = [{ title: "基础信息", form: { columns: [{ prop: "name", label: "名称", el: "el-input" }] } }, { title: "确认", form: { columns: [{ prop: "remark", label: "备注", el: "el-input" }] } }];
</script>

<template>
  <ClientOnly>
    <div class="demo-surface">
      <ProFormSteps :columns="columns" />
    </div>
  </ClientOnly>
</template>

隐藏源代码

引入方式

import { ProFormSteps } from "@/components/pro/form-steps";

Props

参数	说明	类型	默认值	必填
columns	步骤表单配置信息	FormStepColumn[]	[]	否
submitText	提交按钮文字	string	"提交"	否
nextText	下一步按钮文字	string	"下一步"	否
preText	上一步按钮文字	string	"上一步"	否
modelValue	组件双向绑定值。	number	1	否

Events

事件名	说明	回调参数
pre	上一步按钮点击事件	currentIndex: number
next	下一步按钮点击事件	currentIndex: number, currentModel: Recordable, allModel: Recordable
submit	提交按钮点击事件	currentIndex: number, currentModel: Recordable, allModel: Recordable
change	表单值改变事件	value: unknown, model: Recordable, column: FormItemColumnProps
update:modelValue	双向绑定值更新时触发。	value: number

Slots

插槽名	说明	参数
icon	图标内容插槽。	icon, title, description

Expose

名称	说明	类型
proFormInstance	暴露 proFormInstance 给外部调用。	-
pre	暴露 pre 给外部调用。	-
next	暴露 next 给外部调用。	-

Module API

名称	说明	类型
ProFormSteps	导出 ProFormSteps 供业务侧复用。	useInstall(index)

Types

ProFormStepsProps

导出 ProFormStepsProps 供业务侧复用。

字段	说明	类型	默认值	必填
columns	步骤表单配置信息	FormStepColumn[]	-	否
submitText	提交按钮文字	string	'提交'	否
nextText	下一步按钮文字	string	'下一步'	否
preText	上一步按钮文字	string	'上一步'	否

FormStepColumn

导出 FormStepColumn 供业务侧复用。

字段	说明	类型	默认值	必填
title	ElSteps 的 title	StepProps["title"]	-	是
description	ElSteps 的 description	StepProps["description"]	-	否
icon	ElSteps 的 icon	StepProps["icon"]	-	否
status	ElSteps 的 status	StepProps["status"]	-	否
form	ProForm Props	ProFormNamespace.Props & { modelValue?: Recordable }	-	否

ProFormStepsEmits

导出 ProFormStepsEmits 供业务侧复用。

字段	说明	类型	默认值	必填
pre	上一步按钮点击事件	[currentIndex: number]	-	是
next	下一步按钮点击事件	[currentIndex: number, currentModel: Recordable, allModel: Recordable]	-	是
submit	提交按钮点击事件	[currentIndex: number, currentModel: Recordable, allModel: Recordable]	-	是
change	表单值改变事件	[value: unknown, model: Recordable, column: FormItemColumnProps]	-	是

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 根据当前组件源码生成；同步版本与验证记录见维护说明。