Form

• 提供的提交按钮
• 完整示例表单
• 填充
• 提交
  • 通过 XHR/Fetch 请求提交
  • 作为页面请求提交
  • 以编程方式提交表单
• 禁用
• 重置
  • 初始值
• 验证
  • 验证未完成消息
  • 提交无效事件
  • 有效性状态
• 错误处理
  • 表单错误
  • 清除错误
  • 输入错误
• 验证和错误摘要
• 移动验证和错误信息
  • 自动移动信息
  • 通过 node 移动信息
  • FormKitMessages 属性
• 卸载输入项
• 可组合函数
  • useFormKitContext
  • useFormKitContextById
  • useFormKitNodeById
• 属性 & 特性
• 章节
• 可访问性

虽然你可以单独使用 FormKit 输入，但你通常会想要将它们组合成一个表单。要做到这一点，只需将你的输入包裹在一个 <FormKit type="form"> 中。

form 类型会主动收集所有子输入的值，使用每个输入的 name 作为结果数据对象中的属性名（就像 groups 一样）。你也可以使用 v-model 来读取和写入表单值，就像在任何输入上一样。

一个 <FormKit type="form"> 跟踪表单的验证状态，并防止用户在任何输入无效时提交表单。

提供的提交按钮

为了方便，form 自动输出一个提交 button，并且提供的主题也包括一个加载旋转器。你可以使用 submit-label 和 submit-attrs 属性来更改这个按钮，或者使用 :actions="false" 来禁用。你可以传递任何 FormKit 属性给 submit-attrs。在下面的示例中，我们传递了类、data 属性、帮助文本，甚至 告诉包含的提交按钮不被忽略：

<FormKit
  type="form"
  submit-label="更新"
  :submit-attrs="{
    inputClass: 'my-input-class',
    wrapperClass: 'my-wrapper-class',
    'data-theme': `dark`,
    help: '我的按钮帮助文本',
    ignore: false
  }"
></FormKit>

完整示例表单

除了后端功能，这里是一个具有输入（form、text、email、password）、帮助文本、标签、自定义消息的验证以及错误和提交处理的完整功能表单：

填充

你可以通过向 <FormKit type="form"> 提供一个 value 属性来填充整个表单。value 属性应该是输入名称到输入值对的对象。如果你需要双向数据绑定，你也可以使用 v-model 来填充表单：

提交

表单通常通过用户操作来提交，例如点击提交按钮或在表单内的文本节点上按下 enter 键。提交时，表单会按顺序：

1. 确保所有输入都已完成（去抖动结束）。
2. 触发 @submit-raw 事件。
3. 将所有输入的 submitted 状态设置为 true — 显示任何剩余的验证错误（不管 validation-visibility 的设置）。
4. 如果表单有验证错误，则触发 @submit-invalid 事件。
5. 如果所有输入都有效，则触发 @submit 事件。
6. 如果 @submit 处理器返回一个 Promise，则将表单的状态设置为 loading，直到它解决。

通过 XHR/Fetch 请求提交

在现代单页应用程序中，表单提交的最常见方法是 XHR 请求（想想 axios 或 fetch）。FormKit 非常适合这项任务：

• 它将收集的表单数据作为一个请求就绪的对象（无需 v-model），以及 form 输入的核心节点，作为方便之用，交给您的 @submit 处理器。
• 如果您使用异步提交处理器，它将禁用表单的输入并将加载状态应用到您的表单（context.state.loading 的 loading 变为 true，并且在 genesis 主题上显示旋转器）。
• 它通过将错误消息直接放置在失败的输入上来处理后端错误。

作为页面请求提交

要通过页面请求提交表单，只需省略 @submit 处理器即可。就像原生 HTML 一样，您也可以提供一个 action，并且可以选择性地提供一个 method 属性。

以编程方式提交表单

虽然使用任何标准 HTML 方法提交表单都是有效的（例如点击 submit 按钮，或在文本输入上按 enter）— 您也可以以编程方式提交表单。有两种方法可以做到这一点：

• 使用 this.$formkit.submit('form-id')（对于组合 API 是 submitForm('form-id')）。
• 使用核心节点对象。

使用 $formkit.submit() 提交

使用 node.submit() 提交

你也可以通过在表单的（或表单内任何输入项的）核心节点上调用 node.submit() 来以编程方式提交表单。为此，你需要获取核心节点的实例。

禁用

要禁用给定表单中的所有输入项，包括提交按钮，你可以使用 disabled 属性。

重置

你可以通过调用 $formkit.reset(formId) 将你的表单（或任何输入项）重置回其初始状态。

初始值

需要注意的是，表单的“初始状态”并不一定是空表单。如果你在表单或表单中的个别输入项上有默认的 :value 或 v-model，FormKit 会自动将它们合并以产生你的初始值，并在重置时恢复到这个合并状态。

如果你更愿意有一个不同的重置状态，你可以选择性地提供第二个参数给 reset(formId, initialState)。

验证

表单在表单中的所有输入项都通过其验证规则之前不会提交。

验证未完成消息

除了不触发提交事件外，还会在提交按钮上方显示一条消息，指示表单仍然不完整。你可以使用 incomplete-message 属性自定义此消息，或通过将属性设置为 false 来禁用它。

提交无效事件

当用户尝试提交包含验证失败的输入的表单时，将触发 @submit-invalid 事件。

例如，我们可以使用这个事件来提醒用户验证规则失败。

有效性状态

表单中所有输入的有效性都会在上下文对象中自动跟踪。这在创建各种界面时非常有用。例如，如果你希望提交按钮在所有输入都有效之前禁用，你可以使用 state.valid 属性来实现。

错误处理

