表单定义与组件速查

从 Halo 2.0 开始，Console 端的表单使用 FormKit 构建。FormKit 既支持 Vue 组件，也支持可序列化的 Schema。Halo 的主题设置、插件设置和元数据表单都可以复用 FormKit Schema 和本文列出的扩展输入组件。

本文是通用速查，只说明 Setting 结构、Schema 约束和输入组件契约。如何关联资源、读取配置以及处理场景特有的限制，请先进入对应指南。

选择正确的使用场景

表 1 选择正确的使用场景

场景	指南	本页提供的内容
主题设置	设置选项	Schema 字段和可用输入组件
插件设置或自定义表单	插件设置与表单组件	Setting Schema、宿主输入组件和数据边界
模型元数据表单	元数据表单定义	可返回字符串的输入组件；具体值类型限制以元数据表单指南为准

FormKit 相关文档：

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

组件支持范围

Halo 使用 FormKit 开源版本提供的默认输入组件，不支持 FormKit Pro 输入组件。Halo 额外提供的组件将在下文列出。

常用 FormKit 原生输入

Halo 已经注册 FormKit 开源版本的原生输入。以下是 Setting Schema 中常用的类型，具体参数和验证规则以 FormKit 官方文档为准。

text、textarea：单行或多行文本
email、url：邮箱或 URL，并可配合对应验证规则
number、range：数值或范围
checkbox、radio：多选、布尔开关或单选项
date、time：日期或时间
password：遮蔽输入内容，但不会加密保存值

Halo 已覆盖原生 select，请使用本文的 select 参数。附件应优先使用 attachment，不要使用 FormKit 原生文件上传自行实现附件管理。

插件需要注册自定义输入类型时，通过 UI 入口文件的 formkit.inputs 注册，详细文档请参考插件 FormKit 扩展。

Setting 资源定义方式

settings.yaml
apiVersion: v1alpha1
kind: Setting
metadata:
  name: example-setting
spec:
  forms:
    - group: general
      label: 基础设置
      formSchema:
        - $formkit: text
          name: display_name
          label: 显示名称
          value: 示例
        - $formkit: radio
          name: display_mode
          label: 展示模式
          value: list
          options:
            - label: 列表
              value: list
            - label: 网格
              value: grid

    - group: features
      label: 功能设置
      formSchema:
        - $formkit: switch
          name: enabled
          label: 启用功能
          value: true

不要在 Setting 中直接保存敏感信息

Setting 的值最终保存在 ConfigMap 中。password 输入类型只会隐藏界面上的输入内容，并不会加密保存的数据。密码、Token、API Key 等敏感信息应保存在 Halo 的 Secret 资源中，并通过 secret 组件选择对应资源。

遵循具体场景的设置边界

主题设置不应重复定义 Logo、favicon、全局代码注入和系统级 SEO，具体边界请参考主题设置选项。插件设置也应只包含插件自身的业务配置，不要为 Halo 已有的系统设置增加第二个配置入口。

YAML 与 FormKit Schema

FormKit Schema 是可 JSON 序列化的数据结构，Setting 使用 YAML 只是资源文件的表示形式，不需要手动进行 JSON 与 YAML 转换。可以将 FormKit 文档中的对象结构改写为等价的 YAML，但不能直接在 YAML 中定义 JavaScript 函数。只有渲染端通过 Schema data 提供的函数才能在表达式中调用。

字段说明：

metadata.name：设置资源的名称，建议以 -setting 结尾。
spec.forms：必填的表单定义列表，至少包含一个表单分组。
spec.forms[].group：必填的分组名称，同时也是 ConfigMap 中保存该组数据的键。发布后应保持稳定，并且不能与同一 Setting 中的其他分组重复。
spec.forms[].label：可选的表单标题。
spec.forms[].formSchema：必填的 FormKit Schema 节点列表。

每个需要持久化的输入项都应设置唯一的 name。保存后，该 name 将作为表单数据对象中的字段名。

默认值的提取规则

