topo-engine 0.1.6 → 0.1.8

package/docs/API.md

@@ -0,0 +1,1358 @@
+# 拓扑引擎 API 参考手册
+
+> `topo-engine` v1.0 · 基于 Vue3 + G6 v5 + 自研正交布局引擎
+
+---
+
+## 目录
+
+- [快速开始](#快速开始)
+- [类型定义](#类型定义)
+- [一、查询 API](#一查询-api)
+- [二、视图控制](#二视图控制)
+- [三、节点样式](#三节点样式)
+- [四、边样式](#四边样式)
+- [五、高亮与标注](#五高亮与标注)
+- [六、动画](#六动画)
+- [七、文字标注](#七文字标注)
+- [八、卡片盒](#八卡片盒)
+- [九、连接线与拓扑线](#九连接线与拓扑线)
+- [十、事件系统](#十事件系统)
+- [十一、导出](#十一导出)
+- [十二、生命周期](#十二生命周期)
+- [十三、TopoGraph 组件 Props / Events 与计量箱客户交互](#十三topograph-组件-props--events-与计量箱客户交互)
+
+---
+
+## 快速开始
+
+```vue
+<template>
+  <TopoGraph ref="topo" data-url="/data/sample.json" />
+</template>
+
+<script setup>
+import { ref, onMounted } from 'vue';
+import TopoGraph from './components/TopoGraph.vue';
+
+const topo = ref(null);
+
+onMounted(async () => {
+  // 等待图渲染完成
+  await new Promise(r => setTimeout(r, 500));
+
+  // 查询节点
+  const nodes = topo.value.findNodes({ cat: 'transformer' });
+
+  // 定位到第一个变压器
+  if (nodes.length) {
+    topo.value.locateNode(nodes[0].id, 1.5);
+  }
+
+  // 高亮 + 标注
+  topo.value.highlightNode(nodes[0].id, {
+    color: '#FF0000',
+    label: '异常',
+    labelColor: '#FF0000',
+  });
+
+  // 监听事件
+  topo.value.on('node:click', ({ nodeId, node }) => {
+    console.log('点击:', node.name);
+  });
+});
+</script>
+```
+
+---
+
+## 类型定义
+
+### NodeData
+
+```ts
+interface NodeData {
+  id: string;            // 唯一标识（String）
+  psrId: string;         // PMS PSR 编号
+  psrType: string;       // PMS 类型码（如 '0302', '3301'）
+  symbolId: string;      // PMS 设备编码
+  name: string;          // 完整名称
+  shortName: string;     // 简称
+  cat: string;           // 设备类别（见下表）
+  catLabel: string;      // 类别中文名
+  status: string;        // 状态码（'0'=正常）
+  insideStation: boolean;// 是否在站房内部
+  isLine: boolean;       // 是否为导线
+  isFuse: boolean;       // 是否为熔丝
+}
+```
+
+### 设备类别（cat）
+
+| cat | 中文 | 尺寸 (w×h) |
+|---|---|---|
+| `transformer` | 配电变压器 | 56×26 |
+| `fuse` | 熔丝 | 56×20 |
+| `switch` | 开关 | 60×24 |
+| `bus` | 低压母线 | 40×12 |
+| `cableTerminal` | 电缆终端头 | 18×22 |
+| `stationTerminal` | 站内终端头 | 24×14 |
+| `meterBox` | 计量箱 | 21×21 |
+| `consumer` | 用户接入点 | 30×30 |
+| `line` | 导线/连接点 | 12×12 |
+| `junction` | 密母分接点 | 12×12 |
+| `station` | 低压配电箱（站房框） | 动态 |
+| `other` | 其他 | 20×20 |
+
+### EdgeData
+
+```ts
+interface EdgeData {
+  source: string;  // 起点节点 ID
+  target: string;  // 终点节点 ID
+}
+```
+
+### HighlightOptions
+
+```ts
+interface HighlightOptions {
+  color?: string;         // 高亮色，默认 '#FFD700'（金色）
+  label?: string;         // 可选标注文字
+  labelColor?: string;    // 标注颜色，默认 '#FFFFFF'
+  labelSize?: number;     // 标注字号，默认 12
+  borderColor?: string;   // 边框色（覆盖 color）
+  borderStyle?: 'solid' | 'dashed';  // 边框样式，默认 'dashed'
+  borderWidth?: number;   // 边框粗细，默认 2
+}
+```
+
+### NodeStyle
+
+```ts
+interface NodeStyle {
+  stroke?: string;       // 描边颜色
+  strokeWidth?: number;  // 描边粗细
+  fill?: string;         // 背景填充
+  opacity?: number;      // 透明度 (0-1)
+  visible?: boolean;     // 是否可见
+  cursor?: string;       // 鼠标样式
+}
+```
+
+### EdgeStyle
+
+```ts
+interface EdgeStyle {
+  stroke?: string;       // 颜色
+  lineWidth?: number;    // 线宽
+  opacity?: number;      // 透明度
+  lineDash?: number[];   // 虚线样式
+}
+```
+
+### PulseOptions
+
+```ts
+interface PulseOptions {
+  color?: string;     // 脉动颜色，默认 '#00C8FF'
+  duration?: number;  // 周期 (ms)，默认 1500
+  maxScale?: number;  // 最大缩放，默认 1.3
+  minScale?: number;  // 最小缩放，默认 1.0
+}
+```
+
+### FlowOptions
+
+```ts
+interface FlowOptions {
+  color?: string;     // 流动颜色，默认 '#00C8FF'
+  duration?: number;  // 周期 (ms)，默认 2000
+  width?: number;     // 线宽，默认 3
+}
+```
+
+### CardContent
+
+```ts
+interface CardContent {
+  title?: string;
+  fields?: Array<{ label: string; value: string }>;
+  buttons?: Array<{ text: string; onClick: () => void; type?: 'primary' | 'default' }>;
+  closable?: boolean;  // 是否可关闭，默认 true
+  width?: number;      // 卡片宽度，默认 240
+}
+```
+
+### ConnectionOptions
+
+```ts
+interface ConnectionOptions {
+  color?: string;            // 颜色，默认 '#00C8FF'
+  width?: number;            // 线宽，默认 2
+  style?: 'solid' | 'dashed'; // 样式，默认 'solid'
+  midArrow?: boolean;        // 沿线简洁方向标记（开口 ›），默认 true
+  arrowSize?: number;        // 方向标记尺寸，默认 7
+  arrowGap?: number;         // 标记间距，默认 60（更小=更多标记）
+  startArrow?: boolean;      // 起点贴边箭头（需显式 true）
+  endArrow?: boolean;        // 终点贴边箭头（需显式 true）
+  label?: string;            // 可选标签
+  animated?: boolean;        // 是否流动动画（场景覆盖线暂未实现）
+}
+```
+
+---
+
+## 一、查询 API
+
+### `getNode(nodeId)`
+
+获取单个节点完整数据。
+
+```ts
+getNode(nodeId: string): NodeData | null
+```
+
+**参数：**
+- `nodeId` — 节点 ID
+
+**返回：** 节点数据对象，未找到返回 `null`
+
+**示例：**
+```js
+const node = topo.getNode('123');
+console.log(node.name, node.catLabel); // "上屋胡2#台区柱上变" "配电变压器"
+```
+
+---
+
+### `getAllNodes()`
+
+获取所有节点。
+
+```ts
+getAllNodes(): NodeData[]
+```
+
+**返回：** 节点数组（只读副本）
+
+---
+
+### `findNodes(filter)`
+
+按条件查找节点，多条件 AND 组合。
+
+```ts
+findNodes(filter: NodeFilter): NodeData[]
+```
+
+**filter 支持的字段：**
+
+| 字段 | 类型 | 匹配方式 |
+|---|---|---|
+| `psrId` | `string` | 精确匹配 |
+| `symbolId` | `string` | 精确匹配 |
+| `cat` | `string` | 精确匹配 |
+| `psrType` | `string` | 精确匹配 |
+| `name` | `string \| RegExp` | 包含 / 正则匹配 |
+| `shortName` | `string \| RegExp` | 包含 / 正则匹配 |
+| `status` | `string` | 精确匹配 |
+| `insideStation` | `boolean` | 精确匹配 |
+
+**示例：**
+```js
+// 查找所有变压器
+const transformers = topo.findNodes({ cat: 'transformer' });
+
+// 查找名称含"开关"的设备
+const switches = topo.findNodes({ name: /开关/ });
+
+// 组合条件：站房内的正常设备
+const inner = topo.findNodes({ insideStation: true, status: '0' });
+```
+
+---
+
+### `getSelectedId()`
+
+获取当前选中节点 ID。
+
+```ts
+getSelectedId(): string | null
+```
+
+---
+
+### `getNeighbors(nodeId)`
+
+获取指定节点的上下游邻居。
+
+```ts
+getNeighbors(nodeId: string): { upstream: NodeData[]; downstream: NodeData[] }
+```
+
+**示例：**
+```js
+const { upstream, downstream } = topo.getNeighbors('123');
+console.log(`上游 ${upstream.length} 个，下游 ${downstream.length} 个`);
+```
+
+---
+
+### `getStreamNodes(nodeId, direction)`
+
+沿拓扑流向获取节点链（BFS 遍历）。
+
+```ts
+getStreamNodes(nodeId: string, direction: 'upstream' | 'downstream'): NodeData[]
+```
+
+**参数：**
+- `nodeId` — 起始节点 ID
+- `direction` — `'upstream'`（向上游/电源侧）或 `'downstream'`（向下游/负荷侧）
+
+**示例：**
+```js
+// 获取某节点的所有下游节点
+const downstream = topo.getStreamNodes('123', 'downstream');
+```
+
+---
+
+### `getTrunkNodes()`
+
+获取主干链节点（从根节点沿叶子数最多路径一直走的链）。
+
+```ts
+getTrunkNodes(): NodeData[]
+```
+
+---
+
+### `getSubtreeNodes(nodeId)`
+
+获取以指定节点为根的子树中所有节点。
+
+```ts
+getSubtreeNodes(nodeId: string): NodeData[]
+```
+
+---
+
+### `getPath(fromId, toId)`
+
+获取两个节点之间的拓扑路径。
+
+```ts
+getPath(fromId: string, toId: string): NodeData[] | null
+```
+
+**返回：** 路径节点数组（含首尾），不可达返回 `null`
+
+---
+
+### `getEdge(srcId, tgtId)`
+
+获取指定边。
+
+```ts
+getEdge(srcId: string, tgtId: string): EdgeData | null
+```
+
+---
+
+### `getEdges()`
+
+获取所有边。
+
+```ts
+getEdges(): EdgeData[]
+```
+
+---
+
+### `getStreamEdges(nodeId, direction)`
+
+沿流向获取边集合（分路导线着色用）。
+
+```ts
+getStreamEdges(nodeId: string, direction: 'upstream' | 'downstream'): EdgeData[]
+```
+
+---
+
+### `getMainEdge()`
+
+获取主干边（非鱼骨肋骨、非站房内部、非末端分支）。
+
+```ts
+getMainEdge(): EdgeData[]
+```
+
+---
+
+### `getNodePosition(nodeId)`
+
+获取节点在画布中的坐标。
+
+```ts
+getNodePosition(nodeId: string): { x: number; y: number } | null
+```
+
+---
+
+### `getEdgePath(srcId, tgtId)`
+
+获取边的折线控制点序列（含端点）。
+
+```ts
+getEdgePath(srcId: string, tgtId: string): [number, number][] | null
+```
+
+---
+
+### `getGraphBounds()`
+
+获取图整体边界。
+
+```ts
+getGraphBounds(): { minX: number; minY: number; maxX: number; maxY: number }
+```
+
+---
+
+### `getStats()`
+
+获取拓扑统计信息。
+
+```ts
+getStats(): {
+  total: number;     // 节点总数
+  depth: number;     // 最大深度
+  leaves: number;    // 叶子节点数
+  byCat: Record<string, number>;  // 按类别统计
+}
+```
+
+---
+
+## 二、视图控制
+
+### `fitView(padding?)`
+
+适配画布到视口。
+
+```ts
+fitView(padding?: number): void
+```
+
+**参数：**
+- `padding` — 内边距（px），默认 `30`
+
+---
+
+### `zoomTo(ratio, center?)`
+
+缩放到指定比例。
+
+```ts
+zoomTo(ratio: number, center?: { x: number; y: number }): void
+```
+
+**参数：**
+- `ratio` — 缩放比例（`1` = 100%，`2` = 200%）
+- `center` — 缩放中心（画布坐标），默认视口中心
+
+---
+
+### `zoomIn(step?)`
+
+放大一级。
+
+```ts
+zoomIn(step?: number): void
+```
+
+**参数：**
+- `step` — 放大倍率增量，默认 `0.2`（即放大 20%）
+
+---
+
+### `zoomOut(step?)`
+
+缩小一级。
+
+```ts
+zoomOut(step?: number): void
+```
+
+**参数：**
+- `step` — 缩小倍率减量，默认 `0.2`
+
+---
+
+### `locateNode(nodeId, zoom?)`
+
+定位节点到视口中央，可选缩放。
+
+```ts
+locateNode(nodeId: string, zoom?: number): void
+```
+
+**参数：**
+- `nodeId` — 要定位的节点 ID
+- `zoom` — 可选的目标缩放比例
+
+**示例：**
+```js
+// 定位到节点，保持当前缩放
+topo.locateNode('123');
+
+// 定位到节点，放大到 2 倍
+topo.locateNode('123', 2);
+```
+
+---
+
+### `getViewport()`
+
+获取当前视口状态。
+
+```ts
+getViewport(): { zoom: number; center: { x: number; y: number } }
+```
+
+---
+
+## 三、节点样式
+
+### `setNodeStyle(nodeId, style)`
+
+设置单个节点的视觉样式。
+
+```ts
+setNodeStyle(nodeId: string, style: NodeStyle): void
+```
+
+**示例：**
+```js
+// 给节点加红色描边
+topo.setNodeStyle('123', { stroke: '#FF0000', strokeWidth: 2 });
+
+// 降低透明度
+topo.setNodeStyle('123', { opacity: 0.3 });
+```
+
+---
+
+### `batchSetNodeStyle(nodeIds, style)`
+
+批量设置节点样式。
+
+```ts
+batchSetNodeStyle(nodeIds: string[], style: NodeStyle): void
+```
+
+---
+
+### `resetNodeStyle(nodeId)`
+
+重置单个节点为默认样式。
+
+```ts
+resetNodeStyle(nodeId: string): void
+```
+
+---
+
+### `resetAllNodeStyles()`
+
+重置所有节点为默认样式。
+
+```ts
+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)`
+
+设置边的视觉样式。
+
+```ts
+setEdgeStyle(srcId: string, tgtId: string, style: EdgeStyle): void
+```
+
+**示例：**
+```js
+// 导线变红加粗
+topo.setEdgeStyle('A', 'B', { stroke: '#FF0000', lineWidth: 3 });
+
+// 虚线
+topo.setEdgeStyle('A', 'B', { lineDash: [5, 3] });
+```
+
+---
+
+### `batchSetEdgeStyle(edgeIds, style)`
+
+批量设置边样式。
+
+```ts
+batchSetEdgeStyle(edgeIds: Array<[string, string]>, style: EdgeStyle): void
+```
+
+---
+
+### `resetEdgeStyle(srcId, tgtId)`
+
+重置边为默认样式。
+
+```ts
+resetEdgeStyle(srcId: string, tgtId: string): void
+```
+
+---
+
+## 五、高亮与标注
+
+### `highlightNode(nodeId, options?)`
+
+高亮节点（选中效果 + 可选文字标注）。
+
+```ts
+highlightNode(nodeId: string, options?: HighlightOptions): void
+```
+
+**示例：**
+```js
+// 金色高亮
+topo.highlightNode('123');
+
+// 红色高亮 + "停电" 标注
+topo.highlightNode('123', {
+  color: '#FF0000',
+  label: '停电',
+  labelColor: '#FF0000',
+});
+
+// 绿色虚线高亮 + "正常" 标注
+topo.highlightNode('123', {
+  color: '#00FF00',
+  label: '正常',
+  borderStyle: 'dashed',
+});
+```
+
+---
+
+### `unhighlightNode(nodeId)`
+
+取消节点高亮并移除标注。
+
+```ts
+unhighlightNode(nodeId: string): void
+```
+
+---
+
+### `highlightPath(nodeIds, options?)`
+
+高亮一组节点和它们之间的边（路径高亮）。
+
+```ts
+highlightPath(nodeIds: string[], options?: HighlightOptions & { edgeColor?: string }): void
+```
+
+**示例：**
+```js
+// 高亮从电源到某用户的路径
+const path = topo.getPath('root', 'user123');
+if (path) {
+  topo.highlightPath(path.map(n => n.id), { color: '#00FF00', label: '供电路径' });
+}
+```
+
+---
+
+### `unhighlightAll()`
+
+取消所有高亮和标注。
+
+```ts
+unhighlightAll(): void
+```
+
+---
+
+### `dimOthers(keepIds, opacity?)`
+
+将非指定节点变暗（聚焦效果）。
+
+```ts
+dimOthers(keepIds: string[], opacity?: number): void
+```
+
+**参数：**
+- `keepIds` — 保持正常的节点 ID 列表
+- `opacity` — 变暗透明度，默认 `0.15`
+
+**示例：**
+```js
+// 聚焦某节点及其上下游
+const { upstream, downstream } = topo.getNeighbors('123');
+const keep = ['123', ...upstream.map(n => n.id), ...downstream.map(n => n.id)];
+topo.dimOthers(keep, 0.15);
+```
+
+---
+
+## 六、动画
+
+### `setNodePulse(nodeId, options?)`
+
+节点脉动/光晕动画。
+
+```ts
+setNodePulse(nodeId: string, options?: PulseOptions): void
+```
+
+**示例：**
+```js
+topo.setNodePulse('123', { color: '#FF0000', duration: 1500 });
+```
+
+---
+
+### `setNodeGlow(nodeId, options?)`
+
+节点发光效果。
+
+```ts
+setNodeGlow(nodeId: string, options?: { color?: string; radius?: number }): void
+```
+
+---
+
+### `setEdgeFlow(srcId, tgtId, options?)`
+
+边流动动画（视觉流动效果）。
+
+```ts
+setEdgeFlow(srcId: string, tgtId: string, options?: FlowOptions): void
+```
+
+**示例：**
+```js
+topo.setEdgeFlow('A', 'B', { color: '#00C8FF', duration: 2000 });
+```
+
+---
+
+### `setEdgePulse(srcId, tgtId, options?)`
+
+边脉动动画（线宽周期变化）。
+
+```ts
+setEdgePulse(srcId: string, tgtId: string, options?: { color?: string; duration?: number }): void
+```
+
+---
+
+### `removeAnimation(targetId)`
+
+移除指定元素的动画。
+
+```ts
+removeAnimation(targetId: string): void
+```
+
+---
+
+### `removeAllAnimations()`
+
+移除所有动画。
+
+```ts
+removeAllAnimations(): void
+```
+
+---
+
+## 七、文字标注
+
+### `setText(nodeId, text, options?)`
+
+在节点旁设置附加文字。
+
+```ts
+setText(nodeId: string, text: string, options?: {
+  fontSize?: number;   // 默认 12
+  color?: string;      // 默认 '#FFFFFF'
+  position?: 'top' | 'bottom' | 'left' | 'right';  // 默认 'top'
+  offset?: number;     // 偏移量 (px)，默认 4
+}): void
+```
+
+**示例：**
+```js
+topo.setText('123', '突变(3次)', { color: '#FF4444', position: 'top' });
+```
+
+---
+
+### `removeText(nodeId)`
+
+移除指定节点的附加文字。
+
+```ts
+removeText(nodeId: string): void
+```
+
+---
+
+### `removeAllTexts()`
+
+移除所有附加文字。
+
+```ts
+removeAllTexts(): void
+```
+
+---
+
+### `setDeviceText(cat, fontSize)`
+
+按设备类型统一设置文字字号。
+
+```ts
+setDeviceText(cat: string, fontSize: number): void
+```
+
+**示例：**
+```js
+// 所有用户接入点字号设为 15
+topo.setDeviceText('consumer', 15);
+```
+
+---
+
+### `changeUserName(mode)`
+
+切换所有用户名的显示方式。
+
+```ts
+changeUserName(mode: 'full' | 'short' | 'hidden'): void
+```
+
+**参数：**
+- `'full'` — 显示完整名称
+- `'short'` — 显示简称
+- `'hidden'` — 隐藏名称
+
+---
+
+## 八、卡片盒
+
+### `showCard(nodeId, content)`
+
+在节点旁弹出信息卡片。
+
+```ts
+showCard(nodeId: string, content: CardContent): void
+```
+
+**示例：**
+```js
+topo.showCard('123', {
+  title: '设备信息',
+  fields: [
+    { label: '设备类型', value: '配电变压器' },
+    { label: 'PSR编号', value: 'GDDW000123' },
+    { label: '状态', value: '正常' },
+  ],
+  buttons: [
+    { text: '查看运行曲线', type: 'primary', onClick: () => openChart('123') },
+    { text: '查看量测曲线', onClick: () => openMeasure('123') },
+  ],
+});
+```
+
+---
+
+### `hideCard(nodeId)`
+
+关闭指定节点的卡片。
+
+```ts
+hideCard(nodeId: string): void
+```
+
+---
+
+### `hideAllCards()`
+
+关闭所有卡片。
+
+```ts
+hideAllCards(): void
+```
+
+---
+
+## 九、连接线与拓扑线
+
+### `addConnection(fromId, toId, options?)`
+
+添加动态连接线（不参与布局/拓扑查询，直接绘制进 **G6 画布场景最上层**，
+随画布缩放平移自动对齐）。默认**中心对中心直线 + 沿线若干简洁方向标记**
+（开口 › 形、数量随线长自动增减、非实心，样式干净）。
+
+**端点支持两种引用：**
+1. **普通设备节点** —— 用该节点的 **`psrId`（设备编码）**（兼容节点内部 id）；
+   变压器/开关/计量箱/用户接入点等均适用；
+2. **箱内用户** —— 用客户档案里的 **`assetNo`（资产编号）**（兼容 `consNo`/`consId`），
+   自动落到该户表位中心 → 支持 **节点↔用户、用户↔用户**（可跨箱、可同箱内两户）。
+
+```ts
+addConnection(fromId: string, toId: string, options?: ConnectionOptions): string | false
+// options: { color?, width?, style?: 'solid'|'dashed',
+//            midArrow?: boolean,        // 沿线方向标记，默认 true
+//            arrowSize?: number,        // 标记尺寸，默认 7
+//            arrowGap?: number,         // 标记间距，默认 60
+//            startArrow?: boolean, endArrow?: boolean,  // 显式 true 才画贴边两端箭头
+//            }
+```
+
+**示例：**
+```js
+// 节点（psrId）→ 某户（assetNo），橙色虚线 + 沿线方向标记（默认）
+topo.addConnection('4241005000000040735831', '4230000100014444282', {
+  color: '#FF6600', width: 2, style: 'dashed',
+});
+
+// 户 ↔ 户（assetNo），方向标记更密更大
+topo.addConnection('4230000100014444282', '4230000100014410530', {
+  color: '#00C8FF', arrowGap: 40, arrowSize: 9,
+});
+
+// 纯直线：midArrow: false
+topo.addConnection('4241005000000040735831', '4230000100014444282', { midArrow: false });
+
+// 想要贴边两端实心箭头：startArrow: true / endArrow: true
+topo.addConnection('4241005000000040735831', '4230000100014444282', {
+  startArrow: true, endArrow: true,
+});
+
+// 解析调试：topo.resolveUserRef('4230000100014444282') → `${计量箱节点id}#cust${下标}`（无匹配为 null）
+```
+
+---
+
+### `removeConnection(fromId, toId)`
+
+移除动态连接线。
+
+```ts
+removeConnection(fromId: string, toId: string): void
+```
+
+---
+
+### `removeAllConnections()`
+
+移除所有动态连接线。
+
+```ts
+removeAllConnections(): void
+```
+
+---
+
+### `addTopoLine(nodeIds, options?)`
+
+沿节点路径添加拓扑高亮线（高亮已有边）。
+
+```ts
+addTopoLine(nodeIds: string[], options?: {
+  color?: string;     // 高亮色，默认 '#00C8FF'
+  width?: number;     // 线宽，默认 3
+  id?: string;        // 线 ID（用于后续移除），默认自动生成
+}): string  // 返回线 ID
+```
+
+**示例：**
+```js
+// 高亮从变压器到用户的路径
+const path = topo.getPath('transformer1', 'user456');
+const lineId = topo.addTopoLine(path.map(n => n.id), { color: '#FF0000' });
+```
+
+---
+
+### `removeTopoLine(id)`
+
+移除拓扑高亮线。
+
+```ts
+removeTopoLine(id: string): void
+```
+
+---
+
+### `removeAllTopoLines()`
+
+移除所有拓扑高亮线。
+
+```ts
+removeAllTopoLines(): void
+```
+
+---
+
+## 十、事件系统
+
+### `on(event, handler)`
+
+监听事件。
+
+```ts
+on(event: string, handler: Function): void
+```
+
+---
+
+### `off(event, handler?)`
+
+移除监听。不传 handler 则移除该事件的所有监听。
+
+```ts
+off(event: string, handler?: Function): void
+```
+
+---
+
+### 标准事件列表
+
+| 事件名 | 触发时机 | Payload |
+|---|---|---|
+| `node:click` | 单击节点 | `{ nodeId, node, event }` |
+| `node:dblclick` | 双击节点 | `{ nodeId, node, event }` |
+| `node:hover` | 鼠标进入节点 | `{ nodeId, node }` |
+| `node:unhover` | 鼠标离开节点 | `{ nodeId }` |
+| `edge:click` | 单击边 | `{ edgeId, source, target }` |
+| `canvas:click` | 单击空白区域 | `{ event }` |
+| `viewport:change` | 缩放/平移后 | `{ zoom, center }` |
+| `card:button` | 点击卡片按钮 | `{ nodeId, buttonIndex }` |
+| `consumer:click` | 点击计量箱内用户（多户箱点格子；单户箱整箱即该户） | `{ nodeId, index, customer, node }` |
+
+> `consumer:click`：点中计量箱内的用户时触发——
+> 多用户箱（`_meterBoxMode='grid'`）点中箱内具体用户电表格；
+> 单用户箱（`_meterBoxMode='single'`）整箱即“这一个用户”，点击即触发。
+> `index` 为该用户在箱内客户列表 `consumerList` 中的下标；`customer` 为该客户档案
+> （含 `consId/consNo/consName/meterId/assetNo/realConsName` 等字段，视数据源而定）。
+> 多用户箱点击空白/外框仍按普通 `node:click` 选中整只计量箱。
+
+**示例：**
+```js
+// 节点点击 → 弹卡片
+topo.on('node:click', ({ nodeId, node }) => {
+  topo.showCard(nodeId, {
+    title: node.name,
+    fields: [
+      { label: '类型', value: node.catLabel },
+      { label: '编号', value: node.psrId },
+    ],
+  });
+});
+
+// 鼠标悬停 → 高亮上下游
+topo.on('node:hover', ({ nodeId }) => {
+  const { upstream, downstream } = topo.getNeighbors(nodeId);
+  const keep = [nodeId, ...upstream.map(n => n.id), ...downstream.map(n => n.id)];
+  topo.dimOthers(keep);
+});
+
+topo.on('node:unhover', () => {
+  topo.resetAllNodeStyles();
+});
+
+// 点击空白 → 清除所有
+topo.on('canvas:click', () => {
+  topo.unhighlightAll();
+  topo.hideAllCards();
+  topo.resetAllNodeStyles();
+});
+
+// 多用户计量箱：点中箱内单个用户 → 打印客户档案
+topo.on('consumer:click', ({ nodeId, index, customer, node }) => {
+  console.log(`箱 ${node.name} 内第 ${index + 1} 户`, customer);
+});
+// 也可编程式选中：topo.selectCustomer(nodeId, index)
+// 或查询当前选中用户：topo.getSelectedCustomer() → { nodeId, index, customer, node } | null
+```
+
+---
+
+## 十一、导出
+
+### `exportPng(filename?)`
+
+导出整图为 PNG 文件并触发下载。
+
+```ts
+exportPng(filename?: string): void
+```
+
+**参数：**
+- `filename` — 文件名（不含扩展名），默认使用图标题
+
+---
+
+### `toDataURL(options?)`
+
+获取图片 DataURL（不触发下载）。
+
+```ts
+toDataURL(options?: {
+  mode?: 'overall' | 'viewport';  // 默认 'overall'（整图）
+  type?: 'image/png' | 'image/jpeg';  // 默认 'image/png'
+  quality?: number;  // JPEG 质量 (0-1)
+}): Promise<string>
+```
+
+---
+
+### `getGraphData()`
+
+获取当前图的完整数据（可序列化为 JSON）。
+
+```ts
+getGraphData(): {
+  model: object;       // 解析后的模型数据
+  layout: {
+    pos: Record<string, { x: number; y: number }>;
+    bounds: object;
+  };
+}
+```
+
+---
+
+## 十二、生命周期
+
+### `loadRaw(text)`
+
+加载本地 JSON 文本并重新渲染。
+
+```ts
+loadRaw(text: string): void
+```
+
+---
+
+### `destroy()`
+
+销毁图实例，释放资源。组件卸载时自动调用。
+
+```ts
+destroy(): void
+```
+
+---
+
+## 十三、TopoGraph 组件 Props / Events 与计量箱客户交互
+
+> 前面章节的 API 均通过 `TopoGraph` 组件 ref 直接调用（组件把 `TopoApi` 全部方法代理到自身）。
+
+### Props
+
+| prop | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `data` | `Object` | `null` | 直接传入台区 JSON（优先于 `dataUrl`） |
+| `dataUrl` | `String` | `''` | 数据地址，内部 `fetch` 加载 |
+| `customerData` | `Array` | `null` | 客户数据（计量箱关联用户），见下 |
+| `theme` | `'dark' \| 'light'` | `'light'` | 画布/图元/导线主题，支持 `v-model:theme` |
+| `toolbar` | `Boolean` | `false` | 是否显示左上工具条（标题/统计/主题/适应画布/导出 PNG），默认隐藏 |
+
+### Events（Vue 组件事件）
+
+| 事件 | 触发时机 | payload |
+|---|---|---|
+| `node-select` | 点击节点 / 空白清除 | `{ node, upstream, downstream }`（空白处 `node=null`） |
+| `customer-select` | 点中计量箱内某个用户 | `{ node, customer, index, count, upstream, downstream }` |
+| `loaded` | 渲染完成 | `{ stats, title }` |
+| `top-distances` | Top10 距离计算完成 | `Array` |
+| `update:theme` | 点击主题切换 | 新主题值 |
+
+### 组件 ref 上的快捷方法
+
+`resetView()`、`exportPng()`、`selectNode(id)`、`selectCustomer(nodeId, index)`、
+`getSelectedCustomer()`（`{ nodeId, index, customer, node } \| null`）；
+其余 `TopoApi` 方法（查询/样式/高亮/动画/卡片/连接线…）全部直接可用。
+
+### 计量箱客户数据 → 渲染与交互
+
+通过 `:customer-data` 传入，格式为数组：每项 `{ psrId, consumerList: [...] }`，
+`psrId` 对应台区 JSON 中计量箱节点的 PSR 编号：
+
+```json
+[{
+  "psrId": "4230000000109100079",
+  "consumerList": [
+    { "assetNo": "4230010007008084768", "consNo": "4219930230186",
+      "consId": "4226040301216283", "meterId": "4225112000503099", "realConsName": "郭勋豪" }
+  ]
+}]
+```
+
+- **渲染形态**：
+  - 单户（1 户）→ 电表图标 + 户名（整箱即“这一个用户”）；
+  - 多户（2 户起）→ 外框内按网格排电表，每格 = 1 户（≤20 户显示户名，超过只显电表）；
+  - 无客户数据 → 保持原始 `JX` 图元。
+- **点击语义**：
+  - 单户箱：点击整箱任意位置 = 点中该户；
+  - 多户箱：点某个电表格/户名 = 点中该户；点箱体空白/外框 = 选中整箱；
+  - 悬停某户青圈提示，选中金圈高亮。
+- **编程式选中 / 事件**：`selectCustomer(nodeId, index)`、`getSelectedCustomer()`、
+  事件 `consumer:click`（见第十章）与组件事件 `customer-select`。
+- **用户级连线**：连接线的端点可用客户档案 `assetNo`（兼容 `consNo`/`consId`）直接引用（见第九章），
+  连线终点会自动落到该户表位。
+
+---
+
+## 附录：G6 v5 底层实例访问
+
+如需使用 G6 v5 原生 API（上述封装未覆盖的能力），可通过以下方式获取底层实例：
+
+```ts
+getGraphInstance(): Graph | null
+```
+
+> ⚠️ **注意：** 直接操作 G6 实例可能导致与引擎内部状态不一致，建议优先使用上述封装 API。
+
+---
+
+## 附录：引擎数据访问
+
+如需直接访问引擎内部数据结构：
+
+```ts
+getModel(): object          // parseTopo 输出的完整模型
+getLayoutData(): object     // computeOrthogonalLayout 输出的完整布局数据
+getNodeByIdMap(): Map       // ID → NodeData 的 O(1) 查找表
+```