---
title: "StepsForm 分步表单"
description: "把一张长表单分成几步填写"
category: Form
status: beta
since: 0.9.2
tags: [form, steps, wizard]
syncStatus: reviewed
verified: true
---

## 用法

### 基础
每一步只校验自己的字段，最后一步提交；开启 `persist` 后当前步骤也写进草稿，刷新后回到原来那一步。
::::TuffDemoWrapper{demo="StepsFormBasicDemo" code-lang="vue"}
---
code: |
  <script setup lang="ts">
  import { reactive, ref } from 'vue'

  const active = ref(0)
  const team = reactive({ name: '', handle: '', email: '', role: 'member', plan: '' })
  const roles = [
    { value: 'admin', label: '管理员' },
    { value: 'member', label: '成员' },
  ]
  const rules = {
    name: { required: true, message: '请输入团队名称' },
    handle: [
      { required: true, message: '请输入团队地址' },
      { pattern: /^[a-z0-9-]+$/, message: '只能使用小写字母、数字或连字符' },
    ],
    email: { type: 'email', message: '邮箱格式不正确' },
    plan: { required: true, message: '请选择套餐' },
  }

  async function create(values) {
    await createTeam(values)
  }
  </script>

  <template>
    <TxStepsForm
      id="new-team"
      v-model:active="active"
      :model="team"
      :rules="rules"
      persist
      prev-text="上一步"
      next-text="下一步"
      submit-text="创建团队"
      @submit="create"
    >
      <TxFormStep title="团队">
        <TxFormItem label="团队名称" prop="name">
          <TuffInput v-model="team.name" />
        </TxFormItem>
        <TxFormItem label="团队地址" prop="handle" help="小写字母、数字或连字符">
          <TuffInput v-model="team.handle" />
        </TxFormItem>
      </TxFormStep>
      <TxFormStep title="邀请">
        <TxFormItem label="成员邮箱" prop="email">
          <TuffInput v-model="team.email" type="email" />
        </TxFormItem>
        <TxFormItem label="角色" prop="role">
          <TxSelect v-model="team.role" :options="roles" />
        </TxFormItem>
      </TxFormStep>
      <TxFormStep title="套餐">
        <TxFormItem label="套餐" prop="plan">
          <TxRadioGroup v-model="team.plan" type="standard" direction="row">
            <TxRadio value="free" label="免费版" />
            <TxRadio value="pro" label="专业版" />
            <TxRadio value="team" label="团队版" />
          </TxRadioGroup>
        </TxFormItem>
      </TxFormStep>
    </TxStepsForm>
  </template>
---
::::

### 跳过与自定义操作
`actions` 插槽替换底部按钮；父级改写 `active` 时直接跳转、不做校验，可以用来跳过选填的步骤。

```vue
<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/`。

<TuffDocSourceLink />
