Form

• 提供的提交按钮
• 完整示例表单
• 填充
• 提交
  • 通过XHR/Fetch请求提交
  • 作为页面请求提交
  • 以编程方式提交表单
• 验证
  • 验证不完整消息
  • 提交无效事件
  • 有效状态
• 禁用
• 重置
  • 初始值
• 错误处理
  • 表单错误
  • 清除错误
  • 输入错误
• 移动验证和错误消息
  • 自动移动消息
  • 通过 node 手动移动消息
  • FormKitMessages 属性
• 卸载输入框
• 属性
• 部分

虽然您可以自由地单独使用FormKit输入，但通常您会希望将它们分组到一个表单中。要做到这一点，只需将输入包装在<FormKit type="form">中即可。

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

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

提供的提交按钮

为了方便起见，form会自动输出一个提交按钮，并且提供的主题还包括一个加载旋转器。您可以使用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请求提交

在现代SPA中，表单提交的最常见方法是XHR请求（例如axios或fetch）。FormKit非常适合这个任务：

• 它将收集到的表单数据作为单个请求准备好的对象（不需要v-model）和form输入的核心节点作为便利，传递给您的@submit处理程序。
• 如果您使用异步提交处理程序，它将禁用表单的输入并将加载状态应用于表单（loading在context.state.loading处为true，并在genesis主题上显示一个旋转器）。
• 它通过将错误消息直接放在失败的输入上来处理后端错误。

作为页面请求提交

要通过页面请求提交表单，只需省略@submit处理程序。就像原生HTML一样，您还可以提供一个action和可选的method属性。

以编程方式提交表单

使用任何标准的HTML方法提交表单（如点击“提交”按钮或在文本输入框上按下“Enter”键）是有效的，但您也可以以编程方式提交表单。有两种方法可以做到这一点：

• 使用 this.$formkit.submit('form-id')（组合API中的 submitForm('form-id')）。
• 使用 core node 对象。

使用 $formkit.submit() 提交

使用 node.submit() 提交

您还可以通过在表单（或表单内的任何输入）的核心节点上调用 node.submit() 来以编程方式提交表单。要做到这一点，您需要检索核心节点的实例。

验证

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

验证不完整消息

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

提交无效事件

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

例如，我们可以使用此事件来向用户警告验证规则失败。

有效状态

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

禁用

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

重置

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

初始值

重要的是要注意，表单的“初始状态”不一定是空表单。您可以在表单上和表单中的各个输入上设置默认的 :value 或 v-model — FormKit 会自动将它们合并在一起以生成您的初始值，并在重置时恢复到此合并状态。

如果您希望使用替代的重置状态，还可以为 reset(formId, initialState) 提供第二个参数。

错误处理

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

• 表单错误。这些错误显示在表单底部的提交按钮上方。例如，全局消息如“抱歉，我们的服务器暂时无法工作”。
• 输入错误。要放置在表单中特定输入上的错误，通常是来自后端的验证错误，如“抱歉，此用户名已被使用”。

表单错误

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

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

使用 errors 属性

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

使用 node.setErrors()

使用 node.setErrors 设置表单的错误非常方便，因为您的提交处理程序会将表单的 node 对象作为第二个参数传递。node.setErrors() 接受两个参数 - 一个用于表单错误的数组，一个用于输入错误的键值对象：

使用 $formkit.setErrors()

或者，您可以通过为表单指定一个 id 并调用 $formkit.setErrors('id', ['Form error here']) 来直接设置错误。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 属性方便地为表单中的所有输入（或组或列表）设置错误消息。该属性接受一个错误对象，其中键是输入名称（支持相对节点地址），值是要应用于该输入的错误或错误数组。

移动验证和错误消息

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

import { FormKitMessages } from '@formkit/vue'

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

• 自动
• 通过 node 手动

自动移动消息

在您的表单中的任何位置放置 <FormKitMessages /> 组件，并且表单的消息将自动移动到该位置：

通过 node 手动移动消息

要在 DOM 中的任何位置移动消息 - 甚至是表单之外 - 您可以将表单的核心节点作为属性传递给 <FormKitMessages />。在此示例中，我们使用消息创建了一个类似弹出式的提示框：

FormKitMessages 属性

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

卸载输入框

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

属性

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

部分