Halo 只会从 formSchema 的直接子节点中提取同时具有 name 和 value 的节点，用于初始化对应 ConfigMap。嵌套在 children 中的节点不会被递归提取；list、array 等容器需要在容器节点上设置完整的默认 value。

Halo 扩展组件速查

表 2 Halo 扩展组件速查

组件	用途	保存值
`select`	静态或远程选择	`string` 或 `string[]`
`list`	基本类型或对象列表	数组
`verificationForm`	提交前远程验证一组字段	不改变子字段的数据结构
`attachment` / `attachmentInput`	上传或选择附件	`string` 或 `string[]`
`attachmentGroupSelect` / `attachmentPolicySelect`	选择附件分组或存储策略	`string`
`code`	编辑代码或结构化文本	`string`
`color`	选择颜色	`string`
`menuSelect` / `menuItemSelect` / `menuCheckbox` / `menuRadio`	选择菜单或菜单项	资源名称或资源名称数组
`postSelect` / `singlePageSelect`	选择文章或独立页面	资源名称
`categorySelect` / `tagSelect` / `categoryCheckbox` / `tagCheckbox`	选择分类或标签	`string` 或 `string[]`
`roleSelect` / `userSelect`	选择角色或用户	资源名称
`iconify`	选择 Iconify 图标	`string` 或对象
`array`	编辑对象数组	对象数组
`switch` / `toggle`	在预设值之间切换	单值或数组
`secret`	选择 Secret 资源	Secret 资源名称

组件可用不代表数据可直接使用

verificationForm 需要可访问的服务端验证接口，通常由插件或其他服务端扩展提供。
secret 只保存 Secret 资源名称，Secret 内容必须由服务端读取，主题模板不能通过设置值直接获得凭据。
multiple: true 会让部分选择器返回数组，不适用于只允许字符串值的 AnnotationSetting。
组件涉及的附件、用户、角色、分类、标签等资源仍受当前用户权限限制。

组件类型

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

select

描述

自定义的选择器组件，支持静态和动态数据源，支持多选等功能。

选项对象至少需要包含 label 与 value。除此之外，还可以提供 icon 与 description 用于增强下拉选项展示（引入版本：2.25.0，远程动态数据源可通过 requestOption.iconField 与 requestOption.descriptionField 映射响应字段）：

icon：图标图片地址，会以 <img> 渲染。
description：显示在 label 下方的说明文字，同时参与本地静态选项搜索。

选中后的单选展示和多选标签仍然只显示 label，提交值保持为选项的 value，多选时提交 value 数组。

参数

options：静态数据源。当 action 存在时，此参数无效。
action：远程动态数据源的接口地址。
requestOption：动态数据源的请求参数，可以通过此参数来指定如何获取数据，适配不同的接口。当 action 存在时，此参数有效。
remoteOptimize：是否开启远程数据源优化，默认为 true。开启后，将会对远程数据源进行优化，减少请求次数。仅在动态数据源下有效。
allowCreate：是否允许把搜索关键词作为新选项值，默认为 false，需要同时开启 searchable。此选项不会在远程服务中创建对应资源。
clearable：是否允许清空选项，默认为 false。
multiple：是否多选，默认为 false。
maxCount：多选时最大可选数量，默认为 Infinity。仅在多选时有效。
sortable：是否支持拖动排序，默认为 true。仅在多选时有效。
searchable: 是否支持搜索，默认为 false。
autoSelect：当初始值不存在且未设置 placeholder 时，是否自动选择第一个选项，默认为 true。仅在单选时有效。

参数类型定义

