3、Widget库详解：标准Widget类型与资源包管理
ThingsBoard 的 Widget 库是构建仪表板的核心资产。本章将深入剖析标准 Widget 的四大分类——图表、卡片、控制、地图，并讲解 Widget 资源包（Resource Bundle）的管理机制。理解这些基础类型与资源管理方式，是后续进行自定义开发的前提。
3.1 标准Widget四大类型
ThingsBoard 内置了超过 60 种标准 Widget，按功能划分为以下四类：
| 类型 | 核心用途 | 典型子类 | 数据绑定方式 |
|---|---|---|---|
| 图表（Charts） | 时间序列数据可视化，展示趋势与分布 | 折线图、柱状图、饼图、雷达图、散点图 | Timeseries 数据源 + 键（Key） |
| 卡片（Cards） | 单值或关键指标展示，强调当前状态 | 数字卡片、HTML 卡片、标签卡片、模拟量显示 | Latest Telemetry 或 Attributes |
| 控制（Controls） | 下发指令、设置属性、切换设备状态 | 开关、滑块、按钮、下拉选择器 | RPC 命令或 Attribute Write |
| 地图（Maps） | 地理空间数据展示与设备定位 | OpenStreetMap、Google Maps、轨迹回放 | Latitude/Longitude 属性 |
选型建议： 展示实时数值变化优先用卡片；分析历史趋势用图表；需要远程操作设备用控制；涉及地理位置用地图。一个仪表板通常混合使用多种类型。
3.2 图表类Widget详解
图表 Widget 是数据可视化的主力。ThingsBoard 的图表基于 Flot 和 ECharts 两种渲染引擎，支持丰富的配置项。
- Timeseries Line Chart（时序折线图）：最常用，支持多条数据线、时间范围选择、缩放与十字准星。
- Timeseries Bar Chart（时序柱状图）：适合对比不同时间段的数据聚合值（如日总量、月均值）。
- Pie Chart（饼图）：展示占比，数据源需为 Latest Telemetry 或 Attributes。
- Radar Chart（雷达图）：多维度指标对比，常用于设备健康度评分。
图表 Widget 的通用配置参数包括：
{
"datasources": [
{
"type": "timeseries",
"dataKeys": [
{
"name": "temperature",
"type": "timeseries",
"label": "温度",
"color": "#3498db",
"func": "avg",
"aggregation": "AVG",
"timeWindow": "1h"
}
]
}
],
"timewindow": {
"realtime": { "interval": 1000, "timewindowMs": 60000 },
"history": { "fixedTime": { "startTs": 0, "endTs": 0 } }
},
"settings": {
"showLegend": true,
"showTooltip": true,
"stackLines": false,
"smoothLines": true
}
}
关键点：
func 和 aggregation 决定了数据点的聚合方式。实时模式下建议用 NONE 或 AVG，历史报表场景常用 SUM 或 MAX。
3.3 卡片与控制类Widget
卡片类 Widget 用于呈现设备的最新状态或关键指标。常见的卡片类型包括：
- Digital Gauge（数字仪表）：模拟指针表盘，适合温度、压力等连续量。
- HTML Card（HTML 卡片）：支持自定义 HTML 模板，可嵌入图标、单位、状态色块。
- Label Card（标签卡片）：纯文本显示，适合展示设备名称、位置、固件版本。
控制类 Widget 实现了从仪表板到设备的反向通道。典型控制组件：
| Widget 名称 | 控制方式 | 适用场景 | 返回值处理 |
|---|---|---|---|
| Switch Control（开关） | RPC 请求 setValue |
继电器、灯光、阀门 | 超时重试 / 状态回显 |
| Slider Control（滑块） | RPC 请求 setValue |
调速、调光、设定阈值 | 实时反馈数值 |
| Button（按钮） | RPC 请求或 Attribute Write | 触发拍照、重启、校准 | 显示执行结果 |
| Dropdown（下拉选择器） | Attribute Write | 切换模式、选择配置 | 写入后刷新 |
安全注意： 控制类 Widget 会直接操作设备。生产环境中务必配置 仪表板权限（只读/可写），并启用 RPC 速率限制，防止误操作或恶意攻击。
3.4 地图类Widget
地图 Widget 依赖设备上报的 latitude 和 longitude 属性。ThingsBoard 支持两种地图引擎：
- OpenStreetMap（默认）：免费、无需 API Key，适合内网或公网部署。
- Google Maps：需要配置 Google Maps API Key，提供更丰富的图层和街景。
地图 Widget 的核心功能：
- 设备标记：根据经纬度在地图上显示设备图标，支持自定义标记颜色和图标。
- 轨迹回放：结合时间序列数据，回放设备移动路径。
- 热力图：聚合大量设备位置，展示密度分布。
- 边界圈选：绘制地理围栏，触发告警。
3.5 Widget资源包管理
Widget 资源包（Resource Bundle）是 ThingsBoard 管理 自定义 Widget 和 第三方 Widget 库 的单位。每个资源包包含一个或多个 Widget，以及对应的 JavaScript、CSS、HTML 资源。
资源包的核心结构：
{
"resourceType": "widgetBundle",
"title": "工业仪表板组件库",
"alias": "industrial_widgets",
"image": "data:image/png;base64,...",
"description": "适用于工厂车间的专用 Widget 集合",
"widgetTypes": [
{
"alias": "machine_status",
"name": "设备状态指示器",
"descriptor": { ... }
},
{
"alias": "production_gauge",
"name": "产量仪表盘",
"descriptor": { ... }
}
]
}资源包管理操作：
| 操作 | 路径 | 说明 |
|---|---|---|
| 查看资源包 | Widgets Library → Resource Bundles | 列出所有已安装的资源包 |
| 导入资源包 | Widgets Library → 右上角 “+” → Import bundle | 支持 JSON 格式的包文件 |
| 导出资源包 | 点击资源包 → Export | 导出为 JSON，便于迁移或分享 |
| 删除资源包 | 点击资源包 → Delete | 删除前需确认无仪表板引用 |
最佳实践： 将业务相关的 Widget 归类到同一个资源包中（如“能源管理组件库”），便于团队协作和版本管理。导出的 JSON 文件应纳入 Git 仓库。
3.6 Widget类型与资源包关系图
下图展示了标准 Widget 类型与资源包之间的组织关系：
3.7 资源包导入与导出实战
以下是通过 REST API 导入资源包的示例：
curl -X POST "http://your-thingsboard-server/api/widgetsBundle" \
-H "Content-Type: application/json" \
-H "X-Authorization: Bearer YOUR_JWT_TOKEN" \
-d '{
"title": "自定义工业组件",
"alias": "custom_industrial",
"image": "data:image/png;base64,iVBOR...",
"description": "包含设备状态、产量仪表等 Widget",
"widgetTypes": []
}'导出资源包时，系统会生成包含所有 Widget 描述符的 JSON 文件。建议在导出前检查以下内容：
- 所有 Widget 的 alias 是否唯一且语义清晰。
- 资源文件（JS/CSS/HTML）是否已内联或通过 resourceUrl 引用。
- 是否包含 依赖库（如 D3.js、ECharts）的版本声明。
版本兼容性： ThingsBoard 3.3 及以上版本支持资源包导入时的 冲突检测。如果 alias 已存在，系统会提示覆盖或跳过。建议在测试环境先导入验证。
3.8 本章小结
标准 Widget 类型是 ThingsBoard 数据可视化的基础积木：
- 图表 负责趋势分析，卡片 负责状态呈现，控制 负责指令下发，地图 负责空间定位。
- Widget 资源包 是组织和分发自定义 Widget 的容器，支持导入/导出，便于团队复用。
- 掌握资源包管理，是迈向 自定义 Widget 开发 的第一步。