多步骤输入插件

介绍
安装
使用
标签样式
步骤标签
允许不完整步骤
有效步骤图标
自定义步骤操作
beforeStepChange 事件
程序化导航
属性 & 特性（multi-step）
属性 & 特性（step）
章节

介绍

FormKit 随附了一个第一方多步骤输入插件，可从 @formkit/addons 包中获取。这个输入允许您构建向导或轻松地将表单分成多个步骤。将表单分成多个步骤可以通过保持它们感觉小巧和易于接近来改善大型表单的用户体验，与一次列出所有输入相比。

多步骤组件概览

2 分钟

安装

要在 FormKit 中使用这个插件，请安装 @formkit/addons：

yarn add @formkit/addons

安装了 addons 包之后，您需要向 FormKit 注册插件并包含支持的 CSS 样式：

// formkit.config.js
import { defaultConfig } from '@formkit/vue'
import { createMultiStepPlugin } from '@formkit/addons'
import '@formkit/addons/css/multistep'

const config = defaultConfig({
  plugins: [createMultiStepPlugin()],
})

export default config

`multi-step` 输入类型的快速演示：

加载实时示例

使用

createMultiStepPlugin 函数为您注册了两种新的输入类型，供您与 FormKit 组件一起使用。

multi-step：整个多步骤输入的包装组。这个输入跟踪哪个步骤是活动的，每个步骤的验证和错误，并且应该只包含 step 输入作为其直接子项
step：在您的多步骤输入中给定步骤的包装组。应该只是 multi-step 输入的直接子项。其子项将作为步骤的内容呈现。

将这些输入一起使用就像将您想要在多步骤表单中的一个步骤中呈现的任何标记包装起来一样简单。

<FormKit type="multi-step">
  <FormKit type="step" name="stepOne">
    <!-- stepOne 的内容在这里！ -->
  </FormKit>
</FormKit>

开箱即用的父 multi-step 输入将跟踪每个子 step 输入中包含的输入的有效性，并阻止在当前步骤有效之前前进到下一个 step。如果用户尝试在满足当前步骤的输入验证之前前进到下一步或提交表单，则会在当前步骤名称旁边显示总阻塞验证和错误的计数。

标签样式

multi-step 输入提供了两种可用的标签样式。

tab：默认的标签体验。每个步骤名称都显示在一个具有活动状态的标签中。错误计数显示在标签的右上角。
progress：一个进度条样式，其中每个步骤是总步骤时间线上的一个“节点”。使用这种显示模式，你还可以使用 hide-progress-labels 属性来隐藏步骤名称。

加载实时示例

步骤标签

默认情况下，multi-step 输入将使用其子 step 输入的 name 属性来生成步骤的标签。如果你想对步骤名称的显示有更多控制，你可以使用 label 属性。你还可以自定义在 step 的 stepActions 部分出现的标签，使用 previous-label 和 next-label 属性。

label：一个覆盖多步骤标签中应该出现的步骤名称的属性。
previous-label：一个覆盖 stepPrevious 按钮标签的属性，默认为 Back。
next-label：一个覆盖 stepNext 按钮标签的属性，默认为 Next。

加载实时示例

允许不完整步骤

默认情况下，即使当前步骤或当前步骤与目标步骤之间的步骤有阻塞验证消息，multi-step 输入也会允许前进到后面的步骤。要防止用户跳过步骤，请将 allow-incomplete 属性设置为 false。

加载实时示例

有效步骤图标

当一个步骤完成且没有验证错误时，默认情况下 multi-step 输入将渲染一个勾选图标，表明该步骤有效且不需要更多操作。valid-step-icon 是一个 FormKit Icon，可以通过属性更改，就像任何其他 FormKit 图标一样。

你可以：

更改 multi-step 输入上的 valid-step-icon，以更改输入内所有步骤的图标。
更改 step 输入上的 valid-step-icon，以仅更改或覆盖该步骤的图标。

加载实时示例

自定义步骤操作

每个multi-step输入中的step都有默认按钮用于在步骤之间移动。默认情况下，multi-step中的第一个step只会渲染一个stepNext操作按钮，最后一个step只会有一个stepPrevious操作按钮。这允许多步骤输入作为更大表单上下文中的一个自包含组。

如果你想在multi-step中添加一个自定义操作，比如表单提交 — 如果你使用multi-step作为你的整个表单，这会很有用 — 你可以通过覆盖所需步骤上的stepNext插槽来实现。在这种情况下，我们将在multi-step输入的最后一步中添加一个submit输入来提交表单。

stepNext和stepPrevious部分可以访问incrementStep处理器 — 它返回一个可调用的函数 — 以启用程序化导航。

标签导航

默认情况下，多步骤输入中的stepNext使用事件监听器捕获通过键盘的标签导航，并允许用户在多步骤中循环通过所有可用步骤。

如果你想在自己的自定义stepNext实现中保留这种行为，那么请确保在触发步骤导航的可聚焦元素上添加一个data-next="true"属性。

加载实时示例

beforeStepChange 事件

