topo-engine 0.1.9 → 0.1.10

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…');

package/package.json

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