Halo 插件如何注册自定义 FormKit 输入组件并在设置表单中通过 $formkit 使用

Halo 插件如何注册自定义 FormKit 输入组件并在设置表单中通过 $formkit 使用【免费下载链接】haloHalo 是一款强大易用的开源建站工具从个人博客、知识库到企业官网、在线商城Halo 都能助您轻松实现一站式满足您的多样化建站需求。项目地址: https://gitcode.com/GitHub_Trending/ha/haloHalo Console 与 User Center用户中心中的所有表单都基于 FormKit 构建但 FormKit 内置的输入类型无法覆盖插件的全部需求例如需要绑定插件自有接口的选择器或远程验证字段。Halo 允许已启用的 UI 插件在插件模块中通过formkit.inputs声明自定义输入类型注册后的类型可以直接在插件或主题的设置表单定义FormKit Schema中以$formkit引用并走完整的 FormKit 输入生命周期。本文面向 Halo 插件开发者说明如何完成定义组件 → 注册输入类型 → 在设置表单中使用 → 验证注册结果这一连续任务。前提插件模块与共享的 FormKit 运行时注册自定义输入类型需要满足以下条件插件是一个 UI 插件其 UI 入口通过halo-dev/ui-shared导出的definePlugin返回一个插件模块PluginModule实现见 ui-plugin-entry.tsformkit是插件模块的可选属性类型为PluginFormKit其中inputs是一个以输入类型名为键、FormKit 输入定义为值的同步对象定义见 ui-plugin-module.ts。不导出formkit的插件会照常加载不受影响插件可以直接import { createInput } from formkit/vue。Halo 的插件打包工具会把formkit/vue外置为共享运行时共享运行时清单见 ui-plugin-bundler-kit/README.md 与 externals.ts插件在 Console 或用户中心中实际使用 Halo 提供的 FormKit 运行时而不是自带一份。这一点在需求文档 plugin-formkit-inputs/spec.md 的 Shared FormKit Vue runtime for plugins 一节中有明确约定。这样设计的背景是Halo 前端原本在安装 FormKit 之后才加载插件模块内置输入通过defaultConfig({ inputs })注册见 setupComponents.ts插件无法再修改 FormKit 的全局输入库。因此 Halo 调整为在认证用户启动 Console 或用户中心时先加载已启用插件的 UI 模块并收集formkit.inputs再安装 FormKit安装时的输入库为Halo 内置输入 被接受的插件输入见 spec 的 Startup registration timing 一节。匿名用户的会话不加载插件输入FormKit 仅以内置输入启动之后由路由守卫走认证重定向流程。第一步编写输入组件自定义输入本身是一个 Vue 组件FormKit 自定义输入组件Halo 仓库文档没有约定该组件的内部实现这部分由插件按 FormKit 自定义输入的要求自行实现下文以MyPluginInput.vue指代它。如果组件体积较大可以用懒加载方式引入这是文档明确支持的组合方式见下文createInput(defineAsyncComponent(...))。第二步在插件模块中注册输入类型在插件 UI 入口中通过formkit.inputs注册代码形式与 custom-formkit-input/README.md 插件扩展 FormKit 输入组件一节给出的示例一致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(./MyPluginInput.vue)) ), }, }, });几点约束需要注意formkit.inputs只支持同步对象不支持异步工厂函数需要懒加载时在输入定义内部使用defineAsyncComponent包裹 Vue 组件formkit必须是对象模块校验阶段发现formkit不是对象会抛出TypeError(PluginModule.formkit must be an object.)见 setupModules.ts输入定义的键这里是myPluginInput就是后续在 Schema 中$formkit引用的类型名。Halo 内置类型名如select、attachment、secret、postSelect等见 custom-formkit-input/README.md 的内置类型列表优先级更高建议插件使用带自身标识的类型名例如myPluginInput以降低冲突概率。第三步在设置表单的 FormKit Schema 中通过 $formkit 使用在插件或主题的设置表单定义YAML 形式的 FormKit Schema中用$formkit引用注册后的类型名- $formkit: myPluginInput name: customField label: 自定义字段该字段随后会像 FormKit 原生输入一样参与表单的值绑定与输入生命周期。同一个类型也可以在 Vue 单文件组件中以FormKit typemyPluginInput /的组件形式使用这与内置输入如typepostSelect的用法相同文档在 使用方式 一节给出了内置类型的 SFC 用法示例注册后的插件输入类型走的是同一条路径。验证注册结果与排查冲突注册与生效的行为都可以从 Console 控制台和网络请求层面核对以认证用户进入 Console 或用户中心打开引用了$formkit: myPluginInput的设置表单。按需求文档此场景下 Halo 会先加载插件 UI 模块再以内置输入 被接受的插件输入安装 FormKit字段应渲染为插件组件并参与表单数据。观察控制台警告。收集插件输入的实现是 plugin-inputs.ts所有跳过都会以[Halo FormKit]为前缀输出console.warn见 warn 函数。源码中的警告格式形如变量在运行时替换为实际值Skipped plugin 插件名 FormKit config because it is not an object.formkit不是对象Skipped FormKit input 类型名 from plugin 插件名 because it conflicts with ...类型名冲突Skipped FormKit input 类型名 from plugin 插件名 because it is not a valid input definition.输入定义不是合法的 FormKit 输入定义。理解冲突时的取舍。当插件输入名与 Halo 内置输入同名时Halo 保留内置输入、跳过插件输入并输出警告多个已启用插件注册同名输入时保留先加载的一个后注册的同名输入被跳过并输出警告。也就是说如果你发现$formkit引用的是内置组件而非自己的组件先检查控制台是否出现上述 conflict 警告再检查插件是否已启用。输入定义的有效性检查。被接受前每条输入定义必须满足是对象、type为字符串、且包含schema或component这三个条件否则按无效定义跳过见 isFormKitInputDefinition。createInput的返回值天然满足该结构。插件 bundle 加载失败时的降级。如果在收集插件输入阶段加载已启用插件的 UI bundle 失败Halo 会以仅内置输入安装 FormKit 并继续核心 UI 启动同时走既有的插件加载失败通知行为不会阻塞 Console 或用户中心挂载。此时设置表单中引用的插件输入类型不可用需要按插件 bundle 的加载失败提示排查。当前能力边界根据设计文档 design.md 的 Non-Goals这一机制目前的范围是插件模块上只支持formkit.inputs这一个 FormKit 相关属性插件不能提供 FormKit 插件、校验规则、主题、语言包或图标不支持异步的formkit.inputs工厂函数插件输入运行时的渲染错误不做额外边界处理交给 Vue 与 FormKit 的正常运行时机制对已有插件无迁移要求不导出formkit的插件、既有$cmp用法以及组件/路由/扩展点注册均不受影响。参考资料ui/docs/custom-formkit-input/README.md、openspec/specs/plugin-formkit-inputs/spec.md、ui/src/formkit/plugin-inputs.ts、ui/src/setup/setupComponents.ts。【免费下载链接】haloHalo 是一款强大易用的开源建站工具从个人博客、知识库到企业官网、在线商城Halo 都能助您轻松实现一站式满足您的多样化建站需求。项目地址: https://gitcode.com/GitHub_Trending/ha/halo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考