配置

简介

FormKit 使用了一个独特的分层配置系统,非常适合表单。要理解这种配置是如何工作的,我们需要回答4个问题:

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

什么是核心节点?

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

没有全局的 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',
  /**
   * 所有只有3个值之一:'input','group',或 'list'
   */
  type: 'input',
  /**
   * 节点的初始值。
   */
  value: 'foobar',
})

什么是 defaultConfig

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

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

defaultConfig({
  /**
   * 添加或覆盖的验证规则。
   * 参见验证文档。
   */
  rules: {},
  /**
   * 注册的语言环境。
   * 参见国际化文档。
   */
  locales: {},
  /**
   * 添加或覆盖的输入定义。
   * 参见自定义输入文档。
   */
  inputs: {},
  /**
   * 覆盖的明确的语言环境消息。
   * 参见国际化文档。
   */
  messages: {},
  /**
   * 当前活动的语言环境。这实际上是一个配置设置,但
   * defaultConfig将其作为顶级值接受,以改善DX。
   */
  locale: 'en',
  /**
   * 接受任何上述节点选项。
   */
  ...nodeOptions,
})

什么是节点属性?

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

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

  • 直接分配
  • 组件属性
  • Vue插件选项

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

1. 直接分配

如果你有一个节点实例,你可以直接给它分配一个属性值:

加载实时示例

2. 组件属性

传递给 <FormKit> 输入的任何属性都会分配给 node.props 对象(你知道的)。

加载实时示例

3. Vue插件选项

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

加载实时示例

什么是节点配置?

Props相当强大,但除了node.props之外,核心节点都有一个配置对象node.config。这就是配置层次结构的作用。node.config对象就像node.props的初始值。如果请求一个给定的prop,比如node.props.validation,并且该属性没有使用上面讨论的任何方法明确设置,那么FormKit将检查node.config对象是否有值。如果它没有值,那么它会递归地检查节点父对象的配置对象——然后是祖父对象的配置对象——依此类推——直到找到一个值或者到达没有父对象的节点。

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

这在实践中意味着什么?当你将表单的树状结构(及其对应的核心节点)和这种层次配置结合起来,你可以做一些相当激动人心的事情。例如,我们在这里设置了整个表单的验证可见性:

加载实时示例

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