• 物联网
• 后端
• 数据可视化
• 消息队列

导读

本文以 ThingsBoard 官方帮助文档 row_style_fn.md 为核心，系统讲解告警表格组件（Alarms Table Widget）中"行样式函数"（Row Style Function）的签名约定、参数含义、返回值规范与完整示例，并结合前端源码（alarms-table-widget.component.ts、alarm.models.ts）揭示其底层执行机制。读完本文，你将能在 ThingsBoard 仪表盘中通过编写一段 JavaScript 函数，依据告警级别（severity）、告警类型（type）、告警状态（status）乃至告警源实体的属性/遥测数据，动态改变表格整行的背景色、字体颜色等 CSS 样式，实现告警列表的高可读性与可视化分级。

一、行样式函数是什么：适用场景与定位

行样式函数是 ThingsBoard 告警表格类组件（Alarms Table Widget）在"高级设置"中提供的一项 JavaScript 扩展能力。其定位是：在每一行告警渲染时，根据告警数据动态计算并返回一组 CSS 样式键值对，从而覆盖该行的默认显示样式。

典型应用场景包括：

• 按告警严重级别着色：CRITICAL 红色、MAJOR 橙色、WARNING 黄色等，让运维人员一眼定位最高危告警；
• 按告警状态区分样式：未确认（ACTIVE_UNACK）、已确认、已清除的行使用不同底色或透明度；
• 按告警来源实体的属性/遥测值定制样式：例如设备温度超过阈值时，将该设备产生的告警行高亮。

说明：该函数能力不仅存在于告警表格组件，实体表格（Entities Table）与时间序列表格（Timeseries Table）同样提供类似的rowStyle入口（见 entities-table-widget.component.ts）。本文聚焦告警表格场景。

二、函数签名与参数详解

根据官方文档，行样式函数签名为：

function (alarm, ctx): {[key: string]: string}

即：输入两个参数，返回一个键为字符串、值为字符串的对象。下面逐参数解析。

2.1alarm参数：AlarmDataInfo 告警数据对象

alarm是一个 AlarmDataInfo 类型对象，表示当前行的告警数据。从源码定义看，AlarmDataInfo extends AlarmInfo，而AlarmInfo extends Alarm，因此它聚合了完整的告警基础属性与来源实体信息：

除此之外，AlarmDataInfo还声明了[key: string]: any索引签名（见 alarm.models.ts），意味着在组件数据源配置中声明引用的告警源实体字段、属性（attributes）或遥测值（timeseries），都会被附加到alarm对象上，可在函数内直接以alarm.xxx方式访问。

2.2ctx参数：WidgetContext 组件上下文

ctx是 WidgetContext 的引用，即当前组件实例的上下文对象，其中封装了组件运行所需的全部 API 与数据，常用成员包括：

• ctx.widgetConfig：组件配置（含数据源、过滤器等）；
• ctx.settings：组件设置（含行样式函数配置本身）；
• ctx.actionsApi：动作 API，可触发组件动作；
• ctx.$injector：Angular 依赖注入器，可访问系统服务（如http服务）实现 HTTP 调用；
• ctx.widgetTitle、ctx.datasource等组件元数据。

在大多数行样式场景中你只需读取alarm，ctx用于在需要额外能力（如访问组件数据源、调用外部服务）时使用。

三、返回值约定：CSS 样式键值对象

函数必须返回一个键值对对象，例如：

{ backgroundColor: 'red', color: '#ffffff', fontWeight: 'bold' }

键为 CSS 属性名（camelCase 形式，如backgroundColor、color、fontSize、fontWeight），值为 CSS 属性值字符串。组件会将返回对象直接应用到表格该行的<tr>元素样式上，从而覆盖默认行样式。

两点重要约定（来自组件源码校验，见 alarms-table-widget.component.ts）：

• 返回值必须是普通对象。如果返回null、字符串、数字等非对象类型，组件会抛出TypeError；
• 返回值不能是数组（Array），否则同样抛出TypeError。

若函数执行抛错或返回非法类型，组件会打印警告日志并回退为不应用任何行样式：

Row style function in widget '...' returns '...'. Please check your row style function.

因此函数末尾务必return {...}一个对象，且建议提供默认分支保证任何情况下都有合法返回。

四、配置入口：在组件设置中启用行样式函数

行样式函数通过告警表格组件的"高级设置"（Advanced settings）启用。对应设置面板源码 alarms-table-widget-settings.component.html 展示了完整配置结构：

1. 打开组件编辑器 →高级设置标签页；
2. 找到Rows（行）分组下的Use row style function（使用行样式函数）开关并打开；
3. 在展开的 JavaScript 编辑器中编写函数，函数参数固定为['alarm', 'ctx']，支持引入模块与使用全局变量；
4. 编辑器内置helpId="widget/lib/alarm/row_style_fn"，即本文对应的帮助文档，可随时点击查看说明。

从源码可见，行样式函数经tb-js-func组件以functionArgs: ['alarm', 'ctx']注入，与官方文档签名(alarm, ctx)严格一致。底层由compileTbFunction编译为可执行函数（见 table-widget.models.ts），并通过getRowStyleInfo(ctx, settings, 'alarm, ctx')在组件初始化时解析配置。

