4、部件库详解：基础部件、图表部件、控制部件、地图部件、输入部件
好，咱们今天来啃一块硬骨头——ThingsBoard 的部件库。
说实话，我刚接触 ThingsBoard 那会儿，面对这几十个部件，心里也犯过嘀咕：这么多玩意儿，到底哪个该用在哪？后来做项目做多了，慢慢就摸清了门道。说白了，部件库就是你的乐高积木盒，每个部件都有它的脾气和用途。
我个人习惯把部件分成五大类：基础、图表、控制、地图、输入。咱们一个一个过。
4.1 基础部件：打地基的活儿
基础部件是仪表盘的骨架。没有它们，你连个像样的界面都搭不起来。
| 部件名称 | 核心用途 | 我常用的场景 |
|---|---|---|
| 卡片 | 展示单个数据点或状态 | 设备在线状态、最新温度值 |
| 标签页 | 切换不同视图 | 按设备分组展示数据 |
| HTML 卡片 | 自定义富文本内容 | 嵌入操作说明或公司Logo |
| 分割线 | 视觉分隔 | 区分不同功能区 |
嗯，这里要注意：卡片部件是最容易被低估的。很多人觉得它太简单，其实它能做的事情很多。比如，你可以通过配置「高级」里的 CSS 样式，让卡片在数据异常时变红。我在项目中就遇到过，客户要求设备离线时卡片边框闪烁红色，用卡片部件的自定义样式轻松搞定。
<span style="color:red">●</span> 这样的方式，在标题里加个小红点，直观显示告警状态。
4.2 图表部件：数据会说话
图表部件是仪表盘的灵魂。数据再漂亮，不会展示也是白搭。
ThingsBoard 内置了三种图表部件：
- 时序图：最常用，展示数据随时间的变化趋势。比如温度曲线、电压波动。
- 柱状图：适合对比不同维度的数据。比如各台设备的能耗对比。
- 饼图/环形图：展示占比关系。比如设备运行状态分布。
我个人最常用的是时序图。为什么？因为物联网数据天生就是时间序列数据。你想想看，传感器每隔几秒上报一次数据，不用时序图用什么？
配置时序图时，有几个坑我曾经踩过：
- 时间范围设置不当：默认显示最近1小时，如果设备上报频率低，图表上可能只有几个点，看起来像没数据。我建议根据设备上报频率调整时间范围。
- 聚合函数选错：时序图默认用「平均值」聚合。但如果你要统计设备运行时长，应该用「计数」或「总和」。有一次客户说数据不对，查了半天发现是聚合函数用错了。
- Y轴范围没锁定：数据波动大时，Y轴自动缩放会让图表看起来很夸张。我习惯手动设置Y轴范围，保持视觉稳定。
4.3 控制部件：让仪表盘动起来
控制部件是 ThingsBoard 区别于普通看板工具的地方。它不只是看，还能操作。
常用的控制部件有：
- 开关：控制设备的开关状态。比如远程控制灯光、电机。
- 滑块：调节数值型参数。比如设定温度、调节音量。
- 按钮：触发一次性操作。比如重启设备、发送指令。
配置控制部件时，核心是理解「RPC 命令」的概念。说白了，就是仪表盘通过 MQTT 或 HTTP 给设备发一条指令。
// 开关部件的 RPC 配置示例
{
"method": "setSwitch",
"params": {
"state": true
},
"timeout": 5000
}嗯，这里有个关键点：超时时间。我建议设成 5-10 秒，太短设备来不及响应，太长用户体验差。我曾经设成 30 秒，结果用户点了开关后以为没反应，又点了一次，设备收到两条指令，直接懵了。
4.4 地图部件：位置即信息
地图部件适合展示设备的地理位置。比如物流追踪、车辆监控、基站分布。
ThingsBoard 支持两种地图：
- OpenStreetMap：免费，但加载速度一般。
- Google Maps：需要 API Key，但体验更好。
配置地图部件时，你需要告诉它两件事：
- 经纬度从哪里来：通常来自设备的属性或遥测数据。比如设备上报的
latitude和longitude字段。 - 标记点长什么样：可以自定义图标、颜色、弹出信息。
我记得有一次做冷链物流项目，客户要求在地图上显示冷藏车的实时位置，并且温度超标时标记点变红。这个需求用地图部件的「标记颜色函数」就能实现：
// 标记颜色函数示例
if (entity.temperature > 8) {
return 'red';
} else {
return 'green';
}你看，几行代码就搞定了。这就是 ThingsBoard 灵活的地方。
4.5 输入部件：让用户填数据
输入部件是仪表盘和人交互的窗口。比如填写备注、设置参数、搜索设备。
常用的输入部件：
- 文本框：输入短文本。比如设备名称、备注信息。
- 下拉框：从预设选项中选择。比如选择设备类型、筛选状态。
- 日期选择器：选择时间范围。比如查询历史数据。
- 数字输入框：输入数值。比如设定阈值、输入数量。
输入部件的核心是「数据绑定」。你输入的内容，可以保存到设备的属性中，也可以作为仪表盘状态变量，供其他部件使用。
举个例子，你想做一个「按设备名称搜索」的功能：
- 放一个文本框部件，绑定到仪表盘状态变量
searchText。 - 在表格部件的数据查询中，添加过滤条件：
name like '%{searchText}%'。 - 用户在文本框输入内容，表格自动过滤。
是不是很简单？但要注意，输入部件的值变化是异步的。也就是说，用户输入后不会立即生效，需要触发「更新」动作。我建议在文本框旁边加一个搜索按钮，用户输入完点击按钮才触发查询，这样更可控。
小结
好了，五大类部件咱们都过了一遍。总结一下：
- 基础部件：搭骨架，别小看卡片和标签页。
- 图表部件：时序图最常用，注意时间范围和聚合函数。
- 控制部件：RPC 指令是核心，超时时间和确认对话框别忘。
- 地图部件：经纬度来源和标记颜色是重点，注意性能。
- 输入部件：数据绑定和默认值设置，用户体验的关键。
下一章咱们会深入讲解「数据源配置」，这是仪表盘开发中最容易出错的地方。到时候我会分享几个我踩过的深坑，保证让你少走弯路。
今天就到这儿。有什么问题，欢迎在评论区留言。