有时你需要在步骤之间对表单数据进行_操作_。也许你想将每个步骤独立提交到后端，或者你需要记录分析事件以确定用户通过表单的程度。在这些情况下，你可以使用beforeStepChange事件。beforeStepChange接受一个函数，并提供一个带有以下键的上下文对象：

currentStep：用户正在离开的当前活动步骤节点上下文对象。
targetStep：用户正在导航到的步骤节点上下文对象。
delta：步骤之间的距离。正整数表示向前步进，负整数表示向后步进。

你的beforeStepChange函数应该返回一个Boolean。返回false将_阻止_步骤更改发生。

beforeStepChange可以在你的multi-step输入中使用，在这种情况下它将适用于_所有_步骤。此外，你可以在特定的step输入上使用beforeStepChange，只有在从分配了该函数的步骤导航时才运行你的函数。应用于step的beforeStepChange将覆盖任何存在的父multi-step上设置的beforeStepChange。

加载实时示例

程序化导航

多步骤节点配备了便捷的辅助函数，旨在促进程序化地在其任何步骤之间导航。这些函数包括：

next：它将从当前选定的步骤转到下一个step。
previous：它将从当前选定的步骤转到上一个step。
goTo：它接受一个step参数，从当前选定的步骤移动到该步骤，它接受步骤的索引或名称。

加载实时示例

属性 & 特性（multi-step）

Prop	Type	默认	描述
allowIncomplete	boolean	true	当`true`时，允许用户即使当前步骤无效也可以在步骤之间导航。
tabStyle	string	tab	用于设置数据属性以创建标签样式。默认主题支持`tab`和`progress`标签样式。
hideProgressLabels	boolean	false	当为真时，隐藏`progress`标签样式的标签。
validStepIcon	string	check	指定当步骤有效时在`badge`部分放置的图标。当应用于`multi-step`时，图标将应用于所有子`step`输入。
beforeStepChange	function	undefined	在活动步骤更改之前运行的函数。该函数提供了一个包含`currentStep`和`targetStep`的上下文对象，这两个都是FormKit `node`上下文对象。另外，提供了一个整数`delta`，反映了`currentStep`和`targetStep`之间的距离。当提供给`multi-step`时，此函数将在每次`step`更改时触发。
显示通用 props
config	Object	{}	提供给 input 的节点和此输入的任何后代节点的配置选项。
delay	Number	20	在调度 `commit` hook 前，输入值的去抖动毫秒数。
dirtyBehavior	string	touched	确定此输入的“dirty”标志设置方式。可以设置为 `touched` 或 `compare` — 默认为 `touched`，性能更好，但无法检测表单是否再次匹配其初始状态。
errors	Array	[]	要在此字段上显示的错误消息的字符串数组。
help	String	''	帮助文本与输入关联的文本。
id	String	input_{n}	输入的唯一标识符。提供一个 id 还可以全局访问输入的节点。
ignore	Boolean	false	防止将输入包含在任何父级（组、列表、表单等）中。在仅用于 UI 而不是实际值的情况下非常有用。
index	Number	undefined	如果父级是列表，允许在给定索引处插入输入。如果输入的值未定义，它将继承该索引位置的值。如果它有一个值，它将在给定索引处将其插入到列表的值中。
label	String	''	与输入关联的 `label` 元素的文本。
name	String	input_{n}	输入的名称，在数据对象中唯一标识。在一组字段中应该是唯一的。
parent	FormKitNode	contextual	默认情况下，父级是包装组、列表或表单，但此属性允许显式分配父级节点。
prefix-icon	String	''	指定放置在 `prefixIcon` 部分的图标。
preserve	boolean	false	在输入卸载时，在父组、列表或表单上保留输入的值。
preserve-errors	boolean	false	默认情况下，使用 `setErrors` 在输入上设置的错误会在输入时自动清除，将此属性设置为 true 可以保留错误，直到明确清除为止。
sections-schema	Object	{}	一个包含部分键和模式部分值的对象，其中每个模式部分应用于相应的部分。
suffix-icon	String	''	指定放置在 `suffixIcon` 部分的图标。
type	String	text	要从库中渲染的输入类型。
validation	String, Array	[]	要应用于输入的验证规则。
validation-visibility	String	blur	确定何时显示输入的验证失败规则。有效值为 `blur`、`dirty` 和 `live`。
validation-label	String	{label prop}	确定在验证错误消息中使用的标签，默认情况下，如果可用，则使用 `label` 属性，否则使用 `name` 属性。
validation-rules	Object	{}	附加的自定义验证规则，可用于验证 prop。
value	Any	undefined	为输入和/或其子元素提供初始值。不是响应式的。可以种子整个组（表单）和列表。

属性 & 特性（step）

