做一个前后端联动的数据管理插件
前面的示例要么纯客户端(区块、字段、操作),要么客户端 + 简单接口(设置页)。这个示例展示一个更完整的场景——服务端定义数据表,客户端继承 TableBlockModel 获得完整的表格能力,再加上自定义字段组件和自定义操作按钮,组成一个有增删改查的数据管理插件。
这个示例把前面学到的区块、字段、操作串在一起,展示一个完整插件的开发流程。
建议先了解以下内容,开发时会更顺畅:
- 编写第一个插件 — 插件创建和目录结构
- Plugin 插件 — 插件入口和
load()生命周期 - FlowEngine → 区块扩展 — BlockModel、CollectionBlockModel、TableBlockModel
- FlowEngine → 字 段扩展 — ClickableFieldModel、bindModelToInterface
- FlowEngine → 操作扩展 — ActionModel、ActionSceneEnum
- i18n 国际化 — 翻译文件写法和
tExpr()用法 - 服务端开发概述 — 服务端插件基础
最终效果
我们要做的是一个「待办事项」数据管理插件,包含以下能力:
- 服务端定义一张
todoItems数据表,插件安装时自动写入示例数据 - 客户端继承
TableBlockModel,开箱即用的表格区块(字段列、分页、操作栏等) - 自定义字段组件——用彩色 Tag 渲染 priority 字段
- 自定义操作按钮——「新建待办」按钮,点击弹窗填写表单创建记录
完整源码见 @nocobase-example/plugin-custom-table-block-resource。如果你想直接在本地跑起来看效果:
下面从零开始,一步步搭建这个插件。
第一步:创建插件骨架
在仓库根目录执行:
详细说明见 编写第一个插件。
第二步:定义数据表(服务端)
新建 src/server/collections/todoItems.ts,NocoBase 会自动加载这个目录下的 collection 定义:
跟设置页示例不同,这里不需要手动注册 resource——NocoBase 会为每个 collection 自动生成标准的 CRUD 接口(list、get、create、update、destroy)。
第三步:配置权限和示例数据(服务端)
编辑 src/server/plugin.ts,在 load() 里配置 ACL 权限,在 install() 里插入示例数据:
几个关键点:
acl.allow()—['list', 'get', 'create', 'update', 'destroy']开放完整的增删改查权限,'loggedIn'表示登录用户即可访问install()— 只在插件首次安装时执行,适合用来写入初始数据this.db.getRepository()— 通过 collection 名称拿到数据操作对象- 不需要
resourceManager.define()——NocoBase 会为 collection 自动生成 CRUD 接口
第四步:创建区块模型(客户端)
新建 src/client-v2/models/TodoBlockModel.tsx。继承 TableBlockModel 可以直接获得完整的表格区块能力——字段列、操作栏、分页、排序等,不需要自己写 renderComponent。

实际插件开发中,如果不需要定制化 TableBlockModel 的话,其实可以不用继承和注册这个区块,直接让用户在添加区块的时候选择 「表格」即可。本文是为了展示区块模型的定义和注册流程,所以才写了一个 TodoBlockModel 来继承 TableBlockModel。TableBlockModel 会处理其余所有事情(字段列、操作栏、分页等)。
通过 filterCollection 限制这个区块只对 todoItems 数据表可用——用户添加「Todo block」时,数据表选择列表里只会出现 todoItems,不会出现其他不相关的表。

第五步:创建自定义字段组件(客户端)
新建 src/client-v2/models/PriorityFieldModel.tsx。用彩色 Tag 渲染 priority 字段,比纯文本直观得多:

注册后,在表格的 priority 列配置里,「字段组件」下拉菜单就能切换到「Priority tag」。
第六步:创建自定义操作按钮(客户端)
新建 src/client-v2/models/NewTodoActionModel.tsx。点击「新建待办」按钮后,用 ctx.viewer.dialog() 打开弹窗,填写表单后创建记录:

