topo-engine 0.1.6 → 0.1.8

package/README.md

@@ -6,18 +6,19 @@
 
 ## 功能特性
 
-- 🧩 **Vue 3 组件** — `TopoGraph`（画布，含标题栏 / 统计 / 适应画布 / 导出 PNG 按钮）、`SidePanel`（设备详情与上下游）、`DistanceTop10`（父子连线距离 Top10 面板）
+- 🧩 **Vue 3 组件** — `TopoGraph`（画布；可选左上工具条默认隐藏，`:toolbar` 开启）、`SidePanel`（设备详情与上下游）、`DistanceTop10`（父子连线距离 Top10 面板）
 - 🎨 **深色 / 浅色双主题** — 黑底 SCADA 或白底两种画布风格，图元 / 导线 / 文字随之配套适配，可随时切换（`theme` prop 或工具栏按钮）。默认浅色主题
 - 📐 **自研正交布局** — 主干沿最长路径横向铺开 + 分支带垂直直走，整图**横平竖直、0 交叉、0 重叠**，边缘路由为直线 / L 形折线
 - 🔍 **拓扑查询 API** — 节点 / 边 / 邻居 / 子树 / 主干链 / 路径 / 坐标 查询
 - 🎨 **样式控制** — 节点、边样式覆盖与批量重置
+- 🎨 **节点 / 电表染色** — 按 **psrId（设备编码）** 染普通节点、按 **assetNo（资产编号）** 染计量箱内电表户（状态色、告警色场景）
 - ✨ **动画与高亮** — 节点脉动、边流动、路径高亮、其余变暗、异常标注
 - 📝 **文字标注** — 附加文字、用户名 full / short / hidden 切换
 - 🃏 **卡片盒** — 节点信息卡片（字段 + 按钮），适配"运行曲线/工单跳转"类场景
 - 🔗 **连接线 / 拓扑线** — 任意两节点动态连接线、路径拓扑高亮线
 - 🎧 **事件系统** — 点击 / 悬停 / 画布空白 / 视口变化事件总线
 - 💾 **导出** — 整图 PNG 下载、DataURL、图数据 JSON
-- 📦 **零配置渲染** — 组件自带深色主题与工具栏，`data` 或 `dataUrl` 二选一即可出图
+- 📦 **零配置渲染** — 组件内置主题与解析渲染，`data` 或 `dataUrl` 二选一即可出图
 
 ## 安装
 
