图片图元（image）

实际项目里总有一堆现成的图：设备照片、厂商给的机组示意、CAD 导出的厂区底图、第三方图标包。image 图元让这些图直接变成组态图元——和内置工业符号完全同权：能接线、能旋转、能做等轴测投影、能绑测点按值换图、能参与多状态与条件样式。

与内嵌「图片组件」的区别：内嵌组件是浮在画布上的一层 HTML，不参与图元的连线与层序；image 图元活在同一张 SVG 里，是真正的图元。

放图方式

方式	操作
图元库「行业图片」	9 行业 2.5D 静态图与等格序列帧；可按行业 / 静态·序列帧 / 分类筛选，双击/拖入即成图片图元，精灵图会同时写入 sprite-*
图元库「我的图片」	账号素材库卡片，双击或拖到画布，自动按原图宽高比摆好
直接拖文件	把图片从桌面拖进组态画布，自动上传素材库并落成图元
粘贴	截图后在画布上 Ctrl+V，同样自动上传并插入

素材统一进素材库，账号级、跨工程复用，同一张图重复上传会按内容散列自动合并。内置行业图地址形如 /scada-images/water/static/bar-screen.png（编辑器 / 预览器已同步 public/scada-images/），工程 JSON 可直接写该路径。

选项

选项	说明
image-url	图片地址：素材库地址（/api/files/…）、外链、或 dataURL
image-fit	contain 等比适配留白（默认）/ cover 等比裁切铺满 / stretch 拉伸铺满（可能变形）
image-by-value	开启「按值换图」（需先 data-enabled + data-key）
image-rules	多行 值1|值2=图片地址；未命中回落 image-url

未填 image-url 时画一个虚线占位框，图元在画布上仍可见可选中。

按值换图

组态最常见的多态需求——泵启停两张图、阀开关三态图——不用叠三个图元再写显隐规则，一条规则搞定：

{
  "uid": "node_pump",
  "type": "scada-node",
  "options": {
    "shape": "image",
    "geo-x": 200, "geo-y": 120, "geo-w": 160, "geo-h": 120,
    "image-url": "/api/files/vp_resources/abc123/pump-stop.png",
    "image-fit": "contain",
    "data-enabled": true,
    "data-key": "pump1.state",
    "image-by-value": true,
    "image-rules": "run|1=/api/files/vp_resources/abc123/pump-run.png\nfault=/api/files/vp_resources/abc123/pump-fault.png"
  }
}

值按字符串比较，数字测点（1/0）与文本测点（run/stop）通吃。测点断线（无值）时保持 image-url 那张，不会让图元凭空消失。

规则在属性面板里是可视化的：逐行填值 + 从素材库挑图 + 缩略图预览，不用手写地址。

精灵图动画（序列帧）

一张图里排好多帧（风机转一圈、管道流一格、告警灯闪一下），图元按网格切帧、逐帧播放。

选项	说明
sprite-enabled	开启精灵图动画
sprite-cols / sprite-rows	帧网格的列数 / 行数
sprite-frames	总帧数，0 = 列×行
sprite-fps	帧率（1~60），一轮时长 = 帧数 ÷ 帧率
sprite-play	播放 / 停止
sprite-reverse	倒放
sprite-stop-frame	静止时显示第几帧（从 0 开始）。运行时用「组态·改图元选项」或 SDK setPieceOption 写本项会自动停播并停在那一帧

帧按行优先编号：左→右、上→下。属性面板里有列/行/帧数三个输入加一条真实帧预览，切歪了一眼就能看出来；点某一帧即把它设为停止帧。

每格恒等于图元盒，所以精灵模式下不出现「贴合方式」——用面板上的 按帧比例适配盒子 按原图单帧宽高比重摆图元盒，就不会被拉变形。

帧数与网格

单行或单列的条带可以让 sprite-frames 少于格数，末尾多余的格子不会被播出来。网格排布（列、行都大于 1）的帧数会被钳回 列×行——两轴逐格步进跳不过末行的空格。

按测点起停

组态里动画通常该跟着设备走：泵运行时叶轮转、停机时停在静止那一帧。

{
  "data-enabled": true,
  "data-key": "fan1.state",
  "sprite-by-value": true,
  "sprite-rules": "run|1=on:16\nstop|0=off:0\nfault=reverse:4"
}

