topo-engine 0.1.9 → 0.1.11

package/docs/API.md

@@ -878,32 +878,67 @@ topo.setNodePulse('123', { color: '#FF0000', duration: 1500 });
 
 ### `setNodeGlow(ref, options?)`
 
-**节点光晕动画** —— 节点周围“扩散 + 渐隐”的发光环（两层光环、呼吸式循环），
-用于告警 / 定位 / 状态强调等场景。
+**节点光晕动画** —— 节点周围的霓虹式发光（多层光环 + 辉光 + 面光底衬），
+用于告警 / 定位 / 状态强调等场景；开启 `blink` 后图元本体还会「整体闪烁」。
 
 ```ts
 setNodeGlow(ref: string, options?: {
-  color?: string;     // 光晕颜色，默认 '#00C8FF'（青）
-  spread?: number;    // 光环外扩半径 (px)，默认 14
-  radius?: number;    // spread 的别名（兼容早期文档）
-  duration?: number;  // 一个周期时长 (ms)，默认 1600
-  opacity?: number;   // 光环最大透明度 (0-1)，默认 0.9
+  color?: string;      // 光晕颜色，默认 '#00C8FF'（青）
+  spread?: number;     // 光环外扩半径 (px)，默认按图元大小自适应（短边 ×0.7，16~46px）
+  radius?: number;     // spread 的别名（兼容早期文档）
+  duration?: number;   // 一个周期时长 (ms)，默认 1600
+  opacity?: number;    // 光环最大透明度 (0-1)，默认 0.95
+  width?: number;      // 主环初始线宽 (px)，默认 5.6（户表位 3.6），随相位收细
+  intensity?: number;  // 强度倍率，默认 1（线宽 / 辉光 / 底光同时放大）
+  level?: number;      // intensity 的别名
+  strength?: number;   // intensity 的别名
+  blink?: boolean | number;  // 图元「整体闪烁」：默认 false（只画光环）
+  flash?: boolean | number;  // blink 的别名
 }): boolean
 ```
 
+**渲染栈（由下到上，为什么现在远看也醒目）：**
+1. **blur 柔光底衬**：用 canvas `filter: blur()` 画一块弥散的同色面光，范围随 `spread`；
+2. **贴合图元轮廓的实心光块**：让节点“整块亮起来”，而不是只靠细线；
+3. 图元本体；
+4. **外扩散环 ×2**：扩散尾迹（最淡）+ 带辉光次环；
+5. **霓虹主环**：粗线 + canvas `shadowBlur` 辉光 —— 真正的“发光”而不是一根线；
+6. **亮芯环**：偏白的细高光，制造刺眼的发光中心。
+
+**参数说明：**
+- `intensity`：整体强度倍率，默认 `1`。想要更夸张给 `1.5`~`2.5`（辉光半径、线宽、面光同步放大），
+  觉得糊/太抢眼给 `0.5`~`0.7`；
+- `spread`：扩散范围。不传时按图元短边自适应（小图元至少 16px，大图元最多 46px）；
+- `blink`：`false`（默认）只有光环；`true` = 0.85；`0.3`~`1` 为自定义强度，
+  数值 = 图元最暗时被压掉的透明度幅度（`1` → 图元完全隐去）。开启后每个周期做一次
+  「图元变暗 ↔ 恢复」的明暗交替，图元最暗的瞬间正是底衬光块最亮之时（与光环相位互补，
+  任何时刻都有强视觉元素，不会出现“整段动画都看不清”的空档）；
+- `duration`：既控制光环扩散快慢，也控制闪烁频率（想要更“急”的告警感给 700~900）。
+
 **说明：**
 - `ref` 支持 **节点内部 id / psrId（设备编码）** → 图元光环；
   **客户 assetNo（资产编号，兼容 consNo/consId）→ 该户表位光环**（多户箱只亮那一格，单户箱即整箱那只表）；
 - 多个目标可同时发光；`removeAllAnimations()` 会一并停止光晕与脉动；
