表单定义

在 Halo 2.0，在 Console 端的所有表单我们都使用了 FormKit 的方案。FormKit 不仅支持使用 Vue 组件的形式来构建表单，同时支持使用 Schema 的形式来构建。因此，我们的 Setting 资源中的表单定义，都是使用 FormKit Schema 来定义的，最常用的场景即主题和插件的设置表单定义。当然，如果要在 Halo 2.0 的插件中使用，也可以参考 FormKit 的文档使用 Vue 组件的形式使用，但不需要在插件中引入 FormKit。

此文档将不会介绍 FormKit 的具体使用教程，因为我们已经很好的集成了 FormKit，并且使用方式基本无异。此文章将介绍 Halo 2.0 中表单定义的一些规范，以及额外的一些输入组件。

FormKit 相关文档：

• Form Schema: https://formkit.com/essentials/schema
• FormKit Inputs: https://formkit.com/inputs

提示

目前不支持 FormKit Pro 中的输入组件，但 Halo 额外提供了部分输入组件，将在下面文档列出。

Setting 资源定义方式

settings.yaml

apiVersion: v1alpha1
kind: Setting
metadata:
  name: foo-setting
spec:
  forms:
    - group: group_1
      label: 分组 1
      formSchema:
        - $formkit: radio
          name: color_scheme
          label: 默认配色
          value: system
          options:
            - label: 跟随系统
              value: system
            - label: 深色
              value: dark
            - label: 浅色
              value: light

    - group: group_2
      label: 分组 2
      formSchema:
        - $formkit: text
          name: username
          label: 用户名
          value: ""
        - $formkit: password
          name: password
          label: 密码
          value: ""

提示

需要注意的是，FormKit Schema 本身应该是 JSON 格式的，但目前我们定义一个表单所使用的是 YAML，可能在参考 FormKit 写法时需要手动转换一下。

字段说明：

1. metadata.name：设置资源的名称，建议以 -setting 结尾。
2. spec.forms：表单定义，可以定义多个表单，每个表单都有一个 group 字段，用于区分不同的表单。
3. spec.forms[].label：表单的标题。
4. spec.forms[].formSchema：表单的定义，使用 FormKit Schema 来定义。虽然我们使用的 YAML，但与 FormKit Schema 完全一致。

组件类型

除了 FormKit 官方提供的常用输入组件之外，Halo 还额外提供了一些输入组件，这些输入组件可以在 Form Schema 中使用。

repeater

描述

一组重复的输入组件，可以用于定义一组数据，最终得到的数据为一个对象的数组，可以方便地让使用者对其进行增加、移除、排序等操作。

参数

• min：数组最小要求数量，默认为 0
• max：数组最大容量，默认为 Infinity，即无限制
• addButton：是否显示添加按钮
• addLabel：添加按钮的文本
• upControl：是否显示上移按钮
• downControl：是否显示下移按钮
• insertControl：是否显示插入按钮
• removeControl：是否显示移除按钮

示例

- $formkit: repeater
  name: socials
  label: 社交账号
  value: []
  max: 5
  min: 1
  children:
    - $formkit: select
      name: enabled
      id: enabled
      label: 是否启用
      options:
        - label: 是
          value: true
        - label: 否
          value: false
    - $formkit: text
      # 在 Repeater 中进行条件判断的方式，当 enabled 为 true 时才显示
      if: "$value.enabled === true",
      name: name
      label: 名称
      value: ""
    - $formkit: text
      if: "$value.enabled === true",
      name: url
      label: 地址
      value: ""

提示

使用 repeater 类型时，一定要设置默认值，如果不需要默认有任何元素，可以设置为 []。

其中 name 和 url 即数组对象的属性，最终保存表单之后得到的值为以下形式：

{
  "socials": [
    {
      "name": "GitHub",
      "url": "https://github.com/halo-dev"
    }
  ]
}

UI 效果：

attachment

描述

附件类型的输入框，支持直接调用附件库弹框选择附件。

参数

• accepts：文件类型，数据类型为 string[]。

示例

- $formkit: attachment
  name: logo
  label: Logo
  accepts:
    - "image/png"
    - "video/mp4"
    - "audio/*"
  value: ""

code

描述

代码编辑器的输入组件，集成了 Codemirror。

参数

• language：代码语言，目前支持 yaml html javascript css json。
• height：代码编辑器的高度。

示例

- $formkit: code
  name: footer_code
  label: 页脚代码注入
  value: ""
  language: yaml

menuCheckbox

描述

菜单复选框，用于选择系统内的导航菜单。其中选择的值为菜单资源 metadata.name 的集合。

示例

- $formkit: menuCheckbox
  name: menus
  label: 菜单
  value: []

menuRadio

描述

菜单单选框，用于选择系统内的导航菜单。其中选择的值为菜单资源 metadata.name。

示例

- $formkit: menuRadio
  name: menu
  label: 菜单
  value: ""

postSelect

描述

文章选择器，用于选择系统内的文章。其中选择的值为文章资源 metadata.name。

示例

- $formkit: postSelect
  name: post
  label: 文章
  value: ""

singlePageSelect

描述

单页选择器，用于选择系统内的独立页面。其中选择的值为独立页面资源 metadata.name。

示例

- $formkit: singlePageSelect
  name: singlePage
  label: 单页
  value: ""

categorySelect

描述

文章分类选择器，用于选择系统内的文章分类。其中选择的值为文章分类资源 metadata.name。

示例

- $formkit: categorySelect
  name: category
  label: 分类
  value: ""

categoryCheckbox

描述

文章分类复选框，用于选择系统内的文章分类。其中选择的值为文章分类资源 metadata.name 的集合。

示例

- $formkit: categoryCheckbox
  name: categories
  label: 分类
  value: []

tagSelect

描述

文章标签选择器，用于选择系统内的文章标签。其中选择的值为文章标签资源 metadata.name。

示例

- $formkit: tagSelect
  name: tag
  label: 标签
  value: ""

tagCheckbox

描述

文章标签复选框，用于选择系统内的文章标签。其中选择的值为文章标签资源 metadata.name 的集合。

示例

- $formkit: tagCheckbox
  name: tags
  label: 标签
  value: []