news 2026/9/12 12:56:55

ToolJet Circular Progressbar 组件完整指南：属性、样式与源码实现解析

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
ToolJet Circular Progressbar 组件完整指南：属性、样式与源码实现解析

ToolJet Circular Progressbar 组件完整指南：属性、样式与源码实现解析

【免费下载链接】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

Circular Progressbar（环形进度条）是 ToolJet 内置的可视化组件，用于在环形图形中展示任务进度、指标达成率或实时加载状态。本文以 2.50.0-LTS 版本文档为骨架，结合前端源码逐一讲解其属性、样式、动态配置（fx）用法及底层渲染原理，读完即可在自建内部工具或数据看板中正确配置并二次定制该组件。

组件概述

Circular Progressbar 组件以圆环形式显示进度。与线性进度条不同，它把进度百分比直观地"圈"出来，适合用在仪表盘卡片、任务执行进度、配额使用率等场景。在 ToolJet 应用编辑器中，从左侧组件面板拖入即可使用，默认尺寸为宽 7、高 50（见 widgets/circularProgressbar.js 中的defaultSize定义）。

该组件底层基于开源 SVG 库react-circular-progressbar实现，ToolJet 在其上封装了可视化配置面板、响应式显示、主题变量与动态绑定能力。

Properties（数据属性）

:::info 所有带有fx按钮的属性都可以通过 JavaScript 表达式进行程序化配置，实现数据驱动的动态更新。 :::

属性描述期望值
Text设置进度圆环内部显示的文本期望String类型，可使用 JS 随进度变化动态更新文本内容
Progress设置组件的进度值期望0 ~ 100之间的整数

从源码看这两个属性的实际行为

在组件配置中，progress字段的校验类型为number，默认值为50；text字段校验类型为string（见 widgets/circularProgressbar.js）。

值得注意的细节是：面板上的Label 开关（labelType，可选auto或custom）决定了文本的来源——在渲染组件中：

const label = labelType === 'custom' ? text : `${exposedVariablesTemporaryState.value}%`;

即：选择Auto时，圆环中央自动显示"进度值 + %"（如50%），无需手动维护文本；选择Custom时，才使用你填写的text字符串，例如可在Text中写{{ '完成率 ' + (progress * 100) + '%' }}这类 JS 表达式做动态拼接。这一行为由 CirularProgressbar.jsx 实现。

此外，配置面板还提供了文档未展开的两个数据属性：

属性说明默认值
Allow negative progress允许进度值为负数。开启后，负进度会取绝对值绘制，并使用独立的"负向"颜色，旋转方向也会翻转{{false}}
Loading state开启后进入加载态：圆环固定显示 25% 并持续旋转，等待数据就绪{{false}}

Component Specific Actions（CSA）

该组件目前没有实现组件专属动作（CSA），无法在事件处理器中直接调用类似setText的专属方法来控制组件。

不过从源码结构可以推断，ToolJet 为该组件注册了三个可编程控制点（定义于 widgets/circularProgressbar.js，并通过 CirularProgressbar.jsx 暴露给运行时）：

  • setValue(value)：动态修改进度值，参数默认{{50}}
  • setVisibility(value)：动态切换可见性，参数默认{{true}}
  • setLoading(value)：动态切换加载态，参数默认{{false}}

这些方法可在其他组件的事件（如按钮点击）中通过运行 JS 代码调用，实现对环形进度条的运行时控制。

Exposed Variables（暴露变量）

2.50.0-LTS 版本文档标注该组件"目前没有暴露变量"，但从源码结构看，组件实际向应用运行时暴露了以下变量（见 widgets/circularProgressbar.js）：

变量含义默认值
value当前进度值50
isVisible组件是否可见true
isLoading组件是否处于加载态false

这些变量可以在应用的其他位置（如文本组件、查询条件、图表数据源）中引用，例如在表格中显示{{components.circularprogressbar1.value}}来读取当前进度。暴露变量与 Progress 属性通过useBatchedUpdateEffectArray保持同步（见 CirularProgressbar.jsx）。

