组件/StepsForm 分步表单

StepsForm 分步表单

把一张长表单分成几步填写

Verified自 0.9.2

用法

基础

每一步只校验自己的字段,最后一步提交;开启 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

属性

属性名类型默认值说明
activenumber-显示的步骤,从 0 开始;用 v-model:active 绑定,或交给表单自己管理。
prevTextstring'Back'「上一步」按钮的文字。
nextTextstring'Next'「下一步」按钮的文字。
submitTextstring'Submit'最后一步提交按钮的文字。

继承自 TxForm 的属性

除 autosave 外,TxForm 的属性都可传入。

属性名类型默认值说明
idstring-表单 id,作为 <form> 与各字段 id 的前缀,也是草稿的键。
modelFormValues-表单数据;TxFormItem 的 prop 指向其中的字段。
rulesFormRules-按字段名给出的校验规则。
schemaFormStandardSchema-对整个数据做校验的 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。
labelWidthstring | number-侧边标签列的最大宽度;所有标签更短时列更窄。
requiredMark'asterisk' | 'optional' | 'none'-必填标记的显示方式。
validateOn'blur' | 'submit'-字段首次显示消息的时机;显示后每次编辑都会重新校验。
messagesPartial<FormMessages>-覆盖内置文案,如草稿提示与错误前缀。
size'small' | 'medium' | 'large'-传给表单内有尺寸的控件。
disabledbooleanfalse禁用表单内读取表单状态的全部控件。
readonlybooleanfalse只读展示:控件可聚焦、可复制但不可修改,且不标记必填;仍可提交。
reconcileFormReconcile-字段已被用户修改时,决定新到达的数据如何合并。
persistboolean | FormPersistOptions-把输入保存为草稿,按 id 区分,刷新后恢复,包括当前步骤。
leaveConfirmFormLeaveConfirm | 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" 的按钮,才会校验当前步。

暴露方法

名称类型说明
formTxForm里面的表单,拥有 TxForm 的全部方法。
back() => void回到上一步,与「上一步」按钮相同。

TxFormStep

属性

属性名类型默认值说明
titlestring必填步骤条中的名称,也是这一组字段的可访问名称。
descriptionstring-步骤条中标题下的说明。

插槽

插槽名参数说明
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