@@ -33,6 +34,9 @@ npm install topo-engine
 import 'topo-engine/style.css';
 ```
 
+> 📖 **完整 API 参考手册**随包发布：安装后可打开 `node_modules/topo-engine/docs/API.md`，
+> 或在线查看仓库中的 [docs/API.md](docs/API.md)（事件、卡片、连接线、布局参数、TS 类型等一应俱全）。
+
 ## 快速开始
 
 ### 1. 最小示例 —— 只画一张图
@@ -186,20 +190,24 @@ const g6Data = buildGraphData(model, layout);   // → G6 可直接消费的 { n
 | ---- | ---- | ---- | ---- |
 | `dataUrl` | `String` | `''` | 拓扑 JSON 的 URL（内部 `fetch` 加载）。变化后自动重新加载 |
 | `data` | `Object` | `null` | 直接传入 JSON 对象；优先级高于 `dataUrl`；深度 watch，变化自动重绘 |
+| `customerData` | `Array` | `null` | 客户数据（`[{ psrId, consumerList }]`），注入计量箱并按户渲染 / 可点 |
 | `theme` | `'dark' \| 'light'` | `'light'` | 画布主题：`dark`（黑底 SCADA）/ `light`（白底，图元配套加深，默认）。支持 `v-model:theme`，也可点内置工具栏 ☀️/🌙 按钮切换 |
+| `toolbar` | `Boolean` | `false` | 是否显示左上工具条（标题 / 统计 / 主题 / 适应画布 / 导出 PNG），默认隐藏 |
 
 ### Emits
 
 | 事件 | 载荷 | 触发时机 |
 | ---- | ---- | ---- |
 | `loaded` | `{ title, stats }`，`stats = { total, depth, leaves, byCat }` | 每次数据渲染完成 |
-| `node-select` | `{ node, upstream, downstream }`（均为解析后模型节点） | 点击节点（含金框选中与详情联动） |
+| `node-select` | `{ node, upstream, downstream }`（均为解析后模型节点） | 点击节点（含金框选中与详情联动）；空白清除时 `node=null` |
+| `customer-select` | `{ node, customer, index, count, upstream, downstream }` | 点中计量箱内某个用户（展示客户档案） |
 | `top-distances` | `Array<{ parent: {id,name,catLabel}, child: {id,name,catLabel}, distance }>`（≤10） | 渲染完成时，父-子连线折线长度 Top10（过滤站内边与主干鱼骨边） |
 
 ### 内置交互与 UI
 
 - 滚轮缩放、拖拽平移、悬停高亮（上下游与连线），点击选中（金色虚框，再次点空白取消）。
-- 左上角深色工具栏：标题 / `节点 n · 边 m · 深度 d · 叶子 l` 统计 / 「适应画布」/「导出 PNG」按钮。
+- **计量箱用户点击**：单户箱整箱即该户；多户箱点电表格 / 户名 = 该户客户档案（悬停青圈、选中金圈），点箱体空白 = 选中整箱（事件 `consumer:click` / `customer-select`）。
+- 左上角工具条**默认隐藏**：传 `:toolbar="true"` 后显示标题 / `节点 n · 边 m · 深度 d · 叶子 l` 统计 / 「适应画布」/「导出 PNG」按钮。
 - 加载中 / 出错（如 dataUrl 404）有内置遮罩提示。
 - 卸载时自动 `destroy()` 图实例与事件监听，无内存泄漏。
 
@@ -211,6 +219,8 @@ const g6Data = buildGraphData(model, layout);   // → G6 可直接消费的 { n
 | ---- | ---- |
 | `loadRaw(jsonText)` | 用一段 JSON 文本（如本地文件上传内容）重新成图 |
 | `selectNode(id)` | 选中某节点并联动 `node-select` 事件 |
+| `selectCustomer(nodeId, index)` | 编程式选中计量箱内第 `index` 户（联动 `customer-select`） |
+| `getSelectedCustomer()` | 当前选中的户：`{ nodeId, index, customer, node } \| null` |
 | `resetView()` | 适应画布 |
 | `exportPng()` | 导出整图 PNG（按画布标题命名下载） |
 | `getLayoutData()` | 获取当前正交布局数据（坐标 / 折线 / stats） |
@@ -220,7 +230,7 @@ const g6Data = buildGraphData(model, layout);   // → G6 可直接消费的 { n
 
 引擎内置两套主题，**浅色为默认**（白底，图元配套深色，适合打印或嵌入浅色页面）；深色为**黑底 SCADA 风格**。
 
-- `TopoGraph`：`:theme` 取值 `'dark'`（默认）或 `'light'`，推荐 `v-model:theme` 双向绑定；组件左上工具栏内置 ☀️ / 🌙 切换按钮（点击 emit `update:theme`）。
+- `TopoGraph`：`:theme` 取值 `'light'`（默认）或 `'dark'`，推荐 `v-model:theme` 双向绑定；开启 `:toolbar="true"` 后工具条内置 ☀️ / 🌙 切换按钮（点击 emit `update:theme`）。
 - `SidePanel` / `DistanceTop10`：同样接收 `theme` prop，与画布保持一致观感。
 - 切换主题会**按当前数据自动重建画布**：G6 画布背景、图元、边、标注文字全部随主题更新，布局不变。
 
@@ -273,6 +283,24 @@ const dataUrl = ref('/data/topology.json');
 `setNodeStyle(id, style)`、`batchSetNodeStyle(ids, style)`、`resetNodeStyle(id)`、`resetAllNodeStyles()`
 `setEdgeStyle(src, tgt, style)`、`batchSetEdgeStyle([[src,tgt],…], style)`、`resetEdgeStyle(src, tgt)`
 
+### 节点 / 箱内电表户染色（psrId / 资产编号）
+
+```javascript
+// 普通节点：按 psrId（设备编码）整图单色换装（主体/引线/描边换成该色，白字细节保留）
+topo.setNodeColor('8ff4786d548a7073a2517297e801518ff456732f4d', '#FF0000');
+// 箱内电表户：按资产编号（assetNo，兼容 consNo/consId）染该户电表图标 + 户名
+topo.setNodeColor('4230010007008084768', '#FF6600');
+// 批量（数组 / 对象数组 / ref→color 对象均可）
+topo.batchSetNodeColor({ '8ff4…': '#FF0000', '4230…': '#FF6600' });
+// 清除 / 查询
+topo.resetNodeColor('4230010007008084768');
+topo.resetAllNodeColors();
+topo.getNodeColor('4230010007008084768'); // → { kind, id, color } | null
+```
+
+> 引用规则与 `addConnection` 一致：节点 id / **psrId** 命中普通节点；**assetNo** 命中计量箱内某户电表。
+> 染色记录随主题切换 / 数据重渲染自动保留并重放（无需重新设置）。详见 [docs/API.md](docs/API.md)。
+
 ### 高亮 / 变暗
 
 ```javascript
