ToolJet Bounded Box 组件实战图像标注、目标框选与 ML 数据集构建指南【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJetBounded Box 是 ToolJet 中用于图像标注的可视化组件支持在图片上绘制矩形框Bounding Box或打点Landmark两种方式对目标区域进行选择与标签化常用于构建机器学习训练数据集或对图像进行任意用途的标注。本文基于 ToolJet 3.0.0-LTS 版本文档与该组件在仓库中的源码实现完整讲解其配置属性、默认值数据结构、事件、暴露变量与样式控制并结合frontend/src/AppBuilder/Widgets/BoundedBox/下的实现代码说明标注坐标换算、越界保护与标签交互的底层原理帮助你把 Bounded Box 真正用起来并读懂其运行细节。组件定位与适用场景官方文档将 Bounded Box 定义为一个无限可定制的图像标注组件an infinitely customizable image annotation component矩形框选Bounding Box在图像上拖拽画出矩形区域框住某个目标点标注Landmarking以特定坐标点标记位置适合关键点标注场景典型用途为机器学习模型创建标注数据集或出于其他目的对图像做人工标注。组件的注册配置位于 boundedBox.js其中displayName为Bounded Boxdescription为 An infinitely customizable image annotation widget默认尺寸defaultSize为宽 30栅格单位× 高 420像素。配置中的actions: []为空数组与文档中目前没有实现任何 CSAComponent-Specific Actions的说明完全一致——该组件不提供组件专属动作交互能力完全由属性、事件和暴露变量承担。Properties 属性配置在画布中点击组件手柄打开右侧属性面板后核心配置项如下继承自 3.0.0-LTS 文档 Properties 表格属性说明期望值Image URL要显示在组件中的图片 URL 或图像数据可动态从数据库获取如{{queries.queryname.data[0].url}}也可使用图像的 base64 数据参见 loading-image-pdf-from-dbDefault valueApp 加载时叠加在图像上的默认标注数据对象数组字段见下文 Default value 数据结构Selector选择模式矩形或点点击fx设置值RECTANGLE或POINTList of labels标注时下拉框中显示的标签列表数组格式如{{[Tree, Car, Stree light]}}对照源码 boundedBox.js各属性在注册层还有以下实现细节imageUrl字段类型为code支持表达式动态取值schema 校验为string即图片地址必须是字符串URL 或 base64 数据selector字段类型为select下拉仅提供Rectangle - RECTANGLE与Point - POINT两个选项默认值RECTANGLE。组件内部按该值切换react-image-annotation的RectangleSelector与PointSelector见 BoundedBox.jsx 的 switch 分支非法取值会回退为RECTANGLElabelsschema 校验为元素是string或number的数组默认值{{[Car, Tree]}}。这些标签会渲染成标注后出现的下拉选项defaultValueschema 校验为string或元素为 object 的数组的联合类型允许静态数组或直接传入表达式。Default value 数据结构Default value用于在 App 加载时把预设标注叠加到图像上数据必须是对象数组。每个标注对象的字段定义如下字段说明期望值type标注类型RECTANGLE或POINTwidth框的宽度数值当type为POINT时设为0height框的高度数值当type为POINT时设为0x框在图像中的 x 坐标水平方向数值如41y框在图像中的 y 坐标垂直方向数值如22text标注文本必须是List of labels属性中提供的标签之一官方文档给出的默认值示例[ { type: RECTANGLE, width: 40, height: 24, x: 41, y: 12, text: Tree }, { type: POINT, width: 0, height: 0, x: 10.28, y: 81.14, text: Car } ]注册配置中的definition也内置了同样的默认演示数据一张含三个标注框的示例图片标签为Tree、Car、Stree light因此新建 Bounded Box 后即可直接看到效果。源码视角坐标换算与越界保护从 BoundedBox.jsx 的源码结构看defaultValue的处理逻辑比文档表格透露的更精细空值处理当defaultValue为空数组或未配置imageUrl时组件会清空所有标注并把暴露变量annotations置为空数组避免残留脏数据坐标体系组件监听图像load事件拿到容器实际宽高后对每个标注执行(item.x item.width) * (1/100) * outerDivWidth一类的换算并对x、y、width、height做 0–100 与负值的钳制clamp。据此可以推断标注坐标实际上是以**图像尺寸百分比0–100 区间**的方式参与布局的文档示例中x: 10.28、y: 81.14这类小数正是百分比语义下的精细定位而非绝对像素越界回收若某个框的右边缘x width或下边缘y height超出容器组件会先尝试把x/y平移到100 - width/100 - height以内若框本身尺寸超过 100则直接收缩width/height到剩余空间保证任何默认标注都不会画出图像边界ID 生成每个默认标注在进入渲染状态前都会生成一个uuid作为id这也是暴露变量中id字段系统生成的由来。Events 事件Bounded Box 暴露一个交互事件点击组件手柄打开属性面板展开Events折叠区并点击 Add handler即可绑定事件说明On change当用户在 Bounded Box 的选择器selector中切换下拉框的标签时触发源码层面该事件的触发路径清晰可查标注框画好后弹出的标签下拉框RenderEditor.jsx中选择标签时会把新标注geometrytextuuid追加进标注集合同步更新暴露变量后调用fireEvent(onChange)已存在标注的标签修改RenderHighlight.jsx以及点击垃圾桶图标删除某条标注同样都会先更新状态、再触发fireEvent(onChange)。也就是说尽管文档只描述标签变更一种情形从源码结构看新增、修改、删除标注三类写操作最终都收敛到On change事件可以把它当作标注数据已发生任何变更的统一钩子来使用例如把annotations的最新值提交回数据库。Exposed Variables 暴露变量Bounded Box 通过annotations变量把当前图像上的全部标注暴露给表达式系统每个元素代表一条标注包含以下键变量说明annotations对象数组每个对象表示图像上的一条标注含type、x、y、width、height、text、idannotations.type标注类型RECTANGLE或POINTannotations.xx 轴坐标annotations.yy 轴坐标annotations.width标注宽度annotations.height标注高度annotations.text为该标注选择的标签annotations.id标注的唯一 ID系统生成取值语法{{components.boundedbox1.annotations[0].text}} {{components.boundedbox1.annotations[1].width}}注册配置 boundedBox.js 中exposedVariables.annotations内置了一份含type、x、y、width、height、text、iduuid 字符串的示例数据供表达式补全系统提示。实现上暴露变量的内容由 BoundedBox.jsx 中的getExposedAnnotations生成——它把内部状态里geometrytype/x/y/width/height与datatext/id两层结构展开合并成扁平对象正好对应上表字段。任何标注增删改之后都会立即调用setExposedVariable(annotations, ...)刷新该变量因此表达式始终能读到最新标注集合。General 通用设置TooltipTooltip 用于在鼠标悬停组件时展示附加说明信息。为 Tooltip 赋值后悬停即显示指定字符串作为提示文本。该能力为所有组件通用设置后无需任何事件绑定由框架统一渲染提示气泡。Devices 设备适配属性说明期望值Show on desktop使组件在桌面视图中可见用开关按钮直接设置或点击fx输入逻辑表达式动态控制Show on mobile使组件在移动视图中可见用开关按钮直接设置或点击fx输入逻辑表达式动态控制从注册配置的definition看Bounded Box 新建时的设备默认为showOnDesktop: {{true}}、showOnMobile: {{false}}即默认只出现在桌面端需要移动端展示时手动打开对应开关。Styles 样式样式说明期望值Visibility控制组件加载时的显隐{{true}}或{{false}}默认{{true}}Disable开启后禁用组件禁止交互标注{{true}}或{{false}}默认{{false}}Box shadow设置组件外框的阴影横向/纵向偏移X、Y 滑杆、模糊与扩散半径、颜色表示 x、y、blur、spread 与颜色的值如9px 11px 5px 5px #00000040这三个样式项在源码中的落点同样明确BoundedBox.jsxvisibility直接决定根容器display: block或display: nonedisabledState映射到底层react-image-annotation的disableAnnotation属性禁用后画布不再响应新的绘制交互boxShadow原样作为内联样式注入根容器。源码实现速览基于 react-image-annotation整体实现链路目录frontend/src/AppBuilder/Widgets/BoundedBox/BoundedBox.jsx主组件。依赖第三方库react-image-annotation注入Annotation画布并传入renderSelector、renderEditor、renderHighlight三个自定义渲染钩子负责默认值解析、坐标换算、越界钳制与annotations暴露变量维护RenderSelector.jsx绘制过程中的选区样式——半透明白底 1px 红色边框的矩形给用户正在框选的视觉反馈RenderEditor.jsx框选完成瞬间渲染的标签下拉框。确认后生成带 uuid 的新标注并触发On changeRenderHighlight.jsx已提交标注的渲染。矩形标注为 3px 绿色边框 半透明灰色填充点标注在渲染时把 geometry 补成width: 2, height: 2并加 50% 圆角呈现为绿色圆点。每条标注旁边挂有可点击的垃圾桶按钮用于删除Box.jsx把标注 geometry 以百分比定位left/top/width/height均为%转换为绝对定位 div 的通用几何渲染器。这一实现解释了文档中的两条约束点标注的 width/height 必须为 0——因为点的大小由渲染层统一补齐为 2×2 像素text 必须来自 List of labels——因为下拉框的选项列表严格由labels属性生成组件不提供自由文本输入。落地建议数据来源图片地址优先用{{queries.queryname.data[0].url}}这类表达式从数据库驱动配合文档 loading-image-pdf-from-db 中的 base64 方案处理存储在库中的图片预置标注把已审核的标注以对象数组形式写入Default value注意POINT类型的width/height必须为0且坐标应控制在 0–100 区间内以获得最稳定的显示效果标签一致性Default value中每个标注的text要与List of labels保持一致避免下拉框初始值与可选项不匹配回写闭环在On change事件处理器中读取{{components.boundedbox1.annotations}}即可把完整的标注集合含系统生成的id序列化后提交到后端形成标注 → 事件 → 入库的数据集生产闭环无 CSA 约束该组件没有 Component-Specific Actions无法通过动作命令式地清空或添加标注清空请通过动态表达式把Default value置空数组添加则依赖用户交互完成。以上内容以当前仓库docs/versioned_docs/version-3.0.0-LTS/widgets/bounded-box.md文档为骨架源码佐证均来自frontend/src/AppBuilder/下可核查的文件可按文中路径继续深入。【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ToolJet Bounded Box 组件实战：图像标注、目标框选与 ML 数据集构建指南
ToolJet Bounded Box 组件实战图像标注、目标框选与 ML 数据集构建指南【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJetBounded Box 是 ToolJet 中用于图像标注的可视化组件支持在图片上绘制矩形框Bounding Box或打点Landmark两种方式对目标区域进行选择与标签化常用于构建机器学习训练数据集或对图像进行任意用途的标注。本文基于 ToolJet 3.0.0-LTS 版本文档与该组件在仓库中的源码实现完整讲解其配置属性、默认值数据结构、事件、暴露变量与样式控制并结合frontend/src/AppBuilder/Widgets/BoundedBox/下的实现代码说明标注坐标换算、越界保护与标签交互的底层原理帮助你把 Bounded Box 真正用起来并读懂其运行细节。组件定位与适用场景官方文档将 Bounded Box 定义为一个无限可定制的图像标注组件an infinitely customizable image annotation component矩形框选Bounding Box在图像上拖拽画出矩形区域框住某个目标点标注Landmarking以特定坐标点标记位置适合关键点标注场景典型用途为机器学习模型创建标注数据集或出于其他目的对图像做人工标注。组件的注册配置位于 boundedBox.js其中displayName为Bounded Boxdescription为 An infinitely customizable image annotation widget默认尺寸defaultSize为宽 30栅格单位× 高 420像素。配置中的actions: []为空数组与文档中目前没有实现任何 CSAComponent-Specific Actions的说明完全一致——该组件不提供组件专属动作交互能力完全由属性、事件和暴露变量承担。Properties 属性配置在画布中点击组件手柄打开右侧属性面板后核心配置项如下继承自 3.0.0-LTS 文档 Properties 表格属性说明期望值Image URL要显示在组件中的图片 URL 或图像数据可动态从数据库获取如{{queries.queryname.data[0].url}}也可使用图像的 base64 数据参见 loading-image-pdf-from-dbDefault valueApp 加载时叠加在图像上的默认标注数据对象数组字段见下文 Default value 数据结构Selector选择模式矩形或点点击fx设置值RECTANGLE或POINTList of labels标注时下拉框中显示的标签列表数组格式如{{[Tree, Car, Stree light]}}对照源码 boundedBox.js各属性在注册层还有以下实现细节imageUrl字段类型为code支持表达式动态取值schema 校验为string即图片地址必须是字符串URL 或 base64 数据selector字段类型为select下拉仅提供Rectangle - RECTANGLE与Point - POINT两个选项默认值RECTANGLE。组件内部按该值切换react-image-annotation的RectangleSelector与PointSelector见 BoundedBox.jsx 的 switch 分支非法取值会回退为RECTANGLElabelsschema 校验为元素是string或number的数组默认值{{[Car, Tree]}}。这些标签会渲染成标注后出现的下拉选项defaultValueschema 校验为string或元素为 object 的数组的联合类型允许静态数组或直接传入表达式。Default value 数据结构Default value用于在 App 加载时把预设标注叠加到图像上数据必须是对象数组。每个标注对象的字段定义如下字段说明期望值type标注类型RECTANGLE或POINTwidth框的宽度数值当type为POINT时设为0height框的高度数值当type为POINT时设为0x框在图像中的 x 坐标水平方向数值如41y框在图像中的 y 坐标垂直方向数值如22text标注文本必须是List of labels属性中提供的标签之一官方文档给出的默认值示例[ { type: RECTANGLE, width: 40, height: 24, x: 41, y: 12, text: Tree }, { type: POINT, width: 0, height: 0, x: 10.28, y: 81.14, text: Car } ]注册配置中的definition也内置了同样的默认演示数据一张含三个标注框的示例图片标签为Tree、Car、Stree light因此新建 Bounded Box 后即可直接看到效果。源码视角坐标换算与越界保护从 BoundedBox.jsx 的源码结构看defaultValue的处理逻辑比文档表格透露的更精细空值处理当defaultValue为空数组或未配置imageUrl时组件会清空所有标注并把暴露变量annotations置为空数组避免残留脏数据坐标体系组件监听图像load事件拿到容器实际宽高后对每个标注执行(item.x item.width) * (1/100) * outerDivWidth一类的换算并对x、y、width、height做 0–100 与负值的钳制clamp。据此可以推断标注坐标实际上是以**图像尺寸百分比0–100 区间**的方式参与布局的文档示例中x: 10.28、y: 81.14这类小数正是百分比语义下的精细定位而非绝对像素越界回收若某个框的右边缘x width或下边缘y height超出容器组件会先尝试把x/y平移到100 - width/100 - height以内若框本身尺寸超过 100则直接收缩width/height到剩余空间保证任何默认标注都不会画出图像边界ID 生成每个默认标注在进入渲染状态前都会生成一个uuid作为id这也是暴露变量中id字段系统生成的由来。Events 事件Bounded Box 暴露一个交互事件点击组件手柄打开属性面板展开Events折叠区并点击 Add handler即可绑定事件说明On change当用户在 Bounded Box 的选择器selector中切换下拉框的标签时触发源码层面该事件的触发路径清晰可查标注框画好后弹出的标签下拉框RenderEditor.jsx中选择标签时会把新标注geometrytextuuid追加进标注集合同步更新暴露变量后调用fireEvent(onChange)已存在标注的标签修改RenderHighlight.jsx以及点击垃圾桶图标删除某条标注同样都会先更新状态、再触发fireEvent(onChange)。也就是说尽管文档只描述标签变更一种情形从源码结构看新增、修改、删除标注三类写操作最终都收敛到On change事件可以把它当作标注数据已发生任何变更的统一钩子来使用例如把annotations的最新值提交回数据库。Exposed Variables 暴露变量Bounded Box 通过annotations变量把当前图像上的全部标注暴露给表达式系统每个元素代表一条标注包含以下键变量说明annotations对象数组每个对象表示图像上的一条标注含type、x、y、width、height、text、idannotations.type标注类型RECTANGLE或POINTannotations.xx 轴坐标annotations.yy 轴坐标annotations.width标注宽度annotations.height标注高度annotations.text为该标注选择的标签annotations.id标注的唯一 ID系统生成取值语法{{components.boundedbox1.annotations[0].text}} {{components.boundedbox1.annotations[1].width}}注册配置 boundedBox.js 中exposedVariables.annotations内置了一份含type、x、y、width、height、text、iduuid 字符串的示例数据供表达式补全系统提示。实现上暴露变量的内容由 BoundedBox.jsx 中的getExposedAnnotations生成——它把内部状态里geometrytype/x/y/width/height与datatext/id两层结构展开合并成扁平对象正好对应上表字段。任何标注增删改之后都会立即调用setExposedVariable(annotations, ...)刷新该变量因此表达式始终能读到最新标注集合。General 通用设置TooltipTooltip 用于在鼠标悬停组件时展示附加说明信息。为 Tooltip 赋值后悬停即显示指定字符串作为提示文本。该能力为所有组件通用设置后无需任何事件绑定由框架统一渲染提示气泡。Devices 设备适配属性说明期望值Show on desktop使组件在桌面视图中可见用开关按钮直接设置或点击fx输入逻辑表达式动态控制Show on mobile使组件在移动视图中可见用开关按钮直接设置或点击fx输入逻辑表达式动态控制从注册配置的definition看Bounded Box 新建时的设备默认为showOnDesktop: {{true}}、showOnMobile: {{false}}即默认只出现在桌面端需要移动端展示时手动打开对应开关。Styles 样式样式说明期望值Visibility控制组件加载时的显隐{{true}}或{{false}}默认{{true}}Disable开启后禁用组件禁止交互标注{{true}}或{{false}}默认{{false}}Box shadow设置组件外框的阴影横向/纵向偏移X、Y 滑杆、模糊与扩散半径、颜色表示 x、y、blur、spread 与颜色的值如9px 11px 5px 5px #00000040这三个样式项在源码中的落点同样明确BoundedBox.jsxvisibility直接决定根容器display: block或display: nonedisabledState映射到底层react-image-annotation的disableAnnotation属性禁用后画布不再响应新的绘制交互boxShadow原样作为内联样式注入根容器。源码实现速览基于 react-image-annotation整体实现链路目录frontend/src/AppBuilder/Widgets/BoundedBox/BoundedBox.jsx主组件。依赖第三方库react-image-annotation注入Annotation画布并传入renderSelector、renderEditor、renderHighlight三个自定义渲染钩子负责默认值解析、坐标换算、越界钳制与annotations暴露变量维护RenderSelector.jsx绘制过程中的选区样式——半透明白底 1px 红色边框的矩形给用户正在框选的视觉反馈RenderEditor.jsx框选完成瞬间渲染的标签下拉框。确认后生成带 uuid 的新标注并触发On changeRenderHighlight.jsx已提交标注的渲染。矩形标注为 3px 绿色边框 半透明灰色填充点标注在渲染时把 geometry 补成width: 2, height: 2并加 50% 圆角呈现为绿色圆点。每条标注旁边挂有可点击的垃圾桶按钮用于删除Box.jsx把标注 geometry 以百分比定位left/top/width/height均为%转换为绝对定位 div 的通用几何渲染器。这一实现解释了文档中的两条约束点标注的 width/height 必须为 0——因为点的大小由渲染层统一补齐为 2×2 像素text 必须来自 List of labels——因为下拉框的选项列表严格由labels属性生成组件不提供自由文本输入。落地建议数据来源图片地址优先用{{queries.queryname.data[0].url}}这类表达式从数据库驱动配合文档 loading-image-pdf-from-db 中的 base64 方案处理存储在库中的图片预置标注把已审核的标注以对象数组形式写入Default value注意POINT类型的width/height必须为0且坐标应控制在 0–100 区间内以获得最稳定的显示效果标签一致性Default value中每个标注的text要与List of labels保持一致避免下拉框初始值与可选项不匹配回写闭环在On change事件处理器中读取{{components.boundedbox1.annotations}}即可把完整的标注集合含系统生成的id序列化后提交到后端形成标注 → 事件 → 入库的数据集生产闭环无 CSA 约束该组件没有 Component-Specific Actions无法通过动作命令式地清空或添加标注清空请通过动态表达式把Default value置空数组添加则依赖用户交互完成。以上内容以当前仓库docs/versioned_docs/version-3.0.0-LTS/widgets/bounded-box.md文档为骨架源码佐证均来自frontend/src/AppBuilder/下可核查的文件可按文中路径继续深入。【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考