使用 FormKit，为你的表单添加前端验证很容易 — 但是后端框架产生的错误或你想手动分配的错误呢？你可以为表单分配两种类型的错误：

• 表单错误。这些显示在表单底部的提交按钮上方。一个例子可能是像“对不起，我们的服务器现在无法工作”这样的全局消息。
• 输入错误。要放置在表单内特定输入上的错误，通常是来自后端的验证错误，比如“对不起，这个用户名已经被占用”。

表单错误

表单错误（适用于整个表单的错误）可以通过三种方式设置。

• 在 <FormKit type="form"> 上使用 errors 属性。
• 使用核心节点 node.setErrors()。
• 使用 $formkit.setErrors() Vue 插件方法。

使用 errors 属性

像任何 FormKit 输入一样，你可以直接使用 errors 属性分配错误。这些错误始终可见（不受 validation-visibility 影响）。

使用 node.setErrors()

使用 node.setErrors 设置表单的错误很方便，因为你的提交处理程序会将表单的 node 对象作为其第二个参数传递。node.setErrors() 接受 2 个参数 — 一个用于表单错误的数组，和一个用于输入错误的键控对象：

使用 $formkit.setErrors()

另外，你可以通过给表单一个 id，然后调用 $formkit.setErrors('id', ['表单错误信息']) 来直接在表单上设置错误。setErrors 方法必须传递表单的 id，然后可以处理 1 或 2 个额外的参数 — 表单错误和输入错误：

清除错误

默认情况下，使用 setErrors() 设置在输入上的错误会在用户更改该输入的值时自动清除。你可以通过设置 preserve-errors 属性来更改这个默认行为。

要清除表单上的所有错误（不管 preserve-errors 属性如何），调用 node.clearErrors()。

如果你更愿意默认保留错误，你可以通过修改 preserveErrors 配置选项来更改默认行为。这可以全局完成，或者针对单个表单完成：

输入错误

输入错误（要与表单中特定输入一起显示的错误）可以通过三种方式应用：

• 在每个单独的输入上手动使用 errors 属性。
• 在表单上使用 input-errors 属性（也适用于组和列表）。
• 使用 $formkit.setErrors() Vue 插件方法（参见上面的示例）。

手动使用 errors 属性

在表单上显示错误的最基本方式是使用每个 FormKit 输入上可用的 errors 属性。

使用 input-errors 属性

你还可以方便地使用 input-errors 属性为你的表单中的所有输入（或组或列表）设置错误消息。该属性接受一个错误对象，其中键是输入名称（支持相对节点地址），值是要应用于该输入的错误或错误数组。

验证和错误摘要

为了提高可访问性，在表单顶部提供验证和错误信息的摘要是有帮助的。FormKit 提供了一个 <FormKitSummary /> 组件来为你渲染这个摘要。

这个组件会自动渲染表单所有的验证和错误信息，并带有跳转链接到它们所适用的输入框。这些错误只有在提交表单后才会显示，但它们被包裹在一个 aria-live 区域内以确保屏幕阅读器在错误出现时会被通知。此外，页面会自动滚动到摘要框并聚焦在第一个列出的错误上。

<FormKitSummary /> 不是一个全局注册的组件 — 你必须导入它：

import { FormKitSummary } from '@formkit/vue'

移动验证和错误信息

默认情况下，表单的验证和错误信息被放置在表单操作部分的正上方。然而，你可以选择通过使用 <FormKitMessages /> 组件在页面的任何位置渲染这些信息。<FormKitMessages /> 不是一个全局注册的组件 — 你必须导入它：

import { FormKitMessages } from '@formkit/vue'

有两种使用 <FormKitMessages /> 的方法：

• 自动地
• 通过 node 手动

自动移动信息

在你的表单_内部_的任何位置放置一个 <FormKitMessages /> 组件，表单的信息将自动移动到那个位置：

通过 node 移动信息

要将信息移动到 DOM 的任何位置 — 即使是_表单之外_ — 你可以将表单的核心节点作为属性传递给 <FormKitMessages />。在这个例子中，我们使用信息来创建一个吐司风格的弹出窗口：

FormKitMessages 属性

<FormKitMessages /> 组件有一些额外的配置选项：

卸载输入项

当输入项从表单中卸载时 — 例如使用 v-if — 其键和值会从表单的数据中移除。然而，在某些情况下，即使输入项被移除后，保留键/值对可能更为合适。这可以通过使用 preserve 属性来实现：

可组合函数

FormKit 提供了一些可组合函数来帮助你访问表单的数据和上下文。这些可从 @formkit/vue 包中导入：

useFormKitContext

useFormKitContext 是一个可组合函数，它返回表单的上下文对象作为 vue Ref，每当它变得可用时。这必须在 <FormKit> 组件的子组件中使用（如表单）。第一个参数是一个可选的遍历路径，它允许你导航到表单树中的任何节点。第二个参数是一个可选的效果回调，每当上下文变得可用时将被调用。

useFormKitContextById

类似于 useFormKitContext，这个可组合函数会找到任何被赋予显式 id 的 <FormKit> 上下文对象。你可以选择性地提供一个效果回调，每当节点变得可用时将被调用。

useFormKitNodeById

获取任何被赋予显式 id 的 FormKit 节点。它返回一个 Ref，每当它被挂载时将填充核心节点。你可以选择性地提供一个效果回调，每当节点变得可用时将被调用。

属性 & 特性

表单在技术上被视为 input 类型 — 因此它们共享许多标准输入使用的通用属性。

章节

可访问性

所有 FormKit 输入都是考虑到以下可访问性因素而设计的。通过在此处提交可访问性问题，帮助我们不断提高所有人的可访问性：