topo-engine 0.1.0 → 0.1.3

package/README.md

@@ -1,163 +1,395 @@
-# 配电台区单线图拓扑成图引擎
-
-基于 **Vue3 + AntV G6 v5 + Vite(Node)** 的配电台区单线图拓扑成图引擎。
-解析国网 PMS 台区拓扑 JSON，在 Web 端以 **深色 SCADA / SVG 单线图风格** 渲染**横平竖直、0 交叉**的树状拓扑图。
-
-## 功能特性
-
-- 🔍 **完整的拓扑查询 API** - 节点查询、路径查找、邻居关系等
-- 🎨 **丰富的样式控制** - 节点样式、边样式、高亮标注
-- ✨ **动画效果** - 节点脉动、边流动动画
-- 📝 **文字标注** - 附加文字、用户名显示控制
-- 🃏 **卡片盒** - 节点信息弹窗
-- 🔗 **连接线/拓扑线** - 动态连接线、拓扑高亮线
-- 🎧 **事件系统** - 节点点击、悬停等事件监听
-- 💾 **导出功能** - PNG 导出、数据导出
-
-## 安装
-
-```bash
-# npm
-npm install topo-engine
-
-# yarn
-yarn add topo-engine
-
-# pnpm
-pnpm add topo-engine
-```
-
-## 快速开始
-
-### 1. 作为 Vue 组件使用
-
-```vue
-<template>
-  <TopoGraph
-    :data-url="dataUrl"
-    @node-select="onNodeSelect"
-    @loaded="onLoaded"
-  />
-</template>
-
-<script setup>
-import { ref } from 'vue';
-import { TopoGraph } from 'topo-engine';
-
-const dataUrl = ref('/data/topology.json');
-
-const onNodeSelect = (payload) => {
-  console.log('选中节点:', payload.node);
-};
-
-const onLoaded = ({ stats, title }) => {
-  console.log('加载完成:', title, stats);
-};
-</script>
-```
-
-### 2. 作为独立 API 使用
-
-```javascript
-import { TopoApi } from 'topo-engine';
-
-// 假设你已经有一个 G6 Graph 实例
-const graph = new Graph({ /* ... */ });
-
-// 加载数据后创建 TopoApi 实例
-const topoApi = new TopoApi(graph, model, layout, nodeByIdMap);
-
-// 使用 API
-const nodes = topoApi.getAllNodes();
-const path = topoApi.getPath('node1', 'node2');
-topoApi.highlightPath(['node1', 'node2', 'node3']);
-topoApi.setEdgeFlow('node1', 'node2', { color: '#FF0000' });
-```
-
-## 运行
-
-```bash
-npm install      # 安装依赖
-npm run dev      # 开发服务器 → http://127.0.0.1:5173/
-npm run build    # 生产构建 → dist/
-npm run build:lib  # 构建库文件
-npm run preview  # 预览生产构建
-```
-
-## 数据
-
-输入：`public/data/上屋胡2台区单线图.json`（源文件 `上屋胡2台区单线图.json` 的副本，UTF-8）。
-
-数据结构：
-
-- `data.nodes[]` — 设备/线路节点：`{ id, psrType, symbolId, name, psrId, status }`
-- `data.relationships[]` — 有向边：`{ from, to }`（电源 → 负荷，103 节点 102 边构成树）
-- `data.stations[]` — 台区根（低压配电箱），`contain` 列出箱内设备 psrId
-
-psrType → 图元映射（见 `src/engine/parser.js`）：
-
-| psrType | 设备 | 图元样式 |
-| ------- | ---- | -------- |
-| 0302 | 配电变压器 | 橙圆 + 红圈（SVG 2030020） |
-| 3301 | 开关/熔丝 | 红色矩形（4030010 / 2100010） |
-| 3303 | 低压母线 | 白色短粗线 |
-| 3202 | 电缆终端头 | 红色三角（3030010） |
-| 310100000 | 低压导线 | 青色连接点 |
-| 3112 | 计量箱 | 黑底白框 "JX"（5040010） |
-| 3218000 | 低压用户接入点 | 白圈 "J"（5010030） |
-| 32500000 | 低压配电箱（台区） | — |
-
-## 代码结构
-
-```
-src/
-  engine/
-    parser.js      # JSON → 图模型（建树、找根、短名提取、类型映射）
-    layout.js      # ★ 主干交替式正交布局引擎（0 交叉）+ 数学校验器
-    orthEdge.js    # ★ 自定义正交折线边（直接用布局引擎的完整点序列绘制）
-    canvasNode.js  # ★ 自定义 canvas 图元节点（@antv/g 原生图形，与边同场景图）
-    symbols.js     # SVG 风格图元规格（尺寸/配色，供 canvasNode 与图例使用）
-    graphData.js   # 模型 → G6 数据（节点/边样式、显式正交点序列）
-  components/
-    TopoGraph.vue  # G6 图组件（布局调用、自定义边/节点、tooltip、点击联动）
-    SidePanel.vue  # 设备详情 / 台区概览
-    LegendBar.vue  # 图例
-  App.vue          # 布局与数据加载
-  style.css
-```
-
-## 渲染要点（强参考 sample/*.svg）
-
-- 黑色画布背景（`#050505`，对照 SVG `BackGround_Layer` 的 `rgb(0,0,0)`）
-- 导线双色：干线白色、支线灰色（对照 SVG 的 `rgb(255,255,255)` / `rgb(128,128,128)`）
-- 图元配色与几何逐项对照 sample SVG 的 `<symbol>` 定义
-- **正交布局（0 交叉，见 `src/engine/layout.js`）—— 单向直走式**：
-  - 主干 = 从根沿**最长路径**前进（每步选到最深叶子距离最大的子节点），主干横向铺开
-  - 主干节点的其余子节点为侧分支，交替挂下方/上方，带内按内容盒 x 排布
-  - 侧分支 = **垂直列式（选定方向后不拐弯）**：分支内每步同样选最长路径子节点**同列垂直直走**，
-    其余子节点独占新列（同样垂直直走），列内递归同规则——整张图只有横向主干 + 垂直列，无方向交替拐弯
-  - 边路由：同向链 = 直线；跨列/跨带 = L 形（垂直段 + 水平带线，带线统一高度）
-  - 数学验证：`assertOrthogonal`（全线段横平竖直）+ `checkZeroCrossing`（0 交叉、0 压线、0 节点重叠）
-  - 实测：102 条边端点全部落在节点边界、0 非正交段；分支链节点同列直走（如 K02 链 5 节点 x 完全一致）
-- 交互：滚轮缩放、拖拽平移、悬停 tooltip（设备/名称/编码/状态）、点击选中（金色虚框 + 右侧详情）
-
-## 布局参数（`TopoGraph.vue` → `computeOrthogonalLayout`）
-
-| 参数 | 默认 | 含义 |
-| ---- | ---- | ---- |
-| nodeGap | 26 | 主干相邻节点边界间距 |
-| band | 50 | 主干轴线到分支带（带线）的距离 |
-| packGap | 22 | 分支带内兄弟子树间距 |
-| sideGap | 40 | 相邻主干节点分支带之间的隔离间距 |
-| margin | 40 | 画布外框留白 |
-
-## 备注
-
-- 布局由自研引擎显式给定节点坐标与边路径点（`orth-polyline` 边直接使用完整点序列，
-  首尾即真实边界端点，绕开 G6 内置边对 HTML 节点失效的 `getIntersectPoint`）。
-- **节点为自定义 canvas 节点 `svg-symbol`**（`canvasNode.js`）：用 @antv/g 原生图形绘制图元，
-  与边同在场景图、同一相机 —— 规避 G6 HTML 节点（DOM 覆盖层）不跟随相机变换导致的
-  fitView/缩放后节点与边错位问题（实测：HTML 节点 DOM 定位停留在世界坐标、无缩放平移）。
-- key shape 为透明 Rect（`fill: rgba(255,255,255,0.01)`，alpha=0 不参与命中测试），
-  图元/标签/选中高亮框作为其子元素绘制。
-- 图元采用 G6 `html` 节点 + 内联 SVG 字符串渲染，文字（宋体）清晰且与 SVG 风格一致。
+# topo-engine
+
+配电台区（低压配电网）**单线图拓扑成图引擎**，基于 **Vue 3 + AntV G6 v5**。
+
+输入一份台区拓扑 JSON，自动完成「解析 → 建树找根 → **横平竖直、0 交叉** 的正交布局 → 深色 SCADA 风格渲染」，并提供开箱即用的 Vue 组件与一整套拓扑查询 / 样式 / 动画 / 标注控制 API。
+
+## 功能特性
+
+- 🧩 **Vue 3 组件** — `TopoGraph`（画布，含标题栏 / 统计 / 适应画布 / 导出 PNG 按钮）、`SidePanel`（设备详情与上下游）、`DistanceTop10`（父子连线距离 Top10 面板）
+- 🎨 **深色 / 浅色双主题** — 黑底 SCADA 或白底两种画布风格，图元 / 导线 / 文字随之配套适配，可随时切换（`theme` prop 或工具栏按钮）
+- 📐 **自研正交布局** — 主干沿最长路径横向铺开 + 分支带垂直直走，整图**横平竖直、0 交叉、0 重叠**，边缘路由为直线 / L 形折线
+- 🔍 **拓扑查询 API** — 节点 / 边 / 邻居 / 子树 / 主干链 / 路径 / 坐标 查询
+- 🎨 **样式控制** — 节点、边样式覆盖与批量重置
+- ✨ **动画与高亮** — 节点脉动、边流动、路径高亮、其余变暗、异常标注
+- 📝 **文字标注** — 附加文字、用户名 full / short / hidden 切换
+- 🃏 **卡片盒** — 节点信息卡片（字段 + 按钮），适配"运行曲线/工单跳转"类场景
+- 🔗 **连接线 / 拓扑线** — 任意两节点动态连接线、路径拓扑高亮线
+- 🎧 **事件系统** — 点击 / 悬停 / 画布空白 / 视口变化事件总线
+- 💾 **导出** — 整图 PNG 下载、DataURL、图数据 JSON
+- 📦 **零配置渲染** — 组件自带深色主题与工具栏，`data` 或 `dataUrl` 二选一即可出图
+
+## 安装
+
+```bash
+npm install topo-engine
+# 或 yarn add topo-engine / pnpm add topo-engine
+```
+
+- 环境要求：**Vue 3.4+**（peerDependency）；`@antv/g6` v5 已作为依赖随包安装，无需手动配置。
+- 组件深色样式不自动注入，使用时需引入样式文件：
+
+```js
+import 'topo-engine/style.css';
+```
+
+## 快速开始
+
+### 1. 最小示例 —— 只画一张图
+
+```vue
+<script setup>
+import { ref } from 'vue';
+import { TopoGraph } from 'topo-engine';
+import 'topo-engine/style.css';
+
+// 两种数据来源任选其一：
+//  - dataUrl：内部用 fetch 加载（注意放 public/ 下或跨域可达）
+//  - data   ：直接传入解析好的 JSON 对象（优先级高于 dataUrl）
+const dataUrl = ref('/data/topology.json');
+
+const onLoaded = ({ title, stats }) => {
+  console.log('加载完成', title, stats); // { total, depth, leaves, byCat }
+};
+</script>
+
+<template>
+  <!-- 组件撑满父容器，父容器必须有明确高度 -->
+  <div class="page">
+    <TopoGraph :data-url="dataUrl" @loaded="onLoaded" />
+  </div>
+</template>
+
+<style scoped>
+.page { height: 640px; }
+</style>
+```
+
+### 2. 组合示例 —— 图 + 详情面板 + Top10 距离面板
+
+```vue
+<script setup>
+import { ref } from 'vue';
+import { TopoGraph, SidePanel, DistanceTop10 } from 'topo-engine';
+import 'topo-engine/style.css';
+
+const topo = ref(null);              // ref → 调用完整控制 API
+const graphData = ref(null);         // 直接传数据对象
+const panelOpen = ref(false);
+const selected = ref(null);
+const upstream = ref([]);
+const downstream = ref([]);
+const stats = ref({});
+const distances = ref([]);
+
+function onSelect({ node, upstream: up, downstream: down }) {
+  selected.value = node;
+  upstream.value = up;
+  downstream.value = down;
+  panelOpen.value = true;
+}
+function onTopDistances(list) { distances.value = list; }
+function jumpTo(id) { topo.value?.selectNode(id); }
+</script>
+
+<template>
+  <div class="app">
+    <div class="graph-area">
+      <TopoGraph
+        ref="topo"
+        :data="graphData"
+        @node-select="onSelect"
+        @top-distances="onTopDistances"
+      />
+      <SidePanel
+        v-if="panelOpen"
+        :node="selected"
+        :upstream="upstream"
+        :downstream="downstream"
+        :stats="stats"
+        @close="panelOpen = false"
+        @jump="jumpTo"
+      />
+    </div>
+    <DistanceTop10
+      v-if="distances.length"
+      :distances="distances"
+      @close="distances = []"
+      @jump="jumpTo"
+    />
+  </div>
+</template>
+
+<style scoped>
+.app { display: flex; height: 720px; }
+.graph-area { flex: 1; display: flex; min-width: 0; position: relative; }
+</style>
+```
+
+### 3. 只用布局 / 解析工具函数（不依赖组件）
+
+```javascript
+import { parseTopo, computeOrthogonalLayout, buildGraphData } from 'topo-engine';
+
+const model  = parseTopo(rawJson);              // 原始 JSON → 图模型（含 nodes/edges/rootId/stats）
+const layout = computeOrthogonalLayout(model);  // 正交布局结果（节点坐标 + 每边折线点序列）
+const g6Data = buildGraphData(model, layout);   // → G6 可直接消费的 { nodes, edges }
+```
+
+> 说明：包内渲染使用的自定义图元节点（`svg-symbol`）与正交折线边（`orth-polyline`）目前仅在 `TopoGraph` 内部注册使用，未作为公开 API 导出。直接用 G6 手工拼图时建议以 `TopoGraph` 组件（或它的 render 流程）为基准，保证节点与边风格一致。
+
+## 输入数据格式
+
+顶层可以是 `{ code, msg, data: { nodes, relationships, stations } }`（常见接口包装格式），也可以是直接 `{ nodes, relationships, stations }` —— 引擎两种都接受。
+
+```json
+{
+  "data": {
+    "nodes": [
+      { "id": 1, "name": "1#台区.", "psrType": "0302", "symbolId": "1664029", "status": "0" },
+      { "id": 2, "name": "1#台区低压熔丝.", "psrType": "3301", "symbolId": "68688", "status": "0" }
+    ],
+    "relationships": [ { "from": 1, "to": 2 } ],
+    "stations": [
+      { "id": 1, "name": "1#台区.", "contain": ["8ff4786d548a7073a2517297e801518ff456732f4d"] }
+    ]
+  }
+}
+```
+
+| 字段 | 说明 |
+| ---- | ---- |
+| `nodes[]` | 设备/线路节点：`id`、`name`（可带结尾 `.`，渲染时会去掉）、`psrType`（图元类型码）、`symbolId`、`psrId`、`status`（`"0"` 视为正常） |
+| `relationships[]` | 有向边 `{ from, to }`，方向为 电源 → 负荷；自动防环（BFS），入度为 0 者作为根，优先选变压器/开关 |
+| `stations[]` | 台区/站房：`name` 作为画布标题，`contain` 内为箱内设备的 `psrId` 列表 |
+
+`parseTopo` 后模型节点会附带派生抽像字段：`cat`、`catLabel`、`shortName`、`isLine`、`insideStation`、`isFuse` 等（完整类型见 `dist/index.d.ts`）。
+
+主要 `psrType` → 图元类别：
+
+| psrType | 类别 | 渲染 |
+| ------- | ---- | ---- |
+| `0302` | 配电变压器 | 橙色圆 + 红圈 |
+| `3301` | 开关 / 熔丝 | 红色矩形（开关名自动缩写为 K 编号） |
+| `3303` | 低压母线 | 白色短粗线 |
+| `3202` / `320300000` | 电缆终端头 / 分接点 | 三角 / 红色米字 |
+| `310100000` | 低压导线 | 青色连接点（名称缩写为杆号区间） |
+| `3112` | 计量箱 | 黑底白框 "JX" |
+| `3218000` | 用户接入点 | 白圈 "J"（名称缩写为户号） |
+| `32500000` | 低压配电箱（台区） | 站房 |
+
+## TopoGraph 组件参考
+
+### Props
+
+| Prop | 类型 | 默认 | 说明 |
+| ---- | ---- | ---- | ---- |
+| `dataUrl` | `String` | `''` | 拓扑 JSON 的 URL（内部 `fetch` 加载）。变化后自动重新加载 |
+| `data` | `Object` | `null` | 直接传入 JSON 对象；优先级高于 `dataUrl`；深度 watch，变化自动重绘 |
+| `theme` | `'dark' \| 'light'` | `'dark'` | 画布主题：`dark`（黑底 SCADA，默认）/ `light`（白底，图元配套加深）。支持 `v-model:theme`，也可点内置工具栏 ☀️/🌙 按钮切换 |
+
+### Emits
+
+| 事件 | 载荷 | 触发时机 |
+| ---- | ---- | ---- |
+| `loaded` | `{ title, stats }`，`stats = { total, depth, leaves, byCat }` | 每次数据渲染完成 |
+| `node-select` | `{ node, upstream, downstream }`（均为解析后模型节点） | 点击节点（含金框选中与详情联动） |
+| `top-distances` | `Array<{ parent: {id,name,catLabel}, child: {id,name,catLabel}, distance }>`（≤10） | 渲染完成时，父-子连线折线长度 Top10（过滤站内边与主干鱼骨边） |
+
+### 内置交互与 UI
+
+- 滚轮缩放、拖拽平移、悬停高亮（上下游与连线），点击选中（金色虚框，再次点空白取消）。
+- 左上角深色工具栏：标题 / `节点 n · 边 m · 深度 d · 叶子 l` 统计 / 「适应画布」/「导出 PNG」按钮。
+- 加载中 / 出错（如 dataUrl 404）有内置遮罩提示。
+- 卸载时自动 `destroy()` 图实例与事件监听，无内存泄漏。
+
+### 通过 ref 调用的方法
+
+`<TopoGraph ref="topo">` 后，`topo` 暴露 **`TopoApi` 的全部公开方法**（下节 API 表），外加：
+
+| 方法 | 说明 |
+| ---- | ---- |
+| `loadRaw(jsonText)` | 用一段 JSON 文本（如本地文件上传内容）重新成图 |
+| `selectNode(id)` | 选中某节点并联动 `node-select` 事件 |
+| `resetView()` | 适应画布 |
+| `exportPng()` | 导出整图 PNG（按画布标题命名下载） |
+| `getLayoutData()` | 获取当前正交布局数据（坐标 / 折线 / stats） |
+| `getTopDistances()` | 获取最近一次 Top10 距离结果 |
+
+### 主题切换（深色 / 浅色）
+
+引擎内置两套主题，**深色为默认**（黑底 SCADA 风格，与历史版本一致）；浅色为**白底**，图元（变压器 / 开关 / 计量箱 / 用户圈…）、导线（干线深灰 / 支线浅灰）、节点文字都已配套加深，适合打印或嵌入浅色页面。
+
+- `TopoGraph`：`:theme` 取值 `'dark'`（默认）或 `'light'`，推荐 `v-model:theme` 双向绑定；组件左上工具栏内置 ☀️ / 🌙 切换按钮（点击 emit `update:theme`）。
+- `SidePanel` / `DistanceTop10`：同样接收 `theme` prop，与画布保持一致观感。
+- 切换主题会**按当前数据自动重建画布**：G6 画布背景、图元、边、标注文字全部随主题更新，布局不变。
+
+```vue
+<script setup>
+import { ref } from 'vue';
+import { TopoGraph } from 'topo-engine';
+import 'topo-engine/style.css';
+
+const theme = ref('dark');          // 初始深色，可在运行时切换
+const dataUrl = ref('/data/topology.json');
+</script>
+
+<template>
+  <div class="page">
+    <TopoGraph v-model:theme="theme" :data-url="dataUrl" />
+  </div>
+</template>
+```
+
+> 说明：主题色板定义在包内 `theme.js`（`THEMES.dark` / `THEMES.light`，已随库打包，未作为公开导出）；若需要按自有品牌定制，可在外层自行覆盖 `dist/style.css` 中各组件的 `--tp-*` / `--sp-*` / `--dt-*` CSS 变量。
+
+## 控制 API（TopoApi 方法，经组件 ref 直接调用）
+
+> 也可自行 `import { TopoApi }`，按 `new TopoApi(graph, model, layout, nodeByIdMap)` 构造后调用同一套方法；事件与查询见下。使用组件时无需关心内部构造。
+
+### 查询
+
+| 方法 | 说明 |
+| ---- | ---- |
+| `getNode(nodeId)` | 按 ID 取节点（解析后模型节点） |
+| `getAllNodes()` | 全部节点 |
+| `findNodes(filter)` | 多条件 AND 过滤，`filter` 支持 `{ cat, psrType, name, shortName, status, insideStation, … }`，值可为字符串 / 布尔 / `RegExp` |
+| `getSelectedId()` | 当前选中节点 ID |
+| `getNeighbors(id)` | `{ upstream: [], downstream: [] }` |
+| `getStreamNodes(id, 'upstream'\|'downstream')` | 沿流向 BFS 取节点链 |
+| `getTrunkNodes()` / `getSubtreeNodes(id)` | 主干链节点 / 子树节点 |
+| `getPath(a, b)` | 两节点间路径（不可达返回 `null`） |
+| `getEdge(src, tgt)` / `getEdges()` | 按端点取边 / 全部边 |
+| `getStreamEdges(id, dir)` / `getMainEdge()` | 沿流边的链 / 主干边 |
+| `getNodePosition(id)` / `getEdgePath(src, tgt)` / `getGraphBounds()` | 坐标 / 边折线点序列 / 全图包围盒 |
+| `getStats()` | `{ total, depth, leaves, byCat }` |
+
+### 视图
+
+`fitView(padding?)`、`zoomTo(ratio, center?)`、`zoomIn(step?)`、`zoomOut(step?)`、`locateNode(id, zoom?)`、`getViewport()`
+
+### 样式
+
+`setNodeStyle(id, style)`、`batchSetNodeStyle(ids, style)`、`resetNodeStyle(id)`、`resetAllNodeStyles()`
+`setEdgeStyle(src, tgt, style)`、`batchSetEdgeStyle([[src,tgt],…], style)`、`resetEdgeStyle(src, tgt)`
+
+### 高亮 / 变暗
+
+```javascript
+topo.highlightNode('5', { color: '#FF0000', label: '异常', labelColor: '#FF0000' });
+topo.unhighlightNode('5');
+
+const path = topo.getPath('1', '5');        // 高亮一条供电路径
+if (path) topo.highlightPath(path.map(n => n.id), { color: '#00FF00' });
+
+topo.dimOthers(['1', '2'], 0.15);           // 除指定节点外整体变暗
+topo.unhighlightAll();
+```
+
+### 动画
+
+```javascript
+topo.setNodePulse('2', { color: '#00C8FF', duration: 1500 });   // 节点脉动
+topo.setEdgeFlow('1', '2', { color: '#00C8FF', duration: 2000 }); // 边流动
+topo.removeAnimation('2');
+topo.removeAllAnimations();
+```
+
+### 文字标注
+
+`setText(id, text, { color, fontSize })`、`removeText(id)`、`removeAllTexts()`、`setDeviceText(cat, fontSize)`、`changeUserName('full' | 'short' | 'hidden')`
+
+### 卡片盒
+
+```javascript
+topo.showCard('5', {
+  title: '设备名称',
+  fields: [
+    { label: '类型', value: '配电变压器' },
+    { label: 'PSR编号', value: 'xxx' },
+  ],
+  buttons: [{ text: '查看运行曲线', type: 'primary', onClick: () => console.log('click') }],
+  closable: true,
+});
+topo.hideCard('5');
+topo.hideAllCards();
+```
+
+### 连接线 / 拓扑线
+
+```javascript
+topo.addConnection('1', '8', { color: '#FF6600', width: 2, style: 'dashed' }); // 任意两节点连线
+topo.removeAllConnections();
+
+const lineId = topo.addTopoLine(['1', '3', '8'], { color: '#FF0000', width: 3 }); // 沿线路径画高亮线
+topo.removeTopoLine(lineId);
+topo.removeAllTopoLines();
+```
+
+### 事件总线（`on` / `off`）
+
+| 事件 | 载荷 | 说明 |
+| ---- | ---- | ---- |
+| `node:click` | `{ nodeId, node }` | 节点点击 |
+| `node:hover` / `node:unhover` | `{ nodeId, node }` / `{ nodeId }` | 悬停进入 / 离开 |
+| `edge:click` | `{ edgeId, source, target }` | 边点击 |
+| `canvas:click` | `{ event }` | 画布空白处点击 |
+| `viewport:change` | `{ zoom, center }` | 视口缩放 / 平移变化 |
+| `card:button` | `{ nodeId, buttonIndex }` | 卡片按钮点击 |
+
+```javascript
+const handler = ({ nodeId }) => console.log('点击了', nodeId);
+topo.on('node:click', handler);
+topo.off('node:click', handler); // 不传 handler 则移除该事件全部监听
+```
+
+### 导出 / 底层
+
+`exportPng(filename?)`（整图下载）、`toDataURL(opts?)`、`getGraphData()`、`getGraphInstance()`（原始 G6 Graph）、`getModel()`、`getLayoutData()`、`getNodeByIdMap()`、`update(graph, model, layout, map)`、`destroy()`
+
+## 布局与渲染参数
+
+`computeOrthogonalLayout(model, options)`：
+
+| 参数 | 默认 | 含义 |
+| ---- | ---- | ---- |
+| `nodeGap` | `26` | 链上相邻节点边界间距 |
+| `band` | `50` | 侧分支根到父节点中心线的距离（分支带宽） |
+| `packGap` | `22` | 分支带内并排子分支间距 |
+| `sideGap` | `40` | 相邻主干节点的分支带隔离间距 |
+| `margin` | `40` | 画布外框留白 |
+
+`TopoGraph` 组件内部即用上述默认参数，返回布局数据含每节点坐标、`edgeCP`（每条边的完整折线点序列）与 `fishboneRibs`，可配 `assertOrthogonal(model, edgeCP)` 做 0 交叉 / 正交性校验。
+
+## TypeScript
+
+类型声明随包发布（`dist/index.d.ts`），支持按需导入：
+
+```typescript
+import { TopoApi, TopoGraph } from 'topo-engine';
+import type { TopoApi } from 'topo-engine'; // 需要类型时
+```
+
+## 常见问题
+
+- **图不显示 / 高度为 0**：`TopoGraph` 撑满父容器（内部 `width/height: 100%`），请给外层元素设置明确高度（如 `height: 600px`）。
+- **样式错乱 / 没有深色背景**：确认已 `import 'topo-engine/style.css'`。
+- **`dataUrl` 加载失败**：确认文件可被 `fetch` 访问（Vite 放 `public/`，不要用相对路径）；失败会触发 `error` 态显示并 `console.error`。
+- **切换数据源**：响应式修改 `:data` / `:data-url` 会自动重新加载；本地文件可用 `ref.loadRaw(text)`。
+- **节点 ID 传字符串**：内部统一按字符串存储（`String(id)`），查询 API 请传字符串，如 `getNode('1')`。
+- **和 Vue 2 / 其它 G6 版本混用**：仅支持 Vue 3.4+，图内部依赖 `@antv/g6` v5，请勿重复安装不同版本。
+
+## 本地开发
+
+```bash
+npm install          # 安装依赖
+npm run dev          # 开发演示（内置 API Playground，可试所有控制 API）→ http://127.0.0.1:5173/
+npm run build        # 生产构建（应用 + 库）
+npm run build:lib    # 仅构建库产物到 dist/
+npm run preview      # 预览生产构建
+npm pack --dry-run   # 查看发布包内容清单
+```
+
+## License
+
+MIT