物联网后端数据可视化消息队列【免费下载链接】thingsboardAll-in-one IoT Platform - Device management, data collection, processing and visualization.项目地址https://gitcode.com/GitHub_Trending/th/thingsboard点击查看免费下载本篇技术指南围绕 ThingsBoard 液位卡片部件Liquid Level Card Widget中的Shape attribute name形状属性名功能展开。该功能允许你在部件运行时根据实体如设备上某个客户端属性或共享属性的取值动态切换液位卡片渲染的储罐形状而无需为每种形状分别创建部件配置。读完本文你将掌握该功能的适用场景、在部件配置界面中的完整配置步骤、10 种内置形状对应的精确属性值字符串、底层源码级实现原理以及属性缺失或非法时的回退与错误提示机制。液位卡片默认储罐形状示例Vertical Cylinder一、什么是 Shape attribute name在 ThingsBoard 的部件配置体系中液位卡片部件源码见 liquid-level-widget.component.ts 与 liquid-level-widget.models.ts支持两种“形状来源”模式Static静态在部件配置里直接选择一个固定形状selectedShapeAttribute属性驱动由属性名shapeAttributeName指定一个属性键部件在运行时读取该属性的字符串值用这个字符串作为形状名去匹配内置形状。shape_attribute_fn.md即本主题的官方帮助文档位于 ui-ngx/src/assets/help/en_US/widget/lib/indicator/shape_attribute_fn.md对它的定义非常明确A string expression value that allows you dynamically select shape image depending on attribute name (ex. tankShape).即一个字符串类型的表达式值允许你根据属性名例如tankShape动态选择形状图片。属性值本身必须是对应形状的精确名称字符串大小写敏感下方第二章给出了完整清单。这种模式的核心价值在于同一台设备的属性值变了仪表板上液位卡片的形状就会随之变化。典型场景包括设备上报tankShape Horizontal Cylinder时卡片自动从立式罐切换为卧式罐用于反映不同的物理储罐构型通过规则引擎或设备端脚本按需改写属性让同一部件在不同实体上呈现不同外观批量复用一套仪表板模板覆盖多种罐型外观完全由各设备的属性值决定。二、可用的形状属性值完整清单以下是官方文档列出的全部 10 种形状及其必须精确匹配的属性值字符串。这些字符串与源码 liquid-level-widget.models.ts 中Shapes枚举定义完全一致属性值必须逐字符一致包括大小写与空格否则无法匹配Vertical Oval {:copy-code}Vertical Cylinder {:copy-code}Vertical Capsule {:copy-code}Rectangle {:copy-code}Horizontal Oval {:copy-code}Horizontal Ellipse {:copy-code}Horizontal Dish Ends {:copy-code}Horizontal Cylinder {:copy-code}Horizontal Capsule {:copy-code}Horizontal 2:1 Elliptical {:copy-code}注{:copy-code}是 ThingsBoard 帮助系统内的标记表示该代码块在帮助弹窗中可直接点击复制方便你把精确值粘贴到属性值中去。2.1 形状与 SVG 资源、液位范围映射源码svgMapping见 liquid-level-widget.models.ts将每个形状映射到对应的 SVG 资源文件以及液面动画在 SVG 坐标系中的min/max位移范围用于将百分比线性换算为液面高度见calculatePosition()的limits.min (percentage / 100) * (limits.max - limits.min)插值逻辑属性值Shapes 枚举SVG 资源文件液位范围 min → maxVertical Ovalvertical-oval.svg171 → 51Vertical Cylindervertical-cylinder.svg161 → 55Vertical Capsulevertical-capsule.svg197 → 25Rectanglerectangle.svg169 → 52Horizontal Ovalhorizontal-oval.svg160 → 63Horizontal Ellipsehorizontal-ellipse.svg160 → 64Horizontal Dish Endshorizontal-dish-ends.svg173 → 50Horizontal Cylinderhorizontal-cylinder.svg165 → 56Horizontal Capsulehorizontal-capsule.svg171 → 52Horizontal 2:1 Ellipticalhorizontal-2_1-elliptical.svg173 → 50这些 SVG 文件全部位于 ui-ngx/src/assets/widget/liquid-level/shapes/ 目录实际渲染时由ResourcesService.loadJsonResource以文本方式加载经createShapeLayout()按布局simple / percentage / absolute改写 SVG DOM 后再以内联 Data URI 形式呈现。三、配置步骤如何在液位卡片中使用属性名选形以下配置入口同时存在于液位卡片的基础配置basic config与高级设置advanced settings中对应模板文件基础配置liquid-level-card-basic-config.component.html高级设置liquid-level-card-widget-settings.component.html配置步骤如下进入仪表板编辑模式添加Liquid Level Card部件位于 Indicator 部件分组下绑定设备/实体数据源。打开部件配置找到Shape形状面板。将“形状来源”切换开关tankSelectionType从Static切到Attribute。切换后静态形状选择卡片selectedShape会被隐藏取而代之的是一个属性名输入框。在输入框中填写属性名shapeAttributeName例如文档示例中的tankShape。该输入框带有字符串自动补全tb-string-autocomplete会根据当前数据源设备或实体别名自动拉取该实体上已存在的属性键减少手输错误补全逻辑见 liquid-level-card-widget-settings.component.ts 的fetchOptions/getKeys属性键通过EntityService.getEntityKeysByEntityFilter获取。在输入框下方会出现提示文案 “Set tank shape by attribute name”通过属性名设置储罐形状右侧是“See examples”按钮——点击后会弹出帮助窗口内容正是本文所依据的 shape_attribute_fn.md 文档在模板中以[tb-help-popup]widget/lib/indicator/shape_attribute_fn方式引用。在实体上为步骤 4 填写的属性键写入值如tankShape Vertical Capsule保存后刷新部件即可看到形状随属性值变化。出于健壮性考虑建议同时在selectedShape中保留一个默认形状默认值为Vertical Cylinder见下方第四节用于属性缺失时的兜底回退。四、默认设置与数据模型在 liquid-level-widget.models.ts 的levelCardDefaultSettings中与本功能相关的默认值如下tankSelectionType: LiquidWidgetDataSourceType.static, // 默认静态模式 selectedShape: Shapes.vCylinder, // 默认形状Vertical Cylinder shapeAttributeName: tankShape, // 默认属性名tankShape对应地表单校验在 liquid-level-card-widget-settings.component.ts 中为selectedShape与shapeAttributeName均挂了Validators.required即静态模式下必须选择形状属性模式下必须填写属性名。当tankSelectionType切换时updatedFormSettingsValidators()见 liquid-level-widget.models.ts会相应地启用/禁用shapeAttributeName与selectedShape字段防止出现二者同时生效或同时缺失的非法配置。LevelCardWidgetSettings接口同文件 L36-L72完整定义了该部件全部配置项其中与形状相关的三个字段为tankSelectionType、selectedShape、shapeAttributeName。五、源码级实现原理5.1 属性读取与形状解析部件在初始化时调用getData()→getShape(entityId)见 liquid-level-widget.component.ts。核心逻辑如下private getShape(entityId: EntityId): ObservableShapes { if (this.settings.tankSelectionType LiquidWidgetDataSourceType.attribute entityId.id ! NULL_UUID) { return this.ctx.attributeService.getEntityAttributes(entityId, null, [this.settings.shapeAttributeName]) .pipe(map(attributes { const shape extractValueShapes(attributes, this.settings.shapeAttributeName); if (!shape || !svgMapping.has(shape)) { this.createdErrorMsg(this.settings.shapeAttributeName, isUndefinedOrNull(shape) || isEmptyStr(shape)); return this.settings.selectedShape; // 回退到默认形状 } return shape; } )); } return of(this.settings.selectedShape); }关键点逐条解读只有tankSelectionType attribute且实体 ID 不是NULL_UUID时才发起属性查询查询通过ctx.attributeService.getEntityAttributes(entityId, null, [shapeAttributeName])完成返回该实体上对应属性键的取值列表extractValue()见 liquid-level-widget.models.ts从属性数组中按attr.key attributeName取出属性值合法性校验取到的值必须非空且必须存在于svgMapping中即必须是第二节列出的 10 个精确字符串之一否则视为无效回退机制属性缺失或非法时部件不会崩溃而是生成错误消息并回退到配置里selectedShape指定的默认形状继续渲染。5.2 形状匹配与 SVG 加载拿到合法的Shapes值后getData()通过svgMapping.get(shape)取出对应的 SVG 路径与液位范围然后用resourcesService.loadJsonResourcestring(svgPath)加载 SVG 文本再与体积/单位等参数并行组装forkJoin最终注入到部件 DOM 中渲染。这解释了为什么属性值必须与枚举字符串精确一致——它本质上是svgMapping这个MapShapes, SvgInfo的键。5.3 液面动画与形状差异处理在updateLevel()liquid-level-widget.component.ts中还针对不同形状做了差异化处理当形状为Vertical Cylinder时液面表面元素的定位属性使用cy圆形中心 y 坐标其他形状则使用y矩形/其他图形顶部 y 坐标const surfacePositionAttr this.shape ! Shapes.vCylinder ? y : cy;这进一步说明形状选择不仅影响外观图片还会影响部件内部的动画定位逻辑是深度耦合到渲染管线中的。六、异常处理与错误提示当属性读取失败或值非法时createdErrorMsg()liquid-level-widget.component.ts会生成两类错误消息国际化 key 见 locale.constant-en_US.json 中widgets.liquid-level-card分组场景错误文案属性键存在但值为空/未设置Attribute key {{attributeName}} is not setkeyattribute-key-not-set属性值存在但不是合法形状名Attribute key {{attributeName}} is invalidkeyattribute-key-invalid错误发生时部件会形状回退沿用selectedShape默认形状继续渲染外观置灰updateShapeColor()将储罐描边与填充色强制改为#CACACA灰updateLevel()将液面颜色改为transparent透明让使用者直观感知“属性驱动失败”的状态消息累积errorsMsg[]中累积错误供部件模板展示同时触发变更检测刷新界面。这一“失败可见、渲染不中断”的设计使属性驱动模式在设备数据不完整时依然具备良好的可观测性。七、静态模式与属性驱动模式对比维度Static静态Attribute属性驱动形状来源配置中selectedShape固定值实体上shapeAttributeName对应属性的字符串值配置界面显示形状图片选择卡片显示属性名输入框带自动补全与 “See examples” 帮助运行时行为恒定不变属性值变化即切换形状非法值处理不适用回退到selectedShape并提示错误适用场景单一固定罐型多罐型复用同一部件/仪表板模板总结Shape attribute name 是 ThingsBoard 液位卡片部件提供的外观数据驱动能力通过在实体上维护一个字符串属性默认约定键名为tankShape即可让同一部件在不同设备、不同时刻呈现 10 种内置罐型立式/卧式椭圆、圆柱、胶囊、矩形、碟形封头等。使用时只需牢记两点属性值必须与Shapes枚举的精确字符串一致务必保留selectedShape默认值作为兜底。其底层实现属性查询 → 枚举匹配 → SVG 映射 → 差异化动画位于 liquid-level-widget.component.ts 与 liquid-level-widget.models.ts官方帮助文档与完整形状清单见 shape_attribute_fn.md可在部件配置界面的 “See examples” 帮助弹窗中随时查阅。赞分享物联网后端数据可视化消息队列【免费下载链接】thingsboardAll-in-one IoT Platform - Device management, data collection, processing and visualization.项目地址https://gitcode.com/GitHub_Trending/th/thingsboard点击查看免费下载相关推荐Reflex Props 完全指南组件属性、通用属性、样式属性与状态绑定Reflex Props 完全指南组件属性、通用属性、样式属性与状态绑定 导读 Props属性是 Reflex 组件系统的核心交互接口——它们以关键字参数后端前端Web框架G6 原子形状Atomic Shape与样式属性完整指南从 BaseShape 到 10 种内置图形G6 原子形状Atomic Shape与样式属性完整指南从 BaseShape 到 10 种内置图形 G6 中的节点node、边edge与组合c数据可视化前端图表库Mihon夜间模式切换动画属性动画与状态管理Mihon夜间模式切换动画属性动画与状态管理 你是否曾在阅读漫画时被夜间模式切换的生硬效果打断沉浸感Mihon作为开源漫画阅读应用通过精心设计的属性动画与移动开发上一篇如何快速成为全栈开发者前端工程化与构建工具终极指南下一篇3分钟掌握vokoscreenNG专业级屏幕录制神器使用指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考