您的第一个表单

• 介绍
• 我们的第一个输入框
  • 基本属性
  • 设置初始值
  • 添加验证
  • 添加插件
• 创建表单
  • 添加提交处理程序
  • 更改提交按钮
  • 分组相关输入
• 深入了解
• 根据另一个输入更新值
  • 将其制作成插件
• 添加分组验证
• 条件渲染
• 下一步

介绍

让我们从创建我们的第一个FormKit表单开始！我们将学习一些FormKit的关键功能以及它们对您的好处。我们还将学习一些很好的技巧 - 例如如何在不使用v-model的情况下管理表单状态。

我们的第一个输入框

FormKit 的主要特点之一是其单一组件 API - <FormKit /> 组件。这个组件为您提供了访问所有输入类型的能力。虽然某些类型可能会扩展并添加功能，但它们共享相同的基本功能。您可以在这里了解更多关于输入的信息。

即使没有任何属性，裸露的 <FormKit /> 组件已经为我们的输入框提供了一个很好的起点，具有可访问的标记、基本的 text 输入类型以及稍后将在后面的部分中解释的其他功能。

基本属性

类型

如果未指定 type，<FormKit /> 组件将默认使用 type="text"。type 是我们指定所需输入的方式。就像原生输入框一样，我们有诸如 text、select、checkbox 等输入框。然而，我们不仅限于“原生”输入框，FormKit Pro 还添加了非原生控件，如 repeater、taglist 和 autocomplete 类型，可以处理更复杂的交互。

名称和 ID

如果查看前面示例生成的 HTML，您将看到 FormKit 已经创建了可访问的标记。但是，由于我们没有指定 name 和 id 属性，它们被自动生成为 name: "text_1" id="input_0"。尽管如此，作为最佳实践，我们应该至少指定 name，因为它使在表单内使用输入框更容易。name 被 form 和 group 类型用于收集值，并根据 name 将值传递给它们的子组件：

辅助功能属性

我们的输入框仍然缺少一些关键的辅助功能功能，例如 label、help，甚至可能是 placeholder。FormKit 接受所有这些作为属性，并输出正确的 aria 属性。屏幕阅读器现在将宣布输入框的名称、帮助文本以及输入框已准备好进行编辑：

设置初始值

有时您希望为输入框添加初始值，例如提供一个合理的起点，或者从数据库中填充预先保存的数据。我们可以使用 value 属性来实现这一点。

让我们开始构建一个示例，我们可以在本指南中添加内容。假设我们正在为一个游戏构建一个“角色创建表单”。让我们为我们的角色分配一个力量评级。当用户首次打开表单时，我们可以使用 range 输入框，并预定义一个值为 5：

添加验证

验证是 FormKit 的主要功能之一。它帮助用户知道他们提交的值是否正确。添加验证非常简单，已经为您实现了许多强大的内置验证规则。我们将使用 validation 属性来确保角色既不太强也不太弱。validation-visibility 属性允许我们控制何时向用户显示验证消息 - 是立即显示、在用户模糊输入框时显示，还是在表单提交时显示。实际的有效状态是实时计算的，并且始终是最新的 - 我们只需选择何时公开这些消息：

请注意，上面的 min 和 max 属性是范围输入框的内置浏览器属性，表示范围滑块的顶部和底部。

添加插件

假设我们的“后端”要求像 strength 这样的数据转换为数字。默认情况下，FormKit 遵循 HTML “原生”输入框的行为，将所有值都作为“字符串”处理。为了解决这个问题，我们可以使用 FormKit 最酷的功能之一 - 插件 - 它可以被视为输入框的中间件。使用插件，我们可以更改输入框的值的返回方式，插件只是函数：

创建表单

首先，让我们创建一个基本的表单并添加更多的输入，这样我们就有内容可以使用。我们将在每个部分中添加更多的功能，如验证、分组和根据其他输入更改值。

我们将使用一个名为 form 的输入，它将使字段的分组和验证变得更加容易。您只需要将所有的输入包装在 <FormKit type="form"> 中：

