如何为Total.js Flow编写自定义Web组件：从--components--目录入手的开发者指南-二趣网

如何为Total.js Flow编写自定义Web组件：从--components--目录入手的开发者指南

【免费下载链接】flowVisual Programming Interface项目地址: https://gitcode.com/gh_mirrors/flow29/flow

Total.js Flow 是一款基于 Total.js 的可视化编程与自动化平台（Visual Programming Interface），支持以拖拽方式编排数据流与监控任务。本文带你从--components--目录入手，快速学会为 Total.js Flow 编写自定义 Web 组件，让你的可视化流程拥有独有能力。

什么是 Total.js Flow 的 Web 组件？🧩

在 Total.js Flow 的设计器画布上，每一个可拖拽的"节点"就是一个Web 组件：它可以检查 URL 是否在线、监控日志关键字、连接 PostgreSQL 数据库，或者打印控制台信息。

组件的本质是一个 HTML 文件，内部同时包含：

后端逻辑（Node.js 环境执行）
配置表单（在 UI 中可编辑）
可视化区块（画布上的展示样式）

也就是说，一个文件 = 一个完整的流程节点，这对新手非常友好。

认识 --components-- 目录：内置组件大公开 📂

打开项目根目录下的--components--/文件夹，你会看到 Total.js Flow 自带的 6 个官方组件：

组件文件	功能
`--components--/checkurl.html`	检查 URL 是否在线
`--components--/checkfreespace.html`	检查服务器剩余磁盘空间
`--components--/checklog.html`	监控日志文件中的关键字
`--components--/checkpg.html`	检查 PostgreSQL 数据库连接
`--components--/console.html`	把 console 输出转发到 Web 控制台
`--components--/print.html`	打印流程中的数据

这些组件都属于 FlowStream 引擎的扩展体系，建议你先通读checkurl.html——它是所有组件中最简洁、最适合作为模板的一个。

解剖一个Web组件：5个区块一次看懂 🔍

以 URL 检查组件--components--/checkurl.html为例，每个组件文件都由 5 个标签区块组成：

1️⃣`<script total>`— 核心逻辑区

这是组件的"大脑"，定义了组件的元信息和行为：

exports.id：组件唯一标识（画布上引用它的名称）
exports.name/exports.icon/exports.group：显示名称、图标和分组
exports.config：默认配置项，会自动变成 UI 设置表单的初始值
exports.inputs/exports.outputs：定义节点的数据输入口和输出口
exports.npm：声明组件依赖的 npm 包（如checkpg组件声明了pg）
exports.make：组件实例化入口，负责注册消息处理函数

其中最重要的就是instance.message函数——每当有数据流入该节点，它就会触发一次。你可以在里面调用$.send('输出口', 数据)把结果传往下游节点，或调用$.destroy()销毁这条消息。

2️⃣`<readme>`— 说明文档区

组件在编辑器组件面板中显示的介绍文字，帮使用者理解节点用途。

3️⃣`<settings>`— 配置表单区

这里使用<ui-component name="input" path="?.字段名">这样的标签，把exports.config中的字段变成可视化输入框。例如checkurl组件把?.url和?.error两个字段暴露出来，用户双击节点就能修改，无需改任何代码。

4️⃣`<style>`— 样式区

通过.CLASS占位符注入组件专属 CSS，控制画布节点的外观。

5️⃣`<body>`— 可视化展示区

节点在画布上的"脸面"。$NAME、$ICON、$STATUS等占位符会自动替换，配合ui-bind组件还能用模板实时渲染运行状态（比如显示绿色的 ONLINE 徽章）。

编写你的第一个自定义Web组件：3步上手 🚀

第 1 步：复制模板

复制--components--/checkurl.html为mycomponent.html，放到--components--/目录下。

第 2 步：修改元信息与逻辑

把exports.id改成你的组件名，更新exports.name、exports.icon、exports.group，然后在exports.make中的instance.message函数里写入你的业务逻辑。需要用到 npm 包时，在exports.npm中声明即可。

第 3 步：设计配置项与表单

在exports.config中定义默认值，再在<settings>区块为每个字段添加<ui-component>输入框。这样用户就能在 UI 里直接调整参数，组件真正做到"零代码配置"。

💡 小技巧：想要实时显示运行状态，可以在消息处理中调用instance.status({...})，并在<body>里用ui-bind绑定$STATUS做模板渲染——checkfreespace组件的磁盘空间展示就是这么实现的。

常用 API 速查表 🧰

API	作用
`instance.message = function($)`	注册消息处理函数，数据流入时触发
`$.send(输出口, 数据)`	从指定输出口向下游发送数据
`$.destroy()`	销毁当前消息（流程到此结束）
`instance.status(对象)`	更新节点运行状态并刷新画布显示
`instance.configure()`	配置变更时重新加载参数
`instance.close()`	组件销毁前的清理钩子

此外，组件内部可以直接使用 Node.js 能力：require('pg')加载数据库驱动（见checkpg.html）、Total.Fs操作文件流（见checklog.html）、SHELL执行系统命令（见checkfreespace.html）等。

如何让 Flow 识别你的组件？加载机制说明 ⚙️

组件的加载由配置驱动：

在 config 文件中可设置components项，指向组件数据库的 db.json 地址；
前端设计器通过 controllers/default.js 中读取CONF.components获取组件列表；
界面层的 UI 组件则由 definitions/init.js 中的COMPONENTATOR()统一注册加载。

因此，把你的组件文件放入--components--/目录并按规范组织好 5 个区块后，即可通过组件数据库地址让 Flow 发现并使用它。

新手避坑最佳实践清单 ✅

id 必须全局唯一：exports.id是节点的身份标识，重复会导致画布混乱；
配置项给默认值：exports.config中提供合理默认值，用户体验更好；
错误走输出口：异常时通过$.send('error', 消息)输出，而不是直接抛异常中断流程；
及时销毁消息：处理完成后调用$.destroy()，避免消息在节点间空转；
依赖走 exports.npm：第三方包统一在exports.npm声明，保持环境一致；
参考源码学习：console.html展示了如何与 Web 端通信，print.html展示了数据序列化处理，都是优质范本。

🎉 到这里，你已经掌握了 Total.js Flow Web 组件的完整开发思路：一个 HTML 文件、五个区块、三步上手。动手改造--components--/checkurl.html，写出属于你的第一个自定义组件吧！

【免费下载链接】flowVisual Programming Interface项目地址: https://gitcode.com/gh_mirrors/flow29/flow

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析