General（通用设置）

Tooltip（悬停提示）

Tooltip 常用于在鼠标悬停组件时展示补充信息。在General手风琴面板的 Tooltip 字段中填入字符串，悬停时即可显示该提示文本。例如填入当前任务完成进度，预览时将鼠标移到圆环上即可看到提示。

从组件配置看，Tooltip 还支持三种格式切换（tooltipFormat，可选Plain text、Markdown、HTML），默认值为Plain text；格式选项定义于 widgets/circularProgressbar.js。这意味着你可以在 Tooltip 字段中填写 Markdown 或 HTML 内容并切换对应格式以获得富文本提示效果。

Devices（设备显示）

属性描述期望值
Show on desktop控制组件在桌面端视图中是否可见通过开关按钮设置，或点击fx输入逻辑表达式动态配置
Show on mobile控制组件在移动端视图中是否可见通过开关按钮设置，或点击fx输入逻辑表达式动态配置

默认行为是桌面端显示（{{true}}）、移动端隐藏（{{false}}），见 widgets/circularProgressbar.js 中的definition.others。

Styles（样式）

属性描述期望值
Color定义进度弧线（stroke）的颜色HEX 颜色值或通过取色器选择
Text color定义圆环内文本的颜色HEX 颜色值或通过取色器选择
Text size定义文本字号取值范围0 ~ 100
Stroke width定义弧线宽度取值范围0 ~ 100
Counter clockwise是否逆时针绘制进度接受{{true}}与{{false}}，默认false
Circle ratio定义进度弧线占整个圆直径的比例接受数值，默认1
Visibility控制组件可见性可通过fx编程设置；为{{false}}时应用部署后组件不可见，默认{{true}}

样式参数的默认值与取值范围（源码级）

样式面板中的各项参数在 widgets/circularProgressbar.js 中均有明确的默认值与约束：

  • Color（进度弧线颜色）：默认var(--cc-primary-brand)，即跟随主题品牌色；
  • Track（轨道颜色）：默认var(--cc-surface3-surface)，用于绘制未填充的底色圆环；
  • Negative（负进度颜色）：默认var(--cc-error-systemStatus)，仅当开启"允许负进度"且值为负时生效；
  • Completion（完成色）：默认var(--cc-success-systemStatus)，当进度值>= 100时自动切换为该颜色，用于强调完成状态；
  • Text size：默认16，滑块控制；
  • Stroke width（面板中显示为 "Progress bar width"）：默认10，滑块控制；
  • Circle ratio：滑块控制，min = 0、max = 1、步长0.01，默认1（整圆）；调低该值可把圆环"切开"成半圆或任意弧度的仪表盘样式；
  • Alignment：圆环在画布容器内的水平对齐方式，可选左对齐、居中、右对齐，默认居中；
  • Box shadow：容器阴影，默认0px 0px 0px 0px #00000040；
  • Padding：容器内边距，可选default或none。

颜色决策逻辑（源码实现）

圆环弧线的最终颜色并不是固定的，而是由渲染层根据进度值动态计算（见 CirularProgressbar.jsx）：

value >= 100 → completionColor（完成色） 开启负进度且 value < 0 → negativeColor（负向色） 其余情况 → color（主色）

同时，负进度场景下进度值会取绝对值绘制，并且counterClockwise方向会临时取反，以保证负值弧线从相反方向生长；加载态则固定value = 25、circleRatio = 1并覆盖为品牌色。这些细节决定了"为什么我设置了颜色却不生效"之类的现象，排查样式时可优先核对进度值是否命中了上述分支。

加载态动画

加载态下的持续旋转由组件样式文件 circularProgressbar.scss 中的rotate-forever类驱动，动画为spin 1.2s linear infinite，即每 1.2 秒匀速旋转一圈；组件根节点则通过display: flex/none控制可见性。该 SCSS 同时将圆环宽度设为unset，使其在画布中按容器尺寸自适应。

底层依赖说明

