NocoBase 前端扩展点基石深入解析 client-v2 的 createFormRegistry 命名注册表【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobasecreateFormRegistry是 NocoBase 客户端框架nocobase/client-v2提供的一个轻量级「命名注册表」工厂函数专门用于解决插件内部同名、同形、不同实现的扩展项管理问题如文件存储类型、认证方式、消息发送通道。本文将以文档与源码实现为骨架讲解其基本用法、完整 API、适用与不适用场景并结合仓库源码揭示其底层原理与 HMR 设计取舍帮助你在插件开发中快速搭建自己的类型安全扩展点。什么是 createFormRegistry在插件开发中经常会出现一类需求同一业务位置上需要支持多种可插拔的实现且每种实现都遵循相同的结构。例如文件管理插件中的「存储类型」本地存储、Amazon S3 等、验证插件中的「OTP 发送通道」。如果直接用原生Map来管理这些条目往往会遇到三个问题缺少namespace 标识多个插件或模块之间的注册表容易互相污染重复注册时没有提示难以发现意外的覆盖API 形态不固定每个开发者都会写出一套风格迥异的增删改查逻辑。createFormRegistry正是为这一场景提供的统一原语。文档中对其定位的描述是一个轻量注册表适合插件内部有「同名、同形、不同实现」的扩展项比起直接用Map它多了 namespace 标识、重复注册提示以及更固定的 API。从源码实现看它的核心逻辑非常精简全部位于 createFormRegistry.tsexport interface FormRegistryEntry { name: string; } export interface FormRegistryT extends FormRegistryEntry { readonly namespace: string; register(entry: T): void; unregister(name: string): boolean; get(name: string): T | undefined; has(name: string): boolean; list(): T[]; } export function createFormRegistryT extends FormRegistryEntry(namespace: string): FormRegistryT { const entries new Mapstring, T(); return { namespace, register(entry) { if (entries.has(entry.name)) { console.warn([${namespace}] entry ${entry.name} already registered, overwriting.); } entries.set(entry.name, entry); }, unregister(name) { return entries.delete(name); }, get(name) { return entries.get(name); }, has(name) { return entries.has(name); }, list() { return Array.from(entries.values()); }, }; }可以看到createFormRegistry的完整实现在一个 60 行左右的函数内即可完成它接受一个namespace字符串内部以闭包持有独立的Mapstring, T每次调用都会返回一个全新的、互不共享状态的 registry 实例。这个设计与文档中每次调用返回一个独立的 registry 实例闭包持有自己的Map的描述完全一致。该文件经由 index.tsx 中的export * from ./createFormRegistry对外导出因此插件开发者可以直接从nocobase/client-v2顶层导入使用。基本用法为存储类型建立注册表文档给出的基本用法以「文件存储类型」为例先定义一个继承自FormRegistryEntry的接口再用createFormRegistry创建注册表并注册多个实现import { createFormRegistry, type FormRegistryEntry } from nocobase/client-v2; interface StorageType extends FormRegistryEntry { title: string; Component: React.ComponentType; } const storageTypes createFormRegistryStorageType(file-manager/storage-types); storageTypes.register({ name: local, title: Local, Component: LocalStorageForm }); storageTypes.register({ name: s3, title: Amazon S3, Component: S3StorageForm }); const s3 storageTypes.get(s3); const all storageTypes.list();代码中的几个要点name是必填字段FormRegistryEntry接口要求每条记录至少包含name: string它充当注册表内查找的唯一键泛型约束StorageType extends FormRegistryEntry自定义字段如这里的title和Component被追加到基础结构上从而让整个注册表具备类型安全——注册、获取、遍历返回的都是StorageType而非任意对象namespace 与业务解耦file-manager/storage-types作为命名空间标识在重复注册的警告信息中会原样输出见源码console.warn中的[${namespace}]前缀便于开发者快速定位是哪个模块发生了覆盖。在nocobase/client-v2组件的中文 READMEREADME.zh-CN.md中官方还补充了一个完整调用链示例注册完local、s3后可以通过storageTypes.get(s3)获取单条、storageTypes.list()列出全部、storageTypes.has(local)判断存在性、storageTypes.unregister(local)删除条目。这五种操作恰好覆盖了注册表的核心使用面。API 参考五个方法的语义与返回值文档将 API 归纳为一张方法表结合源码实现可以进一步明确每个方法的精确语义与返回值方法说明返回值源码确认register(entry)注册一条记录void若name已存在则先console.warn再覆盖unregister(name)删除一条记录booleanMap.delete的返回值不存在时返回falseget(name)按 name 获取记录T \| undefined未命中时返回undefinedhas(name)判断是否存在booleanlist()返回所有记录T[]通过Array.from(entries.values())生成数组其中两个细节值得注意unregister返回布尔值这是原生Map.delete的透传结果调用方可以用它判断删除是否真正发生list()返回的是值数组Array.from(entries.values())会把Map中的条目按插入顺序平铺成数组便于直接交给map/filter等数组方法渲染 UI。因为Map本身保持插入顺序所以注册顺序即list()的返回顺序。重复注册覆盖 console.warn 的设计取舍文档特别强调了重复注册的行为重复的name会覆盖旧值并输出console.warn。源码中的实现为register(entry) { if (entries.has(entry.name)) { console.warn([${namespace}] entry ${entry.name} already registered, overwriting.); } entries.set(entry.name, entry); }这是一个经过权衡的设计对 HMR 友好开发期热更新Hot Module Replacement会反复执行模块代码如果重复注册直接抛错HMR 场景下页面会频繁报错甚至崩溃选择覆盖 警告则能保证热更新平滑进行开发期可见性警告信息同时包含 namespace 和冲突的name让意外的重复注册在开发期就能被察觉而不是等到运行时出现难以排查的覆盖问题。什么时候用适用与不适用的判断标准文档为开发者划定了清晰的决策边界。适合用createFormRegistry的场景插件需要暴露内部扩展点允许其他插件或插件内部多个模块向同一位置注册实现扩展项具有统一结构可以通过继承FormRegistryEntry的类型约束来表达调用方只需要按name查找或渲染即注册表的使用模式足够简单。不适合用的场景只是页面里的临时状态例如组件内部的局部数据用 React 自身的 state 或 context 即可不需要全局注册表扩展项强绑定业务流程外部插件不会复用此时引入注册表只会增加不必要的抽象层需要权限、排序、生命周期等复杂管理能力——createFormRegistry刻意保持轻量只提供注册、查询、遍历五类基本操作复杂的管理需求应选择更重的扩展机制。源码视角命名空间隔离与状态边界从 createFormRegistry.ts 的实现可以提炼出两个关键的工程特性其一闭包隔离保证多实例互不干扰。每个createFormRegistry(namespace)调用都会创建一个新的Map且该Map只被返回的 registry 对象通过闭包引用。因此即使两个插件都调用createFormRegistry只要它们各自持有自己的实例就不会共享任何注册数据。这也意味着 registry 实例本身是模块级还是组件级状态完全由使用者决定——通常推荐像文档示例那样在模块顶层创建一次作为插件内部的单例扩展点。其二namespace 是标识而非隔离机制。namespace 参数主要出现在重复注册的警告信息中用于人肉定位冲突来源真正的数据隔离依靠的是每次调用返回独立实例这一闭包机制。从源码结构看可以推断官方刻意避免用全局 Map namespace 做键的方式正是为了让插件之间不隐式共享状态保持扩展点注册的显式与可控。在插件开发中落地最小可运行模板综合文档与源码一个可复用的插件内部扩展点模板如下// 1. 定义扩展项结构必须继承 FormRegistryEntry import { createFormRegistry, type FormRegistryEntry } from nocobase/client-v2; export interface NotifyChannel extends FormRegistryEntry { label: string; send: (payload: { to: string; content: string }) Promisevoid; } // 2. 模块级创建命名注册表单例扩展点 export const notifyChannels createFormRegistryNotifyChannel(notification/channels); // 3. 其他模块/插件向扩展点注册实现 notifyChannels.register({ name: email, label: Email, send: async ({ to, content }) { /* 邮件发送实现 */ }, }); notifyChannels.register({ name: sms, label: SMS, send: async ({ to, content }) { /* 短信发送实现 */ }, }); // 4. 调用方按 name 查找并按统一结构渲染/调用 const channel notifyChannels.get(email); if (channel) { await channel.send({ to: userexample.com, content: Hello }); } for (const c of notifyChannels.list()) { console.log(c.label, c.name); // 遍历所有已注册实现 }这段模板完整串联了文档中的基本用法与 API定义结构 → 创建注册表 → 注册实现 → 按名查找/遍历渲染。在 NocoBase 插件中你只需把注册动作放在插件加载或组件挂载阶段执行即可。总结createFormRegistry是 NocoBaseclient-v2提供给插件开发者的一把小而精的扩展点工具。它以约 60 行源码实现了带命名空间、类型安全、重复注册告警、HMR 友好的条目注册表覆盖了同名、同形、不同实现扩展项管理的全部基础操作。对插件开发者而言掌握它意味着无需重复手写 Map 增删改查样板代码即可为文件存储、认证方式、消息通道等场景搭建出结构统一、调用方友好的内部扩展点同时通过console.warn在开发期捕获意外的重复注册。建议在动手前先通读 create-form-registry.md 原文与 createFormRegistry.ts 源码并结合 README.zh-CN.md 中工具一节的补充示例在自己的插件项目中实践一遍完整的注册-查找-渲染链路。【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 NocoBase 前端扩展点基石：深入解析 client-v2 的 createFormRegistry 命名注册表
NocoBase 前端扩展点基石深入解析 client-v2 的 createFormRegistry 命名注册表【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobasecreateFormRegistry是 NocoBase 客户端框架nocobase/client-v2提供的一个轻量级「命名注册表」工厂函数专门用于解决插件内部同名、同形、不同实现的扩展项管理问题如文件存储类型、认证方式、消息发送通道。本文将以文档与源码实现为骨架讲解其基本用法、完整 API、适用与不适用场景并结合仓库源码揭示其底层原理与 HMR 设计取舍帮助你在插件开发中快速搭建自己的类型安全扩展点。什么是 createFormRegistry在插件开发中经常会出现一类需求同一业务位置上需要支持多种可插拔的实现且每种实现都遵循相同的结构。例如文件管理插件中的「存储类型」本地存储、Amazon S3 等、验证插件中的「OTP 发送通道」。如果直接用原生Map来管理这些条目往往会遇到三个问题缺少namespace 标识多个插件或模块之间的注册表容易互相污染重复注册时没有提示难以发现意外的覆盖API 形态不固定每个开发者都会写出一套风格迥异的增删改查逻辑。createFormRegistry正是为这一场景提供的统一原语。文档中对其定位的描述是一个轻量注册表适合插件内部有「同名、同形、不同实现」的扩展项比起直接用Map它多了 namespace 标识、重复注册提示以及更固定的 API。从源码实现看它的核心逻辑非常精简全部位于 createFormRegistry.tsexport interface FormRegistryEntry { name: string; } export interface FormRegistryT extends FormRegistryEntry { readonly namespace: string; register(entry: T): void; unregister(name: string): boolean; get(name: string): T | undefined; has(name: string): boolean; list(): T[]; } export function createFormRegistryT extends FormRegistryEntry(namespace: string): FormRegistryT { const entries new Mapstring, T(); return { namespace, register(entry) { if (entries.has(entry.name)) { console.warn([${namespace}] entry ${entry.name} already registered, overwriting.); } entries.set(entry.name, entry); }, unregister(name) { return entries.delete(name); }, get(name) { return entries.get(name); }, has(name) { return entries.has(name); }, list() { return Array.from(entries.values()); }, }; }可以看到createFormRegistry的完整实现在一个 60 行左右的函数内即可完成它接受一个namespace字符串内部以闭包持有独立的Mapstring, T每次调用都会返回一个全新的、互不共享状态的 registry 实例。这个设计与文档中每次调用返回一个独立的 registry 实例闭包持有自己的Map的描述完全一致。该文件经由 index.tsx 中的export * from ./createFormRegistry对外导出因此插件开发者可以直接从nocobase/client-v2顶层导入使用。基本用法为存储类型建立注册表文档给出的基本用法以「文件存储类型」为例先定义一个继承自FormRegistryEntry的接口再用createFormRegistry创建注册表并注册多个实现import { createFormRegistry, type FormRegistryEntry } from nocobase/client-v2; interface StorageType extends FormRegistryEntry { title: string; Component: React.ComponentType; } const storageTypes createFormRegistryStorageType(file-manager/storage-types); storageTypes.register({ name: local, title: Local, Component: LocalStorageForm }); storageTypes.register({ name: s3, title: Amazon S3, Component: S3StorageForm }); const s3 storageTypes.get(s3); const all storageTypes.list();代码中的几个要点name是必填字段FormRegistryEntry接口要求每条记录至少包含name: string它充当注册表内查找的唯一键泛型约束StorageType extends FormRegistryEntry自定义字段如这里的title和Component被追加到基础结构上从而让整个注册表具备类型安全——注册、获取、遍历返回的都是StorageType而非任意对象namespace 与业务解耦file-manager/storage-types作为命名空间标识在重复注册的警告信息中会原样输出见源码console.warn中的[${namespace}]前缀便于开发者快速定位是哪个模块发生了覆盖。在nocobase/client-v2组件的中文 READMEREADME.zh-CN.md中官方还补充了一个完整调用链示例注册完local、s3后可以通过storageTypes.get(s3)获取单条、storageTypes.list()列出全部、storageTypes.has(local)判断存在性、storageTypes.unregister(local)删除条目。这五种操作恰好覆盖了注册表的核心使用面。API 参考五个方法的语义与返回值文档将 API 归纳为一张方法表结合源码实现可以进一步明确每个方法的精确语义与返回值方法说明返回值源码确认register(entry)注册一条记录void若name已存在则先console.warn再覆盖unregister(name)删除一条记录booleanMap.delete的返回值不存在时返回falseget(name)按 name 获取记录T \| undefined未命中时返回undefinedhas(name)判断是否存在booleanlist()返回所有记录T[]通过Array.from(entries.values())生成数组其中两个细节值得注意unregister返回布尔值这是原生Map.delete的透传结果调用方可以用它判断删除是否真正发生list()返回的是值数组Array.from(entries.values())会把Map中的条目按插入顺序平铺成数组便于直接交给map/filter等数组方法渲染 UI。因为Map本身保持插入顺序所以注册顺序即list()的返回顺序。重复注册覆盖 console.warn 的设计取舍文档特别强调了重复注册的行为重复的name会覆盖旧值并输出console.warn。源码中的实现为register(entry) { if (entries.has(entry.name)) { console.warn([${namespace}] entry ${entry.name} already registered, overwriting.); } entries.set(entry.name, entry); }这是一个经过权衡的设计对 HMR 友好开发期热更新Hot Module Replacement会反复执行模块代码如果重复注册直接抛错HMR 场景下页面会频繁报错甚至崩溃选择覆盖 警告则能保证热更新平滑进行开发期可见性警告信息同时包含 namespace 和冲突的name让意外的重复注册在开发期就能被察觉而不是等到运行时出现难以排查的覆盖问题。什么时候用适用与不适用的判断标准文档为开发者划定了清晰的决策边界。适合用createFormRegistry的场景插件需要暴露内部扩展点允许其他插件或插件内部多个模块向同一位置注册实现扩展项具有统一结构可以通过继承FormRegistryEntry的类型约束来表达调用方只需要按name查找或渲染即注册表的使用模式足够简单。不适合用的场景只是页面里的临时状态例如组件内部的局部数据用 React 自身的 state 或 context 即可不需要全局注册表扩展项强绑定业务流程外部插件不会复用此时引入注册表只会增加不必要的抽象层需要权限、排序、生命周期等复杂管理能力——createFormRegistry刻意保持轻量只提供注册、查询、遍历五类基本操作复杂的管理需求应选择更重的扩展机制。源码视角命名空间隔离与状态边界从 createFormRegistry.ts 的实现可以提炼出两个关键的工程特性其一闭包隔离保证多实例互不干扰。每个createFormRegistry(namespace)调用都会创建一个新的Map且该Map只被返回的 registry 对象通过闭包引用。因此即使两个插件都调用createFormRegistry只要它们各自持有自己的实例就不会共享任何注册数据。这也意味着 registry 实例本身是模块级还是组件级状态完全由使用者决定——通常推荐像文档示例那样在模块顶层创建一次作为插件内部的单例扩展点。其二namespace 是标识而非隔离机制。namespace 参数主要出现在重复注册的警告信息中用于人肉定位冲突来源真正的数据隔离依靠的是每次调用返回独立实例这一闭包机制。从源码结构看可以推断官方刻意避免用全局 Map namespace 做键的方式正是为了让插件之间不隐式共享状态保持扩展点注册的显式与可控。在插件开发中落地最小可运行模板综合文档与源码一个可复用的插件内部扩展点模板如下// 1. 定义扩展项结构必须继承 FormRegistryEntry import { createFormRegistry, type FormRegistryEntry } from nocobase/client-v2; export interface NotifyChannel extends FormRegistryEntry { label: string; send: (payload: { to: string; content: string }) Promisevoid; } // 2. 模块级创建命名注册表单例扩展点 export const notifyChannels createFormRegistryNotifyChannel(notification/channels); // 3. 其他模块/插件向扩展点注册实现 notifyChannels.register({ name: email, label: Email, send: async ({ to, content }) { /* 邮件发送实现 */ }, }); notifyChannels.register({ name: sms, label: SMS, send: async ({ to, content }) { /* 短信发送实现 */ }, }); // 4. 调用方按 name 查找并按统一结构渲染/调用 const channel notifyChannels.get(email); if (channel) { await channel.send({ to: userexample.com, content: Hello }); } for (const c of notifyChannels.list()) { console.log(c.label, c.name); // 遍历所有已注册实现 }这段模板完整串联了文档中的基本用法与 API定义结构 → 创建注册表 → 注册实现 → 按名查找/遍历渲染。在 NocoBase 插件中你只需把注册动作放在插件加载或组件挂载阶段执行即可。总结createFormRegistry是 NocoBaseclient-v2提供给插件开发者的一把小而精的扩展点工具。它以约 60 行源码实现了带命名空间、类型安全、重复注册告警、HMR 友好的条目注册表覆盖了同名、同形、不同实现扩展项管理的全部基础操作。对插件开发者而言掌握它意味着无需重复手写 Map 增删改查样板代码即可为文件存储、认证方式、消息通道等场景搭建出结构统一、调用方友好的内部扩展点同时通过console.warn在开发期捕获意外的重复注册。建议在动手前先通读 create-form-registry.md 原文与 createFormRegistry.ts 源码并结合 README.zh-CN.md 中工具一节的补充示例在自己的插件项目中实践一遍完整的注册-查找-渲染链路。【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考