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/ToolJet

Statistics 是 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配置可以看到组件拖入画布时的完整默认值：

属性	默认值	类型
`primaryValueLabel`	`This months earnings`	code（字符串）
`primaryValue`	`682.3`	code（字符串）
`secondaryValueLabel`	`Last month`	code（字符串）
`secondaryValue`	`2.85`	code（字符串）
`secondarySignDisplay`	`positive`	code（字符串）
`hideSecondary`	`false`	toggle（布尔）
`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-LTS）

Component Specific Actions (CSA)：当前版本文档声明尚无针对 Statistics 的组件专属动作；
Exposed Variables（暴露变量）：当前版本文档声明尚无暴露变量。

更新版本源码中的实现（供参考）

需要说明的是，上述"无 CSA / 无暴露变量"是针对 2.50.0-LTS 文档版本的结论。从当前仓库的前端源码（对应更新的 ToolJet 版本）看，Statistics 组件已经实现了完整的暴露变量与组件方法体系（Statistics.jsx）：

暴露变量	说明	初始默认值
`primaryLabel`	主值标签文本	`This months earnings`
`secondaryLabel`	次值标签文本	`Last month`
`primaryValue`	主值	`682.3`
`secondaryValue`	次值	`2.85`
`secondarySignDisplay`	次值正负符号	`positive`
`isLoading`	加载状态	`false`
`isVisible`	可见状态	`true`

同时在 widgets/statistics.js 的actions中注册了四个可被事件触发的组件方法：

setPrimaryValue(text)—— 动态设置主值；
setSecondaryValue(text)—— 动态设置次值；
setLoading(loading)—— 动态切换加载状态（参数为 toggle）；
setVisibility(disable)—— 动态切换可见性（参数为 toggle）。

如果你在使用更新版本的 ToolJet，可以通过事件处理器（如按钮的 On click）调用这些方法，例如{{components.statistics1.setPrimaryValue('1024')}}。若你的环境与 2.50.0-LTS 一致，请以文档中"无 CSA/无暴露变量"的结论为准。

General（通用）：Tooltip 悬浮提示

在General折叠面板下可以配置 Tooltip：以字符串形式输入提示文本，当用户将鼠标悬停在 Statistics 组件上时，会显示该文本作为悬浮提示。

从源码配置看（widgets/statistics.js），Tooltip 在更新的实现中还支持三种渲染格式：

plainText（纯文本，默认）；
markdown（Markdown）；
html（HTML）。

在 2.50.0-LTS 文档中，Tooltip 以纯字符串形式配置即可满足大部分场景。

Layout（布局）配置

布局选项	说明	期望值
Show on desktop（桌面端显示）	开关控制组件是否在桌面视图中显示	可通过fx编程式设置`{{true}}`或`{{false}}`
Show on mobile（移动端显示）	开关控制组件是否在移动视图中显示	可通过fx编程式设置`{{true}}`或`{{false}}`

这两个开关在源码中定义为others.showOnDesktop与others.showOnMobile（widgets/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（主标签与主值）

样式键	默认值	说明
`primaryLabelSize`	`14`	主标签字号（px）
`primaryLabelColour`	`var(--cc-placeholder-text)`	主标签颜色
`primaryValueSize`	`34`	主值字号（px），渲染时作为主数字的`fontSize`且字重为 700（Statistics.jsx）
`primaryTextColour`	`var(--cc-primary-text)`	主值颜色
`iconColor`	`var(--cc-primary-brand)`	图标颜色

Secondary label and value（次标签与次值）

样式键	默认值	说明
`secondaryLabelSize`	`14`	次标签字号（px）
`secondaryLabelColour`	`var(--cc-placeholder-text)`	次标签颜色
`secondaryValueSize`	`14`	次值字号（px）
`positiveSecondaryValueColor`	`var(--cc-success-systemStatus)`	次值为正时的颜色（通常为绿色系）
`negativeSecondaryValueColor`	`var(--cc-error-systemStatus)`	次值为负时的颜色（通常为红色系）

Container（容器）

样式键	默认值	说明
`backgroundColor`	`var(--cc-surface1-surface)`	卡片背景色
`borderColor`	`var(--cc-default-border)`	卡片边框颜色
`borderRadius`	`6`	圆角（px）
`boxShadow`	`0px 0px 0px 0px #00000040`	盒阴影
`padding`	`default`	内边距，可选`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）实现更灵活的交互控制。

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

企业官网建设流程全解析