Prop	Type	默认	描述
label	string		用于更改步骤的标签。如果没有提供自定义标签，则将使用步骤的`name`。
previousLabel	string	Previous	用于更改默认`previousAction`按钮的标签。
nextLabel	string	Next	用于更改默认`nextAction`按钮的标签。
previousAttrs	object	[object Object]	用于将属性应用于默认`previousAction`按钮输入。
nextAttrs	object	[object Object]	用于将属性应用于默认`nextAction`按钮输入。
validStepIcon	string	check	指定当步骤有效时在`badge`部分放置的图标。当应用于一个`step`时，图标将只应用于目标`step`。
beforeStepChange	function	undefined	在活动步骤更改之前运行的函数。该函数提供了一个包含`currentStep`和`targetStep`的上下文对象，这两个都是FormKit `node`上下文对象。另外，提供了一个整数`delta`，反映了`currentStep`和`targetStep`之间的距离。当提供给一个`step`时，此函数将只在从指定`step`导航时触发。
显示通用 props
config	Object	{}	提供给 input 的节点和此输入的任何后代节点的配置选项。
delay	Number	20	在调度 `commit` hook 前，输入值的去抖动毫秒数。
dirtyBehavior	string	touched	确定此输入的“dirty”标志设置方式。可以设置为 `touched` 或 `compare` — 默认为 `touched`，性能更好，但无法检测表单是否再次匹配其初始状态。
errors	Array	[]	要在此字段上显示的错误消息的字符串数组。
help	String	''	帮助文本与输入关联的文本。
id	String	input_{n}	输入的唯一标识符。提供一个 id 还可以全局访问输入的节点。
ignore	Boolean	false	防止将输入包含在任何父级（组、列表、表单等）中。在仅用于 UI 而不是实际值的情况下非常有用。
index	Number	undefined	如果父级是列表，允许在给定索引处插入输入。如果输入的值未定义，它将继承该索引位置的值。如果它有一个值，它将在给定索引处将其插入到列表的值中。
label	String	''	与输入关联的 `label` 元素的文本。
name	String	input_{n}	输入的名称，在数据对象中唯一标识。在一组字段中应该是唯一的。
parent	FormKitNode	contextual	默认情况下，父级是包装组、列表或表单，但此属性允许显式分配父级节点。
prefix-icon	String	''	指定放置在 `prefixIcon` 部分的图标。
preserve	boolean	false	在输入卸载时，在父组、列表或表单上保留输入的值。
preserve-errors	boolean	false	默认情况下，使用 `setErrors` 在输入上设置的错误会在输入时自动清除，将此属性设置为 true 可以保留错误，直到明确清除为止。
sections-schema	Object	{}	一个包含部分键和模式部分值的对象，其中每个模式部分应用于相应的部分。
suffix-icon	String	''	指定放置在 `suffixIcon` 部分的图标。
type	String	text	要从库中渲染的输入类型。
validation	String, Array	[]	要应用于输入的验证规则。
validation-visibility	String	blur	确定何时显示输入的验证失败规则。有效值为 `blur`、`dirty` 和 `live`。
validation-label	String	{label prop}	确定在验证错误消息中使用的标签，默认情况下，如果可用，则使用 `label` 属性，否则使用 `name` 属性。
validation-rules	Object	{}	附加的自定义验证规则，可用于验证 prop。
value	Any	undefined	为输入和/或其子元素提供初始值。不是响应式的。可以种子整个组（表单）和列表。

章节

步骤名称

⚠️

... 步骤内容 ...

下一步

Section-key	描述
tabs	围绕所有标签页的包装器。
tab	一个包含标签页名称和反映验证状态的装饰器的按钮元素。
tabLabel	一个包含标签页名称的 span 元素。
badge	用作装饰器的 span 元素，用于显示当前标签页的有效性状态。
steps	围绕所有步骤的包装器。
step	围绕默认插槽内容和步骤的操作按钮的包装器。每个步骤都自动应用了可见性样式，这取决于它是否是当前活动步骤。
stepInner	围绕步骤的默认插槽内容的包装器。
stepActions	围绕移动步骤的操作按钮的包装器。
stepPrevious	围绕导航至上一步的操作按钮的包装器。
stepNext	围绕导航至下一步的操作按钮的包装器。
显示通用 section keys
outer	最外层的包装元素。
wrapper	标签和输入周围的包装器。
label	输入的标签。
prefix	默认情况下没有输出，但允许直接在输入元素之前放置内容。
prefixIcon	输出在前缀部分之前放置一个图标的元素。
inner	实际输入元素周围的包装器。
suffix	默认情况下没有输出，但允许直接在输入元素之后放置内容。
suffixIcon	输出在后缀部分之后放置一个图标的元素。
input	输入元素本身。
help	包含帮助文本的元素。
messages	包装所有消息的容器。
message	包含消息的元素（或多个元素） - 最常见的是验证和错误消息。

文档

入门指南

基本要素

输入框

插件

指南

API 参考文档

工具

关于

赞助商

入门指南

基本要素

输入框

插件

指南

多步骤输入插件

介绍

多步骤组件概览

安装

`multi-step` 输入类型的快速演示：

使用

标签样式

步骤标签

允许不完整步骤

有效步骤图标

自定义步骤操作

beforeStepChange 事件

程序化导航

属性 & 特性（multi-step）

属性 & 特性（step）

章节

文档

工具

关于

文档

入门指南

基本要素

输入框

插件

指南

API 参考文档

工具

关于

赞助商

入门指南

基本要素

输入框

插件

指南

多步骤输入插件

多步骤组件概览

文档

工具

关于

注册获取最新消息