@@ -336,6 +364,7 @@ topo.removeAllTopoLines();
 | `canvas:click` | `{ event }` | 画布空白处点击 |
 | `viewport:change` | `{ zoom, center }` | 视口缩放 / 平移变化 |
 | `card:button` | `{ nodeId, buttonIndex }` | 卡片按钮点击 |
+| `consumer:click` | `{ nodeId, index, customer, node }` | 点中计量箱内用户（多户箱点格子；单户箱整箱即该户） |
 
 ```javascript
 const handler = ({ nodeId }) => console.log('点击了', nodeId);
@@ -361,10 +390,13 @@ topo.off('node:click', handler); // 不传 handler 则移除该事件全部监
 | 模式 | 条件 | 渲染效果 |
 | ---- | ---- | ---- |
 | 无客户数据 | 未传入 customerData 或无匹配 | 原始 JX 黑底白字方框 |
-| 单用户 | customerList 有 1 个用户 | 电能表图标（圆圈 + 竖线）+ 用户名 |
+| 单用户 | customerList 有 1 个用户 | 电能表图标（圆圈 + 竖线）+ 用户名；**整箱即该户，点击即客户档案** |
 | 多用户（显示名称） | customerList 2~20 个用户 | 方框内电能表网格，每个格子含图标 + 用户名（每行最多 5 个） |
 | 多用户（仅图标） | customerList >20 个用户 | 方框内电能表网格，仅显示图标（格子更紧凑） |
 
+> 交互：多用户箱内**点击某个电表格 / 户名 = 选中该户**（金圈高亮 + `customer-select` / `consumer:click`），
+> 点箱体空白 / 外框 = 选中整箱；悬停该户有青圈提示。用户端点（连接线）用客户档案 `assetNo` 引用即可。
+
 客户数据格式（与拓扑 JSON 配套的 customer JSON）：
 
 ```json

package/dist/index.d.ts

@@ -2,6 +2,11 @@
  * 拓扑引擎类型声明文件
  */
 