{
  options?: Array<
    Record<string, unknown> & {
      label: string;
      value: string;
      icon?: string;
      description?: string;
      attrs?: {
        disabled?: boolean;
      };
    }
  >;
  action?: string;
  requestOption?: {
    method?: "GET" | "POST";

    /**
     * 请求结果中 page 的字段名，默认为 `page`。
     */
    pageField?: PropertyPath;

    /**
     * 请求结果中 size 的字段名，默认为 `size`。
     */
    sizeField?: PropertyPath;

    /**
     * 请求结果中 total 的字段名，默认为 `total`。
     */
    totalField?: PropertyPath;

    /**
     * 从请求结果中解析数据的字段名，默认为 `items`。
     */
    itemsField?: PropertyPath;

    /**
     * 从 items 中解析出 label 的字段名，默认为 `label`。
     */
    labelField?: PropertyPath;

    /**
     * 从 items 中解析出 value 的字段名，默认为 `value`。
     */
    valueField?: PropertyPath;

    /**
     * 从 items 中解析出选项图标地址的字段名。
     */
    iconField?: PropertyPath;

    /**
     * 从 items 中解析出选项描述的字段名。
     */
    descriptionField?: PropertyPath;

    /**
     * 使用 value 查询详细信息时，fieldSelector 的查询参数 key，默认为 `metadata.name`。
     */
    fieldSelectorKey?: PropertyPath;
  };
  remoteOptimize?: boolean;
  allowCreate?: boolean;
  clearable?: boolean;
  multiple?: boolean;
  maxCount?: number;
  sortable?: boolean;
  searchable?: boolean;
  autoSelect?: boolean;
}

PropertyPath 表示响应对象中的属性路径，例如 post.spec.title。

静态数据示例

- $formkit: select
  name: countries
  label: What country makes the best food?
  sortable: true
  multiple: true
  clearable: true
  searchable: true
  placeholder: Select a country
  options:
    - label: China
      value: cn
      icon: /assets/flags/cn.svg
      description: Chinese cuisine with rich regional styles
    - label: France
      value: fr
      icon: /assets/flags/fr.svg
      description: French cuisine and bakery classics
    - label: Germany
      value: de
    - label: Spain
      value: es
    - label: Italy
      value: it
    - label: Greece
      value: gr

远程动态数据示例

支持远程动态数据源，通过 action 和 requestOption 参数来指定如何获取数据。

请求的接口将会自动拼接 page、size 与 keyword 参数，其中 keyword 为搜索关键词。

action 使用 Halo Console 提供的 Axios 实例和当前登录会话发起请求，因此应指向当前用户有权访问的同源 Halo API。如果需要访问第三方服务，应由插件后端代理请求并向 Console 暴露受权限保护的接口。

- $formkit: select
  name: postName
  label: Choose a post
  clearable: true
  action: /apis/api.console.halo.run/v1alpha1/posts
  requestOption:
    method: GET
    pageField: page
    sizeField: size
    totalField: total
    itemsField: items
    labelField: post.spec.title
    valueField: post.metadata.name
    iconField: post.spec.cover
    descriptionField: post.status.excerpt
    fieldSelectorKey: metadata.name

分页数据的默认选项

当远程数据具有分页时，可能会出现默认选项不在第一页的情况，此时 Select 组件将会发送另一个查询请求，以获取默认选项的数据。此接口会携带如下参数：

fieldSelector: `${requestOption.fieldSelectorKey}=(value1,value2,value3)`;

其中，value1, value2, value3 为默认选项的值。返回值与查询一致，通过 requestOption 解析。

list

描述

列表类型的输入组件，支持动态添加、删除数据项。

list 与 array 的区别

list 组件与 array 组件功能类似，但它们的用途不同。list 组件适合展示基本类型的数据，而 array 组件更适合于展示复杂类型的数据。

参数

itemType：数据项的数据类型，用于初始化数据。可选参数 string、number、boolean、object，默认为 string
min：数组最小要求数量，默认为 0
max：数组最大容量，默认为 Infinity，即无限制
addButton：是否显示添加按钮
addLabel：添加按钮的文本
upControl：是否显示上移按钮
downControl：是否显示下移按钮
insertControl：是否显示插入按钮
removeControl：是否显示移除按钮

示例

- $formkit: list
  name: socials
  label: 社交账号
  addLabel: 添加账号
  min: 1
  max: 5
  itemType: string
  children:
    - $formkit: text
      index: "$index"
      validation: required

list 子节点限制

