topo-engine 0.1.9 → 0.1.11

package/README.md

@@ -8,6 +8,7 @@
 
 - 🧩 **Vue 3 组件** — `TopoGraph`（画布；可选左上工具条默认隐藏，`:toolbar` 开启）、`SidePanel`（设备详情与上下游）、`DistanceTop10`（父子连线距离 Top10 面板）
 - 🎨 **深色 / 浅色双主题** — 黑底 SCADA 或白底两种画布风格，图元 / 导线 / 文字随之配套适配，可随时切换（`theme` prop 或工具栏按钮）。默认浅色主题
+- 🗺 **图例** — 可选图例面板（`legend` prop，**默认关闭**）：按当前图实际设备类别自动生成、颜色随主题，支持 `legendItems` 自定义项与点击折叠
 - 📐 **自研正交布局** — 主干沿最长路径横向铺开 + 分支带垂直直走，整图**横平竖直、0 交叉、0 重叠**，边缘路由为直线 / L 形折线
 - 🔍 **拓扑查询 API** — 节点 / 边 / 邻居 / 子树 / 主干链 / 路径 / 坐标 查询
 - 🎨 **样式控制** — 节点、边样式覆盖与批量重置
@@ -192,7 +193,9 @@ const g6Data = buildGraphData(model, layout);   // → G6 可直接消费的 { n
 | `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），默认隐藏 |
+| `toolbar` | `Boolean` | `false` | 是否显示左上工具条（标题 / 统计 / 主题 / 图例 / 适应画布 / 导出 PNG），默认隐藏 |
+| `legend` | `Boolean` | `false` | **是否显示右下角图例面板，默认否**。支持 `v-model:legend`（开启 `toolbar` 后工具条内有 🗺 图例按钮）。图例按当前图**实际出现的设备类别**自动生成，颜色跟随主题；面板可点击标题折叠 |
+| `legendItems` | `Array` | `null` | 自定义图例项（覆盖自动生成）：`[{ label, shape, color?, text?, key? }]`。`shape` 可选 `transformer/switch/fuse/bus/cableTerminal/junction/meterBox/consumer/line/meterUser/station/edge` 或通用 `square/ring/triangle/hline/text/dot` |
 
 ### Emits
 
@@ -202,12 +205,37 @@ const g6Data = buildGraphData(model, layout);   // → G6 可直接消费的 { n
 | `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（过滤站内边与主干鱼骨边） |
+| `update:legend` | 新布尔值 | 工具条 🗺 图例按钮点击（配合 `v-model:legend`） |
+
+### 图例（legend）
+
+```vue
+<!-- 默认不显示；开启即用（按图内容自动生成条目，颜色随主题） -->
+<TopoGraph :data-url="'/data/topo.json'" legend />
+
+<!-- 自定义图例项 -->
+<TopoGraph
+  :data-url="'/data/topo.json'"
+  :legend="true"
+  :legend-items="[
+    { label: '正常设备', shape: 'square', color: '#22C55E' },
+    { label: '告警设备', shape: 'ring',   color: '#EF4444' },
+    { label: '停电',     shape: 'triangle', color: '#9CA3AF' },
+    { label: 'JX',       shape: 'text',   color: '#3A3A3A', text: 'JX' },
+  ]"
+/>
+```
+
+> 自动图例内容：配电变压器 / 开关 / 熔丝 / 低压母线 / 电缆终端头 / 密母分接点 / 计量箱 /
+> 用户接入点 / 低压导线点 / 低压配电箱 / 其它设备（仅显示图中存在的），末尾固定为
+> **主干导线 / 分支导线**，图中含计量箱客户数据时再追加 **客户电表**。
 
 ### 内置交互与 UI
 
 - 滚轮缩放、拖拽平移、悬停高亮（上下游与连线），点击选中（金色虚框，再次点空白取消）。
 - **计量箱用户点击**：单户箱整箱即该户；多户箱点电表格 / 户名 = 该户客户档案（悬停青圈、选中金圈），点箱体空白 = 选中整箱（事件 `consumer:click` / `customer-select`）。
-- 左上角工具条**默认隐藏**：传 `:toolbar="true"` 后显示标题 / `节点 n · 边 m · 深度 d · 叶子 l` 统计 / 「适应画布」/「导出 PNG」按钮。
+- 左上角工具条**默认隐藏**：传 `:toolbar="true"` 后显示标题 / `节点 n · 边 m · 深度 d · 叶子 l` 统计 / 🌙 主题 / 🗺 图例 /「适应画布」/「导出 PNG」按钮。
+- **图例默认关闭**：传 `:legend="true"`（或 `v-model:legend`）后右下角出现图例面板，点击标题可折叠。
 - 加载中 / 出错（如 dataUrl 404）有内置遮罩提示。
 - 卸载时自动 `destroy()` 图实例与事件监听，无内存泄漏。
 
