你的第一个表单

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

简介

让我们开始创建我们的第一个FormKit表单！我们将学习FormKit的一些关键特性以及它们如何对你有益。我们也会在过程中学到一些好的提示 —— 比如如何在不使用v-model的情况下管理表单状态。

我们的第一个输入

FormKit的主要特性之一是它的单一组件API —— <FormKit />组件。这一个组件让你可以访问到_所有_的输入类型。虽然有些类型可能会扩展并添加特性，但它们共享相同的基础功能。你可以在这里了解更多关于输入的信息。

即使没有任何props，裸露的<FormKit />组件已经给我们的输入提供了一个很好的起点，包括可访问的标记，基础的text输入类型，以及将在后面部分解释的额外特性。

基本props

类型

默认情况下，如果没有指定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接受所有这些作为props，并输出正确的 aria 属性。屏幕阅读器现在会宣布输入名称，帮助文本，以及输入已准备好进行编辑：

设置初始值

有时你想给输入添加一个初始值，比如提供一个合理的起始点，或者从数据库填充预保存的数据。我们用 value prop来做这个。

让我们开始构建一个我们可以为这个指南添加的例子。假设我们正在为一个游戏构建一个"角色创建表单"。让我们给我们的角色分配一个力量等级。当用户首次打开表单时，我们可以使用 range 输入，预定义值为 5：

添加验证

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

注意，上面的 min 和 max props是浏览器内置的范围输入props，代表范围滑块的顶部和底部。

添加插件

假设我们的"后端"要求像 strength 这样的数据被转换为数字。默认情况下，FormKit遵循HTML "native" 输入行为，将所有值作为 "strings"。为了解决这个问题，我们可以使用FormKit的最酷的功能之一——插件——可以被认为是输入的中间件。有了插件，我们可以改变我们的输入值的返回方式：

创建表单

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

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

添加提交处理器

我们将探索的表单的第一个特性是我们有一个 @submit 事件，当我们需要提交表单时，它可以使我们的生活更轻松。@submit 事件给我们的第一个参数是表单从输入中收集的所有后代字段。无需使用大量的 v-model 来收集表单数据。让我们添加我们的 createCharacter() 提交处理器：

更改提交按钮

作为使用 type="form" 的便利，form 会自动输出一个提交按钮。对于我们的情况，"提交"文本并不能正确显示表单的意图。为了解决这个问题，我们可以使用 submit-label 属性，这是一个 form 特定的功能，只需添加 submit-label="Create Character" 来显示表单的意图：

<FormKit type="form" @submit="createCharacter" submit-label="创建角色">
  <!-- 我们创建表单的其余部分 -->
</FormKit>

分组相关输入

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

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

深入了解

就是这样！我们可以在这里停下来，介绍一下如何使用 FormKit 处理表单和输入。然而，让我们添加一些用户体验的增强功能，并使用它来让我们接触到你可以使用的额外的概念和特性，以将你的表单提升到一个新的水平。

基于另一个输入更新值

我们可以做的一件事是改变角色的默认 属性，基于所选的角色 类别。为此，我们将使用一些新功能：

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

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

将其制作成插件

现在的代码变得有点难以阅读，所以让我们将逻辑提取到另一个文件中，创建一个插件。注意，我们只在 class 输入上放置新的 updateAttributesPlugin，所以它不会影响任何其他输入。我们还将学习另一个有用的功能，称为 遍历，通过使用节点的 at 函数：

添加组验证

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

条件渲染

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

• 上下文对象 —— 我们可以在表单内部访问输入的值（以及其他数据），因为所有的 FormKit 组件都在 #default 插槽属性中接收到他们的上下文对象。
• group的值 - group（和 form）输入的值是一个对象，该对象的值是其子项的值，由子项的 name 键控制。

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

下一步

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

有一些主题我们建议你接下来探索，你可以按任何顺序阅读，甚至在自己试用FormKit之后再阅读：

• 样式化你的表单： 学习如何使用 sections 为FormKit添加类，或者甚至使用我们的 指南 帮助使用Tailwind CSS。
• 多语言表单： 学习FormKit如何通过数十种可用语言使 i18n 变得简单。或者你可以添加自己的语言！
• 探索FormKit的模式： 学习关于FormKit的 JSON兼容模式 ，以及你如何可以使用它进行表单生成，将表单以JSON格式保存到数据库，或者构建自己的表单构建器。