Introducing KickStart — AI generated FormKit forms in seconds. Generate from a screenshot, edit with drag-and-drop or conversational AI, copy & paste as components or schema!
Try for free
让我们开始创建我们的第一个FormKit表单!我们将学习FormKit的一些关键特性以及它们如何对你有益。我们也会在过程中学到一些好的提示 —— 比如如何在不使用v-model
的情况下管理表单状态。
这个指南假设你已经熟悉Vue组合API。
FormKit的主要特性之一是它的单一组件API —— <FormKit />
组件。这一个组件让你可以访问到_所有_的输入类型。虽然有些类型可能会扩展并添加特性,但它们共享相同的基础功能。你可以在这里了解更多关于输入的信息。
即使没有任何props,裸露的<FormKit />
组件已经给我们的输入提供了一个很好的起点,包括可访问的标记,基础的text
输入类型,以及将在后面部分解释的额外特性。
默认情况下,如果没有指定type
,<FormKit />
组件将使用type="text"
。type
是我们指定我们想要什么输入的方式。就像原生输入,我们有像text
,select
,checkbox
等输入。然而,我们并不仅限于只有"原生"输入,FormKit Pro添加了非原生控件,如repeater
,taglist
,和autocomplete
类型,它们可以处理更复杂的交互。
如果你看一下前面例子生成的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">
中:
form
类型将使用每个输入的 name
作为数据对象,主动收集所有子输入的值(就像 group
一样)。
我们将探索的表单的第一个特性是我们有一个 @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
使用其 id
作为标识符获取输入的核心节点。每个输入都有一个关联的核心节点。events
监听对某个输入的更改。input
函数让我们更新它的值。结合这些功能,我们可以获取输入的核心 节点
,监听和响应 事件
,并使用 input
函数更新另一个字段的值:
现在的代码变得有点难以阅读,所以让我们将逻辑提取到另一个文件中,创建一个插件。注意,我们只在 class
输入上放置新的 updateAttributesPlugin
,所以它不会影响任何其他输入。我们还将学习另一个有用的功能,称为 遍历,通过使用节点的 at
函数:
at
函数使用 name
属性,而不是 getNode
使用的 id
。
假设不同的角色在不同的属性上更优秀,但没有一个应该太强大。我们可以通过创建一个点数预算,并向属性 group
添加组验证,以确保它们总共不超过20点。我们将学习一个新功能 —— 自定义规则 —— 来实现这一点:
默认情况下,group
类型不输出任何标记,所以要显示验证错误,我们需要手动添加它。
有时表单需要根据另一个输入的值显示或隐藏字段。我们可以通过学习2个新概念来实现这一点:
FormKit
组件都在 #default
插槽属性中接收到他们的上下文对象。group
的值 - group(和 form
)输入的值是一个对象,该对象的值是其子项的值,由子项的 name
键控制。在使用条件渲染时,请注意,Vue需要提示才能知道DOM元素需要重新渲染,而不是试图重用它。我们可以为元素添加一个唯一的key
属性来帮助Vue。
所以,让我们获取 group
输入的上下文对象并提取 value
:#default="{ value }"
。如果用户决定将所有属性都改为1,我们想为他们添加一个小彩蛋:
这就结束了我们对FormKit的介绍!你现在已经准备好开始使用它了!
有一些主题我们建议你接下来探索,你可以按任何顺序阅读,甚至在自己试用FormKit之后再阅读: