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的情况下管理表单状态。

组合API

这个指南假设你已经熟悉Vue组合API

健壮的Vue.js表单 - Vue学校课程

1小时49分钟

我们的第一个输入

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

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

基本props

类型

默认情况下,如果没有指定type<FormKit />组件将使用type="text"type是我们指定我们想要什么输入的方式。就像原生输入,我们有像textselectcheckbox等输入。然而,我们并不仅限于只有"原生"输入,FormKit Pro添加了非原生控件,如repeatertaglist,和autocomplete类型,它们可以处理更复杂的交互。

加载实时示例

名称和id

如果你看一下前面例子生成的HTML,你会看到FormKit已经创建了可访问的标记。然而,由于我们没有指定nameid属性,它们为我们自动生成了:name: "text_1" id="input_0"。即使如此,作为最佳实践,我们应该至少指定name,因为它使得在表单内部使用输入更容易。nameformgroup类型用来从其子元素中收集值,并根据name向其子元素传递值:

加载实时示例

为了无障碍访问的属性

我们的输入仍然缺少一些关键的无障碍功能,如 labelhelp,甚至可能是 placeholder。FormKit接受所有这些作为props,并输出正确的 aria 属性。屏幕阅读器现在会宣布输入名称,帮助文本,以及输入已准备好进行编辑:

加载实时示例

设置初始值

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

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

加载实时示例

添加验证

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

加载实时示例

注意,上面的 minmax 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 处理表单和输入。然而,让我们添加一些用户体验的增强功能,并使用它来让我们接触到你可以使用的额外的概念和特性,以将你的表单提升到一个新的水平。

基于另一个输入更新值

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

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

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

加载实时示例

将其制作成插件

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

at() 使用 name

at 函数使用 name 属性,而不是 getNode 使用的 id

加载实时示例

添加组验证

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

默认情况下,组不显示消息

默认情况下,group 类型不输出任何标记,所以要显示验证错误,我们需要手动添加它。

加载实时示例

条件渲染

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

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

在使用条件渲染时,请注意,Vue需要提示才能知道DOM元素需要重新渲染,而不是试图重用它。我们可以为元素添加一个唯一的key属性来帮助Vue。

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

加载实时示例

下一步

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

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

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