Halo UI 插件自定义 FormKit 输入注册指南：`formkit.inputs` 契约、启动时序与命名冲突处理

Halo UI 插件自定义 FormKit 输入注册指南formkit.inputs契约、启动时序与命名冲突处理【免费下载链接】haloHalo 是一款强大易用的开源建站工具从个人博客、知识库到企业官网、在线商城Halo 都能助您轻松实现一站式满足您的多样化建站需求。项目地址: https://gitcode.com/GitHub_Trending/ha/haloHalo 的管理后台Console与用户中心UC的绝大多数表单都基于 FormKit 构建插件既可以使用 Halo 内置的select、repeater、secret等输入类型也可以通过 UI 模块入口中的formkit.inputs字段注册自己的 FormKit 输入类型让自定义字段像内置字段一样完整参与 FormKit 的输入生命周期、取值与校验。本文依据仓库中的 OpenSpec 需求规格 及其设计与实现档案结合源码讲解formkit.inputs的插件契约、注册启动时序、内置输入优先级、加载失败兜底与formkit/vue共享运行时读完你可以为 Halo 插件正确注册、调试并发布自定义 FormKit 输入类型。背景为什么插件需要真正的 FormKit 输入而非$cmp在formkit.inputs能力引入之前Halo 插件虽然可以用 FormKit Schema 的$cmp渲染任意 Vue 组件但这种组件并不会成为 FormKit 的输入类型它不参与 FormKit 的输入生命周期、取值处理、校验规则、Features 机制与 Schema 库无法在validation、v-model、父子节点联动等场景中表现一致。这正是本次规格要解决的问题允许已启用的 UI 插件声明自定义 FormKit 输入使插件提供的表单字段类型与 Halo 内置输入select、attachment、secret、repeater、list等处于同等的生态地位。从源码结构上看该能力的前端测试覆盖在 ui/src/formkit/tests/plugin-inputs.spec.ts 与 ui/src/setup/setupModules.spec.ts规格正文见 openspec/specs/plugin-formkit-inputs/spec.md。一、插件 FormKit 输入契约PluginModule.formkit.inputs1. 契约要求Requirements规格对插件侧契约提出了三条必须满足的行为要求插件声明输入当已启用 UI 插件的模块导出formkit.inputs内含 FormKit 输入定义时Halo 必须在对应 key 下注册该输入定义供 FormKit Schema 使用插件省略 FormKit 配置当插件模块未导出formkit时Halo 应照常加载插件不要求任何 FormKit 专属配置即该字段完全可选保证向后兼容懒加载输入组件插件在同步的formkit.inputs对象内使用懒加载 Vue 组件创建输入定义时Halo 应直接接受该定义而不要求提供异步的输入工厂函数。2. 契约的 TypeScript 形态从 UI 共享类型库 ui/packages/shared/src/plugin/types/ui-plugin-module.ts 可以看到该契约的类型定义/** * FormKit-related extensions provided by a UI plugin. */ export interface PluginFormKit { /** * Custom FormKit input definitions registered when the plugin is activated. * * remarks * The key is the FormKit input type used by $formkit in schemas. */ inputs?: Recordstring, FormKitTypeDefinition; }而PluginModule接口新增了可选的顶层命名空间export interface PluginModule { /** FormKit integrations provided by the plugin. */ formkit?: PluginFormKit; components?: Recordstring, Component; routes?: RouteRecordRaw[] | RouteRecordAppend[]; ucRoutes?: RouteRecordRaw[] | RouteRecordAppend[]; extensionPoints?: ExtensionPoint; }设计文档design.md明确指出之所以在插件模块顶层增加formkit命名空间是为了保持插件模块契约整洁并为未来可能的 FormKit 能力验证规则、主题、图标等预留空间本版本的第一个受支持属性仅为formkit.inputs。3. 最小可用示例在插件入口中使用createInput来自formkit/vue与definePlugin来自halo-dev/ui-shared注册自定义输入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 Schema例如插件设置表单定义中直接使用该类型- $formkit: myPluginInput name: customField label: 自定义字段需要再次强调的两点约束formkit.inputs仅支持同步对象映射如果需要懒加载输入组件请在输入定义内部使用defineAsyncComponent。异步输入工厂被明确排除在范围之外——设计文档的理由是异步工厂会显著复杂化启动时序与错误处理而其价值完全可以被异步 Vue 组件替代。该输入类型一旦注册将完整走 FormKit 的输入生命周期而不是被当作普通$cmp组件渲染。二、注册时机必须在安装 FormKit 之前完成收集1. 为什么时机如此关键Halo 前端通过defaultConfig({ inputs })安装全局 FormKit 插件FormKit 的全局输入库正是在defaultConfig调用期间创建的。此前setupComponents()会先于插件模块加载完成 FormKit 安装插件只能等 FormKit 装好后再注册组件、路由和扩展点无法把自己的输入类型塞进全局输入库。因此本规格要求Halo 必须在为已认证的 Console 与 User Center 会话安装全局 FormKit 插件之前完成插件 FormKit 输入的收集。2. 已认证用户与匿名用户的差异规格区分了两种启动路径场景启动路径已认证用户启动 Console / UC先加载已启用插件的 UI 模块 → 收集插件formkit.inputs→ 以内置输入 被接受的插件输入安装 FormKit匿名用户启动 Console / UC只安装内置输入在认证重定向流程之前不加载插件 FormKit 输入3. 源码中的启动顺序证据在 ui/console-src/main.ts 中可以清楚看到这条路径的分支async function initApp() { try { setupCoreModules({ app, router, platform: console, modules }); const currentUserStore stores.currentUser(); await currentUserStore.fetchCurrentUser(); // ... if (currentUserStore.isAnonymous) { setupAppComponents(); // 匿名只装内置输入 return; } await setupUserPermissions(app); await setupUiPluginRuntime({ // 已认证先加载插件模块 app, router, platform: console, setupComponents: setupAppComponents, registeredFormKitInputs: builtinFormKitInputs, }); // ... } // ... }其中setupComponents有componentsReady守卫保证只执行一次——也就是说FormKit 的安装只会发生在setupUiPluginRuntime内部完成的第一次setupComponents(...)调用时其 options 携带的formkitInputs是内置 已接受插件输入的合并结果从而实现真正意义的先收集、后安装。在 ui/src/setup/setupComponents.ts 中输入库合并顺序一目了然app.use( FormKit, defaultConfig({ ...FormKitConfig, inputs: { ...options.formkitInputs, // 插件输入先展开 ...builtinFormKitInputs, // 内置输入后展开 → 同名时内置输入覆盖插件 }, }) );4. 收集发生在加载与初始化分离之后ui/src/setup/setupModules.ts 的setupUiPluginRuntime是本能力的运行时中枢它先通过 provider 描述符统一加载 legacy IIFE 脚本与 ESM 模块Promise.allSettled并行等待样式、脚本与模块导入把能成功拿到PluginModule的插件放入loadedByName随后才逐个执行registerPluginModule注册组件、路由、扩展点。全部注册完成后才调用setupComponents({ formkitInputs: collectPluginFormKitInputs( registeredModules.filter((module) module.type plugin), registeredFormKitInputs ), });注意两点实现细节只有module.type plugin的模块参与 FormKit 输入收集主题等其他 provider 类型被排除在外传入的registeredFormKitInputs即builtinFormKitInputs用于在收集阶段就识别与内置输入的冲突详见下一节。这种加载 → 注册组件/路由 → 收集输入 → 安装 FormKit → 再安装其余组件的顺序正是设计文档所说拆分插件 bundle 加载与插件模块初始化从而既满足 FormKit 需要提前拿到输入库的要求又不改变既有的组件/路由初始化语义。三、命名冲突处理内置输入优先冲突插件被跳过并告警1. 规格要求插件输入与内置输入冲突插件声明了与 Halo 内置输入同名的输入类型时保留内置输入定义、跳过该插件输入并输出描述性警告插件输入彼此冲突多个启用插件声明同名输入时保留最先被接受的插件输入定义、跳过后续冲突定义并输出警告。这样既避免了插件篡改核心输入如select、attachment、secret的默认行为也保证即使插件选了冲突名字Console 与 User Center 依然可用。2. 收集算法的源码实现冲突检测逻辑集中在 ui/src/formkit/plugin-inputs.ts 的collectPluginFormKitInputs中。其核心思路是维护一张输入名 → 归属者映射表先以 Halo built-in inputs 占满内置输入名export function collectPluginFormKitInputs( sources: PluginFormKitInputSource[], registeredInputs: FormKitLibrary ): FormKitLibrary { const acceptedInputs: FormKitLibrary {}; const inputOwners new Mapstring, string(); // 1) 先登记所有内置输入名所有者标记为 Halo built-in inputs for (const inputName of Object.keys(registeredInputs)) { inputOwners.set(inputName, Halo built-in inputs); } for (const source of sources) { const formkit (source.module as { formkit?: unknown }).formkit; if (formkit undefined || formkit null) continue; if (!isRecord(formkit)) { warn(Skipped plugin ${source.name} FormKit config because it is not an object.); continue; } // ... 校验 formkit.inputs 为对象 ... for (const [inputName, inputDefinition] of Object.entries(inputs)) { if (!isFormKitInputDefinition(inputDefinition)) { warn(Skipped FormKit input ${inputName} from plugin ${source.name} because it is not a valid input definition.); continue; } const existingOwner inputOwners.get(inputName); if (existingOwner) { warn(Skipped FormKit input ${inputName} from plugin ${source.name} because it conflicts with ${existingOwner}.); continue; } acceptedInputs[inputName] inputDefinition; inputOwners.set(inputName, plugin ${source.name}); } } return acceptedInputs; }算法逐条对应规格行为先到先得inputOwners一旦被插件占用后续同名输入都会被existingOwner分支拦截并warn跳过、保留先接受者内置永远优先因为内置名预先占位任何同名插件输入在第一次出现时就已被拒绝并在setupComponents的合并展开顺序{...options.formkitInputs, ...builtinFormKitInputs}中再做一层兜底后展开的内置输入最终覆盖防御性校验isFormKitInputDefinition要求定义是普通对象、带字符串type、且包含schema或component不满足即跳过告警格式统一输出带[Halo FormKit]前缀的console.warn方便在浏览器控制台定位冲突来源。因此在插件中设计输入名时规格与官方文档都建议使用带插件标识的名称例如myPluginInput、myCompanyColorPicker以最大限度降低与内置输入或其他插件的撞名概率。四、加载失败兜底核心 UI 不被插件拖垮FormKit 输入收集发生在插件 bundle 加载成功之后而插件加载本身可能失败。规格要求当 Halo 在收集插件 FormKit 输入时无法加载已启用的插件 UI bundle应只以内置输入安装 FormKit继续核心 UI 启动并复用既有的插件 bundle 加载失败通知行为。从 ui/src/setup/setupModules.ts 的实现看这一兜底有两层保障模块解析失败legacy 脚本无对应全局PluginModule、ESM 模块缺少 default 导出、provider 描述符判定为invalid等都会进入report(...)记录诊断并把该插件从 FormKit 输入收集的registeredModules中剔除——失败的插件不会参与collectPluginFormKitInputs自然也不会阻断后续setupComponents对 FormKit 的安装最外层兜底如果连fetchProviders拉取 UI provider 描述符的接口见consoleApiClient.uiPlugin.fetchUiPluginProviders都失败则直接setupComponents()仅内置输入并notifyPluginLoadError(error)后返回核心 UI 照常挂载。随后若存在样式或入口加载失败会通过Toast.error抛出对应国际化文案core.plugin.loader.toast.style_load_failed/entry_load_failed即既有插件 bundle 加载失败通知行为。五、共享formkit/vue运行时插件与 Halo 使用同一个 FormKit1. 规格要求插件输入的createInput等工厂来自formkit/vue。如果插件 bundle 各自打包一份 FormKit会带来重复实例与生命周期错乱。因此规格要求Halo 将formkit/vue暴露为共享的 UI 插件运行时 external。当插件从formkit/vue导入createInput时插件打包器应将其外部化使插件使用 Halo 在 Console / UC 中共享的formkit/vue运行时。2. 实现证据在 ui/packages/ui-plugin-bundler-kit/src/constants/externals.ts 中可以确认映射formkit/vue: FormKitVue,插件在构建时对formkit/vue的导入会被外部化并指向 Halo 全局共享的FormKitVue运行时保证只有一份 FormKit 实例。设计文档进一步说明边界本次仅把formkit/vue加入运行时 externalformkit/core只可能作为导出类型的类型级依赖出现而formkit/inputs的运行时辅助函数不在本次共享 external 范围内。从兼容性角度把formkit/vue作为 external 意味着插件输入与 Halo 的 FormKit 主版本产生生命周期层面的耦合这是有意为之——插件 FormKit 输入应当使用 Halo 提供的 FormKit 运行时。建议插件作者在文档中明确这一前提。六、设计取舍、范围边界与迁移1. 为何不采用扩展点机制设计文档记录了一个被否定的备选方案新增诸如formkit:inputs:create的扩展点。否定理由是FormKit 输入注册属于启动期配置而非按视图触发的运行时扩展扩展点机制会引入不必要的异步与重复执行问题。因此最终选择在PluginModule上声明formkit.inputs这种声明式的同步数据契约。2. 明确不在范围内的能力Non-Goals为避免功能蔓延本次规格明确不支持插件提供的 FormKit 插件、验证规则、主题、locale、图标要求插件输入类型名携带命名空间前缀仅建议不强制异步的formkit.inputs工厂函数为插件输入运行时渲染包裹自定义错误边界任何后端插件 API、OpenAPI 契约或数据库 Schema 的变更。3. 迁移与回滚formkit是可选字段存量插件无需迁移既有的$cmpSchema 用法、插件组件、路由与扩展点继续正常工作。需要 FormKit 生命周期能力的插件作者只需按上文方式 opt-in。回滚同样简单移除可选的formkit契约处理与formkit/vueexternal 映射即可未 opt-in 的插件完全不受影响。七、配套资料与速查围绕该主题仓库内可进一步阅读的配套资料插件端完整自定义输入教程含内置输入清单与select/list/repeater的完整参数表与 Schema 示例ui/docs/custom-formkit-input/README.md前端类型契约与PluginFormKit接口ui/packages/shared/src/plugin/types/ui-plugin-module.tsFormKit 输入收集与冲突判定实现ui/src/formkit/plugin-inputs.ts内置输入定义注册于builtinFormKitInputsui/src/formkit/inputs插件运行时装配与收集调用点ui/src/setup/setupModules.tsFormKit 安装与输入合并顺序ui/src/setup/setupComponents.tsConsole 启动入口的匿名/已认证分支ui/console-src/main.ts。最终在使用插件自定义 FormKit 输入时可按下面清单自查输入名是否与内置输入select、attachment、secret、repeater、list等或先加载插件冲突是则需改名否则会被静默跳过并在控制台出现[Halo FormKit]警告formkit.inputs是否是同步对象懒加载请用defineAsyncComponent包裹在输入定义内而不是使用异步工厂插件模块是否以PluginModule形态正确导出ESM 需 default 导出加载失败会导致插件输入不可用但不会拖垮核心 UI确认从formkit/vue导入createInput等运行时 API使其在构建时被外部化并复用 Halo 的共享 FormKit 运行时。【免费下载链接】haloHalo 是一款强大易用的开源建站工具从个人博客、知识库到企业官网、在线商城Halo 都能助您轻松实现一站式满足您的多样化建站需求。项目地址: https://gitcode.com/GitHub_Trending/ha/halo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考