规则里每行一条 值1|值2=token，token 是 on / off / reverse。冒号后的参数：on 与 reverse 跟帧率，off 跟停止帧号。未命中或测点断线时沿用图元自己的静态设置，动画不会乱跳。

按值选帧（图像集）

把精灵图当组态经典的「多态图」：正常显示第 0 张、报警显示第 1 张，不必叠多个图元再写显隐。

选项	说明
sprite-frame-by-value	开启按值选帧（需先 data-enabled + data-key）
sprite-frame-mode	rules 按值集合（枚举状态）/ linear 按量程均分（液位/开度）
sprite-frame-rules	多行 值1|值2=帧号，如 normal|0=0、alarm|1=1
sprite-frame-in-min / sprite-frame-in-max	线性模式的量程，均分到 0..帧数-1

命中即静止在该帧。与「按值起停」可同时开：起停规则没表态时默认停在选中帧。测点断线不覆盖，画面不乱跳。

按钮 / SDK 指定第几张

不必先造测点。两种口子等价：

• 交互动作 组态·改图元选项（scadaSetOption）：目标画板 + 图元 uid + option 填 sprite-stop-frame + value 填帧号。
• SDK：ctx.getScada('画板uid')?.setPieceOption('图元uid', 'sprite-stop-frame', 1)。

关掉 sprite-play 后，图元就是一张可切换的图像集。

和 GIF 的区别

GIF / APNG / 动图 WebP 直接放进 image-url 也能动，但那是浏览器自己在播——起停、速度、停在哪一帧都控不了，也没法跟测点联动。要让动画听设备的话，用精灵图。

与内置形状同等能力

图片图元和泵、阀走同一套几何与动画，不另开接口：

• 端口：四向端口（上 / 右 / 下 / 左），可被连线吸附，图片也能接进工艺流程。
• 动画：anim / anim-speed（闪烁、脉冲、旋转、抖动…），以及 anim-by-value 按测点切动画。
• 数据：visible-by-value 按值显隐、rotate/move/scale-by-value 值驱动位移旋转缩放（叠加在 geo-rotate 之上）。
• 外观：opacity、geo-rotate、iso-plane 等轴测投影；多状态与条件样式照常生效。

需要矢量图形（可随主题换色、无限放大不糊）请用 自定义 SVG；位图照片用本图元。

开源符号示例

仓库自带两套 Apache-2.0 常用组态符号，可直接导入工程对照，也可把文件夹拖进素材库：

工程	符号来源	演示
data/组态/10-开源组态符号-ISA101工艺流程-科技蓝.vpproj.json	ISA-101 HP-HMI 线框符号	泵/阀/电机/输送带 按值换图（停/运/故障）
data/组态/11-开源组态符号-ThingsBoard高画质厂区-科技蓝.vpproj.json	ThingsBoard HP 写实符号	罐/泵/换热/阀/光伏/风机/储能厂区
data/组态/12-精灵图动画-序列帧图片图元-科技蓝.vpproj.json	编译期内联 SVG 条带	横排/网格/竖排 + 按值起停/选帧
data/组态/13-行业图像集画廊-静态与序列帧-科技蓝.vpproj.json	data/images 行业库	9 行业墙：静态卡 + 精灵图自动播
data/组态/14-水务工艺-序列帧与按值换图-科技蓝.vpproj.json	同上	泵叶轮 sprite-by-value、曝气序列帧、阀换图
data/组态/15-2.5D场站-等轴测与序列帧-科技蓝.vpproj.json	同上	iso-platform + 风机/输送带精灵图
data/组态/16-煤矿采运提-皮带与瓦斯序列帧-科技蓝.vpproj.json	同上	皮带 / 采煤机 / 瓦斯闪 + 测点起停
data/组态/20-生成图复原-化工储运罐区-科技蓝.vpproj.json	生成图抠图 + /scada-images/	对照原图复原罐区，反应釜搅拌序列帧、阀换图；2.5D 摆位规范的参考实现
data/组态/21-生成图复原-煤矿井口洗选-科技蓝.vpproj.json	同上	对照原图复原矿区，皮带走带 / 主扇通风机双序列帧 + 测点起停

原始 SVG 与许可说明见 data/组态素材/ATTRIBUTION.md。ThingsBoard 源文件里的 tb: 脚本已剥离，本平台只当静态图用。