自定义输入

构建您的第一个自定义输入?阅读指南

FormKit包括许多输入的开箱即用,但您也可以定义自己的输入,这些输入会自动继承FormKit的增值功能,如验证、错误消息、数据建模、分组、标签、帮助文本等。

修改或重构现有输入

如果您的使用场景需要修改现有的输入,如移动部分、更改或重构HTML元素等,可以考虑使用FormKit的输入导出功能

输入由两个基本部分组成:

  1. 输入定义
  2. 输入的代码:模式组件
从指南开始

如果您刚开始使用自定义输入,建议阅读“创建自定义输入”指南。本页的内容旨在解释自定义输入的复杂性,适用于高级用例,如编写插件或库,并不适用于许多常见用例。

注册输入

新的输入需要一个输入定义。输入定义可以通过三种方式在FormKit中注册:

输入定义

输入定义是包含初始化输入所需信息的对象,如接受哪些属性,渲染什么模式或组件,以及是否包含任何额外的功能函数。定义对象的形状是:

{
  // 节点类型:输入、组、列表。
  type: 'input',
  // 渲染的模式(模式对象或返回对象的函数)
  schema: [],
  // 渲染的Vue组件(使用模式 _OR_ 组件,但不同时使用两者)
  component: YourComponent,
  // (可选)<FormKit>组件应接受的特定于输入的属性。
  // 应为驼峰式字符串的数组
  props: ['fooBar'],
  // (可选)接收节点的函数数组。
  features: []
}

使用 type 属性

让我们制作最简单的输入 —— 一个只输出 "Hello world" 的输入。

加载实时示例

尽管这个简单的例子不包含任何输入/输出机制,但它仍然可以作为一个完整的输入。它可以有一个值,运行验证规则(它们不会被显示,但它们可以阻止表单提交),并执行插件。从根本上说,所有的输入都是核心节点,输入的定义提供了与该节点交互的机制。

全局自定义输入

要在您的应用程序中通过 "type" 字符串(例如:<FormKit type="foobar" />)使用您的自定义输入,您可以向 defaultConfig 选项添加一个 inputs 属性。inputs 对象的属性名成为 <FormKit> 组件在您的应用程序中可用的 "type" 字符串。

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

const helloWorld = {
  type: 'input',
  schema: ['Hello world'],
}

createApp(App)
  .use(
    plugin,
    defaultConfig({
      inputs: {
        // 属性将是 <FormKit type="hello"> 中的 “type”
        hello: helloWorld,
      },
    })
  )
  .mount('#app')

现在我们已经定义了我们的输入,我们可以在应用程序的任何地方使用它:

加载实时示例

插件库

上面的例子扩展了 @formkit/inputs 库(通过 defaultConfig)。然而,FormKit 的一个强大的特性是它能够从多个插件加载输入库。这些输入可以在任何可以定义插件的地方注册:

  • 全局
  • 每个组
  • 每个表单
  • 每个列表
  • 每个输入

让我们重构我们的 hello world 输入,使用它自己的插件:

加载实时示例
插件继承

注意在上面的例子中,我们的插件是在实际使用它的元素的父元素上定义的!这要归功于 插件继承 —— FormKit 插件的一个核心特性。

Schema vs 组件

您的输入可以使用 FormKit 的 schema 或一个通用的 Vue 组件编写。每种方法都有优点和缺点:

代码优点缺点
Vue
  • 学习曲线(你可能知道如何编写一个 Vue 组件)。
  • 更成熟的开发工具。
  • 初始渲染稍快。
  • 不能使用 :sections-schema 属性 来修改结构。
  • 插件不能修改 schema 来改变渲染输出。
  • 框架特定(仅 Vue)。
  • 容易编写不适合 FormKit 生态系统的输入。
Schema
  • 可以通过 :sections-schema 属性修改结构(如果你允许的话)。
  • 插件可以修改/改变渲染输出。
  • 框架无关(当 FormKit 支持新框架时的未来可移植性)。
  • 生态系统兼容性(非常适合发布你自己的开源输入)。
  • 学习曲线(需要 理解 schemas)。
  • 初始渲染稍慢。
  • 开发工具不够成熟。
schemas 中的组件

即使你更喜欢使用标准的 Vue 组件来编写一个自定义输入,你仍然可以在你的输入定义中使用一个 schema。请阅读 使用 createInput 扩展基础 schema 部分。

主要的结论是,如果你计划在多个项目中使用自定义输入 —— 那么考虑使用基于 schema 的方法。如果你的自定义输入只会在一个项目中使用,并且灵活性不是问题,使用 Vue 组件。