几个关键点:
ActionSceneEnum.collection— 按钮出现在区块顶部的操作栏on: 'click'— 通过registerFlow监听按钮的click事件ctx.viewer.dialog()— NocoBase 内置的弹窗能力,content接收一个函数,参数view可以调用view.close()关闭弹窗resource.create(values)— 调用数据表的 create 接口创建记录,创建后表格会自动刷新observable+observer— 用 flow-engine 提供的响应式状态管理替代useState,组件会自动响应formState.loading的变化
第七步:添加多语言文件
编辑插件的 src/locale/ 下的翻译文件:
初次添加语言文件需要重启应用才能生效。
关于翻译文件的写法和 tExpr() 的更多用法,详见 i18n 国际化。
第八步:在插件中注册(客户端)
编辑 src/client-v2/plugin.tsx。需要做两件事:注册模型,以及把 todoItems 注册到客户端数据源。
在插件代码里通过 addCollection 手动注册数据表是一种少见的做法,这里只是为了演示前后端联动的完整流程。实际项目中,数据表通常由用户在 NocoBase 界面上创建和配置,或者通过 API / MCP 等方式管理,不需要在插件客户端代码里显式注册。
通过 defineCollection 定义的表是服务端内部表,默认不会出现在区块的数据表选择列表中。通过 addCollection 手动注册后,用户在添加区块时就能选到 todoItems 了。

几个关键点:
registerModelLoaders— 按需加载注册三个模型:区块、字段、操作this.app.eventBus— 应用级事件总线,用于监听生命周期事件dataSource:loaded事件 — 数据源加载完成后触发。必须在这个事件回调里调用addCollection,因为ensureLoaded()会在load()之后运行,它会先清空再重新设置所有 collection——直接在load()里调用addCollection会被覆盖addCollection()— 把 collection 注册到客户端数据源。字段需要带interface和uiSchema属性,这样 NocoBase 才知道怎么渲染filterTargetKey: 'id'— 必须设置,指定用于唯一标识记录的字段(通常是主键)。如果不设置,collection 不会出现在区块的数据表选择列表中- 服务端的
defineCollection负责创建物理表和 ORM 映射,客户端的addCollection负责让 UI 知道这张表的存在——两边配合才能完成前后端联动
第九步:启用插件
启用后:
- 新建一个页面,点击「添加区块」,选择「Todo block」,绑定
todoItems数据表 - 表格会自动加载数据,显示字段列、分页等
- 在「配置操作」里添加「New todo」按钮,点击后弹窗填写表单创建记录
- 在 priority 列的「字段组件」里切换到「Priority tag」,priority 会用彩色 Tag 展示
完整源码
- @nocobase-example/plugin-custom-table-block-resource — 前后端联动数据管理插件完整示例
小结
这个示例用到的能力:
相关链接
- 编写第一个插件 — 从零创建插件骨架
- FlowEngine 概述 — FlowModel 基础用法和 registerFlow
- FlowEngine → 区块扩展 — BlockModel、TableBlockModel
- FlowEngine → 字段扩展 — ClickableFieldModel、bindModelToInterface
- FlowEngine → 操作扩展 — ActionModel、ActionSceneEnum
- 做一个自定义展示区块 — BlockModel 基础示例
- 做一个自定义字段组件 — FieldModel 基础示例
- 做一个自定义操作按钮 — ActionModel 基础示例
- 服务端开发概述 — 服务端插件基础
- 服务端 → Collections 数据表 — defineCollection 和 addCollection
- Resource API 速查表 — MultiRecordResource / SingleRecordResource 的完整方法签名
- Plugin 插件 — 插件入口和 load() 生命周期
- i18n 国际化 — 翻译文件写法和 tExpr 用法
- 服务端 → ACL 权限控制 — 权限配置
- 服务端 → Plugin 插件 — 服务端插件生命周期
- Context → 常用能力 — ctx.viewer、ctx.message 等
- Component 组件开发 — Antd Form 等组件用法
- FlowEngine 完整文档 — FlowModel、Flow、Context 的完整参考