-- 与「染色 / 高亮」互不冲突：光环画在图元之上、选中金框之下，随节点/表位对齐。
+- 与「染色 / 高亮」互不冲突：光环画在图元之上、选中金框之下，随节点/表位对齐；
+  `blink` 只压图元本体透明度，光环、高亮框、标注文字始终清晰。
 
 **示例：**
 ```js
-// 默认青色光晕
+// 默认青色光晕（已经带辉光 + 底衬面光）
 topo.setNodeGlow('8ff4786d548a7073a2517297e801518ff456732f4d');
 
-// 红色告警光晕（更亮、扩散更大、周期更快）
-topo.setNodeGlow('8ff4…', { color: '#FF0000', spread: 20, duration: 900, opacity: 1 });
+// 红色告警：更大扩散 + 更快周期 + 整体闪烁 + 加强
+topo.setNodeGlow('8ff4…', { color: '#FF3B30', duration: 900, blink: true, intensity: 1.6 });
+
+// 最夸张一档（远看/投影上都醒目）
+topo.setNodeGlow('2', { color: '#FF2D2D', intensity: 2.4, spread: 34, width: 9, blink: 0.9, duration: 700 });
+
+// 收敛一点（只要一个柔和光环）
+topo.setNodeGlow('2', { intensity: 0.6, blink: false });
+
+// 温和闪烁（最暗只降到 30%）/ 强烈闪烁（图元近乎全灭）
+topo.setNodeGlow('2', { blink: 0.3 });
+topo.setNodeGlow('2', { blink: 1 });
 
 // 停止：removeNodeGlow(ref) / 停止全部 removeAllNodeGlows()
 topo.removeNodeGlow('8ff4…');
@@ -1369,7 +1404,9 @@ destroy(): void
 | `dataUrl` | `String` | `''` | 数据地址，内部 `fetch` 加载 |
 | `customerData` | `Array` | `null` | 客户数据（计量箱关联用户），见下 |
 | `theme` | `'dark' \| 'light'` | `'light'` | 画布/图元/导线主题，支持 `v-model:theme` |
-| `toolbar` | `Boolean` | `false` | 是否显示左上工具条（标题/统计/主题/适应画布/导出 PNG），默认隐藏 |
+| `toolbar` | `Boolean` | `false` | 是否显示左上工具条（标题/统计/主题/图例/适应画布/导出 PNG），默认隐藏 |
+| `legend` | `Boolean` | `false` | **是否显示右下角图例面板，默认否**；支持 `v-model:legend` |
+| `legendItems` | `Array` | `null` | 自定义图例项（覆盖自动生成），见下 |
 
 ### Events（Vue 组件事件）
 
@@ -1380,12 +1417,56 @@ destroy(): void
 | `loaded` | 渲染完成 | `{ stats, title }` |
 | `top-distances` | Top10 距离计算完成 | `Array` |
 | `update:theme` | 点击主题切换 | 新主题值 |
+| `update:legend` | 点击工具条 🗺 图例按钮 | 新布尔值（配合 `v-model:legend`） |
+
+### 图例（legend）
+
+```ts
+legend: boolean          // 默认 false（不显示）
+legendItems?: LegendItem[] // 自定义项，覆盖自动生成
+```
+
+**自动图例**（不传 `legendItems` 时）：按当前图**实际出现的设备类别**生成条目
+（配电变压器 / 开关 / 熔丝 / 低压母线 / 电缆终端头 / 密母分接点 / 计量箱 / 用户接入点 /
+低压导线点 / 低压配电箱 / 其它设备），末尾固定追加 **主干导线 / 分支导线**；
+若图中计量箱注入了客户数据，再追加 **客户电表**。图例颜色取自当前主题色板（与图元同源），
+切换主题自动同步；点击图例标题可折叠。
+
+```ts
+interface LegendItem {
+  key?: string;    // 唯一键（可选）
+  label: string;   // 显示文字
+  shape?: 'transformer' | 'switch' | 'fuse' | 'bus' | 'cableTerminal' | 'junction'
+        | 'meterBox' | 'consumer' | 'line' | 'meterUser' | 'station' | 'edge'
+        | 'square' | 'ring' | 'triangle' | 'hline' | 'text' | 'dot';  // 默认 dot
+  color?: string;  // 覆盖色（不传用主题色）
+  text?: string;   // shape='text' 时显示的文字（默认 'JX'）
+}
+```
+
+**示例：**
+```vue
+<!-- 开启自动图例 -->
+<TopoGraph :data-url="url" legend />
+
+<!-- 自定义图例 -->
+<TopoGraph
+  :data-url="url"
+  legend
+  :legend-items="[
+    { label: '正常设备', shape: 'square', color: '#22C55E' },
+    { label: '告警设备', shape: 'ring', color: '#EF4444' },
+    { label: '客户电表', shape: 'meterUser' },
+  ]"
+/>
+```
 
 ### 组件 ref 上的快捷方法
 
-`resetView()`、`exportPng()`、`selectNode(id)`、`selectCustomer(nodeId, index)`、
+`resetView()`、`exportPng()`、`selectNode(ref)`、`selectCustomer(nodeRef, index)`、
 `getSelectedCustomer()`（`{ nodeId, index, customer, node } \| null`）；
 其余 `TopoApi` 方法（查询/样式/高亮/动画/卡片/连接线…）全部直接可用。
+其中 `ref` 支持节点 id / psrId / 资产编号 assetNo（见[引用规则](#引用规则id--psrid--assetno-统一)）。
 
 ### 计量箱客户数据 → 渲染与交互
 

package/package.json

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