五、官方示例：按告警级别设置行背景色

文档给出的标准示例——根据告警严重级别动态设置行背景色：

var severity = alarm.severity; var color = '#fff'; switch (severity) { case 'CRITICAL': color = 'red'; break; case 'MAJOR': color = 'orange'; break; case 'MINOR': color = '#ffca3d'; break; case 'WARNING': color = '#abab00'; break; case 'INDETERMINATE': color = 'green'; break; } return { backgroundColor: color };

要点解读：

• 五级严重度恰好对应源码中 AlarmSeverity 枚举的全部取值，alarm.severity是字符串枚举值，可直接switch；
• 返回对象中backgroundColor为 CSS 属性（组件内部通过angular样式绑定应用）；
• 你也可以复用系统预置的严重度颜色映射alarmSeverityColors（见 alarm.models.ts），其默认色值与主题 CSS 变量挂钩。

六、扩展实战：更丰富的行样式编写技巧

6.1 同时设置多个样式属性

var style = {color: '#fff', fontWeight: '500'}; switch (alarm.severity) { case 'CRITICAL': style.backgroundColor = 'red'; style.fontWeight = 'bold'; break; case 'MAJOR': style.backgroundColor = 'orange'; break; case 'WARNING': style.backgroundColor = '#abab00'; break; default: style.backgroundColor = '#fff'; } return style;

6.2 依据告警状态（未确认/已清除）区分样式

if (alarm.cleared) { return {backgroundColor: '#e0e0e0', color: '#9e9e9e'}; } else if (!alarm.acknowledged) { return {backgroundColor: '#fff3cd', fontWeight: 'bold'}; } else { return {backgroundColor: '#fff'}; }

6.3 结合告警源实体的属性/遥测值

前提：在组件数据源中额外声明了告警来源实体的字段（如设备temperature）。随后即可在函数内直接读取：

var temp = alarm.temperature; // 数据源中声明引用的实体遥测/属性 if (temp && temp > 80) { return {backgroundColor: '#ffdddd', color: '#b71c1c'}; } return {backgroundColor: '#fff'};

七、底层执行机制：从配置到渲染的完整链路

结合源码可梳理出该功能的完整执行链路（以告警表格组件为例，对应 alarms-table-widget.component.ts）：

1. 解析配置：组件初始化时调用getRowStyleInfo(this.ctx, this.settings, 'alarm, ctx')（见 L419），若settings.useRowStyleFunction === true且配置了非空函数，则调用compileTbFunction编译函数体并声明参数alarm与ctx；编译失败或未启用时降级为useRowStyleFunction: false。
2. 逐行渲染：模板中对每一行调用rowStyle(alarm, row)（见 L767-L801），从rowStylesInfo流中取出编译结果并执行styleInfo.rowStyleFunction.execute(alarm, this.ctx)。
3. 类型校验：执行结果必须是普通对象且非数组，否则抛TypeError；异常被catchError捕获并输出警告，同时返回{}兜底，不影响表格渲染。
4. 结果缓存：计算出的样式按行号写入rowStyleCache[row]（见 L794），同一行在数据刷新前直接复用缓存，避免重复执行函数，提升大表格滚动性能；数据刷新时清空缓存（见 L1329）。

实体表格组件的rowStyle(entity, row)（见 entities-table-widget.component.ts）走同一套getRowStyleInfo机制，仅参数从alarm换为entity，机制完全一致。

八、编写注意事项与调试建议

• 始终返回对象：确保函数在所有代码路径上都能return {...}，且不要返回null、数组或原始类型；
• 注意大小写：告警级别枚举值为全大写字符串（CRITICAL等），switch分支必须精确匹配，可先console.log(alarm.severity)调试确认实际值；
• 善用ctx：当样式依赖组件数据源、需要调用 HTTP 服务或读取组件配置时，通过ctx获取，例如ctx.$injector.get('http')；
• 性能考量：行样式函数会在每行渲染时执行，组件已通过行级缓存优化（见上文第七节），但函数内部仍应避免耗时操作（如同步 HTTP 请求、大数组遍历）；
• 结合主题变量：组件默认严重度配色使用 CSS 变量（--tb-alarm-severity-critical等），自定义函数内也可直接使用这些变量名，保持与整体主题一致（映射见 alarm.models.ts）；
• 验证依据：相关单元测试与组件测试可在仓库ui-ngx下检索rowStyle相关用例进一步验证行为边界。

总结

行样式函数是 ThingsBoard 告警表格组件实现"告警可视化分级"的核心扩展点。掌握(alarm, ctx) => {[key: string]: string}这一函数契约，理解alarm（AlarmDataInfo）的可访问字段范围与返回值校验规则，再结合组件源码中的解析与缓存机制，即可在仪表盘中稳定、高效地实现按严重级别、按状态、按来源实体数据驱动的行样式定制。

• 物联网
• 后端
• 数据可视化
• 消息队列