+// 让本类型声明在消费方 tsconfig 未开启 ES2015+ lib 时也能编译：
+// 声明里用到了 Map/Promise（TS2583: Cannot find name 'Map'），此处自动引入对应 lib 定义。
+/// <reference lib="es2015.collection" />
+/// <reference lib="es2015.promise" />
+
 // 核心 API
 export class TopoApi {
   constructor(graph: any, model: any, layout: any, nodeByIdMap: Map<string, any>);
@@ -38,6 +43,13 @@ export class TopoApi {
   batchSetNodeStyle(nodeIds: string[], style: object): void;
   resetNodeStyle(nodeId: string): void;
   resetAllNodeStyles(): void;
+
+  // 节点 / 箱内电表户染色（ref：节点 id 或 psrId；电表户用客户 assetNo/consNo/consId）
+  setNodeColor(ref: string, color: string | null): boolean;
+  batchSetNodeColor(entries: any, color?: string): { total: number, ok: number, failed: Array<{ ref: string, reason: string }> };
+  resetNodeColor(ref: string): boolean;
+  resetAllNodeColors(): void;
+  getNodeColor(ref: string): { kind: 'node' | 'customer', id: string, index?: number, color: string | null } | null;
   
   // 边样式
   setEdgeStyle(srcId: string, tgtId: string, style: object): void;
@@ -69,8 +81,9 @@ export class TopoApi {
   hideCard(nodeId: string): void;
   hideAllCards(): void;
   
-  // 连接线与拓扑线
-  addConnection(fromId: string, toId: string, opts?: object): void;
+  // 连接线与拓扑线（端点支持节点 id 或箱内用户的客户档案编号 consNo/consId）
+  resolveUserRef(ref: string): string | null;
+  addConnection(fromId: string, toId: string, opts?: object): string | false;
   removeConnection(fromId: string, toId: string): void;
   removeAllConnections(): void;
   addTopoLine(nodeIds: string[], opts?: object): string;
@@ -112,6 +125,7 @@ export function getSymbolSpec(cat: string): { w: number, h: number };
 export function buildCustomerMap(customerData: Array<any>): Map<string, Array<any>>;
 export function injectCustomers(model: any, customerMap: Map<string, Array<any>>): void;
 export function getMeterBoxSize(node: any): { w: number, h: number } | null;
+export function getCustomerLocalPositions(node: any): Array<{ x: number, y: number }>;
 
 // 常量
 export const SYMBOL_SPEC: Record<string, { w: number, h: number }>;

package/dist/style.css

@@ -1,6 +1,6 @@
 
 /* —— 主题变量：dark 为默认值，light 由 [data-theme='light'] 覆盖 —— */
-.topo-wrap[data-v-b02bff98] {
+.topo-wrap[data-v-c2cd8b2c] {
   --tp-bg: #050505;
   --tp-toolbar-bg: rgba(20, 20, 20, 0.88);
   --tp-toolbar-border: #333;
@@ -19,7 +19,7 @@
   overflow: hidden;
   background: var(--tp-bg);
 }
-.topo-wrap[data-theme='light'][data-v-b02bff98] {
+.topo-wrap[data-theme='light'][data-v-c2cd8b2c] {
   --tp-bg: #ffffff;
   --tp-toolbar-bg: rgba(255, 255, 255, 0.92);
   --tp-toolbar-border: #d9d9d9;
@@ -33,11 +33,11 @@
   --tp-text: #555;
   --tp-error: #d32f2f;
 }
-.topo-container[data-v-b02bff98] {
+.topo-container[data-v-c2cd8b2c] {
   width: 100%;
   height: 100%;
 }
-.topo-toolbar[data-v-b02bff98] {
+.topo-toolbar[data-v-c2cd8b2c] {
   position: absolute;
   top: 10px;
   left: 12px;
@@ -52,14 +52,14 @@
   color: var(--tp-text);
   z-index: 10;
 }
-.topo-title[data-v-b02bff98] {
+.topo-title[data-v-c2cd8b2c] {
   color: var(--tp-title);
   font-weight: 600;
 }
-.topo-meta[data-v-b02bff98] {
+.topo-meta[data-v-c2cd8b2c] {
   color: var(--tp-meta);
 }
-.btn[data-v-b02bff98] {
+.btn[data-v-c2cd8b2c] {
   margin-left: 4px;
   padding: 3px 10px;
   border: 1px solid var(--tp-btn-border);
@@ -69,12 +69,12 @@
   cursor: pointer;
   font-size: 12px;
 }
-.btn[data-v-b02bff98]:hover {
+.btn[data-v-c2cd8b2c]:hover {
   border-color: var(--tp-accent);
   color: var(--tp-accent);
 }
-.topo-loading[data-v-b02bff98],
-.topo-error[data-v-b02bff98] {
+.topo-loading[data-v-c2cd8b2c],
+.topo-error[data-v-c2cd8b2c] {
   position: absolute;
   inset: 0;
   display: flex;
@@ -85,12 +85,12 @@
   z-index: 5;
   background: var(--tp-overlay-bg);
 }
-.topo-error[data-v-b02bff98] {
+.topo-error[data-v-c2cd8b2c] {
   color: var(--tp-error);
 }
 
 /* —— 主题变量：dark 默认，light 由 [data-theme='light'] 覆盖 —— */
-.panel[data-v-547b7d57] {
+.panel[data-v-f5a2adf8] {
   --sp-bg: rgba(16, 16, 18, 0.96);
   --sp-border: #2c2c30;
   --sp-text: #ddd;
@@ -116,7 +116,7 @@
   flex-direction: column;
   color: var(--sp-text);
 }
-.panel[data-theme='light'][data-v-547b7d57] {
+.panel[data-theme='light'][data-v-f5a2adf8] {
   --sp-bg: rgba(255, 255, 255, 0.97);
   --sp-border: #e4e4ea;
   --sp-text: #333;
@@ -135,7 +135,7 @@
   --sp-hint: #8a8a8a;
   --sp-label: #666;
 }
-.panel-head[data-v-547b7d57] {
+.panel-head[data-v-f5a2adf8] {
   display: flex;
   align-items: center;
   justify-content: space-between;
@@ -145,7 +145,7 @@
   color: var(--sp-title);
   border-bottom: 1px solid var(--sp-border);
 }
-.panel-close[data-v-547b7d57] {
+.panel-close[data-v-f5a2adf8] {
   border: none;
   background: none;
   color: var(--sp-close);
@@ -153,57 +153,86 @@
   cursor: pointer;
   line-height: 1;
 }
-.panel-close[data-v-547b7d57]:hover {
+.panel-close[data-v-f5a2adf8]:hover {
   color: var(--sp-close-hover);
 }
-.panel-body[data-v-547b7d57] {
+.panel-body[data-v-f5a2adf8] {
   padding: 14px;
   overflow-y: auto;
   flex: 1;
 }
-.kv[data-v-547b7d57] {
+.kv[data-v-f5a2adf8] {
   display: flex;
   gap: 10px;
   margin-bottom: 10px;
   font-size: 13px;
   word-break: break-all;
 }
-.kv .k[data-v-547b7d57] {
+.kv .k[data-v-f5a2adf8] {
   color: var(--sp-sub);
   flex: none;
-  width: 64px;
+  width: 74px;
 }
-.kv .v[data-v-547b7d57] {
+.kv .v[data-v-f5a2adf8] {
   color: var(--sp-text);
 }
-.mono[data-v-547b7d57] {
+.mono[data-v-f5a2adf8] {
   font-family: Consolas, monospace;
   font-size: 12px;
   color: var(--sp-mono);
 }
-.ok[data-v-547b7d57] {
+.ok[data-v-f5a2adf8] {
   color: var(--sp-ok);
 }
-.warn[data-v-547b7d57] {
+.warn[data-v-f5a2adf8] {
   color: var(--sp-warn);
+}
+/* 客户档案：所属计量箱信息卡 + 返回按钮 */
+.cust-box[data-v-f5a2adf8] {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 8px 10px;
+  margin-bottom: 12px;
+  background: var(--sp-item);
+  border: 1px solid var(--sp-item-border);
+  border-radius: 5px;
+}
+.cust-box .kv[data-v-f5a2adf8] {
+  margin-bottom: 0;
+}
+.panel-back[data-v-f5a2adf8] {
+  align-self: flex-start;
+  border: 1px solid var(--sp-item-border);
+  border-radius: 4px;
+  background: var(--sp-item);
+  color: var(--sp-accent);
+  font-size: 12px;
+  padding: 3px 10px;
+  cursor: pointer;
+}
+.panel-back[data-v-f5a2adf8]:hover {
+  border-color: var(--sp-hover-border);
+  background: var(--sp-hover-bg);
+  color: var(--sp-title);
 }
-.neighbor-section[data-v-547b7d57] {
+.neighbor-section[data-v-f5a2adf8] {
   margin-top: 16px;
   border-top: 1px solid var(--sp-border);
   padding-top: 12px;
 }
-.neighbor-title[data-v-547b7d57] {
+.neighbor-title[data-v-f5a2adf8] {
   font-size: 13px;
   font-weight: 600;
   color: var(--sp-title);
   margin-bottom: 6px;
 }
-.neighbor-list[data-v-547b7d57] {
+.neighbor-list[data-v-f5a2adf8] {
   display: flex;
   flex-direction: column;
   gap: 4px;
 }
-.neighbor-item[data-v-547b7d57] {
+.neighbor-item[data-v-f5a2adf8] {
   display: flex;
   flex-direction: column;
   gap: 3px;
@@ -214,34 +243,34 @@
   cursor: pointer;
   font-size: 12px;
 }
-.neighbor-item[data-v-547b7d57]:hover {
+.neighbor-item[data-v-f5a2adf8]:hover {
   border-color: var(--sp-hover-border);
   background: var(--sp-hover-bg);
 }
-.n-main[data-v-547b7d57] {
+.n-main[data-v-f5a2adf8] {
   display: flex;
   align-items: center;
   gap: 8px;
   min-width: 0;
 }
-.n-type[data-v-547b7d57] {
+.n-type[data-v-f5a2adf8] {
   flex: none;
   color: var(--sp-accent);
   font-size: 11px;
 }
-.n-name[data-v-547b7d57] {
+.n-name[data-v-f5a2adf8] {
   color: var(--sp-text);
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
 }
-.n-psr[data-v-547b7d57] {
+.n-psr[data-v-f5a2adf8] {
   display: flex;
   align-items: center;
   gap: 6px;
   min-width: 0;
 }
-.n-psr-id[data-v-547b7d57] {
+.n-psr-id[data-v-f5a2adf8] {
   font-family: Consolas, monospace;
   font-size: 11px;
   color: var(--sp-mono);
@@ -252,7 +281,7 @@
   user-select: text;
   -webkit-user-select: text;
 }
-.copy-btn[data-v-547b7d57] {
+.copy-btn[data-v-f5a2adf8] {
   flex: none;
   border: 1px solid var(--sp-item-border);
   border-radius: 3px;
@@ -263,40 +292,40 @@
   padding: 2px 5px;
   cursor: pointer;
 }
-.copy-btn[data-v-547b7d57]:hover {
+.copy-btn[data-v-f5a2adf8]:hover {
   border-color: var(--sp-hover-border);
   color: var(--sp-title);
   background: var(--sp-hover-bg);
 }
-.neighbor-empty[data-v-547b7d57] {
+.neighbor-empty[data-v-f5a2adf8] {
   font-size: 12px;
   color: var(--sp-hint);
   padding: 4px 0;
 }
-.stat-grid[data-v-547b7d57] {
+.stat-grid[data-v-f5a2adf8] {
   display: grid;
   grid-template-columns: 1fr 1fr;
   gap: 10px;
   margin-bottom: 16px;
 }
-.stat[data-v-547b7d57] {
+.stat[data-v-f5a2adf8] {
   background: var(--sp-item);
   border: 1px solid var(--sp-item-border);
   border-radius: 6px;
   padding: 10px;
   text-align: center;
 }
-.stat-num[data-v-547b7d57] {
+.stat-num[data-v-f5a2adf8] {
   font-size: 20px;
   font-weight: 700;
   color: var(--sp-accent);
 }
-.stat-label[data-v-547b7d57] {
+.stat-label[data-v-f5a2adf8] {
   font-size: 12px;
   color: var(--sp-label);
   margin-top: 2px;
 }
-.hint[data-v-547b7d57] {
+.hint[data-v-f5a2adf8] {
   font-size: 12px;
   color: var(--sp-hint);
   line-height: 1.7;