ThingsBoard 自定义 Widget 动作的 additionalParams 对象：各 Widget 类型下的数据结构与实战用法

物联网后端数据可视化消息队列【免费下载链接】thingsboardAll-in-one IoT Platform - Device management, data collection, processing and visualization.项目地址https://gitcode.com/GitHub_Trending/th/thingsboard点击查看免费下载导读在 ThingsBoard 仪表盘中为 Widget 配置自定义动作Custom Action是扩展交互逻辑的核心手段。当动作被触发时如点击表格行、地图标记或饼图扇区ThingsBoard 会向你的自定义 JS 函数传入一系列参数其中additionalParams是一个可选但极其重要的键值对对象其内容随 Widget 类型和动作触发源不同而变化。本文以 custom_additional_params.md 为骨架结合仓库前端源码中对应接口定义系统讲解additionalParams在实体表格、告警表格、时序表格、地图、实体层级、饼图等 Widget 中的具体数据结构、字段含义以及如何在自定义动作函数中正确消费这些数据。读完本文你将掌握additionalParams在不同 Widget/触发源下的完整类型清单如何从EntityData、AlarmDataInfo、TimeseriesRow、FormattedData等对象中提取所需字段以及「其他 Widget 无 additionalParams」这一边界行为的正确理解。1. additionalParams 是什么additionalParams是自定义动作函数的一个可选入参类型为{[key: string]: any}即一个键值对对象其中键为字符串、值为任意类型。它在自定义动作函数签名中的位置如下参考 custom_action_args.md$event, widgetContext, entityId, entityName, additionalParams, entityLabel$event触发动作的MouseEvent等事件对象widgetContextWidget 实例的上下文引用封装了 Widget 所需的全部 API 与数据entityId/entityName/entityLabel目标实体的可选 ID、名称与标签additionalParams可选的键值对象其具体内容取决于 Widget 类型与动作触发源。从源码看additionalParams在前端被广泛使用。例如在 widget-api.models.ts 中additionalParams出现在WidgetActionDescriptor相关签名中在 widget.component.ts 中执行自定义动作时会通过compiled.execute($event, this.widgetContext, entityId, entityName, additionalParams, entityLabel)将该参数透传给编译后的动作函数若传入的additionalParams为空代码会将其兜底为空对象{}见if (!additionalParams) { additionalParams {}; }。这说明additionalParams始终以「已初始化的对象」形态出现在动作函数中但你拿到的字段集取决于触发场景。2. 实体表格 Widgetentity当动作触发源为实体表格 WidgetEntities table且触发方式为**行点击On row click或动作单元格按钮Action cell button**时additionalParams的结构为additionalParams: { entity: EntityData }2.1 EntityData 接口定义EntityData定义于 table-widget.models.tsexport interface EntityData { id: EntityId; entityName: string; entityLabel?: string; entityType?: EntityType; actionCellButtons?: TableCellButtonActionDescriptor[]; hasActions?: boolean; [key: string]: any; }id实体的EntityId包含实体类型与 IDentityName实体名称entityLabel可选的实体标签entityType实体类型DEVICE、ASSET 等[key: string]: any索引签名意味着实体表格数据源中声明的其他实体属性attributes与时序数据timeseries也会直接挂载在该对象上可通过数据键名直接访问。要点EntityData不仅提供基础实体属性如id、entityName还提供对「数据源配置中声明的其他实体属性/时序数据」的访问。也就是说只要你在实体表格数据源中勾选了某个属性或时序键其值就会以该键名为属性出现在additionalParams.entity上。2.2 使用示例// 假设数据源中声明了温度 timeseries 键 temperature const params additionalParams; const entity params.entity; console.log(entity.id, entity.entityName); // 实体 ID 与名称 console.log(entity.temperature); // 数据源声明的时序值3. 告警表格 Widgetalarm当动作触发源为告警表格 WidgetAlarms table触发方式为行点击或动作单元格按钮时additionalParams: { alarm: AlarmDataInfo }3.1 AlarmDataInfo 接口定义AlarmDataInfo定义于 alarm.models.ts它继承自AlarmInfoexport interface AlarmDataInfo extends AlarmInfo { actionCellButtons?: TableCellButtonActionDescriptor[]; hasActions?: boolean; [key: string]: any; }而AlarmInfo见同文件 L151-L156扩展自Alarm额外提供originatorName、originatorLabel、originatorDisplayName、assignee等字段。Alarm基础模型则包含告警核心属性type告警类型、severity严重级别、originator发起实体、startTs/endTs、ackTs/clearTs、assigneeId等。要点AlarmDataInfo呈现告警基础属性如type、severity、originator等同时通过索引签名提供对「告警自身或发起者originator实体的其他字段/属性/时序数据」的访问前提是这些数据已在数据源配置中声明。3.2 使用示例const alarm additionalParams.alarm; console.log(alarm.type, alarm.severity); // 告警类型与级别 console.log(alarm.originatorName); // 发起实体名称 console.log(alarm.originator); // 发起实体 {entityType, id} // 若数据源声明了发起实体的属性/时序也可直接读取4. 时序表格 WidgetTimeseriesRow当动作触发源为时序表格 WidgetTimeseries table触发方式为行点击或动作单元格按钮时additionalParams本身就是一个TimeseriesRow对象不再是{entity: ...}包裹结构additionalParams: TimeseriesRow4.1 TimeseriesRow 接口定义TimeseriesRow定义于 timeseries-table-widget.component.tsinterface TimeseriesRow { actionCellButtons?: TableCellButtonActionDescriptor[]; hasActions?: boolean; [col: number]: any; formattedTs: string; }formattedTs格式化后的时间戳字符串按 Widget 配置的时间格式渲染[col: number]: any以列索引为键的时序值。注意这里键是数字类型——每列对应数据源中声明的一个 timeseries 数据键按声明顺序编号。4.2 使用示例// 注意此处 additionalParams 直接就是 TimeseriesRow而不是 { row: ... } const row additionalParams; console.log(row.formattedTs); // 格式化时间戳 console.log(row[0], row[1]); // 第 0 列、第 1 列对应的时序值与实体表格的差异提醒实体表格的additionalParams是{ entity: EntityData }属性按名称访问而时序表格的additionalParams直接是TimeseriesRow时序值按列索引访问两者结构完全不同编写动作函数时务必区分。5. 地图 WidgetFormattedData当动作触发源为地图类 WidgetMap widgets触发方式为**标记/多边形/圆形点击On marker/polygon/circle click或标签动作Tag action**时additionalParams: FormattedData5.1 FormattedData 接口定义FormattedData定义于 widget.models.tsexport interface FormattedDataD extends Datasource Datasource { $datasource: D; entityName: string; deviceName: string; entityId: string; entityType: EntityType; entityLabel: string; entityDescription: string; aliasName: string; dsIndex: number; dsName: string; deviceType: string; [key: string]: any; }FormattedData是与数据图层标记、多边形、圆形相关联的对象对于轨迹trips类数据图层它关联的是某条轨迹的特定数据点。它包含基础实体属性如entityId、entityName、entityType、entityLabel、deviceName、deviceType、entityDescription等并通过索引签名提供对图层数据源中声明的附加属性与时序数据的访问。5.2 使用示例const data additionalParams; console.log(data.entityId, data.entityName); // 标记对应实体 console.log(data.entityType); // 实体类型 console.log(data.$datasource); // 图层数据源对象 // 图层数据源声明的属性/时序同样可直接访问6. 实体层级 WidgetnodeCtx当动作触发源为实体层级 WidgetEntities hierarchy触发方式为**节点选中On node selected**时additionalParams: { nodeCtx: HierarchyNodeContext }6.1 HierarchyNodeContext 接口定义HierarchyNodeContext定义于 entities-hierarchy-widget.models.tsexport interface HierarchyNodeContext { parentNodeCtx?: HierarchyNodeContext; entity: BaseDataEntityId; childrenNodesLoaded?: boolean; level?: number; data: {[key: string]: any}; }entity当前节点的基础实体对象含id、name、label等基础属性继承自BaseDatadata其他实体属性/时序数据来自 Widget 数据源配置parentNodeCtx父节点上下文可递归追溯level节点层级深度。要点HierarchyNodeContext中的entity字段持有基础实体属性id、name、labeldata字段持有数据源中声明的其他实体属性/时序数据。动作函数中既可通过additionalParams.nodeCtx.entity访问实体基础信息也可通过additionalParams.nodeCtx.data.xxx访问扩展数据。6.2 使用示例const nodeCtx additionalParams.nodeCtx; console.log(nodeCtx.entity.id, nodeCtx.entity.name); // 节点实体基础信息 console.log(nodeCtx.data); // 数据源声明的属性/时序集合 console.log(nodeCtx.level); // 节点层级7. 饼图 WidgetLatestChartDataItem 与 TbFlotPlotItem饼图分「最新值饼图Pie基于 ECharts 的 Latest chart」与「Flot 版饼图已弃用 deprecated」两类additionalParams结构各不相同。7.1 PieLatest ChartLatestChartDataItem当触发方式为**扇区点击On slice click**时additionalParams是一个LatestChartDataItem数据对象定义于 latest-chart.models.tsexport interface LatestChartDataItem { id: number; datasource: Datasource; dataKey: DataKey; value: number; hasValue: boolean; enabled: boolean; }dataKey被点击扇区对应的数据键datasource数据源对象value扇区数值此外还包含id、hasValue、enabled等辅助字段。const item additionalParams; console.log(item.dataKey.name, item.value); // 数据键名称与扇区值 console.log(item.datasource); // 数据源7.2 Pie - FlotdeprecatedTbFlotPlotItem同样在扇区点击时Flot 版饼图的additionalParams是TbFlotPlotItem定义于 flot-widget.models.tsexport interface TbFlotPlotItem extends jquery.flot.item { series: TbFlotPlotDataSeries; }它扩展自jquery.flot.item包含series字段携带被点击饼图扇区对应数据源与数据键的信息TbFlotPlotDataSeries内含datasource、dataKey、percent等见同文件 L50-L53// TbFlotPlotDataSeries 片段 datasource?: Datasource; dataKey?: TbFlotDataKey; percent?: number;const item additionalParams; console.log(item.series.datasource); // 数据源信息 console.log(item.series.dataKey); // 扇区对应的数据键8. 其他 Widget不提供 additionalParams对于上述列表之外的所有其他 Widget动作触发时不提供additionalParams值。也就是说在这些 Widget 上编写自定义动作时additionalParams参数要么为兜底的空对象{}由 widget.component.ts 的if (!additionalParams) { additionalParams {}; }逻辑保证要么为undefined语义因此不应在代码中无条件假设其存在。9. 各类型一览表为便于速查将上述所有场景汇总如下Widget 类型动作触发源additionalParams 结构关键字段实体表格 Entities table行点击 / 动作单元格按钮{ entity: EntityData }entity.id、entity.entityName以及数据源声明的属性/时序按名访问告警表格 Alarms table行点击 / 动作单元格按钮{ alarm: AlarmDataInfo }alarm.type、alarm.severity、alarm.originator、originatorName等时序表格 Timeseries table行点击 / 动作单元格按钮TimeseriesRow直接row.formattedTs时序值按列索引row[0]、row[1]访问地图 Map widgets标记/多边形/圆形点击、标签动作FormattedData直接entityId、entityName、entityType、$datasource等实体层级 Entities hierarchy节点选中{ nodeCtx: HierarchyNodeContext }nodeCtx.entity基础属性、nodeCtx.data扩展属性/时序饼图 PieLatest Chart扇区点击LatestChartDataItem直接dataKey、datasource、value饼图 Pie - Flotdeprecated扇区点击TbFlotPlotItem直接series.datasource、series.dataKey其他所有 Widget—不提供兜底为空对象{}勿假设其存在10. 实战要点与注意事项先判断再使用编写动作函数时应先用if (additionalParams)或if (additionalParams additionalParams.entity)之类的守卫判断目标字段是否存在再访问具体属性避免在其他 Widget 上运行时报错。结构差异需警惕表格类与地图/时序类 Widget 的additionalParams结构不同——实体/告警表格是「包裹对象」{ entity }/{ alarm }而时序表格、地图、饼图是「直接对象」。混淆二者是最常见的编码错误。依赖数据源声明实体属性与时序数据只有「在 Widget 数据源配置中声明」时才会出现在additionalParams对应对象上未声明的键无法访问。因此在使用前需确认数据源已勾选相应数据键。同名键冲突由于EntityData、AlarmDataInfo、FormattedData都带有[key: string]: any索引签名自定义的属性/时序键名应避免与内置字段如entityName、entityId重名以免覆盖语义不清。Flot 饼图已弃用新开发优先使用 Latest Chart 类饼图LatestChartDataItemFlot 版饼图TbFlotPlotItem仅用于维护既有仪表盘。联动其它动作参数additionalParams通常与entityId、entityName、entityLabel配合使用——基础实体信息可通过独立参数直接获得而additionalParams补充的是「数据源级」的扩展数据二者互补而非替代。11. 延伸阅读custom_action_args.md自定义动作函数的完整参数签名说明additionalParams的官方定位即来源于此custom_action_fn.md自定义动作函数的基本写法custom_pretty_action_fn.md进阶的「Pretty」自定义动作函数widget.component.ts自定义动作编译与执行的核心调用链可见additionalParams的兜底与透传逻辑widget-api.models.tsadditionalParams在动作描述符 API 中的类型签名place-map-item-sample-js.raw地图相关自定义动作中消费additionalParams如坐标、周长、圆形参数的实际示例代码。赞分享物联网后端数据可视化消息队列【免费下载链接】thingsboardAll-in-one IoT Platform - Device management, data collection, processing and visualization.项目地址https://gitcode.com/GitHub_Trending/th/thingsboard点击查看免费下载相关推荐ThingsBoard 静态 Widget 开发实战从 Widget Editor 创建无数据源的自定义 UI 组件ThingsBoard 静态 Widget 开发实战从 Widget Editor 创建无数据源的自定义 UI 组件 导读 静态 WidgetStatic物联网后端数据可视化消息队列qiankun3 内部共享层 qiankunjs/shared从版本履历看微前端基础能力的演进与实现qiankun3 内部共享层 qiankunjs/shared从版本履历看微前端基础能力的演进与实现 导读 qiankunjs/shared 是 qi物联网后端数据可视化消息队列ThingsBoard Alarm Widget 从零到实战基于 Widget Editor 开发自定义告警表格组件ThingsBoard Alarm Widget 从零到实战基于 Widget Editor 开发自定义告警表格组件 本指南以 ThingsBoard 官方示物联网后端数据可视化消息队列上一篇Blender新手工具箱用awesome-blender精选清单10分钟找对工具下一篇OBS多平台同步直播终极指南obs-multi-rtmp插件完整教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考