From d3f3bd029832b70f7377e2c7d50f970b7bebf505 Mon Sep 17 00:00:00 2001
From: Ryan Wang <i@ryanc.cc>
Date: Mon, 8 Jun 2026 19:03:58 +0800
Subject: [PATCH] Document plugin FormKit inputs

---
 docs/developer-guide/form-schema.md           |  2 +
 docs/developer-guide/plugin/api-changelog.md  |  6 +++
 .../plugin/api-reference/ui/formkit.md        | 40 +++++++++++++++++++
 .../developer-guide/plugin/basics/ui/entry.md | 10 +++++
 sidebars.js                                   |  1 +
 5 files changed, 59 insertions(+)
 create mode 100644 docs/developer-guide/plugin/api-reference/ui/formkit.md

diff --git a/docs/developer-guide/form-schema.md b/docs/developer-guide/form-schema.md
index 88177a2e..86351589 100644
--- a/docs/developer-guide/form-schema.md
+++ b/docs/developer-guide/form-schema.md
@@ -15,6 +15,8 @@ FormKit 相关文档：
 目前不支持 FormKit Pro 中的输入组件，但 Halo 额外提供了部分输入组件，将在下面文档列出。
 :::
 
+如果需要在插件中创建自定义的 FormKit 表单类型，可以通过插件 UI 入口文件的 `formkit.inputs` 注册，详细文档可参考 [插件 FormKit 扩展](./plugin/api-reference/ui/formkit.md)。
+
 ## Setting 资源定义方式
 
 ```yaml title="settings.yaml"
diff --git a/docs/developer-guide/plugin/api-changelog.md b/docs/developer-guide/plugin/api-changelog.md
index 07c8a04f..9565bd8d 100644
--- a/docs/developer-guide/plugin/api-changelog.md
+++ b/docs/developer-guide/plugin/api-changelog.md
@@ -5,6 +5,12 @@ description: 记录每一个版本的插件 API 变更记录，方便开发者
 
 ## 2.25.0
 
+### 支持插件注册自定义 FormKit 输入组件
+
+在 2.25.0 中，插件可以通过 UI 入口文件的 `formkit.inputs` 注册自定义 FormKit 输入组件，并在插件提供的 FormKit Schema 中通过 `$formkit` 使用。详细文档可查阅：[FormKit 扩展](./api-reference/ui/formkit.md)。
+
+如果插件使用 `@formkit/vue` 创建 input definition，需要将 `@halo-dev/ui-plugin-bundler-kit` 升级到 2.25.0 或更高版本，并将 `plugin.yaml` 中的 `spec.requires` 提升到 `>=2.25.0`。
+
 ### 表单定义 > `secret` 表单类型新增 `descriptionPreset` 参数
 
 在 2.25.0 中，`secret` 表单类型新增了 `descriptionPreset` 参数，用于在创建密钥时预填备注。详细文档可查阅：[表单定义#secret](../../developer-guide/form-schema.md#secret)。
diff --git a/docs/developer-guide/plugin/api-reference/ui/formkit.md b/docs/developer-guide/plugin/api-reference/ui/formkit.md
new file mode 100644
index 00000000..ef57535e
--- /dev/null
+++ b/docs/developer-guide/plugin/api-reference/ui/formkit.md
@@ -0,0 +1,40 @@
+---
+title: FormKit 扩展
+description: 介绍如何通过插件注册自定义 FormKit 输入组件
+---
+
+从 Halo 2.25.0 开始，插件可以通过 UI 入口文件的 `formkit.inputs` 注册自定义 FormKit 输入组件。注册后，插件提供的 FormKit Schema 可以通过 `$formkit` 使用对应类型。
+
+关于如何创建 FormKit 自定义输入组件，可参考 FormKit 官方文档：[Create a custom input](https://formkit.com/guides/create-a-custom-input)。
+
+## 注册输入组件
+
+```ts title="ui/src/index.ts"
+import { createInput } from "@formkit/vue";
+import { definePlugin } from "@halo-dev/ui-shared";
+import { defineAsyncComponent } from "vue";
+
+export default definePlugin({
+  formkit: {
+    inputs: {
+      myPluginInput: createInput(
+        defineAsyncComponent(() => import("./components/MyPluginInput.vue"))
+      ),
+    },
+  },
+});
+```
+
+## 在 FormKit Schema 中使用
+
+```yaml
+- $formkit: myPluginInput
+  name: customField
+  label: 自定义字段
+```
+
+## 注意事项
+
+`formkit.inputs` 仅支持同步对象。如果输入组件需要懒加载，可以在 input definition 内部使用 `defineAsyncComponent`。
+
+当插件注册的输入类型名称与 Halo 内置类型或更早加载的插件类型重复时，Halo 会保留已有类型，跳过冲突的插件类型并在控制台输出警告。建议使用带插件标识的类型名称，例如 `myPluginInput`。
diff --git a/docs/developer-guide/plugin/basics/ui/entry.md b/docs/developer-guide/plugin/basics/ui/entry.md
index 84854386..a224c4cf 100644
--- a/docs/developer-guide/plugin/basics/ui/entry.md
+++ b/docs/developer-guide/plugin/basics/ui/entry.md
@@ -13,6 +13,7 @@ description: UI 扩展部分的入口文件
 import { definePlugin } from "@halo-dev/ui-shared";
 
 export default definePlugin({
+  formkit: {},
   components: {},
   routes: [],
   ucRoutes: [],
@@ -49,6 +50,7 @@ import type {
 import type { AnyExtension } from "@halo-dev/richtext-editor";
 import type { Component, Ref } from "vue";
 import type { RouteRecordName, RouteRecordRaw } from "vue-router";
+import type { FormKitTypeDefinition } from "@formkit/core";
 import type {
   DashboardWidgetDefinition,
   DashboardWidgetQuickActionItem,
@@ -63,6 +65,10 @@ export interface RouteRecordAppend {
   route: RouteRecordRaw;
 }
 
+export interface PluginFormKit {
+  inputs?: Record<string, FormKitTypeDefinition>;
+}
+
 export interface ExtensionPoint {
   // @deprecated
   "page:functional:create"?: () => FunctionalPage[] | Promise<FunctionalPage[]>;
@@ -145,6 +151,8 @@ export interface ExtensionPoint {
 }
 
 export interface PluginModule {
+  formkit?: PluginFormKit;
+
   /**
    * These components will be registered when plugin is activated.
    */
@@ -159,6 +167,8 @@ export interface PluginModule {
 
 ```
 
+- `formkit`：FormKit 相关扩展定义。
+  - `inputs`：自定义 FormKit 输入组件定义，key 为在 FormKit Schema 中使用的 `$formkit` 类型名称，value 为 FormKit input definition。详细文档可参考 [FormKit 扩展](../../api-reference/ui/formkit.md)。
 - `components`：组件列表，key 为组件名称，value 为组件对象，在此定义之后，加载插件时会自动注册到 Vue App 全局。
 - `routes`：Console 控制台路由定义，详细文档可参考 [路由定义](../../api-reference/ui/route.md)
 - `ucRoutes`：UC 个人中心路由定义，详细文档可参考 [路由定义](../../api-reference/ui/route.md)
diff --git a/sidebars.js b/sidebars.js
index d4d7deb8..c02ce5ef 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -246,6 +246,7 @@ module.exports = {
               items: [
                 "developer-guide/plugin/api-reference/ui/route",
                 "developer-guide/plugin/api-reference/ui/api-request",
+                "developer-guide/plugin/api-reference/ui/formkit",
                 "developer-guide/plugin/api-reference/ui/shared",
                 {
                   type: "category",