ToolJet Statistics 组件完全指南属性配置、样式定制与加载状态实战【免费下载链接】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/ToolJetStatistics 是 ToolJet 内置的统计信息展示组件用于在仪表盘或内部工具页面中以标签 数值 趋势的卡片形态呈现关键指标例如本月营收、环比变化、用户增长等。读完本文你将掌握 Statistics 组件在属性面板、样式面板中的全部配置项理解 Loading state 与查询isLoading的联动方式并了解其在前端源码中的真实渲染逻辑与默认值。本文基于 ToolJet 2.50.0-LTS 版本的官方文档widgets/statistics.md并结合仓库前端源码frontend/src/AppBuilder/Widgets/Statistics.jsx、frontend/src/AppBuilder/WidgetManager/widgets/statistics.js进行深化说明。组件定位与典型应用场景Statistics 组件的官方定义非常简洁Statistics can be used to display different statistical information.用于展示不同的统计信息。它是一个典型的只读型 KPI 卡片组件适合放在应用顶部或表格/图表上方快速传达关键数字。从组件注册信息看frontend/src/AppBuilder/WidgetManager/widgets/statistics.js其默认尺寸为width: 10、height: 152组件描述为Show key metrics展示关键指标这印证了它的核心用途就是关键指标卡。典型应用场景包括电商后台本月销售额主值 较上月增减次值运营看板DAU/MAU、转化率、订单量数据大屏与查询结果绑定自动展示最新统计结果。Properties属性配置详解在右侧属性面板Properties中Statistics 组件提供以下配置项属性说明Primary value label主值标签添加或移除主值上方的文字标签用于说明该统计项的名称。Primary value主值主值本身即实际数值例如682.3。Hide secondary value隐藏次值控制是否显示次值区域。默认关闭即默认显示次值。开启后隐藏次值也可点击旁边的fx按钮动态设置为{{true}}或{{false}}。Secondary value label次值标签添加或移除次值旁边的文字标签通常用于说明对比基准如 Last month上月。Secondary value次值次值本身通常表示变化量或对比值例如2.85。Secondary sign display次值正负符号为次值设置正positive或负negative符号用于表达上升或下降趋势。默认值为 positive。Loading state加载状态在组件上显示加载 spinner。常用于与查询的isLoading属性绑定在查询执行期间展示加载状态。可通过开关On启用或点击fx编程式设置为{{true}}或{{false}}。源码中的默认值从 widgets/statistics.js 的definition与properties配置可以看到组件拖入画布时的完整默认值属性默认值类型primaryValueLabelThis months earningscode字符串primaryValue682.3code字符串secondaryValueLabelLast monthcode字符串secondaryValue2.85code字符串secondarySignDisplaypositivecode字符串hideSecondaryfalsetoggle布尔loadingState{{false}}toggle布尔visibility{{true}}toggle布尔这些属性类型均为code意味着它们支持 JS 表达式{{...}}可以直接绑定查询结果、全局变量或组件状态实现数据驱动。Loading state 与查询联动实战重点文档明确指出 Loading state 最常用的做法是绑定查询的isLoading属性// 在属性面板中将 Loading state 的 fx 值设置为 {{queries.查询名称.isLoading}}当对应查询处于运行中时Statistics 组件会渲染加载指示器。查看渲染实现 Statistics.jsx当isLoading true时组件渲染一个 Bootstrap 风格的spinner-border转圈动画加载结束后自动恢复为统计数据卡片。同时源码还通过useBatchedUpdateEffectArray将loadingState的变化同步到暴露变量isLoading供其他组件或事件引用。组件专属动作CSA与暴露变量官方文档说明2.50.0-LTSComponent Specific Actions (CSA)当前版本文档声明尚无针对 Statistics 的组件专属动作Exposed Variables暴露变量当前版本文档声明尚无暴露变量。更新版本源码中的实现供参考需要说明的是上述无 CSA / 无暴露变量是针对 2.50.0-LTS 文档版本的结论。从当前仓库的前端源码对应更新的 ToolJet 版本看Statistics 组件已经实现了完整的暴露变量与组件方法体系Statistics.jsx暴露变量说明初始默认值primaryLabel主值标签文本This months earningssecondaryLabel次值标签文本Last monthprimaryValue主值682.3secondaryValue次值2.85secondarySignDisplay次值正负符号positiveisLoading加载状态falseisVisible可见状态true同时在 widgets/statistics.js 的actions中注册了四个可被事件触发的组件方法setPrimaryValue(text)—— 动态设置主值setSecondaryValue(text)—— 动态设置次值setLoading(loading)—— 动态切换加载状态参数为 togglesetVisibility(disable)—— 动态切换可见性参数为 toggle。如果你在使用更新版本的 ToolJet可以通过事件处理器如按钮的 On click调用这些方法例如{{components.statistics1.setPrimaryValue(1024)}}。若你的环境与 2.50.0-LTS 一致请以文档中无 CSA/无暴露变量的结论为准。General通用Tooltip 悬浮提示在General折叠面板下可以配置 Tooltip以字符串形式输入提示文本当用户将鼠标悬停在 Statistics 组件上时会显示该文本作为悬浮提示。从源码配置看widgets/statistics.jsTooltip 在更新的实现中还支持三种渲染格式plainText纯文本默认markdownMarkdownhtmlHTML。在 2.50.0-LTS 文档中Tooltip 以纯字符串形式配置即可满足大部分场景。Layout布局配置布局选项说明期望值Show on desktop桌面端显示开关控制组件是否在桌面视图中显示可通过fx编程式设置{{true}}或{{false}}Show on mobile移动端显示开关控制组件是否在移动视图中显示可通过fx编程式设置{{true}}或{{false}}这两个开关在源码中定义为others.showOnDesktop与others.showOnMobilewidgets/statistics.js默认值分别为{{true}}与{{false}}即默认在桌面端显示、移动端不显示。另外从更新版本源码看组件内部还提供了更细粒度的内容对齐配置本文档版本未列出但同属属性面板Data数据对齐left/center/right控制主值、标签的整体对齐方向Secondary value次值排列horizontal水平默认/vertical垂直Icon 与 Icon direction可为卡片配置图标默认IconDatabaseDollar并控制图标在左或右。Styles样式配置样式选项说明Primary label colour主标签颜色输入 Hex 色值或使用取色器修改主值标签的文字颜色。Primary text colour主文本颜色修改主值大数字的文字颜色。Secondary label colour次标签颜色修改次值标签的文字颜色。Secondary text colour次文本颜色修改次值的文字颜色。Visibility可见性控制组件整体是否可见。通过fx可编程式修改若为{{false}}应用部署后组件将不可见。默认值为{{true}}。样式面板的源码级扩展虽然 2.50.0-LTS 文档仅列出上述五项但当前仓库源码的样式定义widgets/statistics.js展示了更完整的样式体系按折叠面板分组如下Primary label and value主标签与主值样式键默认值说明primaryLabelSize14主标签字号pxprimaryLabelColourvar(--cc-placeholder-text)主标签颜色primaryValueSize34主值字号px渲染时作为主数字的fontSize且字重为 700Statistics.jsxprimaryTextColourvar(--cc-primary-text)主值颜色iconColorvar(--cc-primary-brand)图标颜色Secondary label and value次标签与次值样式键默认值说明secondaryLabelSize14次标签字号pxsecondaryLabelColourvar(--cc-placeholder-text)次标签颜色secondaryValueSize14次值字号pxpositiveSecondaryValueColorvar(--cc-success-systemStatus)次值为正时的颜色通常为绿色系negativeSecondaryValueColorvar(--cc-error-systemStatus)次值为负时的颜色通常为红色系Container容器样式键默认值说明backgroundColorvar(--cc-surface1-surface)卡片背景色borderColorvar(--cc-default-border)卡片边框颜色borderRadius6圆角pxboxShadow0px 0px 0px 0px #00000040盒阴影paddingdefault内边距可选default/none在渲染层Statistics.jsx组件外层容器会应用borderRadius、backgroundColor、border与boxShadow并通过display: flex组织主值区与次值区当加载状态为true或数据居中时内容会切换为纵向居中排列。此外次值区会根据secondarySignDisplay的值选择上箭头图标upstatistics正值或下箭头图标downstatistics负值并以胶囊形borderRadius: 58px容器展示配合正/负专用颜色强化趋势语义Statistics.jsx。:::info 任何带有fx按钮的属性都可以通过编程方式配置即在属性值中写入{{...}}表达式绑定查询结果、变量或组件状态。 :::实战构建一个绑定数据的 KPI 卡片综合上述配置一个完整的 Statistics 组件接入流程如下拖入组件从组件库Component Manager注册于 frontend/src/AppBuilder/WidgetManager/componentTypes.js将 Statistics 拖入画布创建查询新建一个查询如 Postgres/REST API用于统计营收数据绑定主值将Primary value的 fx 值设为{{queries.incomeQuery.data.total}}绑定次值与趋势将Secondary value设为环比变化量Secondary sign display用表达式根据正负动态返回positive或negative{{queries.incomeQuery.data.change 0 ? positive : negative}}绑定加载状态将Loading state的 fx 值设为{{queries.incomeQuery.isLoading}}查询运行时自动出现 spinner调整样式在 Styles 面板中按需设置主值字号、正/负颜色与容器外观更新版本动态更新若组件方法可用可在按钮事件中调用{{components.statistics1.setPrimaryValue(新值)}}实时刷新数值。验证与测试线索仓库的 Cypress 测试中Statistics 组件以statistics1、statistics2的实例名参与应用构建器的冒烟测试componentsBasicHappypath.skip.js说明它是应用构建器中常规校验的基础组件之一。如需了解组件如何被渲染、事件与暴露变量如何流转可继续阅读 Statistics.jsx 与 widgets/statistics.js 两个核心文件。小结Statistics 组件以极低的配置成本满足了关键指标展示这一高频需求主值 次值 趋势符号构成信息骨架Loading state 与查询isLoading天然联动样式面板提供了标签、数值、颜色、容器四层级的定制能力。对于 2.50.0-LTS 用户请以本文档列出的属性/样式表为准若使用更新版本还可借助源码中已实现的暴露变量与组件方法setPrimaryValue、setSecondaryValue、setLoading、setVisibility实现更灵活的交互控制。【免费下载链接】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 Statistics 组件完全指南：属性配置、样式定制与加载状态实战
ToolJet Statistics 组件完全指南属性配置、样式定制与加载状态实战【免费下载链接】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/ToolJetStatistics 是 ToolJet 内置的统计信息展示组件用于在仪表盘或内部工具页面中以标签 数值 趋势的卡片形态呈现关键指标例如本月营收、环比变化、用户增长等。读完本文你将掌握 Statistics 组件在属性面板、样式面板中的全部配置项理解 Loading state 与查询isLoading的联动方式并了解其在前端源码中的真实渲染逻辑与默认值。本文基于 ToolJet 2.50.0-LTS 版本的官方文档widgets/statistics.md并结合仓库前端源码frontend/src/AppBuilder/Widgets/Statistics.jsx、frontend/src/AppBuilder/WidgetManager/widgets/statistics.js进行深化说明。组件定位与典型应用场景Statistics 组件的官方定义非常简洁Statistics can be used to display different statistical information.用于展示不同的统计信息。它是一个典型的只读型 KPI 卡片组件适合放在应用顶部或表格/图表上方快速传达关键数字。从组件注册信息看frontend/src/AppBuilder/WidgetManager/widgets/statistics.js其默认尺寸为width: 10、height: 152组件描述为Show key metrics展示关键指标这印证了它的核心用途就是关键指标卡。典型应用场景包括电商后台本月销售额主值 较上月增减次值运营看板DAU/MAU、转化率、订单量数据大屏与查询结果绑定自动展示最新统计结果。Properties属性配置详解在右侧属性面板Properties中Statistics 组件提供以下配置项属性说明Primary value label主值标签添加或移除主值上方的文字标签用于说明该统计项的名称。Primary value主值主值本身即实际数值例如682.3。Hide secondary value隐藏次值控制是否显示次值区域。默认关闭即默认显示次值。开启后隐藏次值也可点击旁边的fx按钮动态设置为{{true}}或{{false}}。Secondary value label次值标签添加或移除次值旁边的文字标签通常用于说明对比基准如 Last month上月。Secondary value次值次值本身通常表示变化量或对比值例如2.85。Secondary sign display次值正负符号为次值设置正positive或负negative符号用于表达上升或下降趋势。默认值为 positive。Loading state加载状态在组件上显示加载 spinner。常用于与查询的isLoading属性绑定在查询执行期间展示加载状态。可通过开关On启用或点击fx编程式设置为{{true}}或{{false}}。源码中的默认值从 widgets/statistics.js 的definition与properties配置可以看到组件拖入画布时的完整默认值属性默认值类型primaryValueLabelThis months earningscode字符串primaryValue682.3code字符串secondaryValueLabelLast monthcode字符串secondaryValue2.85code字符串secondarySignDisplaypositivecode字符串hideSecondaryfalsetoggle布尔loadingState{{false}}toggle布尔visibility{{true}}toggle布尔这些属性类型均为code意味着它们支持 JS 表达式{{...}}可以直接绑定查询结果、全局变量或组件状态实现数据驱动。Loading state 与查询联动实战重点文档明确指出 Loading state 最常用的做法是绑定查询的isLoading属性// 在属性面板中将 Loading state 的 fx 值设置为 {{queries.查询名称.isLoading}}当对应查询处于运行中时Statistics 组件会渲染加载指示器。查看渲染实现 Statistics.jsx当isLoading true时组件渲染一个 Bootstrap 风格的spinner-border转圈动画加载结束后自动恢复为统计数据卡片。同时源码还通过useBatchedUpdateEffectArray将loadingState的变化同步到暴露变量isLoading供其他组件或事件引用。组件专属动作CSA与暴露变量官方文档说明2.50.0-LTSComponent Specific Actions (CSA)当前版本文档声明尚无针对 Statistics 的组件专属动作Exposed Variables暴露变量当前版本文档声明尚无暴露变量。更新版本源码中的实现供参考需要说明的是上述无 CSA / 无暴露变量是针对 2.50.0-LTS 文档版本的结论。从当前仓库的前端源码对应更新的 ToolJet 版本看Statistics 组件已经实现了完整的暴露变量与组件方法体系Statistics.jsx暴露变量说明初始默认值primaryLabel主值标签文本This months earningssecondaryLabel次值标签文本Last monthprimaryValue主值682.3secondaryValue次值2.85secondarySignDisplay次值正负符号positiveisLoading加载状态falseisVisible可见状态true同时在 widgets/statistics.js 的actions中注册了四个可被事件触发的组件方法setPrimaryValue(text)—— 动态设置主值setSecondaryValue(text)—— 动态设置次值setLoading(loading)—— 动态切换加载状态参数为 togglesetVisibility(disable)—— 动态切换可见性参数为 toggle。如果你在使用更新版本的 ToolJet可以通过事件处理器如按钮的 On click调用这些方法例如{{components.statistics1.setPrimaryValue(1024)}}。若你的环境与 2.50.0-LTS 一致请以文档中无 CSA/无暴露变量的结论为准。General通用Tooltip 悬浮提示在General折叠面板下可以配置 Tooltip以字符串形式输入提示文本当用户将鼠标悬停在 Statistics 组件上时会显示该文本作为悬浮提示。从源码配置看widgets/statistics.jsTooltip 在更新的实现中还支持三种渲染格式plainText纯文本默认markdownMarkdownhtmlHTML。在 2.50.0-LTS 文档中Tooltip 以纯字符串形式配置即可满足大部分场景。Layout布局配置布局选项说明期望值Show on desktop桌面端显示开关控制组件是否在桌面视图中显示可通过fx编程式设置{{true}}或{{false}}Show on mobile移动端显示开关控制组件是否在移动视图中显示可通过fx编程式设置{{true}}或{{false}}这两个开关在源码中定义为others.showOnDesktop与others.showOnMobilewidgets/statistics.js默认值分别为{{true}}与{{false}}即默认在桌面端显示、移动端不显示。另外从更新版本源码看组件内部还提供了更细粒度的内容对齐配置本文档版本未列出但同属属性面板Data数据对齐left/center/right控制主值、标签的整体对齐方向Secondary value次值排列horizontal水平默认/vertical垂直Icon 与 Icon direction可为卡片配置图标默认IconDatabaseDollar并控制图标在左或右。Styles样式配置样式选项说明Primary label colour主标签颜色输入 Hex 色值或使用取色器修改主值标签的文字颜色。Primary text colour主文本颜色修改主值大数字的文字颜色。Secondary label colour次标签颜色修改次值标签的文字颜色。Secondary text colour次文本颜色修改次值的文字颜色。Visibility可见性控制组件整体是否可见。通过fx可编程式修改若为{{false}}应用部署后组件将不可见。默认值为{{true}}。样式面板的源码级扩展虽然 2.50.0-LTS 文档仅列出上述五项但当前仓库源码的样式定义widgets/statistics.js展示了更完整的样式体系按折叠面板分组如下Primary label and value主标签与主值样式键默认值说明primaryLabelSize14主标签字号pxprimaryLabelColourvar(--cc-placeholder-text)主标签颜色primaryValueSize34主值字号px渲染时作为主数字的fontSize且字重为 700Statistics.jsxprimaryTextColourvar(--cc-primary-text)主值颜色iconColorvar(--cc-primary-brand)图标颜色Secondary label and value次标签与次值样式键默认值说明secondaryLabelSize14次标签字号pxsecondaryLabelColourvar(--cc-placeholder-text)次标签颜色secondaryValueSize14次值字号pxpositiveSecondaryValueColorvar(--cc-success-systemStatus)次值为正时的颜色通常为绿色系negativeSecondaryValueColorvar(--cc-error-systemStatus)次值为负时的颜色通常为红色系Container容器样式键默认值说明backgroundColorvar(--cc-surface1-surface)卡片背景色borderColorvar(--cc-default-border)卡片边框颜色borderRadius6圆角pxboxShadow0px 0px 0px 0px #00000040盒阴影paddingdefault内边距可选default/none在渲染层Statistics.jsx组件外层容器会应用borderRadius、backgroundColor、border与boxShadow并通过display: flex组织主值区与次值区当加载状态为true或数据居中时内容会切换为纵向居中排列。此外次值区会根据secondarySignDisplay的值选择上箭头图标upstatistics正值或下箭头图标downstatistics负值并以胶囊形borderRadius: 58px容器展示配合正/负专用颜色强化趋势语义Statistics.jsx。:::info 任何带有fx按钮的属性都可以通过编程方式配置即在属性值中写入{{...}}表达式绑定查询结果、变量或组件状态。 :::实战构建一个绑定数据的 KPI 卡片综合上述配置一个完整的 Statistics 组件接入流程如下拖入组件从组件库Component Manager注册于 frontend/src/AppBuilder/WidgetManager/componentTypes.js将 Statistics 拖入画布创建查询新建一个查询如 Postgres/REST API用于统计营收数据绑定主值将Primary value的 fx 值设为{{queries.incomeQuery.data.total}}绑定次值与趋势将Secondary value设为环比变化量Secondary sign display用表达式根据正负动态返回positive或negative{{queries.incomeQuery.data.change 0 ? positive : negative}}绑定加载状态将Loading state的 fx 值设为{{queries.incomeQuery.isLoading}}查询运行时自动出现 spinner调整样式在 Styles 面板中按需设置主值字号、正/负颜色与容器外观更新版本动态更新若组件方法可用可在按钮事件中调用{{components.statistics1.setPrimaryValue(新值)}}实时刷新数值。验证与测试线索仓库的 Cypress 测试中Statistics 组件以statistics1、statistics2的实例名参与应用构建器的冒烟测试componentsBasicHappypath.skip.js说明它是应用构建器中常规校验的基础组件之一。如需了解组件如何被渲染、事件与暴露变量如何流转可继续阅读 Statistics.jsx 与 widgets/statistics.js 两个核心文件。小结Statistics 组件以极低的配置成本满足了关键指标展示这一高频需求主值 次值 趋势符号构成信息骨架Loading state 与查询isLoading天然联动样式面板提供了标签、数值、颜色、容器四层级的定制能力。对于 2.50.0-LTS 用户请以本文档列出的属性/样式表为准若使用更新版本还可借助源码中已实现的暴露变量与组件方法setPrimaryValue、setSecondaryValue、setLoading、setVisibility实现更灵活的交互控制。【免费下载链接】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），仅供参考