list 组件有且只有一个子节点，并且必须为子节点传递 index 属性。若想提供多个字段组成对象，则建议改为使用 array 组件。

最终保存表单之后得到的值为以下形式：

{
  "socials": ["GitHub", "Twitter"]
}

verificationForm

描述

用于远程验证一组数据是否符合要求的组件。

参数

action：对目标数据进行验证的接口地址
label：验证按钮文本
buttonAttrs：验证按钮的属性，例如通过 disabled 禁用按钮

示例

- $formkit: verificationForm
  action: /apis/console.api.my-plugin.halo.run/v1alpha1/configurations/verify
  label: 验证配置
  children:
    - $formkit: text
      label: 仓库地址
      name: repository_url
      validation: required|url
    - $formkit: text
      label: 分支
      name: branch
      value: main
      validation: required

verificationForm 不改变数据结构

尽管 verificationForm 本身是一个输入组件，但与其他输入组件不同的是，它仅仅用于包装待验证的数据，所以并不会破坏原始数据的格式。例如上述示例中的值在保存后为：

{
  "repository_url": "https://github.com/halo-dev/halo",
  "branch": "main"
}

而不是

{
  "verificationForm": {
    "repository_url": "https://github.com/halo-dev/halo",
    "branch": "main"
  }
}

示例中发送至验证地址的值为如下格式：

{
  "repository_url": "https://github.com/halo-dev/halo",
  "branch": "main"
}

当验证接口返回成功响应时，则验证通过，否则验证失败。

若用户在验证失败时想显示错误信息，可以在验证接口返回错误信息，该错误信息的结构定义需遵循 RFC 7807 - Problem Details for HTTP APIs。例如：

{
  "title": "配置验证失败",
  "status": 400,
  "detail": "无法访问指定的仓库或分支。"
}

UI 效果：

repeater(已过时)

请使用 array 组件

repeater 组件已不再推荐使用，请使用 array 组件代替。

描述

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

参数

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 默认值

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

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

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

UI 效果：

attachment

描述

Halo 2.22 的 attachment 类型变更

在 Halo 2.22 中，我们重构了原有的 attachment 表单类型，支持了预览和直接上传文件，并将旧版的表单类型更名为了 attachmentInput。

附件类型的输入框，支持预览附件、直接上传文件、从附件库选择。

参数

accepts：允许选择的文件类型，数据类型为 string[]，默认为 ["*"]
width：预览区域宽度，默认为 5rem
aspectRatio：预览区域长宽比，默认为 1/1，也可以设置为 16/9 等比例
multiple：是否支持多选，默认为 false。设置为 true 后，值为字符串数组

示例

- $formkit: attachment
  name: hero_image
  label: 首页横幅
  width: 10rem
  aspectRatio: 16/9
  accepts:
    - "image/png"
    - "image/jpeg"
    - "image/webp"
  value: ""

附件上传和附件库入口会根据当前用户权限显示；用户也可以输入可访问的附件链接。

attachmentInput

描述

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

参数

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

示例

- $formkit: attachmentInput
  name: project_cover
  label: 项目封面
  accepts:
    - "image/png"
    - "image/jpeg"
  value: ""

attachmentGroupSelect

附件分组选择器，用于选择系统中未被隐藏的附件分组，保存值为分组资源的 metadata.name。

引入版本：2.4.0

- $formkit: attachmentGroupSelect
  name: attachment_group
  label: 附件分组
  value: ""

attachmentPolicySelect

附件存储策略选择器，用于选择系统中的附件存储策略，保存值为策略资源的 metadata.name。

引入版本：2.4.0

- $formkit: attachmentPolicySelect
  name: attachment_policy
  label: 存储策略
  value: ""

code

描述

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

参数

language：代码语言，目前支持 yaml、html、javascript、css、json、markdown。其中 markdown 从 Halo 2.22.0 开始支持。
height：代码编辑器的高度。

示例

- $formkit: code
  name: mapping_rules
  label: 字段映射规则
  value: |-
    title: spec.title
    cover: spec.cover
  language: yaml

color

