StepsForm 分步表单
把一张长表单分成几步填写
用法
基础
每一步只校验自己的字段,最后一步提交;开启 persist 后当前步骤也写进草稿,刷新后回到原来那一步。
Loading demo...
跳过与自定义操作
actions 插槽替换底部按钮;父级改写 active 时直接跳转、不做校验,可以用来跳过选填的步骤。
<TxStepsForm v-model:active="active" :model="team" @submit="create">
…
<template #actions="{ last, back, submitting }">
<TxButton v-if="active > 0" :disabled="submitting" @click="back">上一步</TxButton>
<TxButton v-if="active === 1" variant="ghost" @click="active = 2">稍后邀请</TxButton>
<TxButton variant="primary" native-type="submit" :loading="submitting">{{ last ? '创建团队' : '下一步' }}</TxButton>
</template>
</TxStepsForm>
最佳实践
- 每一步三到五个字段,步骤标题用名词说明这一步填什么。
- 开启
persist时给出id;步骤随草稿保存,用户刷新或回来后不必从头开始。 - 跳过的步骤仍会在最后提交时校验:选填步骤里不要放必填字段。
- 分步表单没有自动保存;需要中途保存时用
persist草稿。 - 非英文界面传入
prevText、nextText与submitText;草稿提示等内置文案用messages覆盖,或由provideTxFormHost统一提供。
API 参考
TxStepsForm
属性
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
active | number | - | 显示的步骤,从 0 开始;用 v-model:active 绑定,或交给表单自己管理。 |
prevText | string | 'Back' | 「上一步」按钮的文字。 |
nextText | string | 'Next' | 「下一步」按钮的文字。 |
submitText | string | 'Submit' | 最后一步提交按钮的文字。 |
继承自 TxForm 的属性
除 autosave 外,TxForm 的属性都可传入。
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
id | string | - | 表单 id,作为 <form> 与各字段 id 的前缀,也是草稿的键。 |
model | FormValues | - | 表单数据;TxFormItem 的 prop 指向其中的字段。 |
rules | FormRules | - | 按字段名给出的校验规则。 |
schema | FormStandardSchema | - | 对整个数据做校验的 Standard Schema v1 校验器,如 Zod、Valibot。 |
layout | 'stacked' | 'side' | 'auto' | 'inline' | 'auto' | 标签布局;auto 在宽度不少于 520px 时用侧边标签。 |
labelPosition | 'left' | 'right' | 'top' | - | 旧写法的标签位置,top 等同 stacked,left 与 right 等同 side。 |
labelAlign | 'start' | 'end' | 'end' | 侧边标签列内的对齐;labelPosition="left" 时默认 start。 |
labelWidth | string | number | - | 侧边标签列的最大宽度;所有标签更短时列更窄。 |
requiredMark | 'asterisk' | 'optional' | 'none' | - | 必填标记的显示方式。 |
validateOn | 'blur' | 'submit' | - | 字段首次显示消息的时机;显示后每次编辑都会重新校验。 |
messages | Partial<FormMessages> | - | 覆盖内置文案,如草稿提示与错误前缀。 |
size | 'small' | 'medium' | 'large' | - | 传给表单内有尺寸的控件。 |
disabled | boolean | false | 禁用表单内读取表单状态的全部控件。 |
readonly | boolean | false | 只读展示:控件可聚焦、可复制但不可修改,且不标记必填;仍可提交。 |
reconcile | FormReconcile | - | 字段已被用户修改时,决定新到达的数据如何合并。 |
persist | boolean | FormPersistOptions | - | 把输入保存为草稿,按 id 区分,刷新后恢复,包括当前步骤。 |
leaveConfirm | FormLeaveConfirm | false | - | 有未保存改动离开时是否询问;false 从不询问。 |
onSubmit | (values: FormValues, event?: Event) => unknown | - | 通过全部校验后调用的提交回调,等价于 @submit。 |
事件
| 事件名 | 参数 | 说明 |
|---|---|---|
update:active | (step: number) | 前进、后退或因字段出错回到某一步时触发。 |
submit-success | (values: FormValues) | 最后一步提交成功。 |
validate | (valid: boolean) | 同 TxForm。 |
persist-error | (error: unknown) | 同 TxForm。 |
插槽
| 插槽名 | 参数 | 说明 |
|---|---|---|
default | { active, dirty, valid, submitting, submitted, errors, rootError } | 各个 TxFormStep。 |
actions | { active, last, back, submitting } | 替换「上一步」与「下一步」或提交按钮;前进用 native-type="submit" 的按钮,才会校验当前步。 |
暴露方法
| 名称 | 类型 | 说明 |
|---|---|---|
form | TxForm | 里面的表单,拥有 TxForm 的全部方法。 |
back | () => void | 回到上一步,与「上一步」按钮相同。 |
TxFormStep
属性
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
title | string | 必填 | 步骤条中的名称,也是这一组字段的可访问名称。 |
description | string | - | 步骤条中标题下的说明。 |
插槽
| 插槽名 | 参数 | 说明 |
|---|---|---|
default | - | 这一步的表单项。 |
概述
- 所有步骤一直挂载,只显示当前一步,因此最后一次提交会校验全部字段;出错的字段在哪一步,就回到哪一步并聚焦它。
- 「下一步」是表单的提交按钮:只校验当前一步的字段,通过后前进,焦点移到下一步的分组上,读屏读出步骤名,Tab 进入第一个字段。
- 前进不算提交:下一步的字段在用户改过并离开,或再次提交后才显示消息。
- 开启
persist时当前步骤随草稿写入,恢复草稿时一并回到那一步;提交成功后草稿删除。 - 步骤在挂载后才登记:服务端渲染与浏览器首次渲染时步骤条为空,挂载后补全。
- 父级改写
active时直接跳转,不校验,也不移动焦点。
技术实现
- 一个
TxForm实例包住全部步骤,步骤条由TxSteps绘制;每一步是以title命名的role="group"。 TxFormStep用 CSS subgrid 沿用表单的列,侧边布局时各步骤的 label 列对齐。- 源码:
packages/tuffex/packages/components/src/steps-form/。
查看源码
packages/tuffex/packages/components/src/steps-form/index.ts