NocoBase 区块插件实战：定义 SimpleBlockModel、注册模型并用 Flow 实现可配置渲染

NocoBase 区块插件实战定义 SimpleBlockModel、注册模型并用 Flow 实现可配置渲染【免费下载链接】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 仓库中的官方示例插件nocobase-example/plugin-simple-block为主线完整演示如何编写第一个区块Block插件从继承BlockModel实现渲染逻辑、通过define与registerModels注册区块到使用registerFlow在beforeRender阶段挂载表单让用户在界面上直接编辑区块内容。读完本文你可以按步骤复刻出一个可配置、可多语言i18n的自定义区块并理解每个 API 在仓库源码中的真实落点。前置准备先了解插件基础编写区块插件的前提是理解 NocoBase 插件的基本结构与生命周期如Plugin基类、load()方法、client/server双端目录约定建议先阅读「编写第一个插件」。区块插件与普通插件的最大区别在于它需要向前端的Flow Engine注册一个或多个模型Model模型负责声明区块的展示名称、渲染组件以及可交互的 Flow 步骤。仓库中已提供可直接对照运行的完整示例示例插件目录plugin-simple-block客户端模型实现SimpleBlockModel.tsx模型注册入口models/index.ts示例插件的package.json声明了包名nocobase-example/plugin-simple-block并对nocobase/client、nocobase/client-v2、nocobase/server、nocobase/test均要求2.x版本见 package.json这也是本文所有代码适用的版本前提。插件整体结构client 侧才是核心查看示例插件源码其目录结构如下src/client/plugin.tsx客户端插件入口负责把模型注册进 Flow Enginesrc/client/models/SimpleBlockModel.tsx区块模型定义核心src/client/models/index.ts模型导出聚合src/client/locale.tsi18n 辅助函数tExpr的实现src/locale/zh-CN.json、src/locale/en-US.json多语言词条src/server/plugin.ts服务端插件桩本例为空实现服务端PluginSimpleBlockServer只是继承nocobase/server的Plugin并留空各生命周期钩子afterAdd、beforeLoad、load、install等说明一个纯展示型区块插件在服务端不需要额外逻辑其价值全部体现在客户端见 server/plugin.ts。第 12 步创建区块模型文件并实现渲染逻辑在插件目录下创建client/models/SimpleBlockModel.tsx定义并实现一个基础区块模型包括其渲染逻辑import { BlockModel } from nocobase/client; import React from react; import { tExpr } from ../locale; export class SimpleBlockModel extends BlockModel { renderComponent() { return ( div h1Hello, NocoBase!/h1 pThis is a simple block rendered by SimpleBlockModel./p /div ); } } SimpleBlockModel.define({ label: tExpr(Hello block), });这里有三个关键 API逐一说明BlockModel区块模型的基类从nocobase/client导入。重写renderComponent()即可控制区块在页面上的实际渲染内容返回任意 React 元素。define({ label })静态方法声明区块的元信息。label决定该区块在界面「添加区块」下拉菜单中显示的名称。tExpr(key)i18n 表达式函数让 label 等文案支持多语言。在示例仓库中它并非来自../utils而是在插件自身的locale.ts中基于 Flow Engine 的_tExpr封装而成命名空间为[pkg.name, client]即词条以插件包名 client为命名空间检索见 locale.ts。对应的中文词条Simple block → 简单区块等定义在 zh-CN.json 中。第 3 步注册区块模型模型写好之后必须导出并交给 Flow Engine。在client/models/index.ts中导出新创建的模型import { ModelConstructor } from nocobase/flow-engine; import { SimpleBlockModel } from ./SimpleBlockModel; export default { SimpleBlockModel, } as Recordstring, ModelConstructor;这里把模型集合显式断言为Recordstring, ModelConstructor键名SimpleBlockModel即 Flow Engine 中该模型的注册名ModelConstructor类型同样来自nocobase/flow-engine与仓库实际文件 models/index.ts 完全一致。随后客户端插件在load()生命周期中调用flowEngine.registerModels完成最终注册import { Plugin } from nocobase/client; import models from ./models; export class PluginSimpleBlockClient extends Plugin { async load() { this.flowEngine.registerModels(models); } }也就是说注册链路为SimpleBlockModel文件 →models/index.ts聚合导出 → 插件load()中this.flowEngine.registerModels(models)见 client/plugin.tsx。this.flowEngine是插件运行时挂载到客户端插件实例上的 Flow Engine 上下文也是后文registerFlow能力的载体。第 4 步激活并体验区块启用插件后在界面「添加区块」的下拉菜单中即可看到新增的Hello block中文环境显示为「简单区块」区块选项插入后区块按renderComponent()返回的内容渲染。值得注意的是仓库中该示例同时维护了src/client/与src/client-v2/两套客户端实现分别对应 NocoBase 的 v1 与 v2 前端两者的SimpleBlockModel.tsx逻辑完全相同仅基类导入源不同v1 从nocobase/client导入BlockModelv2 从nocobase/client-v2导入见 client-v2/SimpleBlockModel.tsx。如果你的插件同时面向双端前端需要同步维护这两份模型定义。第 5 步为区块添加配置能力Flow静态渲染只是起点。接下来通过Flow为区块添加可配置功能使用户可以在界面上编辑区块内容。继续编辑SimpleBlockModel.tsximport { BlockModel } from nocobase/client; import React from react; import { tExpr } from ../locale; export class SimpleBlockModel extends BlockModel { renderComponent() { return div dangerouslySetInnerHTML{{ __html: this.props.html }} /; } } SimpleBlockModel.define({ label: tExpr(Simple block), }); SimpleBlockModel.registerFlow({ key: flow1, title: tExpr(Simple Block Flow), on: beforeRender, steps: { editHtml: { title: tExpr(Edit HTML Content), uiSchema: { html: { type: string, title: tExpr(HTML Content), x-decorator: FormItem, x-component: Input.TextArea, }, }, defaultParams: { html: h3This is a simple block/h3 pYou can edit the HTML content./p, }, handler(ctx, params) { ctx.model.props.html params.html; }, }, }, });这段代码与仓库中的最终实现逐行对应SimpleBlockModel.tsx#L24-L48下面拆解registerFlow各参数的作用参数作用key: flow1Flow 的唯一标识供 Flow Engine 内部区分不同 Flow 配置titleFlow 的显示名称出现在区块的配置入口中on: beforeRender触发时机。在渲染前执行因此用户提交配置后能立即影响区块的展示内容steps.editHtml一个表单步骤标题为「编辑 HTML 内容」uiSchema表单字段定义采用 Formily 风格x-decorator: FormItem指定装饰器x-component: Input.TextArea指定多行文本输入组件title为字段标签defaultParams表单默认值示例预填了一段 HTML 片段handler(ctx, params)提交回调。ctx.model即当前区块模型实例把表单值写入ctx.model.props.html工作流上handler写入的this.props.html正是renderComponent()通过dangerouslySetInnerHTML渲染的属性两者首尾呼应Flow 表单修改 props → 模型重新渲染 → 页面展示用户编辑后的 HTML。需要留意的是该示例直接使用原始 HTML 字符串渲染在生产插件中应改用受控的富文本组件并做必要的输入处理。小结与源码索引本文按照官方文档的五步流程完整覆盖了一个区块插件从创建到可配置的完整实现定义区块模型继承BlockModel重写renderComponent()用define({ label })声明名称注册区块模型models/index.ts聚合导出为Recordstring, ModelConstructor客户端插件在load()中调用this.flowEngine.registerModels(models)通过 Flow 添加配置能力registerFlow声明on: beforeRender的表单步骤uiSchema描述表单、defaultParams提供默认值、handler将表单值写回ctx.model.props驱动区块重新渲染。所有关键文件均可以在仓库中直接对照查看示例插件总入口plugin-simple-blockv1 客户端模型src/client/models/SimpleBlockModel.tsxv2 客户端模型src/client-v2/models/SimpleBlockModel.tsx模型导出src/client/models/index.ts插件注册src/client/plugin.tsxi18n 工具src/client/locale.ts中文词条src/locale/zh-CN.json【免费下载链接】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），仅供参考