颜色选择器，支持通过拾色器或文本输入颜色，保存值为指定格式的字符串。

引入版本：2.22.0

参数

format：颜色格式，可选值为 hex、hex8、rgb、hsl，默认为 hex

- $formkit: color
  name: accent_color
  label: 强调色
  format: hex
  value: "#2563eb"

menuSelect

描述

菜单选择器，用于选择系统内的导航菜单，支持单选、多选、排序。

示例

- $formkit: menuSelect
  name: menus
  label: 菜单
  multiple: true
  value: []

menuSelect 兼容 select 参数

menuSelect 基于 select，并兼容 select 的参数。

menuItemSelect

菜单项选择器，用于从指定的菜单项资源中选择一项，保存值为菜单项资源的 metadata.name。

引入版本：2.4.0

参数

menuItems：必填的菜单项资源名称数组，用于限定可选范围

- $formkit: menuItemSelect
  name: featured_menu_item
  label: 推荐菜单项
  menuItems:
    - menu-item-a
    - menu-item-b
  value: ""

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；开启多选后，值为资源名称数组。

参数

multiple：是否支持多选，默认为 false
excludedNames：需要排除的分类资源名称数组（引入版本：2.26.0）
allowCreate：是否允许创建新分类，默认为 true（引入版本：2.26.0）

示例

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

创建分类需要当前用户具有文章管理权限。如果设置表单只应选择现有分类，请显式设置 allowCreate: false。

categoryCheckbox

描述

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

示例

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

tagSelect

描述

文章标签选择器，用于选择系统内的文章标签。其中选择的值为文章标签资源 metadata.name；开启多选后，值为资源名称数组。

参数

multiple：是否支持多选，默认为 false

示例

- $formkit: tagSelect
  name: tags
  label: 标签
  multiple: true
  value: []

当用户输入不存在的标签且具有文章管理权限时，选择器可以创建新标签。使用方不应假定该组件只会读取已有资源。

tagCheckbox

描述

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

示例

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

roleSelect

角色选择器，用于选择系统中的非模板角色，保存值为角色资源的 metadata.name。

引入版本：2.4.0

- $formkit: roleSelect
  name: default_role
  label: 默认角色
  value: ""

userSelect

用户选择器，支持远程搜索，并排除匿名用户和已删除用户，保存值为用户资源的 metadata.name。

引入版本：2.4.0

- $formkit: userSelect
  name: owner
  label: 负责人
  value: ""

iconify

统一的图标选择器，基于 Iconify。

引入版本: 2.22.0

示例

- $formkit: iconify
  name: social_icon
  label: 社交图标
  format: svg # svg / dataurl / url / name

参数

format：图标格式，默认为 svg
- svg：svg 字符串
- dataurl：经过 URI 编码的 SVG Data URL，可以直接用于 img 标签
- url：Iconify 的 CDN 链接
- name：Iconify 的图标名称，需要在使用的地方自行加载图标
value-only：是否仅返回图标数据，默认为 false
popper-placement：图标选择弹窗的打开位置，默认为 auto，可以为：auto、auto-end、auto-start、bottom、bottom-end、bottom-start、left、left-end、left-start、right、right-end、right-start、top、top-end、top-start
sizing：图标尺寸配置对象（引入版本：2.23.0），包含以下属性：
- enabled：是否显示图标尺寸配置，默认为 false
- default：默认尺寸，字符串类型，默认为 "24"
- presets：预设尺寸，字符串数组类型

值类型

当 value-only 参数为 true 时，此表单项的值为 string 类型，比如当 format 为 svg 时，返回值数据形如 <svg>...</svg>

当 value-only 参数不填写或为 false 时，表单类型的值为对象，包含以下属性：