Circular Progressbar 组件基于开源 SVG 库 react-circular-progressbar。在 ToolJet 中实际传给该库的关键参数为：

<CircularProgressbar value={value} text={text} strokeWidth={strokeWidth} counterClockwise={counterClockwise} circleRatio={circleRatio} styles={{ root: { height }, path: { stroke: color }, text: { fill: textColor, fontSize: textSize }, trail: { stroke: trackColor }, }} />

其中path（进度弧）、trail（轨道）、text（中心文本）分别对应面板中的 Color、Track、Text color 与 Text size 等样式项。若需要比面板更细粒度的定制（例如自定义圆角端点、弧线动画），可以参考该库文档，并留意其属性最终会被 ToolJet 的上述映射关系覆盖。

典型使用场景

  • 任务/批处理进度看板：将Progress绑定到后端查询返回的百分比字段，如{{queries.taskStatus.data.progress}}，圆环自动刷新；
  • 配额与指标卡：Circle ratio设为0.75制作 270° 弧形仪表，配合Text显示{{ '已用 ' + used + ' / ' + total }}；
  • 加载状态反馈：在数据查询运行期间将Loading state绑定为{{queries.task.isLoading}}，数据就绪后自动切回真实进度；
  • 完成态强调：将进度值推至100，圆环自动切换为主题成功色（Completion），无需额外写条件。

小结

Circular Progressbar 是 ToolJet 中"配置简单、表现力强"的进度展示组件：面板层提供文本、进度、设备可见性等数据属性，样式层提供弧线、轨道、文本、比例、方向与可见性控制；源码层则封装了负进度、完成态、加载态等高级行为。若需了解组件在其他版本中的差异，可对照 3.0.0-LTS 版本文档 与 最新文档；想深入阅读实现细节，可从 组件渲染实现 与 组件配置定义 入手。

【免费下载链接】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），仅供参考

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/9/12 12:52:37

基于Django的智慧医疗挂号系统设计与实践

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

作者头像 李华
网站建设 2026/9/12 12:51:39

LS信道估计与深度学习残差校正的一对一映射方法

简介&#xff1a;本资源是一份面向通信工程与人工智能交叉领域初学者及进阶研究者的实践型代码包&#xff0c;聚焦深度学习在无线信道估计中的落地应用&#xff0c;重点解决IS&#xff08;干扰抑制&#xff09;场景下传统估计算法精度受限的问题。压缩包共7个文件&#xff0c;含…

作者头像 李华
网站建设 2026/9/12 12:50:34

聚簇索引和非聚簇索引简介

聚簇索引&#xff0c;是对磁盘的数据按照一个或多个列进行重新排序的算法。 磁盘上数据的存储顺序与索引的顺序是一致的。 一般情况下&#xff0c;主键会默认创建聚簇索引。一张表中只能有一个聚簇索引。 所以&#xff0c;在MySQL中&#xff0c;一张表如果存在主键&am…

作者头像 李华
网站建设 2026/9/12 12:48:38

RK3588与RK3588S工业选型本质差异解析

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

作者头像 李华
网站建设 2026/9/12 12:47:01

Dapr 端到端测试编写指南：Test App 与 Test Driver 双角色实战

Dapr 端到端测试编写指南&#xff1a;Test App 与 Test Driver 双角色实战 【免费下载链接】dapr Dapr is a portable runtime for building distributed applications across cloud and edge, combining event-driven architecture with workflow orchestration. 项目地址: …

作者头像 李华
网站建设 2026/9/12 12:46:25

多巴胺消失了？从神经科学到成瘾机制，找回行动力与快乐

读《消失的多巴胺》时&#xff0c;我刚从一个“短视频循环”里挣扎出来。那天晚上我发现自己刷了近两个小时的短视频&#xff0c;完全停不下来&#xff0c;脑子却空得发麻。手机屏幕的光映在脸上&#xff0c;我对自己说“再看一条就睡”&#xff0c;但手指压根没停。第二天起床…

作者头像 李华