配置

介绍

FormKit 使用一种独特的层次化配置系统,非常适用于表单。为了理解这个配置是如何工作的,我们需要回答以下四个问题:

  1. 什么是核心节点?
  2. 什么是节点选项?
  3. 什么是节点属性?
  4. 什么是节点配置?

什么是核心节点?

每个 <FormKit> 组件都有自己的核心节点实例。这个节点负责几乎所有组件的功能。核心节点有三种类型:输入、列表和组(表单只是组的一种类型!)。

没有全局的 FormKit 实例来控制应用程序。相反,您可以将每个节点看作是自己的小应用程序 - 完全具备自己的配置。

关于节点的最后一件事 - 它们都可以有父节点。组和列表也可以有子节点。例如,登录表单可能有两个子节点 - 电子邮件和密码输入框。您可以将这种关系绘制为一个简单的树状图:

将鼠标悬停在每个节点上以查看其初始选项。

什么是节点选项?

在创建我们称之为核心节点的这些“小应用程序”时,可以传递一些选项。除非在极其高级的用例中,您不会创建自己的核心节点 - 这通常由 <FormKit> 组件为您完成。然而,定义一些全局的节点选项可能是有用的。这可以通过 @formkit/vue 插件来实现 - 💡 核心节点选项与 @formkit/vue 插件选项相同

例如,在典型的 FormKit Vue 注册中,我们使用 defaultConfig,它只是一个返回核心节点选项的函数:

import { createApp } from 'vue'
import App from 'App.vue'
import { plugin, defaultConfig } from '@formkit/vue'

// 👀 defaultConfig 只是一个返回核心节点选项的函数!
createApp(App).use(plugin, defaultConfig)

可用的节点选项

以下是在注册 FormKit 或单独创建节点时可以使用的所有可用选项的列表。传递给 @formkit/vue 插件的选项将应用于每个 <FormKit> 组件的核心节点在创建时。

createNode({
  /**
   * 用于重命名全局的 "FormKit" 组件。
   */
  alias: 'FormKit',
  /**
   * 这个数组通常由 FormKit 组件为您构建。
   */
  children: [],
  /**
   * 一个配置设置的对象。继续阅读以了解更多信息。
   */
  config: {},
  /**
   * 节点的名称 - 通常与输入的名称相对应。
   */
  name: 'inputName',
  /**
   * 父节点 - 通常由 FormKit 组件为您设置。
   */
  parent: null,
  /**
   * 一个插件函数的数组
   */
  plugins: [],
  /**
   * 默认的属性值,请继续阅读以了解更多信息。
   */
  props: {},
  /**
   * 用于重命名全局的 "FormKitSchema" 组件。
   */
  schemaAlias: 'FormKitSchema',
  /**
   * 所有值只有三个之一:'input'、'group' 或 'list'
   */
  type: 'input',
  /**
   * 节点的初始值。
   */
  value: 'foobar',
})

什么是 defaultConfig?

熟悉 FormKit 的开发人员会注意到上面的节点选项列表与可以传递给 defaultConfig 函数的值略有不同。

FormKit 的许多功能,如验证、输入和 Vue 支持,都是由官方插件提供的。defaultConfig 函数在将这些插件提供给 Vue 插件作为节点选项之前,配置了其中许多插件。因此,defaultConfig 可以接受上述任何节点选项,但还可以接受一些额外的选项:

defaultConfig({
  /**
   * 要添加或覆盖的验证规则。
   * 请参阅验证文档。
   */
  rules: {},
  /**
   * 要注册的本地化。
   * 请参阅国际化文档。
   */
  locales: {},
  /**
   * 要添加或覆盖的输入定义。
   * 请参阅自定义输入文档。
   */
  inputs: {},
  /**
   * 要覆盖的显式本地化消息。
   * 请参阅国际化文档。
   */
  messages: {},
  /**
   * 当前活动的本地化。实际上,这是一个配置设置,但
   * defaultConfig 将其作为顶级值接受以提高开发体验。
   */
  locale: 'en',
  /**
   * 接受上述任何节点选项。
   */
  ...nodeOptions,
})

什么是节点属性?

所有核心节点都有一个 props 对象(node.props)。FormKit 核心和任何第三方插件或代码都可以读取和写入此对象的值。实际上,FormKit 的几乎所有功能都引用 node.props 来确定它应该如何运行。

例如,验证插件会查看 node.props.validation 来确定是否有任何需要运行的规则。所以真正的问题是 - 这些属性是如何设置的?有三种主要的机制可以设置属性:

  • 直接赋值
  • 组件属性
  • Vue 插件选项

让我们看看如何通过这三种方式设置输入的验证规则(node.props.validation):

1. 直接赋值

如果您有一个节点实例,可以直接为其赋值:

加载实时示例

2. 组件属性

传递给 <FormKit> 输入的任何属性都会被分配给 node.props 对象(您知道该怎么做)。

加载实时示例

3. Vue 插件选项

在注册 @formkit/vue 插件时,您可以提供要注入到所有 <FormKit> 组件中的属性值。

加载实时示例

什么是节点配置?

属性非常强大,但除了 node.props,核心节点还具有一个配置对象 node.config。这就是配置层次结构的作用。node.config 对象就像 node.props 的初始值。如果请求了给定的属性,比如 node.props.validation,并且该属性没有使用任何上述讨论的方法显式设置,那么 FormKit 将检查 node.config 对象是否有一个值。如果没有值,则递归检查节点父级的配置对象,然后是祖父级的配置对象,依此类推,直到找到一个值或达到没有父级的节点。

此图描述了对 node.props 属性的请求是如何解析的。

这在实践中意味着什么?当您将表单的树状结构(及其对应的核心节点)与此层次配置结合起来时,您可以做一些非常令人兴奋的事情。例如,在这里我们设置整个表单的验证可见性:

加载实时示例

值得注意的是,插件有自己的继承模型,与 configprops 不同,并在核心文档中有更详细的描述。