企业官网建设流程全解析

ToolJet Table 组件条件格式指南：用 cellValue 与 rowData 动态控制单元格文字与背景色

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

本篇指南讲解如何在 ToolJet 的Table组件中实现高级条件格式（Conditional Formatting）：通过一段 JavaScript 表达式，让单元格的文本颜色与背景颜色随数据内容动态变化。文章以 REST API 数据源为示例，完整走通「建应用 → 拉数据 → 绑定表格 → 配置条件格式」的链路，并给出基于cellValue与基于rowData的两类共四个可直接复用的表达式示例。读完你将掌握 Table 组件条件格式的配置入口、可用标识符、表达式写法，以及它在源码层面的解析原理。

一、条件格式的原理：cellValue 与 rowData 两个标识符

在 ToolJet 的 Table 组件中，每一列都可以配置独立的样式属性。条件格式的核心思想是：把「颜色」本身当作一个可以动态求值的属性，输入{{ ... }}表达式，表达式返回的值就是最终渲染的颜色。

从源码看，单元格背景色的求值发生在每一行渲染时。在 TableRow.jsx 中，表格通过getResolvedValue解析列定义里的cellBackgroundColor元数据：

const resolvedCellBackgroundColor = getResolvedValue(cell.column.columnDef?.meta?.cellBackgroundColor, { rowData: row.original, cellValue: cell.getValue(), });

这里传入的rowData与cellValue正是条件格式表达式里可以引用的仅有两个标识符：

• cellValue：当前单元格的值（本列数据）；
• rowData：当前整行的数据对象（可以访问该行所有列的字段）。

这也是官方文档明确提醒的约束：条件格式表达式中只能用cellValue和rowData作为变量，其余上下文变量不可用。

二、第一步：创建应用并配置数据源

1. 新建一个应用，向画布拖入一个Table组件。
2. 打开底部Query Panel，点击+ Add按钮新建查询。
3. 数据源选择REST API，方法（Method）设为GET。
4. 在 URL 中填入如下接口地址：

https://fakestoreapi.com/products

5. 点击Preview按钮预览查询返回的数据，确认无误后点击Run执行查询。

执行成功后，查询会以默认名称restapi1保存，后续可以通过queries.restapi1.data引用它的返回结果。

提示：示例使用的是公开的 Fake Store API，返回的是带title、price、category、rating等字段的商品列表，非常适合用来演示「按数值区间变色」「按分类变色」等场景。实际使用时替换为任意 REST 接口或 ToolJet 支持的其他数据源即可。

三、第二步：把查询数据显示到表格

1. 收起 Query Panel，点击画布上的Table组件，打开右侧属性面板。
2. 在Data属性中填入：

{{queries.restapi1.data}}

保存后，表格即会渲染查询返回的商品数据。此时各列的列类型（Column Type）默认为Default，可以直接进入下一步配置条件格式。

四、第三步：开启条件格式

1. 在 Table 组件的属性面板中找到Columns属性，展开列管理。
2. 选中要配置的列（例如category列）。
3. 当该列的列类型为Default或String时，即可为该列设置Text color（文本颜色）与Cell background color（单元格背景颜色）两个条件格式属性。

结合源码可以确认这两个属性的支持范围更广。在 StylesTabElements.jsx 中，以下列类型都会渲染出「Text color / Cell color」配置项：

string、default、number、json、markdown、html、select、text、newMultiSelect、tagsV2、datepicker等；其中boolean列只提供背景色配置，不提供文本颜色配置。link、rating、button等特殊列类型则使用各自独立的颜色属性（如linkColor、selectedBgColorStars等）。

在 Text color 或 Cell background color 的输入框中，用{{ }}包裹一段 JS 表达式即可。表达式最终返回的颜色值可以是：

• 命名颜色，如red、green、cyan；
• 十六进制色值，如#D9534F、#5CB85C；
• CSS 支持的其他颜色表示（如rgb(...)）。

五、基于 cellValue 的条件格式