value: 图标数据，当 format 参数不同时，value 的形式也不同，具体如下：
- svg：value 的值为 svg 字符串，可以直接放置在 HTML 中使用
- dataurl / url：可以使用 img 标签加载
- name：Iconify 对应的图标名称，需要在前端加载 Iconify 的依赖配合使用
name：Iconify 对应的图标名称，保留这个字段的目的是为了在 Console 中回显图标信息，通常不需要使用此字段
width：用户在选择图标时设置的图标大小，此字段的目的是为了在 Console 中再次编辑时回显，通常不需要使用此字段
color：用户在选择图标时设置的图标颜色，此字段的目的是为了在 Console 中再次编辑时回显，通常不需要使用此字段

在主题模板中的使用示例：

<!-- 当 format 为 name 时，使用 Iconify 封装的 Web Component 加载图标 -->
<script src="https://code.iconify.design/iconify-icon/3.0.0/iconify-icon.min.js"></script>
<iconify-icon th:icon="${theme.config.group.social_icon.value}"></iconify-icon>

<!-- svg -->
<th:block th:utext="${theme.config.group.social_icon.value}"></th:block>

<!-- dataurl 或者 url -->
<img th:src="${theme.config.group.social_icon.value}" />

开发者可根据具体使用情况自行选择图标格式，通常推荐 svg 或者 dataurl，因为这样无需任何网络请求，确保图标可以稳定地正常加载。

UI 效果：

array

一组重复的输入组件，展示为列表形式，可以用于定义一组数据。最终得到的数据为一个对象的数组，方便使用者对此数组进行增加、删除、排序等操作。

引入版本: 2.22.0（计划用于替换已过时的 repeater 组件）

参数

min：数组最小要求数量，默认为 0
max：数组最大容量，默认为 Infinity，即无限制
removeControl：是否允许移除元素
addButton：是否显示添加按钮
addLabel：添加按钮上显示的文本
addAttrs：添加按钮的额外属性
emptyText: 当数组为空时显示的文本
itemLabels: 列表元素上显示的内容，数据类型为 { type: "image" | "text" | "iconify" | "color"; label: string }[]

建议设置 itemLabels

强烈建议为 array 设置 itemLabels 属性，以便于更直观的展示元素内容，设置的元素内容将按照设置顺序展示在列表元素上。

在 itemLabels 中定义 label 时，可以使用 $value 指向当前项的值，也可以使用 $value.name、$value.profile.name 等路径读取嵌套字段。

示例

- $formkit: array
  name: socials
  label: 社交账号
  value: []
  max: 5
  min: 1
  itemLabels:
    - type: image
      label: $value.icon
    - type: text
      label: $value.name
  children:
    - $formkit: attachment
      name: icon
      label: 图标
      value: ""
    - $formkit: text
      name: name
      label: 名称
      value: ""
    - $formkit: text
      name: url
      label: 地址
      value: ""

switch

开关组件，提供两个值之间的选择；当您想使用户切换功能开或关时，这是一个很好的选项

引入版本: 2.22.1

参数

onValue：开关打开时的值，默认为 true
offValue：开关关闭时的值，默认为 false
disabled：是否禁用开关，默认为 false

示例

- $formkit: switch
  name: enabled
  label: 是否启用
  value: false

如果需要开关的值为其他值，可以设置 onValue 和 offValue 参数。

- $formkit: switch
  name: enabled
  label: 是否启用
  value: "active"
  onValue: "active"
  offValue: "inactive"

toggle

切换组件，用于对一组图片、颜色或文字等选择切换，支持单选与多选。它的功能与 select 组件类似，但相较于 select 组件，toggle 组件可以更直观的展示选项。

引入版本: 2.22.8

参数：

renderType：当前组件的渲染类型，可选参数为 image、color、text，默认为 text。
options：一组同类型的数据源，数据类型为 { label?: string; value: string; render?: string }[]，其中 label 为选项的文本，value 为选项的值。render 为选项的渲染展示内容，与 renderType 参数配合使用。
- 当 renderType 为 image 时，render 参数为图片的 URL。
- 当 renderType 为 color 时，render 参数为颜色的十六进制代码。例如 #000000。
- 当 renderType 为 text 时，render 参数为文字内容。
multiple：可选，是否支持多选，默认为 false。
size：可选，渲染内容的尺寸，number 类型，单位为 px。
gap：可选，渲染内容之间的间距，number 类型，单位为 px。
value: 可选初始值，数据类型为 string | number | boolean | (string | number | boolean)[]。

