NocoBase 插件开发速查表从“想做什么”到“写哪个文件、调哪个 API”的一站式定位指南【免费下载链接】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编写 NocoBase 插件时最常困扰开发者的不是某个 API 的细节而是“这个东西到底该写在哪个文件、调用哪个 API、继承哪个基类”。本文以官方插件开发速查表为主体结合仓库内nocobase/client-v2的Plugin基类源码与服务端collections等实现为你整理出一份从需求到落地的快速定位手册拿到需求后对照速查表即可确定代码放置位置、所需 API 与对应文档随后直接进入编码。插件目录结构先认清“代码该放哪”通过yarn pm create my-project/plugin-name创建插件会自动生成规范目录结构。不要手动创建目录否则容易遗漏注册步骤导致插件不生效。完整的创建与开发流程见 编写第一个插件。plugin-name/ ├── src/ │ ├── client-v2/ # 客户端代码v2 │ │ ├── plugin.tsx # 客户端插件入口 │ │ ├── locale.ts # useT / tExpr 翻译 hook │ │ ├── models/ # FlowModel区块、字段、操作 │ │ └── pages/ # 页面组件 │ ├── client/ # 客户端代码v1兼容 │ │ ├── plugin.tsx │ │ ├── locale.ts │ │ ├── models/ │ │ └── pages/ │ ├── server/ # 服务端代码 │ │ ├── plugin.ts # 服务端插件入口 │ │ └── collections/ # 数据表定义 │ └── locale/ # 多语言翻译文件 │ ├── zh-CN.json │ └── en-US.json ├── client-v2.js # 根目录入口构建产物指向 ├── client-v2.d.ts ├── client.js ├── client.d.ts ├── server.js ├── server.d.ts └── package.json几个值得注意的约定src/client-v2/是 v2 客户端代码的存放位置src/client/仅用于 v1 兼容两者都包含plugin.tsx、locale.ts、models/、pages/四个典型组成部分。src/server/collections/是服务端数据表定义目录约定式加载无需手动注册。根目录的client-v2.js/client.js/server.js是构建产物入口指向编译后的代码。从仓库实际脚手架看创建出的最小骨架在src/client-v2/下只有入口文件models/、locale.ts需要开发者自行新建见 编写第一个插件 第 2 步。客户端速查我想做什么 → 写在哪个文件 → 调什么 API我想做什么写在哪个文件调什么 API文档注册一个页面路由plugin.tsx的load()this.router.add()Router注册一个插件设置页plugin.tsx的load()pluginSettingsManager.addMenuItem()addPageTabItem()Router注册一个自定义区块plugin.tsx的load()this.flowEngine.registerModelLoaders()FlowEngine → 区块扩展注册一个自定义字段plugin.tsx的load()this.flowEngine.registerModelLoaders()FlowEngine → 字段扩展注册一个自定义操作plugin.tsx的load()this.flowEngine.registerModelLoaders()FlowEngine → 操作扩展让内部表出现在区块的数据表选择中plugin.tsx的load()mainDS.addCollection()Collections 数据表翻译插件的文案locale/zh-CN.jsonlocale/en-US.json—i18n 国际化所有客户端注册动作几乎都发生在plugin.tsx的load()生命周期中。从 Plugin.ts 源码 可以看到Plugin基类为插件实例注入了多个便捷 getterthis.router— 路由管理器对应app.routerthis.flowEngine别名this.engine— FlowEngine 实例用于注册 FlowModelthis.pluginSettingsManager— 插件设置页管理器this.context— 上下文对象与组件里的useFlowContext()返回同一个对象this.t()— 翻译方法自动以插件包名为命名空间this.app.i18n.t(text, { ns: this.options?.packageName })。页面路由与插件设置页路由注册通常放在load()中页面组件建议使用componentLoader按需加载访问时才加载模块且页面文件必须使用export default导出组件。v2 插件路由注册后会默认加上/v前缀async load() { // 注册一个独立页面访问 /v/hello this.router.add(hello, { path: /hello, componentLoader: () import(./pages/HelloPage), }); // 注册插件设置页先加菜单项再加页面 Tab this.pluginSettingsManager.addMenuItem({ key: hello-settings, title: this.t(Hello 设置), icon: SettingOutlined, }); this.pluginSettingsManager.addPageTabItem({ menuKey: hello-settings, key: index, title: this.t(Hello 设置), componentLoader: () import(./pages/HelloSettingPage), }); }NocoBase 已内置三条默认路由/v/admin/*后台管理页、/v/admin/:name动态页面、/v/admin/settings/*插件配置页插件注册的新路由与它们并行存在详见 Router 路由。注册区块 / 字段 / 操作区块、字段、操作三类可配置组件都通过this.flowEngine.registerModelLoaders()注册接收的是懒加载函数——模型只有在首次被真正使用时才会加载对应模块async load() { this.flowEngine.registerModelLoaders({ HelloBlockModel: { loader: () import(./models/HelloBlockModel), }, }); }键名HelloBlockModel必须与模型类名一致运行时按这个名字从模块的具名导出中取出模型类。详细机制见 FlowEngine 概述 与 Plugin 插件客户端。服务端速查我想做什么 → 写在哪个文件 → 调什么 API我想做什么写在哪个文件调什么 API文档定义一张数据表server/collections/xxx.tsdefineCollection()Collections 数据表扩展已有数据表server/collections/xxx.tsextendCollection()Collections 数据表注册自定义接口server/plugin.ts的load()this.app.resourceManager.define()ResourceManager配置接口权限server/plugin.ts的load()this.app.acl.allow()ACL 权限控制插件安装时写入初始数据server/plugin.ts的install()this.db.getRepository().create()Plugin 插件服务端新建数据表用defineCollection()扩展已有表用extendCollection()都放在src/server/collections/下// server/collections/articles.ts —— 定义新表 import { defineCollection } from nocobase/database; export default defineCollection({ name: articles, title: 示例文章, fields: [ { type: string, name: title, interface: input, uiSchema: { title: 标题, required: true } }, { type: text, name: content, interface: textarea, uiSchema: { title: 正文 } }, { type: belongsTo, name: author, target: users, foreignKey: authorId, interface: recordPicker, uiSchema: { title: 作者 }, }, ], });// server/collections/articles.extend.ts —— 为已有表增加字段 import { extendCollection } from nocobase/database; export default extendCollection({ name: articles, fields: [ { type: boolean, name: isPublished, defaultValue: false }, ], });激活插件后系统会自动同步字段到数据库表。注意代码定义的 Collection 通常是系统级元数据表不会出现在「数据源管理」的列表中这一点与界面建表不同详见 Collections 数据表。FlowModel 速查根据扩展类型选择基类NocoBase 界面上的区块、字段、操作按钮都由 FlowEngine 统一管理渲染、配置面板、配置持久化。开发者通过继承不同基类来扩展我想做什么继承什么基类关键 API做一个纯展示区块BlockModelrenderComponent()define()做一个绑定数据表的区块自定义渲染CollectionBlockModelcreateResource()renderComponent()做一个完整表格区块在内置表格基础上定制TableBlockModelfilterCollection()customModelClasses做一个字段展示组件ClickableFieldModelrenderComponent(value)bindModelToInterface()做一个操作按钮ActionModelstatic sceneregisterFlow({ on: click })各类基类的典型用法BlockModel纯展示区块——不依赖数据源实现renderComponent()并用define({ label })设置「添加区块」菜单中的显示名export class HelloBlockModel extends BlockModel { renderComponent() { return ( div h1Hello, NocoBase!/h1 pThis is a simple block rendered by HelloBlockModel./p /div ); } } HelloBlockModel.define({ label: tExpr(Hello block), });CollectionBlockModel数据表区块——自动处理数据获取用static scene声明区块场景BlockSceneEnum.many多条列表 /BlockSceneEnum.one单条详情表单createResource()创建数据资源this.resource.getData()取数export class ManyRecordBlockModel extends CollectionBlockModel { static scene BlockSceneEnum.many; createResource() { return this.context.makeResource(MultiRecordResource); } renderComponent() { return pre{JSON.stringify(this.resource.getData(), null, 2)}/pre; } }TableBlockModel完整表格区块——继承CollectionBlockModel自带字段列、操作栏、分页、排序只有在需要定制时才继承它例如用filterCollection限制只对特定数据表可用、用customModelClasses替换内置模型export class TodoBlockModel extends TableBlockModel { static filterCollection(collection: Collection) { return collection.name todoItems; } }ClickableFieldModel字段组件——renderComponent(value)接收当前字段值this.context.record获取当前行完整记录最后用bindModelToInterface()绑定到字段接口类型export class DisplaySimpleFieldModel extends ClickableFieldModel { public renderComponent(value) { return span[{value}]/span; } } DisplayItemModel.bindModelToInterface(DisplaySimpleFieldModel, [input]);ActionModel操作按钮——用static scene声明出现场景ActionSceneEnum.collection数据表级如新建、ActionSceneEnum.record记录级如编辑/删除、ActionSceneEnum.both两者皆可、ActionSceneEnum.all所有场景含弹窗等特殊上下文。场景值写在defaultProps的按钮文案里并通过registerFlow({ on: click })绑定点击流程。完整的基类选择逻辑与代码示例见 区块扩展、字段扩展、操作扩展。define() 常用元数据FlowModel.define()除了label菜单显示名支持tExpr()延迟翻译还支持icon、sort排序权重数字越小越靠前默认 0、hide是否隐藏支持函数动态判断、group分组、children子菜单项、toggleable、searchable等参数。大多数插件只需设置label。翻译方法速查不同场景用什么取翻译场景用什么从哪里导入Pluginload()里this.t(key)Plugin 基类自带React 组件里const t useT(); t(key)locale.tsFlowModel 静态定义define()、registerFlow()tExpr(key)locale.ts三者的取舍逻辑Plugin 实例内直接用基类自带的this.t()源码见 Plugin.ts自动带插件包名命名空间React 组件内通过useT()取翻译函数而define()、registerFlow()这类模块加载时就执行的静态定义i18n 尚未初始化必须用tExpr()做延迟翻译// src/client-v2/locale.ts —— 典型实现 import { tExpr as _tExpr, useFlowEngine } from nocobase/flow-engine; // ts-ignore import pkg from ../../package.json; export function useT() { const engine useFlowEngine(); return (str: string) engine.context.t(str, { ns: [pkg.name, client] }); } export function tExpr(key: string) { return _tExpr(key, { ns: [pkg.name, client] }); }多语言文案文件放在src/locale/zh-CN.json与src/locale/en-US.json中详见 i18n 国际化。常见 API 调用速查Plugin 内 vs 组件内我想做什么在 Plugin 里在组件里发 API 请求this.context.api.request()ctx.api.request()获取翻译this.t()useT()获取日志this.context.loggerctx.logger注册路由this.router.add()—页面导航—ctx.router.navigate()打开弹窗—ctx.viewer.dialog()关键区别Plugin 内的能力要么来自基类 getterthis.router、this.t()要么经由this.contextapi、logger组件内则统一从 Context 获取——useT()、ctx.api、ctx.logger、ctx.router.navigate()页面跳转、ctx.viewer.dialog()打开弹窗等。关于 Context 提供的完整能力清单见 Context 上下文 与 客户端开发概述。相关链接客户端开发概述 — 学习路径和快速索引Plugin 插件客户端 — 插件入口、生命周期afterAdd()→beforeLoad()→load()与常用属性编写第一个插件 — 从零创建插件骨架并完成注册常见问题 排错指南 — 踩坑排查Router 路由 — 页面路由与插件设置页注册FlowEngine → 区块扩展 — BlockModel 系列基类FlowEngine → 字段扩展 — FieldModel 开发FlowEngine → 操作扩展 — ActionModel 开发Collections 数据表服务端 — defineCollection 与字段类型i18n 国际化 — 翻译文件写法ResourceManager 资源管理服务端 — 自定义 REST APIACL 权限控制服务端 — 权限配置Plugin 插件服务端 — 服务端插件生命周期使用建议把本文作为开发时的第一站——拿到需求先对照速查表定位文件 API 文档再跳转到对应章节阅读完整示例写代码时记住两个原则——客户端注册动作集中在plugin.tsx的load()中v2 用registerModelLoaders懒加载注册模型服务端数据表与接口分别放在server/collections/与server/plugin.ts中。【免费下载链接】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），仅供参考