topo-engine 0.1.7 → 0.1.8

package/docs/API.md

@@ -575,6 +575,118 @@ resetAllNodeStyles(): void
 
 ---
 
+### 节点 / 箱内电表户染色（psrId / 资产编号）
+
+> 给图元“换颜色”。引用规则与 `addConnection` 完全一致：
+> - **普通节点** —— 节点内部 id 或 **`psrId`（设备编码）**：变压器 / 开关 / 熔丝 /
+>   导线连接点 / 母线 / 用户接入点 / 计量箱本体均可；
+> - **箱内电表户** —— 客户档案里的 **`assetNo`（资产编号）**（兼容 `consNo`/`consId`）：
+>   命中计量箱内该户的**电表图标 + 户名**（单户箱即整箱那一只表；多户箱只染该格）。
+>
+> 渲染效果：
+> - 普通节点为**整图单色换装**——主体 / 引线 / 描边全部换成指定色，
+>   白字与浅色细节（开关 Kxx 标签、内高光、装饰条）保留以保证可读；
+> - 箱内电表户染该户表体 / 显示窗 / 脉冲点与户名颜色；悬停（青）与选中（金）优先级更高，
+>   取消悬停 / 选中后自动回到所染颜色。
+>
+> 染色记录保存在 API 内部，**主题切换 / 数据重渲染后自动保留并重放**（同一次会话内
+> 无需重新调用；`resetNodeColor` / `resetAllNodeColors` 可清除）。
+
+#### `setNodeColor(ref, color)`
+
+按 **节点 psrId / id** 或 **用户 assetNo（资产编号）** 染色。
+
+```ts
+setNodeColor(ref: string, color: string | null): boolean
+// color 传 null / '' / undefined 等价于清除该处染色（回到主题默认配色）
+```
+
+**示例：**
+```js
+// 1) 普通节点：按 psrId（设备编码）把变压器染红
+topo.setNodeColor('8ff4786d548a7073a2517297e801518ff456732f4d', '#FF0000');
+
+// 2) 电表户：按资产编号（assetNo）把某户电表染橙
+topo.setNodeColor('4230010007008084768', '#FF6600');
+
+// 3) 也支持节点内部 id
+topo.setNodeColor('5', '#00FF00');
+
+// 4) 清除染色（回到主题默认色）
+topo.setNodeColor('4230010007008084768', null);
+```
+
+---
+
+#### `batchSetNodeColor(entries, color?)`
+
+批量染色（如后端返回「psrId → 状态色」「assetNo → 状态色」列表时一次性下发）。
+三种入参形式：
+
+```ts
+batchSetNodeColor(entries: any, color?: string): {
+  total: number;
+  ok: number;
+  failed: Array<{ ref: string, reason: string }>;
+}
+```
+
+**示例：**
+```js
+// 形式 1：[ref, color] 数组
+topo.batchSetNodeColor([
+  ['8ff4786d548a7073a2517297e801518ff456732f4d', '#FF0000'],
+  ['4230010007008084768', '#FF6600'],
+]);
+
+// 形式 2：对象数组（color 缺省时用第 2 参）
+topo.batchSetNodeColor([
+  { psrId: '8ff4…', color: '#FF0000' },
+  { assetNo: '4230…' },
+], '#FF6600');
+
+// 形式 3：ref → color 对象
+topo.batchSetNodeColor({
+  '8ff4786d548a7073a2517297e801518ff456732f4d': '#FF0000',
+  '4230010007008084768': '#FF6600',
+});
+```
+
+---
+
+#### `resetNodeColor(ref)`
+
+清除指定节点 / 电表户的染色。
+
+```ts
+resetNodeColor(ref: string): boolean
+```
+
+---
+
+#### `resetAllNodeColors()`
+
+清除全部染色（所有节点与电表户回到主题默认配色）。
+
+```ts
+resetAllNodeColors(): void
+```
+
+---
+
+#### `getNodeColor(ref)`
+
+查询某处当前生效的染色（未命中返回 `null`）。
+
+```ts
+getNodeColor(ref: string):
+  | { kind: 'node', id: string, color: string | null }
+  | { kind: 'customer', id: string, boxId: string, index: number, color: string | null }
+  | null
+```
+
+---
+
 ## 四、边样式
 
 ### `setEdgeStyle(srcId, tgtId, style)`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "topo-engine",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "private": false,
   "type": "module",
   "description": "配电台区单线图拓扑成图引擎 (Vue3 + G6 v5 + Node/Vite)",