示例

- $formkit: toggle
  label: 选择图片
  name: toggle
  render-type: image
  size: 100
  gap: 10
  help: 选择图片作为背景
  options:
    - label: 图文1
      value: 1
      render: https://placehold.co/600x400
    - label: 图文2
      value: 2
      render: https://placehold.co/600x400
    - label: 图文3
      value: 3
      render: https://placehold.co/600x400

UI 效果

secret

密钥输入组件，用于选择一个密钥资源。

引入版本：2.17.0

使用 Secret 存储敏感数据

在 Halo 中，我们提供了一种更加安全的数据存储模型，即 Secret，通常我们使用 Secret 来存储敏感数据，比如密码、token、密钥等。

需要注意的是，此表单类型保存的是 Secret 资源名称，需要服务端根据该名称查询 Secret 资源。主题模板不能通过该设置值直接获取 Secret 内容。

参数

requiredKeys：所需的密钥字段，用于说明所选 Secret 应包含的字段（引入版本：2.22.10）。此字段为对象数组类型，对象包含以下属性：
- key：密钥字段名称
- help：可选的密钥字段说明
descriptionPreset：创建密钥时的备注预设（引入版本：2.25.0）。打开创建密钥弹窗时，备注字段会预填为 <descriptionPreset> - <当前时间>，用户仍可在保存前编辑。

requiredKeys 不是后端校验

requiredKeys 只用于 Console 中的创建提示和缺失提醒，不会阻止服务端读取到字段缺失或值为空的 Secret。使用 Secret 的服务端代码必须自行校验所需字段，并返回清晰的错误信息。

示例

- $formkit: secret
  name: secret
  label: 密钥
  descriptionPreset: 第三方 API
  requiredKeys:
    - key: apiKey
      help: API 密钥
    - key: secretKey
      help: 密钥

选择正确的使用场景​

常用 FormKit 原生输入​

Setting 资源定义方式​

Halo 扩展组件速查​

组件类型​

select​

描述​

参数​

参数类型定义​

静态数据示例​

远程动态数据示例​

list​

描述​

参数​

示例​

verificationForm​

描述​

参数​

示例​

repeater(已过时)​

描述​

参数​

示例​

attachment​

描述​

参数​

示例​

attachmentInput​

描述​

参数​

示例​

attachmentGroupSelect​

attachmentPolicySelect​

code​

描述​

参数​

示例​

color​

参数​

menuSelect​

描述​

示例​

menuItemSelect​

参数​

menuCheckbox​

描述​

示例​

menuRadio​

描述​

示例​

postSelect​

描述​

示例​

singlePageSelect​

描述​

示例​

categorySelect​

描述​

参数​

示例​

categoryCheckbox​

描述​

示例​

tagSelect​

描述​

参数​

示例​

tagCheckbox​

描述​

示例​

roleSelect​

userSelect​

iconify​

参数​

值类型​

array​

示例​

switch​

示例​

toggle​

选择正确的使用场景

常用 FormKit 原生输入

Setting 资源定义方式

Halo 扩展组件速查

组件类型

select

描述

参数

参数类型定义

静态数据示例

远程动态数据示例

list

描述

参数

示例

verificationForm

描述

参数

示例

repeater(已过时)

描述

参数

示例

attachment

描述

参数

示例

attachmentInput

描述

参数

示例

attachmentGroupSelect

attachmentPolicySelect

code

描述

参数

示例

color

参数

menuSelect

描述

示例

menuItemSelect

参数

menuCheckbox

描述

示例

menuRadio

描述

示例

postSelect

描述

示例

singlePageSelect

描述

示例

categorySelect

描述

参数

示例

categoryCheckbox

描述

示例

tagSelect

描述

参数

示例

tagCheckbox

描述

示例

roleSelect

userSelect

iconify

参数

值类型

array

示例

switch

示例

toggle