cellValue代表当前单元格自身的值，适合做「单列数值/文本驱动的变色」。

示例 1：按单元格数值切换文本颜色

选中Rate列（该列是商品评分，取值范围 1~5，列类型为Default/String），在Text color属性中输入：

{{cellValue < 2 ? 'red' : cellValue > 2 && cellValue < 3 ? 'Orange' : 'green'}}

规则解读：

示例 2：按单元格数值切换背景色

仍然选中Rate列，在Cell background color属性中输入：

{{cellValue >= 4 ? 'lightgreen' : cellValue >= 3 ? 'lightyellow' : 'lightcoral'}}

规则解读：

六、基于 rowData 的条件格式

rowData代表整行数据对象，可以用它引用其他列的字段，实现「跨列联动」的配色。访问嵌套字段时直接使用点号语法，例如rowData.rating.rate。

示例 1：按其他列的值切换文本颜色

选中Title列，在Text color属性中输入：

{{rowData.price > 50 ? '#D9534F' : (rowData.rating.rate >= 4 ? '#5CB85C' : rowData.rating.rate >= 3 ? '#F0AD4E' : '#D9534F' )}}

规则解读：

这个例子展示了条件格式的典型用法：Title列的文字颜色由同一行price与rating两列的值共同决定。

示例 2：按分类字段切换背景色

继续选中Title列，在Cell background color属性中输入：

{{rowData.category === "electronics" ? 'cyan' : rowData.category === "jewelery" ? 'pink' : 'lightgray'}}

规则解读：

七、源码级补充：条件格式的求值与回退逻辑

理解底层实现有助于写出更稳的表达式：

1. 背景色求值：如上文所示，TableRow.jsx在渲染每个<td>前，先用getResolvedValue解析cellBackgroundColor表达式（传入rowData与cellValue两个变量），把解析结果直接写入单元格的内联样式backgroundColor。

2. 默认回退与固定列特殊处理：在 TableRow.jsx 中，如果条件格式解析结果为空（undefined、null、''、inherit、transparent），且该列是固定列（pinned），背景色会回退到固定的表面色变量；否则回退为inherit（继承表格默认样式）。因此表达式未命中任何分支时，单元格会保持默认外观，这为「默认样式兜底」提供了便利。

3. 文本颜色回退：在 useTextColor.js 中，若列级文本颜色未设置或等于默认值#11181C，则回退到 Table 组件级样式表里的textColor。这意味着你可以在表格级别设置统一文字色，再在特定列上用条件格式局部覆盖。

4. 行数据来源：表达式中的rowData即row.original（未经表格处理前的原始行数据），所以你可以放心地访问原始 API 返回的任意字段，包括嵌套对象（如rowData.rating.rate）。

八、进阶实践建议

• 表达式保持简洁：条件格式表达式本质上是一行 JS，建议控制分支数量。分支过多时先拆分逻辑，或改用颜色映射表，避免可读性下降。
• 颜色值统一风格：命名颜色与十六进制色值可以混用，但同一批规则建议统一，便于后期维护。
• 默认分支兜底：务必让最后一个else分支返回一个明确颜色或让条件覆盖所有情况，避免出现「部分行没变色」的意外（虽然按源码逻辑会回退到默认样式）。
• 与其他数据源复用：条件格式属性与数据源无关，REST API、PostgreSQL、ToolJet Database 等数据源的查询结果都可以直接套用cellValue/rowData表达式。
• 相关联文档：关于在 Table 中动态取用单元格值的更多技巧，可参考 access-cellvalue-rowdata。

总结

ToolJet 的 Table 组件把条件格式做成了「列属性上的表达式」，通过cellValue与rowData两个标识符即可实现从单列数值、跨列字段到嵌套字段的任意动态配色：文本颜色用Text color属性，单元格背景色用Cell background color属性，表达式返回命名颜色或十六进制色值即可生效。掌握这套写法后，你可以轻松做出评分分档、价格预警、分类着色等数据可视化效果，让表格信息一目了然。

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