@@ -230,8 +258,7 @@ const g6Data = buildGraphData(model, layout);   // → G6 可直接消费的 { n
 
 引擎内置两套主题，**浅色为默认**（白底，图元配套深色，适合打印或嵌入浅色页面）；深色为**黑底 SCADA 风格**。
 
-- `TopoGraph`：`:theme` 取值 `'light'`（默认）或 `'dark'`，推荐 `v-model:theme` 双向绑定；开启 `:toolbar="true"` 后工具条内置 ☀️ / 🌙 切换按钮（点击 emit `update:theme`）。
-- `SidePanel` / `DistanceTop10`：同样接收 `theme` prop，与画布保持一致观感。
+- `TopoGraph`：`:theme` 取值 `'light'`（默认）或 `'dark'`，推荐 `v-model:theme` 双向绑定；开启 `:toolbar="true"` 后工具条内置 ☀️ / 🌙 切换按钮（点击 emit `update:theme`）。- `SidePanel` / `DistanceTop10`：同样接收 `theme` prop，与画布保持一致观感。
 - 切换主题会**按当前数据自动重建画布**：G6 画布背景、图元、边、标注文字全部随主题更新，布局不变。
 
 ```vue
@@ -268,6 +295,7 @@ const dataUrl = ref('/data/topology.json');
 > topo.locateNode(assetNo);                                  // 定位到某户表位中心
 > topo.highlightNode(assetNo, { color: '#FF0000' });          // 该户表位高亮环
 > topo.setNodeGlow(assetNo, { color: '#FF6600' });            // 该户表位光晕
+> topo.setNodeGlow(assetNo, { blink: true, color: '#FF6600' }); // 该户表位整体闪烁
 > topo.setNodePulse(assetNo);                                 // 该户电表格脉动
 > topo.setText(assetNo, '异常');                              // 表位上方标注
 > topo.showCard(assetNo);                                     // 客户档案卡片（定位在表位旁）
@@ -337,7 +365,8 @@ topo.unhighlightAll();
 
 ```javascript
 topo.setNodePulse('2', { color: '#00C8FF', duration: 1500 });   // 节点脉动
-topo.setNodeGlow('2', { color: '#FF0000', spread: 18 });         // 节点光晕（发光环，颜色可设；ref 支持 psrId）
+topo.setNodeGlow('2', { color: '#FF0000' });                     // 节点光晕（多层光环 + shadowBlur 辉光 + blur 面光底衬；ref 支持 psrId）
+topo.setNodeGlow('2', { color: '#FF0000', intensity: 2, spread: 30, blink: true, duration: 800 }); // 更夸张：加强 + 更大扩散 + 图元整体闪烁
 topo.removeNodeGlow('2');
 topo.setEdgeFlow('1', '2', { color: '#00C8FF', duration: 2000 }); // 边流动
 topo.removeAnimation('2');

package/dist/index.d.ts