添加提交处理程序

我们将要探索的表单的第一个功能是，我们有一个 @submit 事件可以在提交表单时方便地使用。@submit 事件将所有从输入中收集到的后代字段作为第一个参数传递给我们。不需要使用多个 v-model 来收集表单数据。让我们添加我们的 createCharacter() 提交处理程序：

更改提交按钮

在使用 type="form" 时，form 会自动输出一个提交按钮。对于我们的情况，"Submit" 文本不能正确显示表单的意图。为了解决这个问题，我们可以使用 submit-label 属性，这是一个 form 特定的功能。我们只需要简单地添加 submit-label="创建角色" 来显示表单的意图：

<FormKit type="form" @submit="createCharacter" submit-label="创建角色">
  <!-- 其他创建表单的内容 -->
</FormKit>

分组相关输入

虽然表单现在可以工作，但我们可以看到一些相关的输入是分开的（即，表单数据是一个扁平的结构，其中所有的表单数据都是兄弟节点）。假设我们的后端需要将所有属性放在一个 attributes 属性中。我们可以使用 group 类型将相关的输入通过一个共同的 name 进行分组。

就像 form 类型一样，您可以将所有的字段包装在 <FormKit type="group" name: "attributes"> 中。不要忘记添加 name 属性：

深入了解

就是这样！我们可以在这里结束关于如何使用 FormKit 处理表单和输入的介绍。然而，让我们添加一些用户体验的增强功能，并利用这些功能来了解更多的概念和特性，以便将您的表单提升到更高的水平。

根据另一个输入更新值

我们可以做一些改进来改变角色的默认 attributes，根据所选的角色 class。为此，我们将使用一些新的功能：

• getNode：getNode 使用它们的 id 作为标识符获取输入的核心节点。每个输入都有一个关联的核心节点。
• events：events 监听对某个输入的更改。
• node.input()：节点上的 input 函数允许我们更新它的值。

通过结合这些功能，我们可以获取输入的核心 node，监听并响应 events，并使用 input 函数更新另一个字段的值：

将其制作成插件

现在的代码变得不太易读，所以让我们将逻辑提取到另一个文件中，并使用插件来代替。请注意，我们只将新的 updateAttributesPlugin 放在 class 输入上，这样它就不会影响任何其他输入。我们还将使用另一个有用的功能，称为 traversal，通过使用节点的 at 函数来学习它：

添加分组验证

假设不同的角色在不同的属性上更擅长，但没有一个属性应该太强大。我们可以通过创建一个点数预算，并将分组验证添加到属性 group 中，以确保它们的总计不超过 20 点。我们将学习一个新的功能 - 自定义规则 - 来实现这一点：

条件渲染

有时候表单需要根据另一个输入的值来显示或隐藏字段。我们可以通过学习两个新概念来实现这一点：

• 上下文对象 - 我们可以在表单中访问输入的值（以及其他数据），因为所有的 FormKit 组件都在 #default slot prop 中接收它们的上下文对象。
• group 的值 - group（以及 form）输入的值是一个对象，其子元素的值以子元素的 name 为键。

所以，让我们获取 group 输入的上下文对象并提取 value：#default="{ value }"。如果用户决定将所有属性都更改为 1，我们想为他们添加一个小彩蛋：

下一步

这就是我们对 FormKit 的介绍！现在你已经准备好开始使用它了！

以下是一些我们建议你继续探索的主题，你可以按任意顺序阅读，甚至在尝试了 FormKit 之后再阅读：

• 为你的表单添加样式： 学习如何使用 sections 为 FormKit 添加类，或者使用我们的 guide 来使用 Tailwind CSS。
• 多语言表单： 学习如何使用 FormKit 轻松实现 国际化，支持多种可用语言。或者你可以添加自己的语言！
• 探索 FormKit 的模式： 了解 FormKit 的 JSON 兼容模式 以及如何使用它进行表单生成、将表单以 JSON 格式保存到数据库或构建自己的表单构建器。