企业官网建设流程全解析

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 Engine
• src/client/models/SimpleBlockModel.tsx：区块模型定义（核心）
• src/client/models/index.ts：模型导出聚合
• src/client/locale.ts：i18n 辅助函数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）。

第 1～2 步：创建区块模型文件并实现渲染逻辑

在插件目录下创建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> <h1>Hello, NocoBase!</h1> <p>This 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 Record<string, ModelConstructor>;

这里把模型集合显式断言为Record<string, 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导入BlockModel，v2 从@nocobase/client-v2导入（见 client-v2/SimpleBlockModel.tsx）。如果你的插件同时面向双端前端，需要同步维护这两份模型定义。

第 5 步：为区块添加配置能力（Flow）

静态渲染只是起点。接下来通过Flow为区块添加可配置功能，使用户可以在界面上编辑区块内容。继续编辑SimpleBlockModel.tsx：

import { 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: `<h3>This is a simple block</h3> <p>You can edit the HTML content.</p>`, }, handler(ctx, params) { ctx.model.props.html = params.html; }, }, }, });

这段代码与仓库中的最终实现逐行对应（SimpleBlockModel.tsx#L24-L48），下面拆解registerFlow各参数的作用：

工作流上，handler写入的this.props.html正是renderComponent()通过dangerouslySetInnerHTML渲染的属性，两者首尾呼应：Flow 表单修改 props → 模型重新渲染 → 页面展示用户编辑后的 HTML。需要留意的是，该示例直接使用原始 HTML 字符串渲染，在生产插件中应改用受控的富文本组件并做必要的输入处理。

小结与源码索引

本文按照官方文档的五步流程，完整覆盖了一个区块插件从创建到可配置的完整实现：

1. 定义区块模型：继承BlockModel，重写renderComponent()，用define({ label })声明名称；
2. 注册区块模型：models/index.ts聚合导出为Record<string, ModelConstructor>，客户端插件在load()中调用this.flowEngine.registerModels(models)；
3. 通过 Flow 添加配置能力：registerFlow声明on: 'beforeRender'的表单步骤，uiSchema描述表单、defaultParams提供默认值、handler将表单值写回ctx.model.props，驱动区块重新渲染。

所有关键文件均可以在仓库中直接对照查看：

• 示例插件总入口：plugin-simple-block
• v1 客户端模型：src/client/models/SimpleBlockModel.tsx
• v2 客户端模型：src/client-v2/models/SimpleBlockModel.tsx
• 模型导出：src/client/models/index.ts
• 插件注册：src/client/plugin.tsx
• i18n 工具：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