@@ -76,7 +76,24 @@ export class TopoApi {
   removeAllAnimations(): void;
 
   // 节点光晕动画（ref 支持节点 id / psrId / assetNo）
-  setNodeGlow(ref: string, opts?: { color?: string; spread?: number; radius?: number; duration?: number; opacity?: number }): boolean;
+  // 渲染栈：blur 柔光底衬 + 实心光块 → 图元 → 外扩散环 ×2 → 霓虹主环(shadowBlur) → 亮芯环
+  // intensity: 强度倍率（默认 1；1.5~2.5 更夸张，0.5~0.7 更收敛）
+  // spread:    光环外扩半径，默认按图元大小自适应（短边 ×0.7，16~46px）
+  // width:     主环初始线宽 (px)，默认 5.6（户表位 3.6）
+  // blink:     图元「整体闪烁」——false 默认只画光环；true = 0.85；数字 0~1 为强度
+  setNodeGlow(ref: string, opts?: {
+    color?: string;
+    spread?: number;
+    radius?: number;
+    duration?: number;
+    opacity?: number;
+    width?: number;
+    intensity?: number;
+    level?: number;
+    strength?: number;
+    blink?: boolean | number;
+    flash?: boolean | number;
+  }): boolean;
   removeNodeGlow(ref: string): boolean;
   removeAllNodeGlows(): void;
 
@@ -123,6 +140,20 @@ export class TopoApi {
   destroy(): void;
 }
 
+// 图例项（TopoGraph 组件 legend / legendItems 参数）
+export type LegendShape =
+  | 'transformer' | 'switch' | 'fuse' | 'bus' | 'cableTerminal' | 'junction'
+  | 'meterBox' | 'consumer' | 'line' | 'meterUser' | 'station' | 'edge'
+  | 'square' | 'ring' | 'triangle' | 'hline' | 'text' | 'dot';
+
+export interface LegendItem {
+  key?: string;       // 唯一键（可选）
+  label: string;      // 显示文字
+  shape?: LegendShape; // 图标形状，默认 'dot'
+  color?: string;     // 覆盖色（不传用当前主题色）
+  text?: string;      // shape='text' 时的文字（默认 'JX'）
+}
+
 // 工具函数
 export function parseTopo(raw: object): any;
 export function computeOrthogonalLayout(model: any, options?: object): any;

package/dist/style.css

@@ -1,6 +1,6 @@
 
 /* —— 主题变量：dark 为默认值，light 由 [data-theme='light'] 覆盖 —— */
-.topo-wrap[data-v-d3774ed5] {
+.topo-wrap[data-v-0736fa17] {
   --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-d3774ed5] {
+.topo-wrap[data-theme='light'][data-v-0736fa17] {
   --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-d3774ed5] {
+.topo-container[data-v-0736fa17] {
   width: 100%;
   height: 100%;
 }
-.topo-toolbar[data-v-d3774ed5] {
+.topo-toolbar[data-v-0736fa17] {
   position: absolute;
   top: 10px;
   left: 12px;
@@ -52,14 +52,14 @@
   color: var(--tp-text);
   z-index: 10;
 }
-.topo-title[data-v-d3774ed5] {
+.topo-title[data-v-0736fa17] {
   color: var(--tp-title);
   font-weight: 600;
 }
-.topo-meta[data-v-d3774ed5] {
+.topo-meta[data-v-0736fa17] {
   color: var(--tp-meta);
 }
-.btn[data-v-d3774ed5] {
+.btn[data-v-0736fa17] {
   margin-left: 4px;
   padding: 3px 10px;
   border: 1px solid var(--tp-btn-border);
@@ -69,12 +69,64 @@
   cursor: pointer;
   font-size: 12px;
 }
-.btn[data-v-d3774ed5]:hover {
+.btn[data-v-0736fa17]:hover {
   border-color: var(--tp-accent);
   color: var(--tp-accent);
+}
+/* —— 图例（legend prop 开启后显示） —— */
+.topo-legend[data-v-0736fa17] {
+  position: absolute;
+  right: 12px;
+  bottom: 12px;
+  z-index: 9;
+  min-width: 132px;
+  max-width: 240px;
+  max-height: 62%;
+  overflow: auto;
+  padding: 8px 10px;
+  background: var(--tp-toolbar-bg);
+  border: 1px solid var(--tp-toolbar-border);
+  border-radius: 6px;
+  font-size: 12px;
+  color: var(--tp-text);
+  pointer-events: auto;
+}
+.topo-legend-title[data-v-0736fa17] {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  color: var(--tp-title);
+  font-weight: 600;
+  cursor: pointer;
+  user-select: none;
+}
+.topo-legend-arrow[data-v-0736fa17] {
+  display: inline-block;
+  transition: transform 0.15s ease;
+  transform: rotate(0deg);
+}
+.topo-legend-arrow.open[data-v-0736fa17] {
+  transform: rotate(90deg);
+}
+.topo-legend-body[data-v-0736fa17] {
+  margin-top: 6px;
+}
+.topo-legend-row[data-v-0736fa17] {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 1px 0;
+  white-space: nowrap;
+}
+.topo-legend-icon[data-v-0736fa17] {
+  flex: none;
+}
+.topo-legend-label[data-v-0736fa17] {
+  color: var(--tp-text);
+  line-height: 1.2;
 }
-.topo-loading[data-v-d3774ed5],
-.topo-error[data-v-d3774ed5] {
+.topo-loading[data-v-0736fa17],
+.topo-error[data-v-0736fa17] {
   position: absolute;
   inset: 0;
   display: flex;
@@ -85,7 +137,7 @@
   z-index: 5;
   background: var(--tp-overlay-bg);
 }
-.topo-error[data-v-d3774ed5] {
+.topo-error[data-v-0736fa17] {
   color: var(--tp-error);
 }