gis-view-webgl2 0.1.0 → 0.1.2

package/docs/manual/16-/345/256/236/344/276/213/346/226/271/346/263/225/346/200/273/350/241/250.md

@@ -12,9 +12,7 @@
 | `updatePointStyle(patch)` / `updateLineStyle(patch)` | 改全局点 / 线样式的某几个字段（字段级合并，不写的保持原来的那一份）：`updateOptions({ pointStyle })` 是整份换（没写的字段等于回到内置默认），这两个只动给出来的键 —— 面板上拖大小 / 换调色板一个键一条，不会把样式表里别的配置碰掉；传 `null` 清掉整份全局样式，写错的字段名走 `onWarning` 点名。只改尺寸链（`size` / `sizeScale`）或配色链（`color` / `strokeColor` / `strokeWidth` / `opacity`）时引擎走「逐要素只重算这条链」的窄路，逐点自己定死了这一项的要素连槽位都不重写，见「大数据量」 |
 | `getOptions()` | 当前配置与数据的副本 |
 | `getData()` | 当前数据副本（**点与线两列**，含拖拽点之后的最新坐标）；通道声明不在这一份里 —— 读整份配置与数据用 `getOptions()`（`getOptions().channels`）、存档 / 回灌用 `exportData({ format: 'input' })` |
-| `updateData(points, lines, channels?)` | 整份换数据：只给两个参数时换点与线（通道不动）；给 `channels` 时连通道一起换（切场景一次换完、只发一条 `onDataChange`）；也收单对象写法 `updateData({ points, lines, channels })`，接口字段先在调用方映射成这三列，见「动态换数据与加载完成」 |
-| `updatePoints(points)` / `updateLines(lines)` | 只替换点或线数据 |
-| `updateChannels(channels)` | 整份替换通道声明（回线怎么分组、骨架拐点在哪），场站与回线数据不动；与 `updateChannel(id, patch)`（按 id 只改一条）一对。声明里没写分组 id 时引擎按「单组用通道 id、多组 `通道id::1` / `通道id::2`…」补，并把最终分组（含拐点路径）与对齐后的成员表写回数据副本；认不出的成员 id、重名的分组 id 各报一句 `onWarning` |
+| `updateData(points, lines, channels?)` | 整份换数据：只给两个参数时换点与线（通道不动）；给 `channels` 时连通道一起换（切场景一次换完、只发一条 `onDataChange`）；也收单对象写法 `updateData({ points, lines, channels })`，只换给出的那几列 —— 只换通道声明写 `updateData({ channels })`，只换节点 / 线路写 `updateData({ points })` / `updateData({ lines })`。接口字段先在调用方映射成这三列，见「动态换数据与加载完成」 |
 | `importData(input, options?)` | 整份喂回一份数据 / 一份标准文档（`exportData` 的五种格式都认，最标准的是 `format: 'full'` 那一份）：顶层出哪一列就应用哪一列（`points` / `lines` / `channels` / `labelStates` / `view` / `filter`），没出的列一个都不动；只给通道（不带点线）时单独换通道声明，只给 `labelStates` 时只动标签状态（整份语义）。返回 `{ ok, reason, applied, counts, warnings }`，见「标准数据文档（full）：接收 == 导出」 |
 | `patchPoints(entries, patch?)` / `patchLines(entries, patch?)` | 批量打补丁（只动点到的这几条，不换整份数据）：`patchPoints([{ id: 'a', name: 'A' }, { index: 3, x: 10 }])` 一次改几条（`id` / `index` 之外的字段就是这一条的补丁），或者 `patchPoints(['a', 'b'], { status: 1 })` 把同一份补丁盖到一批定位上（`'a'` / `{ index: 2 }` 都认）。认不出来的进 `skipped`、不影响其余条目；返回 `{ ok, reason, indexes, items, count, skipped }`，**只记一条历史、只发一条** `updatePoints` / `updateLines` 数据变更 —— 十万级批量改不必逐条付事件与历史的代价，见「批量更新（batch）」 |
 | `getLabelStates(kind?)` | 标签的运行时状态（拖出来的偏移 + 逐条覆盖，每条带 `labelId`）：`kind` 写 `'point'` / `'line'` 只取一类；做持久化 / 回显编辑面板用它，见「标签的拖动与编辑」 |
@@ -70,12 +68,11 @@
 | `hoverAt(clientX, clientY)` / `clearHover()` / `getHover()` | 程序化悬停：`hoverAt` 让指针「停」到某个客户端坐标上（悬停高亮、光标与 `onHover` 一起更新，返回与 `onHover` 载荷同一份读数，空白处 `null`；不走悬停阈值，也不用先订阅事件）、`clearHover()` 撤掉并补发一条 `onHover(null)`、`getHover()` 随时读当前这一份 —— 外部列表 / 表格 hover 到某一行时联动高亮图上的要素用它 |
 | `getFeaturesInRect(rect)` | 画布 CSS 像素矩形里有什么（与框选 / `selectInBox` 同一套坐标与判定）：返回 `{ rect, worldRect, points, lines }` —— `points` 是框内的节点（与 `onSelect` 的 `items` 同一口径）、`lines` 是包围盒沾到框的线路（与 `listLines` 同一份）、`worldRect` 是这块像素对应的世界坐标范围；只读，不改选中也不画框 |
 | `getChannelsInView()` | 当前视口里有哪几条通道（同一通道的几回线只算一条）：每条给 `{ channelId, channelIndex, channel, lineIndexes, groupIds }`，侧边栏「画面里的通道」、按视口统计用它 |
-| `select(refs, options?)` | 接口选中（换一份选中集；`select(null)` / 空数组就是清空）：`refs` 认 id、id 数组、`{ type, index }`、通道写法（`{ type: 'channel', channelId }` / `{ channelId, groupId }` / `{ channelId, lineIds }`）以及拾取载荷与搜索命中，传 `null` / 空数组清空；`options` 与 `selectFeatures` 同一份（`mode: 'add' / 'toggle' / 'remove'`），见「接口选中（select / selectFeatures）与读回选中」 |
-| `selectFeatures(refs, options?)` | 同一份接口选中，另给 `options.mode`：`'replace'`（缺省，换一份）/ `'add'` / `'toggle'`（在就取消、不在就选上）/ `'remove'`，决定这一批怎么并进当前选中集 |
-| `deselect(refs?)` | 取消选中：写法与 `selectFeatures` 完全一样，把这些从当前选中集里去掉、其余选中原样留着；不传 / `null` 等于取消全部（也就是 `select(null)`），空数组是「没有目标」什么都不做，见「取消选中（deselect / select(null)）」 |
+| `selectFeatures(refs, options?)` | 接口选中（换一份选中集；`selectFeatures(null)` / 空数组就是清空）：`refs` 认 id、id 数组、`{ type, index }`、通道写法（`{ type: 'channel', channelId }` / `{ channelId, groupId }` / `{ channelId, lineIds }`）以及拾取载荷与搜索命中；`options.mode` 给 `'replace'`（缺省，换一份）/ `'add'` / `'toggle'`（在就取消、不在就选上）/ `'remove'`，见「接口选中（selectFeatures）与读回选中」 |
+| `deselect(refs?)` | 取消选中：写法与 `selectFeatures` 完全一样，把这些从当前选中集里去掉、其余选中原样留着；不传 / `null` 等于取消全部（也就是 `selectFeatures(null)`），空数组是「没有目标」什么都不做，见「取消选中（deselect / selectFeatures(null)）」 |
 | `getSelections()` | 读回选中结果 `[{ type, index, item, … }]`（按选中顺序）：要 id 列表 / 个数 / 包围盒看 `getSelectionData()` |
 | `isSelected(ref)` | 这个要素在不在当前选中集里：`isSelected('node-0')`（id）/ `isSelected({ type: 'line', index: 12 })`（也可以只写下标，按 id 认不出来时当下标），返回 `true` / `false`。面板上高亮「当前这一行」时不必自己比对 `getSelections()`；选中集变化时缓存一份键集合（见「接口选中」），十万级选中下这一问也是常数级 |
-| `getSelectionData()` | 选中集一次取全：读数（`ids` / `count` / `pointCount` / `lineCount` / `channelCount`）加要素本身（`points` / `lines` / `channels`（按通道去重，与 `getData()` 同一批对象）），另有 `items`（与 `getSelections()` 同一份）、`pointIndexes` / `lineIndexes` 与 `bounds`（世界包围盒，空选中时 `null`），见「接口选中（select / selectFeatures）与读回选中」 |
+| `getSelectionData()` | 选中集一次取全：读数（`ids` / `count` / `pointCount` / `lineCount` / `channelCount`）加要素本身（`points` / `lines` / `channels`（按通道去重，与 `getData()` 同一批对象）），另有 `items`（与 `getSelections()` 同一份）、`pointIndexes` / `lineIndexes` 与 `bounds`（世界包围盒，空选中时 `null`），见「接口选中（selectFeatures）与读回选中」 |
 | `selectInBox(box, options?)` | 按画布 CSS 像素矩形框选，等价于 Shift + 拖动（跟随 `shortcuts.boxSelect`）；`options.selectionKinds` 可只覆盖这一次的节点 / 线路 / 通道类型过滤 |
 | `beginCopyPoint(options?)` | 开始复制一个节点：给 `id` / `index` 直接出预览（`commit: true` 出预览即落地，`follow: true` 跟随鼠标，`autoCommit: false` 停在预览态），不给来源就是「先点按钮再选节点」模式，见「节点复制」 |
 | `commitPointCopy()` / `cancelPointCopy()` | 落地 / 取消预览中的复制（返回 `end` / `cancel` 载荷） |
@@ -86,7 +83,8 @@
 | `copyPointToClipboard(sources?, options?)` / `copyPointsToClipboard(sources?, options?)` / `pastePoint(options?)` / `pastePoints(options?)` / `getPointClipboard()` | 剪贴板：`copyPointToClipboard` 默认收当前选中的全部节点（只有没选中才回落到光标下的那个），`copyPointsToClipboard` 只认给定 / 选中的一批；Ctrl+V 时单节点且没有内部线路 / 通道仍走原预览，多节点或带线路 / 通道走整组落地，`pastePoints` 强制整组（单节点也走批量载荷）。`getPointClipboard()` 读 `count` / `sources` / `items` / `lines` / `channels` / `anchor` 快照，见「节点复制」 |
 | `mergePoints(source, target, options?)` | 把来源节点并进目标节点（接口调用，不做确认）：来源 / 目标收 id、下标或 `{ id }` / `{ index }`，节点数据按 `merge.createItem` 合并（缺省目标优先、尺寸取双方最大、图标优先目标），改线路绑定、删自环 / 零长线 / 自环通道、把撞成同一条的通道合成一条，返回 `{ ok, item, linesChanged, removedLines, removedChannels, mergedChannels }`；并不了返回 `ok: false` 并另发一条失败事件，见「节点合并」 |
 | `mergeSelectedPoints(options?)` | 框选 / 多选之后一步把选中的节点并到一个目标上（接口调用）：`target` 不指定就自动挑**绑定线路最多**的那一个（一样多取画得大的、再取下标小的），来源默认是除目标之外的选中节点、也可以用 `sources`（id / 下标 / `{ id }` / `{ index }`，单个或数组）直接给 —— 这时不用先选中；`mergeable: false` 默认跳过（`force: true` 越过）、`label` 改这一步历史的标签。**多个来源合成一步历史**（数据变更收成一条 `batch`），返回 `{ phase: 'mergeSelected', ok, reason, target, merged, skipped, sourcesMerged, linesChanged, removedLines, removedChannels, mergedChannels, channelsChanged }`，见「节点合并」 |
-| `getPointMerge()` / `resolvePointMerge(confirmed?, options?)` / `confirmPointMerge(options?)` / `cancelPointMerge()` / `commitPointMerge()` / `revertPointMerge(options?)` | 读 / 裁决 / 收尾当前待确认的合并（把一个节点拖到另一个节点上之后）：`resolvePointMerge(true, { keep, item })` / `confirmPointMerge({ keep, item })` 推进到 `confirm` 阶段 —— `keep` 选保留碰撞目标（缺省）还是拖动的来源，`item` 改写最终节点的信息与样式，位置 / id 始终取保留端；`resolvePointMerge(false)` / `cancelPointMerge()` 让拖动的节点回原位。`pending` / `confirm` / `getPointMerge()` 的载荷带 `impact`（受影响线路条数、具体 lineIds 与通道读数；`lineCount` 按线路去重，`linesChanged` / `removedLines` 与落地结果同口径）。自己接管数据落地时用 `commitPointMerge()` 收状态、`revertPointMerge()` 还原（`silent: true` 不补发 cancel 载荷） |
+| `splitPoint(source, parts, options?)` | `mergePoints` 的逆操作：把一个节点拆成两份或更多（第一份接在原下标上、缺省沿用原 id，其余追加到末尾），按每份的 `item` / 顶层字段生成新节点，按 `lines` 分配线路、按 `channels` / `channelFrom` / `channelTo` 分配受影响通道的两端。没显式分配的线路跟第一份；没显式分配的通道端点跟它第一条被分配过的成员回线。线路的 `from` / `to` 与和来源坐标重合的 `start` / `end` / `path` 顶点改到对应新节点；拆完后的自环 / 零长度线路与两端落到同一份的通道删掉，成员全没了的通道也删掉。整次调用只记一条历史、只发一条 `splitPoint` 数据变更，返回的 `changes` 可直接作为后端事务输入；至少两份、坐标必须有效、线路不能重复分配，写错时 `ok: false` 并在 `reason` 说明 |
+| `getPointMerge()` / `resolvePointMerge(confirmed?, options?)` / `commitPointMerge()` / `revertPointMerge(options?)` | 读 / 裁决 / 收尾当前待确认的合并（把一个节点拖到另一个节点上之后）：`resolvePointMerge(true, { keep, item })` 推进到 `confirm` 阶段 —— `keep` 选保留碰撞目标（缺省）还是拖动的来源，`item` 改写最终节点的信息与样式，位置 / id 始终取保留端；`resolvePointMerge(false)` 让拖动的节点回原位。`pending` / `confirm` / `getPointMerge()` 的载荷带 `impact`（受影响线路条数、具体 lineIds 与通道读数；`lineCount` 按线路去重，`linesChanged` / `removedLines` 与落地结果同口径）。自己接管数据落地时用 `commitPointMerge()` 收状态、`revertPointMerge()` 还原（`silent: true` 不补发 cancel 载荷） |
 | `removePoints(refs, options?)` | 移除节点（接口调用）：`'a'` / `{ index: 2 }` / 数组都收，绑在它上面的线路一并删掉、声明了它当端点的整条通道（含成员回线）跟着删，返回 `{ ok, indexes, items, removedLines, removedChannels }` |
 | `requestRemove(options?)` | 发起一次删除（Delete 键同一条路）：把选中的拐点 / 线路 / 节点与它们的连带影响摊成一份载荷交给 `onRemove` / `'remove'`，停在 `pending` 等裁决（确认方式见 `remove.confirm`），没有可删的东西时返回 `{ phase: 'empty', ok: false, reason }`，见「删除（remove）」 |
 | `getRemoveRequest()` | 当前待确认的删除请求（没有就返回 `null`）：面板自己弹确认框时拿它渲染 |
@@ -96,15 +94,12 @@
 
 | `exportImage(options?)` | 导出当前画面（含标签）为图片，返回 data URL，见「导出图片」 |
 | `exportSelection(options?)` | 把选中的节点（可选带上两端都在集合里的线路）单独导成图片 / 数据：`points` 不给就用选中集，`withLines` / `format` / `padding` 见「导出选中的节点」；返回 `{ ok, reason, points, lines, counts, box, pointIndexes, lineIndexes, image }`，出图时临时藏起别的要素与相机、出完还原 |
-| `exportSelectionData(options?)` | 同一批选中换成**业务表口径**分项导出：选中口径与 `exportSelection` 一致，出的却是 `points` / `channels` / `lines` / `parallelGroups`（`parts` 多选，选通道 / 线路自动带上拐点）；一个节点都没解析出来时返回 `{ ok: false, reason }`，不抛异常，见「导出选中的数据（分项）」 |
-| `exportData(options?)` | 一次把数据按概念分好：`format: 'view'`（缺省）给 `{ points, lines, channels, parallelGroups }`、`'new'` 给 new.json 口径（`station_data` + `channel_data` + 四至范围那几列）、`'test'` 给 test.json 口径（`point_data` + `line_data` + `parallel_groups`）、`'input'` 给与 `createGisView` 入参同构的 `{ points, lines, channels }`（回灌口径，导出再导入即回显）；`parts` 多选分项（没要的连记录都不生成，选通道 / 线路自动带上拐点）、`points` / `lines` / `channels` 可以只要一部分，解不出的引用进 `warnings`，`format` 写错抛异常，见「导出数据」 |
-| `exportViewportData(options?)` | **视口内**的那一撮数据：范围按 `getViewRect()` 筛（节点按中心、线路按包围盒、通道按成员回线，分组一起走），其余口径与 `exportData` 完全同写；`margin` 是屏幕 CSS 像素的外扩、`rect` 直接给世界矩形，返回多带 `viewRect` / `margin` 两条读数，见「导出数据」 |
-| `exportStationData(options?)` | 节点按 new.json 的 `station_data` 口径导出（另带 `show_station_list` / `show_station_data` 与四至范围，`box: false` / `showStation: false` 可关） |
-| `exportPointData(options?)` | 节点按 test.json 的 `point_data` 口径导出（同一份数据换一套列名，带 `zone_id` / `zone_name`） |
-| `exportLineData(options?)` | 线路按 test.json 的 `line_data` 口径导出：通道回线带上 `channel_id` / `channel_name` / `parallel_group_id` 与 `index`（第几回），`coords_list` 是当下画出来的折线 |
-| `exportChannelData(options?)` | 通道按 new.json 的 `channel_data` 口径导出：一条通道一行、回线在 `line_data` 里、路由在 `coords` 里；`options.lines` 可以只要其中几条回线 |
-| `exportParallelGroups(options?)` | 拐点分组按 test.json 的 `parallel_groups` 口径导出（与通道数据分开）：缺省只出加过 / 拖过拐点的，`all: true` 连没编辑过的一起列，`channels` 可以只留某几条通道 / 分组 |
+| `exportData(options?)` | **统一导出入口**：`scope` 选范围（`'all'` 缺省 / `'viewport'` / `'selection'`，也认 `visible` / `view` / `selected`），`parts` 选分项，`format` 选口径。`format: 'view'`（缺省）给 `{ points, lines, channels, parallelGroups }`、`'new'` 给 new.json 口径、`'test'` 给 test.json 口径、`'input'` 给与 `createGisView` 入参同构的回灌口径、`'full'` 给标准文档；`format` 也可以是注册过的自定义名字。`points` / `lines` / `channels` 可以只要一部分，解不出的引用进 `warnings`，`format` 写错（或没注册）抛异常，见「导出数据」与「自定义导出格式」 |
 | `snapshotScene(options?)` | 当前画面的矢量快照（屏幕坐标的线 / 点 / 标签 / 背景 / 网格）：`{ width, height, background, backgroundImage, grid, regions, lines, points, backgroundPoints, decorations, waypoints, raised, labels }`，`options.background: false` 丢背景、`options.backgroundColor` 只换底色、`options.labels` 原样带进去，见「导出图片」 |
+| `addGraphic(graphic)` / `addGraphics(list)` | 新增扩展图形（SVG 路径 / 图片 / Canvas）：世界坐标锚点、屏幕像素尺寸、可选 `scaleWithView`；`id` 已存在时按更新覆盖，返回归一化后的图形读数（批量返回数组）。只动图形层 DOM，不重排场景，见「扩展图形（graphic）」 |
+| `updateGraphic(id, patch)` | 改一个扩展图形的字段（写法与创建一致，`style.width` / `style.height` 也认），返回改后的读数；id 不存在返回 `null` |
+| `removeGraphic(id)` / `clearGraphics()` | 按 id 删一条 / 清空整层，分别返回删掉的读数与清掉的条数；节点 / 线路 / 标签 / 数据 / 历史都不受影响 |
+| `getGraphic(id)` / `getGraphics()` | 读一条（副本，没有时 `null`）/ 读全部（按 `zIndex`、再按加入顺序） |
 | `isLayoutReady()` | 大数据发散渲染（`progressiveInit`）是否已经铺完；没铺完时标签与拾取只看得到已经画出去的那部分 |
 | `addWaypoint(lineId, coordinate)` / `removeWaypoint(lineId, pathIndex)` | 在线路上增删拐点，等价于 Ctrl + 点击与 Delete |
 | `addWaypoints(lineId, coordinates, options?)` | 一次给一条线路插多个拐点：按数组顺序插入，多个拐点合成**一步历史**；坐标写错的条目跳过，返回 `{ ok, reason, count, lineId, lineIndex, coordinates }`（`coordinates` 是实际插入成功的坐标），线路不存在或 `waypointEditable: false` 时 `ok: false` |
@@ -124,40 +119,44 @@
 | `addChannelGroupWaypoint(channelId, groupId?, coordinate?)` | 给某个分组加拐点、把这一组单独拉走：不给坐标就按默认位置放一个（第 n 组沿法线往外让 n 档），其余分组一根拐点都不动，见「分组拐点」 |
 | `removeChannelGroupWaypoint(channelId, groupId?, pathIndex?)` | 删掉某个分组的拐点（缺省删最后一个） |
 | `runChannelAction(actionId, options?)` | 执行右键交互框里的动作：`select-group` / `deselect-group` / `add-waypoint` / `remove-waypoint` / `split` / `merge`（`options` 带 `channelId` / `groupId` / `coordinate` / `pathIndex` / `size`），返回执行之后的上下文 |
-| `beginAddChannel(options?)` | 进入「新增通道」：点第一个节点当起点，一条线跟随光标，点第二个节点出方案；`options` 支持 `kind`（`'channel'` 新建通道 / `'line'` 新建独立线路，缺省 `'channel'`）/ `circuits`（一次加几条，缺省 1）/ `autoCommit` / `continuous` / `chain` / `name` / `lineId` / `lineProps` / `lineItems`（第二段，连同线路一起新建）/ `channelProps` / `handoff`（交接模式：ready 发完收起草稿，自己调 `addChannel` 落地）/ `select`（点中的节点顺手选中），见「新增通道」 |
+| `beginAddChannel(options?)` | 进入「新增通道」：点第一个节点当起点，一条线跟随光标，点第二个节点出方案；`options` 支持 `kind`（`'channel'` 新建通道 / `'line'` 新建独立线路，缺省 `'channel'`）/ `circuits`（一次加几条，缺省 1）/ `autoCommit` / `continuous` / `chain` / `name` / `lineId` / `lineProps` / `lineItems`（第二段，连同线路一起新建）/ `routing`（`'straight'` / `'orthogonal'`）/ `path`（中间拐点）/ `channelProps` / `channelDraftStyle`（本次草稿的预览样式）/ `handoff`（交接模式：ready 发完收起草稿，自己调 `addChannel` 落地）/ `select`（点中的节点顺手选中），见「新增通道」 |
 | `getAddChannelDraft()` | 当前新增通道草稿（两个节点的信息与可选方案），没有草稿时为 `null` |
+| `updateAddChannelStyle(patch?)` | 字段级合并当前草稿的预览样式（`color` / `width` / `dot` / `dotColor` / `arrow` / `arrowSize` / `arrowPositions` / `arrowReverse` / `arrowColor` / `circuitSpacing` / `opacity` / `customDraw`）；传 `null` 回到全局 `channelDraftStyle`，没有草稿时什么也不做 |
 | `continueAddChannel(options?)` | 开下一段草稿：连续模式落地时内部自动调（发 `phase: 'restart'`），也可以手动调；草稿已经退出时按 `options` 重新进来 |
 | `cancelAddChannel()` | 取消新增通道（草稿期间按 Esc 等价，会补一条 `phase: 'cancel'`） |
 | `endAddChannel()` | 结束新增通道：静默收掉视图上的示例假通道 / 线路（不补 `cancel` 事件），数据一个字节都不改 —— 结束事件里决定「不新建了」就用它 |
-| `commitAddChannel(resolution?, options?)` | 把草稿按方案落到数据上：`resolution` 缺省用草稿里的推荐方案 |
+| `commitAddChannel(resolution?, options?)` | 把草稿按方案落到数据上：`resolution` 缺省用草稿里的推荐方案 |；草稿里的 `routing` / `path` 会一起交给落地
 | `getChannelAddOptions(from, to, count?, kind?)` | 两个节点之间的新增方案：新通道 / 新分组 / 并进某一组 / 无法添加；`count` 是这一次要加的回数（余量按它判），`kind: 'line'` 时方案表为空（独立线路不挑方案） |
 | `getChannelBetween(from, to)` | 两个节点之间的通道读数（只读）：有通道时 `hasChannel: true`，`channelId` / `channelIndex` / `groupCount` / `currentGroupId` 与 `groups` / `group` / `channel`（id / name / lineIds / 分组明细）都给全；没有通道时 `hasChannel: false`、`channel: null`、`groups: []`，端点认不出来返回 `null` —— 与 `getChannelAddOptions` 的读数同一份，界面做「这两个点之间已经有通道 / 有几组」的判断用它，不必算方案表 |
 | `addChannel(spec, lineData?, group?)` | 程序化新增通道（新签名，只新建）：第一段通道信息（`from` / `to` / `name` / `id` / `path` 等通道字段），第二段线路数组 line_data —— 一条或一批（字符串 / 数字按 id 认），**按每项 id 建 `lineIds`**，第三段可选分组信息（`{ id?, lineIds?, path? }`，单个 / 一组一个）—— **第二段 / 第三段显式给了**才走这条新路；两个节点之间已经有通道时整条失败（`reason` 指路下面两条）。旧写法 `addChannel(input, lineItems?)`（带 `circuits` / `resolution` / `channelId` / `groupId` / `groupIndex` / `kind`，或只写 `{ from, to }`）照样认：按方案表新建或并进已有通道，第二段 `lineItems` 给了几条就建几条 |
 | `addChannelGroupLines(channelId, lineData, groupInfo?)` | 给已有通道**新加一组**回线（原 `addChannel` 的 `newGroup` 那一支）：第二段线路数组 line_data 按每项 id 建回线，`groupInfo`（`{ id?, path? }`）给新分组的 id 与中间拐点，缺省 `${通道 id}::N`、不带拐点；通道 / 线路认不出来时 `ok: false` + `reason` |
 | `addChannelGroups(channelId, groups, options?)` | 给已有通道**一次新加多组**回线：`groups` 每项 `{ id?, path?, lineData \| lines \| lineItems }`，线路数据与 `addChannel` 第二段同一份写法；逐组落地但**只记一步历史、只发一条** `addChannelGroups` 数据变更，返回 `{ ok, reason, count, results, lineIds, groupIds, groups }`，`options.emit: false` 只落地不通知 |
 | `joinChannelGroupLines(channelId, groupId, lineData)` | 把新回线**并进已有通道的某一组**（原 `addChannel` 的 `joinGroup` 那一支）：第二段线路数组 line_data，`groupId` 认分组 id 也认序号（从 0 起、按声明顺序），不传就挑第一个还有余量的分组 |
-| `addChannels(input, options?)` | `addChannel` 的批量版：一次新增多条通道 / 独立线路（每条是新签名或旧写法，逐条各自认），逐条落地但**只重排一次场景、只记一步历史、只发一条** `addChannels` 数据变更；返回 `{ ok, count, results, lineIds, channelIds, items }`，失败条目在各自的 `reason` 里说明原因、不影响其余条目，`options.emit: false` 时不发 `onDataChange`，见「动态换数据与加载完成」 |
-| `addLine(input, lineItems?)` | 程序化新增独立线路：等价于 `addChannel({ ...input, kind: 'line' })`，只往 `lines` 里加、不碰任何通道（`resolution: 'newLine'` 也认）；第二段 `lineItems` 同样认 |
+| `addChannels(input, options?)` | `addChannel` 的批量版：一次新增多条通道 / 独立线路（每条是新签名或旧写法，逐条各自认；每项的 `routing` / `path` 走同一套解析，`path` 是中间拐点），逐条落地但**只重排一次场景、只记一步历史、只发一条** `addChannels` 数据变更；返回 `{ ok, count, results, lineIds, channelIds, items }`，失败条目在各自的 `reason` 里说明原因、不影响其余条目，`options.emit: false` 时不发 `onDataChange`，见「动态换数据与加载完成」 |
+| `addLine(input, lineItems?)` | 程序化新增独立线路：等价于 `addChannel({ ...input, kind: 'line' })`，只往 `lines` 里加、不碰任何通道（`resolution: 'newLine'` 也认）；第二段 `lineItems` 同样认 |；`routing: 'orthogonal'` 自动正交折线，`path` 是中间拐点，落地成含两端的完整折线
 | `addPoint(item, options?)` / `addPoints(items, options?)` / `addLines(items, options?)` | 把**现成的数据对象**追加到末尾（批量导入、从别处拷过来、按坐标补几条）：老数据一条不动，返回 `{ ok, count, indexes, items }`（`addPoint` 另有单条的 `index` / `item`），`options.emit: false` 时不发 `onDataChange`；与 `addChannel` / `addLine` 的分工是后者走「通道 / 草稿」那一套 |
 | `removeLine(lineId)` | 移除一条线路（撤销刚落地的新增线路）：挂在通道上的回线会从通道声明里一起摘掉，通道空了整条删掉，返回 `{ ok, line, lineId, index, channelId, removedChannel }` |
 | `removeLines(lineIds)` | 一次移除多条线路（传数组或单条 id）：通道声明与分组跟着收拾、删空的通道整条走，返回 `{ ok, lineIds, indexes, lines, entries, removedChannels }` |
 | `removeChannel(channelId)` | 移除整条通道：它名下的回线一条条摘掉，返回 `{ ok, channelId, lineIds, lines, removedChannel }` |
-| `updatePoint(id, patch)` / `updateLine(id, patch)` / `updateChannel(id, patch)` | 定向更新一个节点 / 线路 / 通道并重渲染：只重排受影响的那一小片（节点 → 绑定线与锚定通道（尺寸 / 图标换过时，锚定通道的宽度一起按新尺寸重排，见「通道与多回线」），线路 → 这一条，通道 → 它的分组与成员），其余要素与缓存一个字节都不动；节点的 `visible: false` / 改回来会走一次整份重排（这一条要连绑定线、锚定通道与拾取索引一起退场 / 排回去，定向更新那条路落不下；同一个 `batch()` 里改一批只重排一次）；`updateLine` 的补丁里还能写 `groupId` / `groupIndex`（可配 `channelId`）顺带把这条回线挪到目标分组，`updateChannel` 写 `groups` / `lineIds` 会顺带改分组并补一条 `channelGroups` 变更（见「通道分组」）；`updateChannel` 还能给第三段 `linePatches`（一条或一批 `{ id \| index, ...字段 }`）把「通道声明 + 成员回线各自的字段 / 分组」一次下发 —— 声明先落、再逐条走 `updateLine`，整次调用只发一条 `batch` 数据变更、历史里只算一步（见「通道分组」与「逐方法示例」）；第三段里认不出的成员 id 带得起定义（`from` / `to` 两端可解析、可用的 `path`、或通道自己声明了两端）会当场建一条回线并挂进通道，给不出定义才跳过点名；`updateLine` 的**拐点**写在 `path` 上（整条折线，含首尾端点 —— 只写中间拐点用 `setLineWaypoints(id, coordinates)`），通道里的回线几何由通道骨架推导（`path` 写了也会被覆盖），改它走 `setLineWaypoints` / `setChannelPath` |
+| `updatePoint(id, patch)` / `updateLine(id, patch)` / `updateChannel(id, patch)` | 定向更新一个节点 / 线路 / 通道并重渲染：单项字段（尺寸、图标、颜色、线宽、通道宽度 / 名称等）直接写补丁；只重排受影响的那一小片（节点 → 绑定线与锚定通道（尺寸 / 图标换过时，锚定通道的宽度一起按新尺寸重排，见「通道与多回线」），线路 → 这一条，通道 → 它的分组与成员），其余要素与缓存一个字节都不动；节点的 `visible: false` / 改回来会走一次整份重排（这一条要连绑定线、锚定通道与拾取索引一起退场 / 排回去，定向更新那条路落不下；同一个 `batch()` 里改一批只重排一次）；`updateLine` 的补丁里还能写 `groupId` / `groupIndex`（可配 `channelId`）顺带把这条回线挪到目标分组，`updateChannel` 写 `groups` / `lineIds` 会顺带改分组并补一条 `channelGroups` 变更（见「通道分组」）；`updateChannel` 还能给第三段 `linePatches`（一条或一批 `{ id \| index, ...字段 }`）把「通道声明 + 成员回线各自的字段 / 分组」一次下发 —— 声明先落、再逐条走 `updateLine`，整次调用只发一条 `batch` 数据变更、历史里只算一步（见「通道分组」与「逐方法示例」）；第三段里认不出的成员 id 带得起定义（`from` / `to` 两端可解析、可用的 `path`、或通道自己声明了两端）会当场建一条回线并挂进通道，给不出定义才跳过点名；`updateLine` 的**拐点**写在 `path` 上（整条折线，含首尾端点 —— 只写中间拐点用 `setLineWaypoints(id, coordinates)`），通道里的回线几何由通道骨架推导（`path` 写了也会被覆盖），改它走 `setLineWaypoints` / `setChannelPath` |
 
-| `setPointSize(id, size)` / `setPointSymbol(id, symbol)` / `setPointColor(id, color)` | 细粒度只改一样：节点的屏幕大小（CSS 像素，再乘 `pointSizeScale` 与缩放档位）/ 图标（内置形状、图片、自定义 SVG；传 `null` 清掉逐点符号回落到规则与 `pointStyle`）/ 填充色。滑块、调色板、图标下拉这类控件一个方法接一个，不必自己拼 patch |
+| `setFeatureVisible(kind, refs, visible)` / `hideFeatures(kind, refs)` / `showFeatures(kind, refs)` | 统一隐藏 / 显示节点、线路或通道：只改数据里的 `visible`，不删要素，分组 / 拐点 / 编辑状态都保留。`kind` 收 `point` / `line` / `channel`，`refs` 收单个或一批 id / 下标 / `{ id }` / `{ index }`，也认 `'selection'`（通道按选中回线的归属取整条）；`hideFeatures` / `showFeatures` 是 `false` / `true` 的快捷写法。整次调用收成一条历史与一条 `batch` 数据变更，返回 `{ ok, reason, kind, visible, indexes, ids, items, skipped }`；认不出的引用逐条进 `skipped`，不影响其余条目 |
 | `movePoint(id, coordinate)` / `movePoint(id, x, y)` | 挪一个节点：`{ x, y }` / `[x, y]` / 两个数字都认；绑在它身上的线路端点与以它为锚点的通道骨架跟着重排（与拖动落地同一条路） |
-| `setLineWidth(id, width)` / `setLineColor(id, color)` | 只改一条线路的线宽 / 颜色 |
 | `setLineWaypoints(id, coordinates)` | 整份换一条线路的拐点：**只写中间拐点**（不含首尾两端；传单个坐标 = 只留一个拐点，空数组 = 拉直）。两端按节点 / `start` / `end` 补齐（绑了 `from` / `to` 时两端始终按节点坐标走），存回 `lines[].path` 的是「首尾端点 + 中间顶点」那一份；只插一个用 `addWaypoint(id, coordinate)`，删一个用 `removeWaypoint(id, pathIndex)`；通道里的回线改的是它所在分组的骨架（与 `setChannelPath` 同一份声明） |
 | `getLineDecorations(id)` / `setLineDecorations(id, list)` / `addLineDecoration(id, decoration)` / `updateLineDecoration(id, index, patch)` / `removeLineDecoration(id, index)` | 线路上标记（图片 / SVG 装饰）的读写：`get` 给副本（要素没找到给空数组），`set` 整份换（空数组 = 全摘掉），`add` 追加在末尾并返回加进去的那一条，`update` / `remove` 按 `decorations` 的顺序数（返回改动的那一条，要素或下标找不到时给 `null` 并记一条 warning）；四个写方法各只发一条数据变更、只落一步历史 |
-| `setChannelWidth(id, width)` / `setChannelNodeWidth(id, nodeWidth)` / `setChannelInset(id, inset)` / `setChannelTangentInset(id, value)` | 只改一条通道的某一项：世界单位的宽度 / 「按两端节点尺寸取宽」的系数（`0` 关掉自动取宽）/ 内收（占通道宽度，负数外收，`null` 回默认）/ 两端切点内收（CSS 像素，`null` 按回线线宽收）。**通道默认按节点尺寸取宽**：`nodeWidth > 0` 且两端锚定时 `setChannelWidth` 不生效，先 `setChannelNodeWidth(id, 0)` |
-| `setChannelName(id, name)` | 只改一条通道的名称：悬停提示 / 标签模板的 `{name}`、搜索与自建面板的通道读数都取它（传 `null` 摘掉名称），一次一条 `updateChannel` 数据变更、一步历史 |
-| `setChannelLineWidth(id, width)` / `setChannelColors(id, colors)` / `setChannelPath(id, coordinates)` | 只改一条通道的回线线宽 / 逐回线颜色 / 骨架拐点：前两个把**成员回线连同通道声明**一起改（一次 `batch`，只发一条数据变更、只落一步历史），颜色不够时按顺序循环取、只给一个就整条通道一个色（改**单条回线**的颜色用 `setLineColor(lineId, color)` / `updateLine(id, { color })`，不必走整条通道的批量写法）；`colors` 传字符串或字符串数组，`setChannelPath` 只写中间拐点（两端由节点坐标补齐）；分过组的通道写第一组的声明（`groups[].path` 优先于顶层 `path`；「第一组」跳过 `lineIds` 空的分组声明 —— 引擎会把这种组整组丢掉），要改别的组用 `updateChannel(id, { groups })` |
+| `getPointDecorations(id)` / `setPointDecorations(id, list)` / `addPointDecoration(id, decoration)` / `updatePointDecoration(id, index, patch)` / `removePointDecoration(id, index)` | 节点上标记（图片 / SVG 装饰）的读写：`get` 给副本（节点没找到给空数组），`set` 整份换（空数组 = 全摘掉），`add` 追加在末尾并返回加进去的那一条，`update` / `remove` 按 `points[].decorations` 的顺序数（返回改动的那一条，节点或下标找不到时给 `null`）；四个写方法各只发一条数据变更、只落一步历史。节点装饰可写屏幕像素偏移（`offset` 或 `distance` + `direction`）、固定世界坐标（`anchor: 'fixed'` / `at`），并可用 `connector` 从节点中心画连接线 |
+| `beginDecorationDraft(options?)` / `getDecorationDraft()` / `updateDecorationDraft(patch?)` / `commitDecorationDraft(overrides?)` / `cancelDecorationDraft(options?)` | 动态装饰器草稿：`target` 取 `'line'`（缺省）/ `'point'` / `'both'`，指针移到线路 / 回线或节点上就画临时装饰，移出立即收掉；`both` 按屏幕距离取更近者、等距优先节点，最近目标被白名单或上限拦住时尝试另一类。线路按 `scope`（`line` 单条 / `group` 同组 / `channel` 整条通道，非通道线退回单条）展开；节点侧 `placement` 只选位置来源（`offset` 相对偏移 / `fixed` 固定坐标 / `pointer` 鼠标位置），`anchor` 再选落地关系（`follow` 保存相对节点的屏幕偏移 / `fixed` 保存世界坐标），两者可自由组合，缺省按 `offset → follow`、`fixed / pointer → fixed` 推导。`allowedLines` / `allowedChannels` / `allowedGroups` / `allowedPoints` 与 `maxPerLine` / `maxPerPoint` 在悬浮与提交两处拦截，`allowDuplicate: false` 时按 `duplicateDistance` 检测同位置重复，`duplicateStrategy` 选 `offset` 自动避让或 `reject` 直接拦住。左键在目标上松开发 `ready`，空白处不发；`get` 取当前载荷，`update` 边交互边改图标 / 大小 / 方向 / 范围 / 位置来源 / 落地关系；`commit` 把线路与节点目标放在同一个 `batch` 里写入（一次 `dataChange`、一条历史），`cancel` 只清假装饰（Esc / 右键等价），数据与历史一个字节不动 |
+| `setChannelLineWidth(id, width)` / `setChannelColors(id, colors)` / `setChannelPath(id, coordinates)` | 只改一条通道的回线线宽 / 逐回线颜色 / 骨架拐点：前两个把**成员回线连同通道声明**一起改（一次 `batch`，只发一条数据变更、只落一步历史），颜色不够时按顺序循环取、只给一个就整条通道一个色（改**单条回线**的颜色用 `updateLine(id, { color })`，不必走整条通道的批量写法）；`colors` 传字符串或字符串数组，`setChannelPath` 只写中间拐点（两端由节点坐标补齐）；分过组的通道写第一组的声明（`groups[].path` 优先于顶层 `path`；「第一组」跳过 `lineIds` 空的分组声明 —— 引擎会把这种组整组丢掉），要改别的组用 `updateChannel(id, { groups })` |
 | `getParallelGroups()` | 新增拐点集合：被加过 / 拖过拐点的通道与线路，结构与 `test.json` 的 `parallel_groups` 一致 |
-| `setFilter(filter \| null)` / `clearFilter()` | 设置 / 清空筛选条件：完整格式 `{ points, lines, cascade, worker }`，只筛节点时可以简写成节点条件本身；见「筛选」 |
+| `setFilter(filter \| null)` | 设置或清空筛选条件（传 `null` 清空）：完整格式 `{ points, lines, cascade, worker }`，只筛节点时可以简写成节点条件本身；见「筛选」 |
 | `getFilter()` / `getFilterResult()` | 当前条件与最近一次结果：隐藏的点 / 线下标、可见数量、是否用了 Worker、耗时 |
 | `getVisibleData()` | 过滤之后的数据副本（`points` / `lines`） |
 | `getMovedPoints()` | 位置对账：相对上次对账（建视图 / 整份换数据 / 上一次 `clearMovedPoints`）位置变过的节点，按 id 去重、一趟扫出 `[{ index, id, x, y, item }]` —— 拖动 / `updatePoint` / `patchPoints` / 撤销都算，`removePoints` 删掉的记录顺手清掉，见「节点位置对账」 |
 | `clearMovedPoints(refs?)` | 位置对账：把当前坐标记成新基准（发完接口告诉组件「这些已经同步过了」）：不传 / `null` 全部对账，传一个或一批（写法与 `removePoints` 一致）只清这些，认不出来的跳过并记一条提醒；返回实例本身 |
+| `getChangedChannels(options?)` | 通道变化对账：相对上次对账（建视图 / 整份换通道声明 / 上一次 `clearChangedChannels`）成员、分组、拐点、端点、可见性或其余声明字段变过的通道。每项带当前 `groups` 快照、六个 `*Changed` 标记、`fields` 与 `reasons`；新加通道只补账不报变化，删掉的通道（含 `removeLines` 连带删除）从账本清掉。`options.reasons` 只取指定原因（空数组直接返回空表），`options.ignoreGroups` 忽略分组新增 / 删除 / 重排、仍报已有分组的拐点变化。节点拖动只改坐标、不改 `from` / `to`，因此不算端点变化；拖 / 加 / 删分组拐点会进 `waypoints`，见「通道变化对账」 |
+| `clearChangedChannels(refs?)` | 通道变化对账：把当前声明记成新基准（发完接口告诉组件「这些已经同步过了」）：不传 / `null` 全部对账，传一个或一批（写法与 `removePoints` 一致）只清这些，认不出来的跳过并记一条提醒；返回实例本身 |
+| `getChangedLines(options?)` | 线路变化对账：相对上次对账（建视图 / 整份换线路 / 上一次 `clearChangedLines`）`path` / `start` / `end`、`from` / `to`、可见性或其余声明字段变过的线路。每项带 `{ index, id, item, path, start, end, from, to, visible, pathChanged, endpointsChanged, visibilityChanged, fieldsChanged, fields, reasons }`；`options.reasons` 可写 `path` / `endpoints` / `visibility` / `fields`。新加线路只补账不报，删除线路（含 `removeChannel` 连带删除）同步清账；通道骨架变化不算线路变化，见「线路变化对账」 |
+| `clearChangedLines(refs?)` | 线路变化对账：不传 / `null` 全部对账，传一个或一批（写法与 `removePoints` 一致）只清这些，空数组无操作；认不出来的跳过并记一条提醒，返回实例本身 |
 | `isPointVisible(index)` | 某个下标的节点当前在不在图上：被筛选 / `visible: false` 隐藏掉的不算，初始化发散渲染还没排到的那部分也不算 |
 | `resize()` / `refresh(options?)` | 手动同步尺寸 / 重新应用配置并重绘（`refresh({ reflow: false })` 只重画一帧，不重解析数据与配置）；容器尺寸或祖先的 `transform: scale` 变过之后要调一次 `resize()` 同步（CSS `zoom` 会自己感知） |
 | `destroy()` | 销毁引擎并移除根节点 |
@@ -177,16 +176,19 @@
 | `clearHistory()` | 清空历史（撤销与重做两份栈一起），返回清掉的条数 |
 | `batch(fn, options?)` | 批量更新：回调里对 `updatePoint` / `updateLine` / `updateData` 的连续改动收成一条 `onDataChange`（`type: 'batch'`，`changes` 按调用顺序列出每一步）与一步历史，`options.label` 给这一步起名；收尾时筛选只重算一次、标签重排 / 提示框 / 鹰眼图各补一次（`onFilter` 也只发一条），可以嵌套（只有最外层收尾），见「批量更新」 |
 | `getQuality()` / `setQuality(next)` | 读当前画质读数 `{ mode, name, level, glow, ornament, scale, budgetMs, frameMs }` / 换一档（`'high'` / `'balanced'` / `'lean'` / `'fast'` / `'auto'` 或 `{ mode, budgetMs, minScale }`），换完发一条 `onQualityChange`，见「画质」 |
-| `setEffects(next)` / `getEffects()` | 换 / 读动画效果的全局配置（`false` 就是一处关掉）：`getEffects()` 给 `{ enabled, respectReducedMotion, line, point }`，其中 `enabled` 是**运行时口径**（只在数据里逐条配了 `effect` 时也是 `true`），见「动画效果（effects）」 |
+| `updateOptions({ effects })` / `getEffects()` | 换 / 读动画效果的全局配置（`effects: false` 就是一处关掉）：`getEffects()` 给 `{ enabled, respectReducedMotion, line, point }`，其中 `enabled` 是**运行时口径**（只在数据里逐条配了 `effect` 时也是 `true`），见「动画效果（effects）」 |
 | `getLineEffects()` | 这一帧动点的读数 `{ lineIndex, slot, x, y, angle, total, size }`（世界坐标 + 朝向 + 所在线路 + 沿线总长）：自建覆盖层（跟着图标走的标签 / 提示）与读数面板用它，没动的时候是空表 |
 | `getPointEffects()` | 这一帧涟漪的读数 `{ index, x, y, color, radius, count, period, from }`（世界坐标 + 颜色 + 圈数 + 周期）：自建覆盖层与自测用它；拖动就地挪过圈之后读到的就是挪完的位置，没配涟漪那些节点不在表里 |
 | `getPrebake()` / `runPrebake()` | 预热读数（这次配了哪些符号 / 颜色 / 尺寸 / 逐组合，没配是 `null`）/ 按当前配置再烤一遍并返回组合条数，见「贴图符号预热（prebake）」 |
 | `getSymbolCombos()` | 收出这份数据真正会用到的贴图组合 `{ combos, symbols, pointColors, sizes, lineColors }`：喂给 `prebake.combos` 就是不重不漏的一份（一条一张、逐条命中），见「贴图符号预热（prebake）」 |
 | `el` / `canvas` / `gl` | 根节点、画布元素与 WebGL2 上下文 |
+| `requestRender()` | 请求重画一帧：WebGL 自定义层的数据源变了、组件自己不知道时调用；返回实例本身 |
+| `addWebGLLayer(layer)` | 加一个 WebGL 自定义层（同 id 覆盖），返回卸载函数；`draw` 拿 `gl` / `canvas` / `viewport` / `camera` / `frame` / `project` / `unproject` / `requestRender`，在内置内容之后绘制 |
+| `updateWebGLLayer(id, patch)` / `removeWebGLLayer(id)` / `clearWebGLLayers()` / `getWebGLLayers()` | 改 / 删 / 清空 / 读自定义层；`order` 小的先画，同 `order` 保持加入顺序，`enabled: false` 跳过，层不参与拾取与导出 |
 
 返回 `this` 的方法都可以链式调用；返回其它值的方法（`get*` / `list*` / `export*` / `search` / `pick*` / `add*` / `remove*` / `copy*` / `merge*` / `locate*` 这些）在下面的「参数速查」里都标了返回类型。
 
-**怎么确认「组件到底有哪些属性和方法」**：上面那张表按功能分组介绍，下面的「参数速查」把实例的**每个成员逐个列全**（当前 233 个：230 个方法 + `el` / `canvas` / `gl` 三个属性），`options` 表列全 85 个键，数据字段表列全 229 个字段。这三份清单不靠手抄 —— 它们直接对着源码与类型对账：
+**怎么确认「组件到底有哪些属性和方法」**：上面那张表按功能分组介绍，下面的「参数速查」把实例的**每个成员逐个列全**（当前 249 个：246 个方法 + `el` / `canvas` / `gl` 三个属性），`options` 表列全 91 个键，数据字段表列全 242 个字段。这三份清单不靠手抄 —— 它们直接对着源码与类型对账：
 
 - `node docs/steps/gen-api-index.mjs`：从 `create.js` 的实例定义、本文档的两张表与 `types.d.ts` 生成 `docs/demos/api-index.js`（`API_SUMMARY` / `API_SECTIONS` / `API_OPTIONS`），demo 的「实例 API」面板读的就是它；带 `--check` 时只校验有没有过期。
 - `node docs/steps/check-doc-coverage.mjs`：10 项双向对账 —— 实例成员 × 文档 / × 参数速查 / × 类型、参数速查与实例方法主表各自反查过期条目、类型反查过期声明、数据字段 × 文档、options 键 × 文档 / options 表反查过期字段、demo 清单是否最新。加一个实例成员、改一个 options 键而没同步文档时，这个脚本会直接报出来。

package/docs/manual/17-/345/217/202/346/225/260/351/200/237/346/237/245.md

@@ -1,6 +1,6 @@
 # 17 参数速查（逐个方法）
 
-> 243 个成员逐个列全：参数、默认值与返回。
+> 241 个成员逐个列全：参数、默认值与返回。
 
 ### 参数速查（逐个方法）
 
@@ -17,10 +17,7 @@
 | `updateLineStyle(patch)` | `patch: GisViewLineStyle \| null` 线的一份，口径与 `updatePointStyle` 完全一致 | `this` |
 | `getOptions()` | 无 | `GisViewOptions` |
 | `getData()` | 无 | `GisViewData` |
-| `updateData(points, lines, channels?)` | 整份换数据：`points?: GisViewPoint[]` 新的节点数组（不传就不动）；`lines?: GisViewLine[]` 新的线路数组（不传就不动）；`channels?: GisViewChannel[]` 给了就连通道声明一起换（切场景一次换完、只发一条 `dataChange`；声明过调和，与 `updateChannels` 同一份口径）。也收单对象写法 `updateData({ points, lines, channels })`（只换给出的那几列）；接口字段先在调用方映射成这三列，见「动态换数据与加载完成」 | `this` |
-| `updateChannels(channels)` | `channels?: GisViewChannel[]` 通道声明的替换值（回线怎么分组、骨架拐点在哪）；省略等于清空。场站与回线数据一个都不动，引擎按新声明重排一遍。与 `updateChannel(id, patch)` 的分工：那一条按 id 给某一条打补丁（定向），这一条是全换；声明里的 `lineIds` 同样是成员整表 —— 与 `groups` 冲突时按它收窄（与 `updateChannel` 的补丁同一份口径）；声明里没写分组 id 时引擎按「单组用通道 id、多组 `通道id::1` / `通道id::2`…」补，并把最终分组（含拐点路径）与对齐后的成员表写回数据副本；认不出的成员 id、重名的分组 id（写回前按调用方的声明查）各报一句 `onWarning` | `this` |
-| `updatePoints(points)` | `points: GisViewPoint[]` 整份节点的替换值（省略等于清空） | `this` |
-| `updateLines(lines)` | `lines: GisViewLine[]` 整份线路的替换值（省略等于清空） | `this` |
+| `updateData(points, lines, channels?)` | 整份换数据：`points?: GisViewPoint[]` 新的节点数组（不传就不动）；`lines?: GisViewLine[]` 新的线路数组（不传就不动）；`channels?: GisViewChannel[]` 给了就连通道声明一起换（切场景一次换完、只发一条 `dataChange`）。也收单对象写法 `updateData({ points, lines, channels })`（只换给出的那几列；只换通道声明写 `updateData({ channels })`）；接口字段先在调用方映射成这三列，见「动态换数据与加载完成」 | `this` |
 | `importData(input, options = {})` | `input: GisViewDocumentInput`：标准文档（`format: 'gis-view'`）/ 与创建入参同构的数据对象（`points` / `lines` / `channels` / `labelStates` / `view` / `filter`，给哪列出哪列）/ 节点数组；`options` 可以把某一列（`points` / `lines` / `channels` / `labelStates` / `view` / `filter`）显式点上，`checkKeys: false` 不点名多余的顶层键 | `GisViewImportResult` |
 | `updatePoint(id, patch)` | `id: string \| number` 节点 id；`patch: Partial<GisViewPoint>` 要合并的字段（写 `x` / `y` 就是移动，写 `null` 摘掉这一项；写 `visible: false` 把这一条从图上收起、写 `visible: true` 排回来 —— 这一条要连绑定线 / 锚定通道一起重排，因此走整份重推一次，`batch()` 里一批只推一次） | `this` |
 | `updateLine(id, patch)` | `id` 线路 id；`patch: GisViewLinePatch` 要合并的字段（`path` / `from` / `to` / `color` / `width` / `labels`… 都能改），还能写三个「分组指令」：`groupId`（或 `groupIndex`，可配 `channelId`）把这条回线挪到目标分组 —— `groupId: 'newGroup'` 单独拆一组、其余按现有分组 id 并组，走的是 `moveChannelLine` 那一套；三个字段只是指令，不会写进线路数据、不会出现在 `updateLine` 的载荷里，挪组成功会先发一条 `channelGroups` 变更（只给指令时这次调用就只发它）；**拐点**写在 `path` 上（整条折线，含首尾端点 —— 只写中间拐点用 `setLineWaypoints(id, 中间拐点)`），通道里的回线几何由通道骨架推导（`path` 写了也会被覆盖，改它走 `setLineWaypoints` / `setChannelPath`） | `this` |
@@ -69,7 +66,6 @@
 | `getQuality()` | 无 | `GisViewQualityState` |
 | `setQuality(next)` | `next: GisViewQualityOptions` 新档位：`'high'` / `'balanced'` / `'lean'` / `'fast'` / `'auto'`，或 `{ mode, budgetMs, minScale }` | `GisViewQualityState` |
 | `getEffects()` | 无 | `GisViewEffectsReadout`：`{ enabled, respectReducedMotion, line, point }`，`enabled` 是**运行时口径**（数据里逐条配了 `effect` 时也是 `true`） |
-| `setEffects(next)` | `next: GisViewEffectsInput` 与 `options.effects` 同一套写法（`false` = 一处关掉） | `this` |
 | `getLineEffects()` | 无 | `GisViewLineEffectReadout[]`：这一帧算过位置的动点 `{ lineIndex, slot, x, y, angle, total, size }`（世界坐标 + 朝向），没动的时候是空表 |
 | `getPointEffects()` | 无 | `GisViewPointEffectReadout[]`：这一帧涟漪的读数 `{ index, x, y, color, radius, count, period, from }`（世界坐标 + 颜色 + 圈数 + 周期），没配涟漪时是空表 |
 | `getPrebake()` | 无 | `GisViewPrebakeReadout \| null`：这次配了哪些符号 / 颜色 / 尺寸 / 逐组合 |
@@ -103,9 +99,8 @@
 | `getContextAt(x, y, options?)` | `x` / `y` 画布 CSS 像素；`options?: GisViewContextAtOptions`：`selection: false` 不整理选中集、`lngLat: false` 不换算经纬度（dragover / 自绘十字线这类每帧来的场合用它省分配） | `GisViewContextAtResult`；给了选项时是 `GisViewContextAtLightResult`（没要的那几项不再生成） |
 | `nearestPointsAt(x, y, options?)` | `x` / `y` 画布 CSS 像素；`options?: GisViewNearestOptions`：`limit`（最多几个，缺省 1）、`maxDistance`（**屏幕像素**上限，缺省不限）、`withScreen: true` 补屏幕坐标 | `GisViewNearestPoint[]`，按距离从近到远：`{ index, item, x, y, radius, distance, distancePx, screen? }`；内部走点网格，十万级数据也只碰光标附近的单元格 |
 | `nearestLineAt(x, y, options?)` | `x` / `y` 画布 CSS 像素；`options?: GisViewNearestLineOptions`：`maxDistance`（**屏幕像素**，缺省 40，超出算没命中）、`editableOnly: true` 只看允许加拐点的线、`withScreen: true` 补屏幕坐标 | `GisViewNearestLine \| null`：`{ index, item, path, distance, distancePx, position, channelId?, groupId?, channelIndex?, screen? }`，`position` 是落点投到线上的沿线比例（0~1），加拐点 / 挂装饰直接当 `position` 用；附近没线返回 `null` |
-| `setDropPreview(preview)` | `preview: GisViewDropPreviewInput \| null`：`kind`（`'point'` / `'line'` / `'channel'` / `'waypoint'` / `'decoration'` / `'label'`，缺省按 `item` 推断）、`screen`（画布 CSS 像素）或 `world`（世界坐标）至少给一个、`item` 是**准备落地的那一份字段**（与 `addPoint` / `addLine` 同一份）、`from`（line / channel 的起点）；传 `null` 等价于 `clearDropPreview()` | `GisViewDropPreview \| null` 解析后的读数 `{ kind, screen, world, size, styleSize, radius, color, strokeColor, strokeWidth, opacity, symbol, width, dashed }`：走的是与真实要素完全相同的样式链（规则 -> 全局样式 -> 这一份字段），`styleSize` 与落地后 `getPointStyle().size` 是同一个数（`size` 是这一刻画出来的宽度，不悬停 / 不选中时两者相同） |
+| `setDropPreview(preview)` | `preview: GisViewDropPreviewInput \| null`：`kind`（`'point'` / `'line'` / `'channel'` / `'waypoint'` / `'decoration'` / `'label'`，缺省按 `item` 推断）、`screen`（画布 CSS 像素）或 `world`（世界坐标）至少给一个、`item` 是**准备落地的那一份字段**（与 `addPoint` / `addLine` 同一份）、`from`（line / channel 的起点）；传 `null` 清掉预览 | `GisViewDropPreview \| null` 解析后的读数 `{ kind, screen, world, size, styleSize, radius, color, strokeColor, strokeWidth, opacity, symbol, width, dashed }`：走的是与真实要素完全相同的样式链（规则 -> 全局样式 -> 这一份字段），`styleSize` 与落地后 `getPointStyle().size` 是同一个数（`size` 是这一刻画出来的宽度，不悬停 / 不选中时两者相同） |
 | `getDropPreview()` | 无 | `GisViewDropPreview \| null`：当前拖拽落点预览的读数，没有预览时 `null` |
-| `clearDropPreview()` | 无 | `this`（与 `setDropPreview(null)` 同一条路） |
 | `getPoint(ref)` | `ref: GisViewFeatureRef` 节点定位：id、下标、`{ id }` / `{ index }` | `GisViewPointInfo \| null` |
 | `getPointStyle(index)` | `index: number` 节点下标 | `GisViewPointStyleSnapshot \| null`：节点解析后的样式快照 `{ index, size, symbol, zIndex }`，`size` / `symbol` 取样式链（节点自身 > 规则 > `pointStyle`）定下来的那一份，含 `sizeScale`、不含悬停 / 选中样式与热力倍率；落点预览的读数与它同源 |
 | `getLine(ref)` | `ref` 线路定位（同上） | `GisViewLineInfo \| null` |
@@ -116,6 +111,13 @@
 | `getVisibleData()` | 无 | `GisViewData` |
 | `getMovedPoints()` | 无 | `GisViewMovedPoint[]`：相对上次对账位置变过的节点（`index` / `id` / `x` / `y` / `item`），按 id 去重；被删掉的记录不在里面（顺手清掉） |
 | `clearMovedPoints(refs?)` | `refs?: GisViewFeatureRef \| GisViewFeatureRef[]` 记成新基准的节点（id / 下标 / `{ id }` / `{ index }`，写法与 `removePoints` 一致）；不传 / `null` 全部对账，空数组无操作 | `this` |
+| `getChangedChannels(options?)` | `options?: GisViewChangedChannelOptions`：`reasons?: GisViewChangedChannelReason[]` 只返回这些原因（`[]` = 空表）；`ignoreGroups?: boolean` 忽略分组新增 / 删除 / 重排，只比较共有分组的拐点 | `GisViewChangedChannel[]`：相对上次通道对账变了哪些通道，每项给 `{ index, id, item, groups, groupsChanged, waypointsChanged, membersChanged, endpointsChanged, visibilityChanged, fieldsChanged, fields, reasons }`；筛选后 `*Changed` 标记与 `fields` 同步收窄，读本身不改基准 |
+| `clearChangedChannels(refs?)` | `refs?: GisViewFeatureRef \| GisViewFeatureRef[]` 记成新基准的通道（id / 下标 / `{ id }` / `{ index }`，写法与 `removePoints` 一致）；不传 / `null` 全部对账，空数组无操作 | `this` |
+| `getChangedLines(options?)` | `options?: GisViewChangedLineOptions`：`reasons?: GisViewChangedLineReason[]` 只返回 `path` / `endpoints` / `visibility` / `fields` 中的指定原因（`[]` = 空表） | `GisViewChangedLine[]`：相对上次线路对账变了哪些线路，每项给 `{ index, id, item, path, start, end, from, to, visible, pathChanged, endpointsChanged, visibilityChanged, fieldsChanged, fields, reasons }`；新加只补账、删除清账，读本身不改基准 |
+| `clearChangedLines(refs?)` | `refs?: GisViewFeatureRef \| GisViewFeatureRef[]` 记成新基准的线路（写法与 `removePoints` 一致）；不传 / `null` 全部对账，空数组无操作 | `this` |
+| `setFeatureVisible(kind, refs, visible)` | `kind: GisViewVisibilityKind`（`'point'` / `'line'` / `'channel'`）；`refs: GisViewVisibilityRefs` 单个 / 一批 id 或下标，也认 `'selection'`（通道按选中回线的归属取整条）；`visible: boolean` | `GisViewSetVisibilityOutcome`：`{ ok, reason, kind, visible, indexes, ids, items, skipped }`；只改数据的 `visible`，整次调用一条历史、一条 `batch` 数据变更 |
+| `hideFeatures(kind, refs)` | 同上，等价于 `setFeatureVisible(kind, refs, false)` | 同上 |
+| `showFeatures(kind, refs)` | 同上，等价于 `setFeatureVisible(kind, refs, true)`（隐藏后原样恢复） | 同上 |
 | `isPointVisible(index)` | `index: number` 节点下标 | `boolean`。在不在图上（被筛选 / `visible: false` 或发散渲染还没铺到的都算 `false`） |
 | `getElementBounds(keys)` | `keys: GisViewFeatureKey[]` 要素定位数组（`{ type, id }` / `{ type, index }` / 裸 id） | `GisViewBounds \| null` |
 | `getViewState()` | 无 | `GisViewViewState` |
@@ -124,9 +126,8 @@
 
 | 方法 | 参数（名字: 类型 = 默认值） | 返回 |
 | --- | --- | --- |
-| `select(refs, options = {})` | `refs: GisViewSelectionRefs` 要选中的东西：id / id 数组（多选）/ `{ type, index }` / 通道写法 / 拾取载荷 / 搜索命中，传 `null` / 空数组等于清空；`options?: GisViewSelectOptions` 只有 `mode`（与 `selectFeatures` 同一份） | `this` |
-| `selectFeatures(refs, options = {})` | `refs: GisViewSelectionRefs` 同上；`options?: GisViewSelectOptions` 只有 `mode`（`'replace'` 缺省 / `'add'` / `'toggle'` / `'remove'`） | `this` |
-| `deselect(refs = null)` | `refs?: GisViewSelectionRefs` 要取消的东西（写法与 `selectFeatures` 一致：节点 / 通道 / 线路 / 混合一批）；不传 / `null` 等于取消全部（= `select(null)`），空数组是「没有目标」什么都不做 | `this` |
+| `selectFeatures(refs, options = {})` | `refs: GisViewSelectionRefs` 要选中的东西：id / id 数组（多选）/ `{ type, index }` / 通道写法 / 拾取载荷 / 搜索命中，传 `null` / 空数组等于清空；`options?: GisViewSelectOptions` 只有 `mode`（`'replace'` 缺省 / `'add'` / `'toggle'` / `'remove'`） | `this` |
+| `deselect(refs = null)` | `refs?: GisViewSelectionRefs` 要取消的东西（写法与 `selectFeatures` 一致：节点 / 通道 / 线路 / 混合一批）；不传 / `null` 等于取消全部（= `selectFeatures(null)`），空数组是「没有目标」什么都不做 | `this` |
 | `getSelections()` | 无 | `GisViewPickResult[]` |
 | `isSelected(ref)` | `ref: GisViewFeatureRef \| GisViewFeatureKey \| GisViewSelectionRefObject` 要素定位（id / 下标 / `{ id }` / `{ index }` / `{ type, index }` / `{ item }`） | `boolean` |
 | `getSelectionData()` | 无 | `GisViewSelectionData`：`{ ids, count, pointCount, lineCount, channelCount, points, lines, channels, items, pointIndexes, lineIndexes, bounds }`（`bounds` 是世界包围盒，空选中时 `null`） |
@@ -146,10 +147,9 @@
 | `getPointClipboard()` | 无 | `GisViewClipboardItem \| null` |
 | `mergePoints(source, target, options = {})` | `source: GisViewPointRef` 被并入的节点（并完就没了）、`target: GisViewPointRef` 接收的节点、`options?: { originalEvent?: Event \| null; item?: GisViewPoint }`：`item` 可以给一份已经改好的合并结果（确认阶段改过 `payload.item` 之后就是它） | `GisViewMergeOutcome` |
 | `mergeSelectedPoints(options = {})` | `options: GisViewMergeSelectedOptions`：`target` 指定并到哪一个（不给就自动挑绑定线路最多的）；`sources` 直接给来源（不依赖选中集）；`item` 是最终节点补丁或 `(context) => 补丁`（上下文含 `item` / `merged` / `source` / `target` / `sourceIndex` / `targetIndex` / `merge` / `view`；坐标与 id 仍按 `target` 保留）；`force: true` 越过 `mergeable: false`；`label` / `originalEvent` | `GisViewMergeSelectedOutcome` |
+| `splitPoint(source, parts, options = {})` | `source: GisViewPointRef` 要拆的节点；`parts: GisViewSplitPointPart[]` 至少两份，每份可直接写节点字段或放进 `item`，并用 `lines` / `channels` / `channelFrom` / `channelTo` 分配线路与通道端点；`options?: GisViewSplitPointOptions`：`keepSourceId`（缺省 `true`，第一份沿用来源 id）/ `label` | `GisViewSplitPointOutcome`：`{ ok, reason, source, items, indexes, pointIds, linesChanged, removedLines, removedLineIds, removedLineIndexes, channelsChanged, removedChannels, removedChannelIds, skipped, changes }`；`changes` 可直接作为后端事务输入 |
 | `getPointMerge()` | 无（载荷带 `impact`：`lineCount` / `linesChanged` / `removedLines` / `lineIds` / `removedLineIds` 与通道读数，确认前就能估算影响） | `GisViewPointMergePayload \| null` |
 | `resolvePointMerge(confirmed, options = {})` | `confirmed?: boolean`（缺省 `true` = 确认，`false` = 取消）；`options?: GisViewPointMergeConfirmOptions`：`keep` 选 `'target'`（缺省，保留碰撞目标）/ `'source'`（保留拖动的来源），`item` 是最终节点字段补丁（名称 / 分区 / 颜色 / 尺寸 / 图标 / 描边等；位置与 id 始终取保留端） | `GisViewPointMergePayload \| null` |
-| `confirmPointMerge(options = {})` | `options?: GisViewPointMergeConfirmOptions`：与 `resolvePointMerge(true, options)` 同一份 `{ keep, item }`，用于拖拽合并确认时决定保留端并改写最终节点 | `GisViewPointMergePayload \| null` |
-| `cancelPointMerge()` | 无（`resolvePointMerge(false)` 的别名；拖动的节点回原位，数据不动） | `GisViewPointMergePayload \| null` |
 | `commitPointMerge()` | 无 | `boolean` |
 | `revertPointMerge(options = {})` | `options?: { originalEvent?: Event \| null; silent?: boolean }`：`silent: true` 时不再补发一条 `cancel` 载荷 | `GisViewPointMergePayload \| null` |
 | `removePoints(refs, options = {})` | `refs: \| GisViewFeatureRef \| 数组 \| 'all' \| 'selection' \| 'visible'` 要删哪些节点；`options?: { reason?: string }` 记进事件载荷的删除原因 | `GisViewRemovePointsOutcome` |
@@ -186,20 +186,21 @@
 | `addChannelGroupWaypoint(channelId, groupId, coordinate)` | `channelId` 通道 id；`groupId` 分组 id；`coordinate` 新拐点世界坐标 | `this` |
 | `removeChannelGroupWaypoint(channelId, groupId, pathIndex)` | `channelId` / `groupId` / `pathIndex` 要删的骨架顶点下标 | `this` |
 | `runChannelAction(actionId, options?)` | `actionId: GisViewChannelActionId` 动作名（`'select-group'` / `'deselect-group'` / `'add-waypoint'` / `'remove-waypoint'` / `'split'` / `'merge'`，见 `getChannelContext().actions`）；`options?: GisViewChannelActionOptions` 动作自己的参数（`groupId` / `lineId` / `coordinate`…） | `GisViewChannelContext \| null` |
-| `beginAddChannel(options = {})` | `options?: GisViewChannelDraftOptions` 草稿配置：`kind` / `circuits` / `autoCommit` / `continuous` / `chain` / `name` / `lineId` / `lineProps` / `linePropsByMember` / `lineItems`（第二段）/ `channelProps` / `handoff`（交接模式）/ `select`（点中的节点顺手选中，走 `onSelect` 那一套） | `this`（只负责那条示例假通道，真正新增走 `addChannel`） |
+| `beginAddChannel(options = {})` | `options?: GisViewChannelDraftOptions` 草稿配置：`kind` / `circuits` / `autoCommit` / `continuous` / `chain` / `name` / `lineId` / `lineProps` / `linePropsByMember` / `lineItems`（第二段）/ `routing` / `path`（中间拐点）/ `channelProps` / `channelDraftStyle`（本次草稿的预览样式）/ `handoff`（交接模式）/ `select`（点中的节点顺手选中，走 `onSelect` 那一套） | `this`（只负责那条示例假通道，真正新增走 `addChannel`） |
 | `getAddChannelDraft()` | 无 | `GisViewChannelDraftPayload \| null` |
+| `updateAddChannelStyle(patch = {})` | `patch?: GisViewChannelDraftStyle \| null` 字段级合并的预览样式（箭头位置 / 多回线间距 / 自绘等）；传 `null` 回到全局 `channelDraftStyle` | `this` |
 | `continueAddChannel(options = {})` | `options?: GisViewChannelDraftOptions` 开下一段草稿（写法与 `beginAddChannel` 一致，不传就沿用这一段原来的） | `this` |
 | `cancelAddChannel()` | 无 | `this`（收掉草稿并补一条 `phase: 'cancel'`） |
 | `endAddChannel()` | 无 | `this`（静默收掉视图上的示例假通道 / 线路，数据不动、不补事件） |
-| `commitAddChannel(resolution?, options?)` | `resolution?: GisViewChannelAddResolution` 落地方式（`'channel'` / `'line'`，缺省看草稿）；`options?: GisViewChannelAddInput` 要覆盖的字段（`name` / `circuits` / `colors` / `lineWidth` / `path`…） | `GisViewChannelAddResult` |
+| `commitAddChannel(resolution?, options?)` | `resolution?: GisViewChannelAddResolution` 落地方式（`'channel'` / `'line'`，缺省看草稿）；`options?: GisViewChannelAddInput` 要覆盖的字段（`name` / `circuits` / `colors` / `lineWidth` / `routing` / `path`…） | `GisViewChannelAddResult` |
 | `getChannelAddOptions(from, to, count?, kind?)` | `from` / `to` 两端节点 id；`count?: number` 回数（缺省 1）；`kind?: 'channel' \| 'line'`（缺省 `'channel'`） | `GisViewChannelAddPlan \| null` |
 | `getChannelBetween(from, to)` | `from` / `to` 两端节点 id | `GisViewChannelBetween \| null` |
-| `addChannel(channel, lineData?, group?)` | `channel: GisViewChannelAddSpec` 通道信息 `{ from, to, name?, id?, lineData?, group? }`（后两个是第二 / 第三段写在对象上的别名）；`lineData?: GisViewChannelLineData` 线路数组（`Partial<GisViewLine>` / `string` / `number` 的一条或一批，按每项 id 建 `lineIds`）；`group?: GisViewChannelAddGroup \| GisViewChannelAddGroup[]` 可选分组信息 `{ id?, lineIds?, path? }`。旧写法 `addChannel(input, lineItems?)`（`GisViewChannelAddInput`：`circuits` / `resolution` / `channelId` / `groupId` / `groupIndex` / `kind` 那套）照样认 | `GisViewChannelAddResult`（`channelLineIds` 是落地后通道的完整成员表，独立线路为 `null`） |
+| `addChannel(channel, lineData?, group?)` | `channel: GisViewChannelAddSpec` 通道信息 `{ from, to, name?, id?, lineData?, group? }`（后两个是第二 / 第三段写在对象上的别名）；`lineData?: GisViewChannelLineData` 线路数组（`Partial<GisViewLine>` / `string` / `number` 的一条或一批，按每项 id 建 `lineIds`）；`group?: GisViewChannelAddGroup \| GisViewChannelAddGroup[]` 可选分组信息 `{ id?, lineIds?, path? }`。旧写法 `addChannel(input, lineItems?)`（`GisViewChannelAddInput`：`circuits` / `resolution` / `channelId` / `groupId` / `groupIndex` / `kind` / `routing` / `path` 那套）照样认；`path` 是中间拐点，独立线路落地成完整折线、通道只写骨架拐点 | `GisViewChannelAddResult`（`channelLineIds` 是落地后通道的完整成员表，独立线路为 `null`） |
 | `addChannelGroupLines(channelId, lineData?, group?)` | `channelId` 目标通道 id；`lineData?: GisViewChannelLineData` 这次新建的线路数组（按每项 id 建回线）；`group?: GisViewChannelAddGroup` 新分组信息 `{ id?, path? }`（缺省 `${通道 id}::N`、不带拐点） | `GisViewChannelAddResult` |
 | `addChannelGroups(channelId, groups, options = {})` | `channelId` 目标通道 id；`groups: GisViewChannelAddGroupInput \| GisViewChannelAddGroupInput[]` 每项 `{ id?, path?, lineData? \| lines? \| lineItems? }`（线路数据与 `addChannel` 第二段同一份写法）；`options?: { emit?: boolean; label?: string }` `emit: false` 只落地不通知 | `GisViewAddChannelGroupsResult` |
 | `joinChannelGroupLines(channelId, groupId, lineData?)` | `channelId` 目标通道 id；`groupId?: string \| number` 并进哪一组（认分组 id 也认序号，从 0 起；不传挑第一个还有余量的分组）；`lineData?: GisViewChannelLineData` 这次新建的线路数组 | `GisViewChannelAddResult` |
-| `addChannels(input, options?)` | `input: GisViewChannelAddInput \| GisViewChannelAddInput[]` 一条或一批声明（每条与 `addChannel` 同一套写法）；`options?: { emit?: boolean }` `emit: false` 只改数据不发 `dataChange` | `GisViewAddChannelsResult` |
-| `addLine(input, lineData?)` | `input: GisViewChannelAddInput` 同上（等价 `addChannel({ ...input, kind: 'line' })`）；第二段 `GisViewChannelLineData` 与 `addChannel` 的线路数组同一份 —— 每项可以只写一个 id（裸字符串 / 数字按 `{ id }` 收）、写对象给逐条字段，不写就按 `from-to-序号` 自动编号 | `GisViewChannelAddResult` |
+| `addChannels(input, options?)` | `input: GisViewChannelAddInput \| GisViewChannelAddInput[]` 一条或一批声明（每条与 `addChannel` 同一套写法；`routing: 'orthogonal'` 自动正交折线，`path` 是中间拐点，独立线路落地成完整 `path`、通道只写骨架）；`options?: { emit?: boolean }` `emit: false` 只改数据不发 `dataChange` | `GisViewAddChannelsResult` |
+| `addLine(input, lineData?)` | `input: GisViewChannelAddInput` 同上（等价 `addChannel({ ...input, kind: 'line' })`；`routing: 'orthogonal'` 自动正交折线，`path` 是中间拐点，落地成含两端的完整折线）；第二段 `GisViewChannelLineData` 与 `addChannel` 的线路数组同一份 —— 每项可以只写一个 id（裸字符串 / 数字按 `{ id }` 收）、写对象给逐条字段，不写就按 `from-to-序号` 自动编号 | `GisViewChannelAddResult` |
 | `removeLine(lineId)` | `lineId: string \| number` 要删的线路 id | `GisViewRemoveLineResult` |
 | `removeLines(lineIds)` | `lineIds: string \| number \| 数组` 一次删多条 | `GisViewRemoveLinesResult` |
 | `removeChannel(channelId)` | `channelId` 通道 id | `GisViewRemoveChannelResult` |
@@ -208,25 +209,25 @@
 
 | 方法 | 参数（名字: 类型 = 默认值） | 返回 |
 | --- | --- | --- |
-| `setPointSize(id, size)` | `id` 节点 id / 下标；`size: number` 新的节点宽度（CSS 像素，圆的直径按 `size × 2 / √π` 算） | `this` |
-| `setPointSymbol(id, symbol)` | `id` 节点定位；`symbol: GisViewSymbolInput \| null` 新符号（`'circle'` / `'square'` / `{ type: 'svg'… }` / 图片地址）；传 `null` 回到内置圆 | `this` |
-| `setPointColor(id, color)` | `id` 节点定位；`color: string` 新的填充色（`#rgb` / `rgba()` / `hsl()` / 颜色名都认） | `this` |
 | `movePoint(id, coordinate)` 或 `movePoint(id, x, y)` | `id` 节点定位；`coordinate: GisViewCoordinate` 新坐标 `[x, y]` / `{ x, y }`，或分开写 `x: number` / `y: number` | `this` |
-| `setLineWidth(id, width)` | `id` 线路定位；`width: number` 新的线宽（CSS 像素） | `this` |
-| `setLineColor(id, color)` | `id` 线路定位；`color: string` 新的颜色 | `this` |
 | `setLineWaypoints(id, coordinates)` | `id` 线路定位；`coordinates: GisViewCoordinate \| GisViewCoordinate[]` 新的**中间拐点**（不含首尾端点；传空数组 = 拉直；传单个坐标 = 只留一个拐点） | `this` |
 | `getLineDecorations(id)` | `id` 线路定位 | `GisViewLineDecoration[]` |
 | `setLineDecorations(id, decorations)` | `id` 线路定位；`decorations: GisViewLineDecoration[]` 整份替换（空数组 = 全摘掉） | `this` |
 | `addLineDecoration(id, decoration)` | `id` 线路定位；`decoration: GisViewLineDecoration` 要追加的标记（`symbol` 必填，`position` / `anchor` / `parallel` / `size`…） | `GisViewLineDecoration \| null` |
 | `updateLineDecoration(id, decorationIndex, patch)` | `id` 线路定位；`decorationIndex: number` 第几个标记（按 `decorations` 顺序，从 0 数）；`patch: Partial<GisViewLineDecoration>` 要合并的字段 | `GisViewLineDecoration \| null` |
 | `removeLineDecoration(id, decorationIndex)` | `id` 线路定位；`decorationIndex` 要摘掉的下标 | `GisViewLineDecoration \| null` |
-| `setChannelWidth(id, width)` | `id` 通道 id；`width: number` 世界单位的通道宽度（`nodeWidth > 0` 且两端锚定时不生效，先 `setChannelNodeWidth(id, 0)`） | `this` |
-| `setChannelNodeWidth(id, nodeWidth)` | `id` 通道 id；`nodeWidth: number` 「按两端节点尺寸取宽」的倍数：`1` 回线铺满节点、`0` 关掉自动取宽改用 `width` | `this` |
-| `setChannelInset(id, inset)` | `id` 通道 id；`inset: number \| null` 两端内收（占通道宽度，负数外收，`null` 回默认），只影响 `offsetMode: 'inset'` 的通道 | `this` |
-| `setChannelTangentInset(id, tangentInset)` | `id` 通道 id；`tangentInset: number \| null` 两端切点内收（CSS 像素：正数内收、负数外收、`0` 切点落在节点边上、`null` 按回线线宽收） | `this` |
-| `setChannelName(id, name)` | `id` 通道 id；`name: string \| number \| null` 新名称（悬停提示 / 标签模板的 `{name}`、搜索都取它；`null` 摘掉名称） | `this` |
+| `getPointDecorations(id)` | `id` 节点定位 | `GisViewPointDecoration[]`：节点没找到时给空数组，返回的是副本 |
+| `setPointDecorations(id, decorations)` | `id` 节点定位；`decorations: GisViewPointDecoration[]` 整份替换（空数组 = 全摘掉） | `this` |
+| `addPointDecoration(id, decoration)` | `id` 节点定位；`decoration: GisViewPointDecoration` 要追加的标记（`symbol` 必填，`offset` / `distance` / `direction` / `at` / `connector` / `size`…） | `GisViewPointDecoration \| null` |
+| `updatePointDecoration(id, decorationIndex, patch)` | `id` 节点定位；`decorationIndex: number` 第几个标记（按 `points[].decorations` 顺序，从 0 数）；`patch: Partial<GisViewPointDecoration>` 要合并的字段 | `GisViewPointDecoration \| null` |
+| `removePointDecoration(id, decorationIndex)` | `id` 节点定位；`decorationIndex` 要摘掉的下标 | `GisViewPointDecoration \| null` |
+| `beginDecorationDraft(options?)` | `options?: GisViewDecorationDraftOptions`：`target`（`'line'` 缺省 / `'point'` / `'both'`）、`symbol`（缺省 `'circle'`）、`size`（缺省 18）、`color` / `strokeColor` / `strokeWidth` / `opacity` / `shadow`、`parallel`（缺省 `false`）、`scope`（`'line'` 缺省 / `'group'` / `'channel'`）、`maxDistance`（屏幕像素，缺省 14）、`maxPerLine` / `maxPerPoint`（0 / 缺省 = 不限）、`allowedLines` / `allowedChannels` / `allowedGroups` / `allowedPoints`、节点侧 `placement`（位置来源：`'offset'` 缺省 / `'fixed'` / `'pointer'`）、`anchor`（落地关系：`'follow'` 保存相对节点的屏幕偏移 / `'fixed'` 保存世界坐标；缺省 `offset → follow`、`fixed / pointer → fixed`）、`offset` / `distance`（缺省 28）/ `direction`（0 度向上、顺时针）/ `at`（仅 `placement: 'fixed'` 时作为世界坐标来源）/ `angle` / `connector`、`allowDuplicate`（缺省 `true`）/ `duplicateStrategy`（`'offset'` 缺省 / `'reject'`）/ `duplicateDistance`（缺省 8）、`originalEvent` | `GisViewDecorationDraftPayload \| null`：`start` 载荷（字段与 `onDecorationDraft` 同一份） |
+| `getDecorationDraft()` | 无 | `GisViewDecorationDraftPayload \| null`：当前草稿读数，没有草稿时 `null` |
+| `updateDecorationDraft(patch?)` | `patch?: Partial<GisViewDecorationDraftOptions>` 只合并给出的图标 / 大小 / 方向 / 范围 / 命中距离 / 命中类型 / 节点位置来源与落地关系 / 白名单 / 重复策略 | `GisViewDecorationDraftPayload \| null`：`update` 载荷；没有草稿时 `null` |
+| `commitDecorationDraft(overrides?)` | `overrides?: Partial<GisViewDecorationDraftOptions> & { position?: number }` 提交前临时覆盖（`position` 是沿线比例 0~1） | `GisViewDecorationCommitResult`：`{ ok, reason?, count, targets, decorations, pointTargets, pointDecorations, draft? }`；没有目标 / 超限 / 不在白名单 / 重复时 `ok: false`，数据不动 |
+| `cancelDecorationDraft(options?)` | `options?: { originalEvent?: Event \| null }` 取消原因 / 原始事件 | `GisViewDecorationDraftPayload \| null`：`cancel` 载荷；没有草稿时 `null`，数据与历史不动 |
 | `setChannelLineWidth(id, lineWidth)` | `id` 通道 id；`lineWidth: number` 新的回线线宽（**成员回线 + 通道声明一起改**，一次 `batch`、只发一条数据变更） | `this` |
-| `setChannelColors(id, colors)` | `id` 通道 id；`colors: string \| string[]` 逐回线颜色（不够时按顺序循环取；只给一个就整条通道一个色；改单条回线颜色用 `setLineColor(id, color)` / `updateLine(id, { color })`） | `this` |
+| `setChannelColors(id, colors)` | `id` 通道 id；`colors: string \| string[]` 逐回线颜色（不够时按顺序循环取；只给一个就整条通道一个色；改单条回线颜色用 `updateLine(id, { color })`） | `this` |
 | `setChannelPath(id, coordinates)` | `id` 通道 id；`coordinates: GisViewCoordinate \| GisViewCoordinate[]` 新的**骨架中间拐点**（不含首尾两端；传空数组 = 拉直、传单个坐标 = 只留一个拐点；两端由节点坐标补齐，与通道数据里的 `path` 同义）；分过组的通道写第一组的声明（`groups[].path` 优先于顶层 `path`；「第一组」跳过 `lineIds` 空的分组声明），要改别的组用 `updateChannel(id, { groups })` | `this` |
 
 #### 增删数据
@@ -255,27 +256,42 @@
 | `resetLabel(kind, ref, labelId?)` | `kind` / `ref`；`labelId?` 复位哪一条（缺省 `'default'`） | `boolean` |
 | `resetLabels(kind?)` | `kind?: 'point' \| 'line'`（缺省两类都复位） | `number` |
 
+#### 扩展图形
+
+| 方法 | 参数（名字: 类型 = 默认值） | 返回 |
+| --- | --- | --- |
+| `addGraphic(graphic)` | `graphic: GisViewGraphic` 一个扩展图形（`type` / `x` / `y` / `width` / `height` 与对应的 `d` / `src` / `canvas`；`id` 已存在时按更新覆盖） | `GisViewGraphic \| null`：归一化后的读数；参数无效时为 `null` 并走 `onWarning` |
+| `addGraphics(list)` | `list: GisViewGraphic \| GisViewGraphic[]` 一条或一批（无效条目单独跳过） | `GisViewGraphic[]`：实际加进去的读数 |
+| `updateGraphic(id, patch)` | `id: string \| number` 图形 id；`patch: Partial<GisViewGraphic>` 要合并的字段（`style.width` / `style.height` / `style.fill` 等也认） | `GisViewGraphic \| null`：改后的读数；id 不存在或结果无效时为 `null` |
+| `removeGraphic(id)` | `id: string \| number` 图形 id | `GisViewGraphic \| null`：删掉的那一条；id 不存在时为 `null` |
+| `clearGraphics()` | 无 | `number`：清掉的条数（只清图形层，不碰要素数据） |
+| `getGraphic(id)` | `id: string \| number` 图形 id | `GisViewGraphic \| null`：副本，没有时 `null` |
+| `getGraphics()` | 无 | `GisViewGraphic[]`：按 `zIndex`、再按加入顺序排的副本数组 |
+
+#### WebGL 自定义层
+
+| 方法 | 参数（名字: 类型 = 默认值） | 返回 |
+| --- | --- | --- |
+| `requestRender()` | 无 | `this`：请求下一帧；层内部画动画时也可以在 `draw` 里调用 |
+| `addWebGLLayer(layer)` | `layer: GisViewWebGLLayer`：`id`（同 id 覆盖）、`order`（小的先画，同 order 保持加入顺序）、`enabled`、`draw(context)`；`context` 给 `gl` / `canvas` / `viewport` / `camera` / `frame` / `project` / `unproject` / `requestRender` | `() => void`：卸载函数 |
+| `updateWebGLLayer(id, patch)` | `id` 层 id；`patch: Partial<GisViewWebGLLayer>` 要改的 `order` / `enabled` / `draw` | `GisViewWebGLLayer \| null`：改后的读数；id 不存在时 `null` |
+| `removeWebGLLayer(id)` | `id` 层 id | `GisViewWebGLLayer \| null`：删掉的读数；id 不存在时 `null` |
+| `clearWebGLLayers()` | 无 | `number`：清掉的层数 |
+| `getWebGLLayers()` | 无 | `GisViewWebGLLayer[]`：按 `order` 排好的副本 |
+
 #### 导出
 
 | 方法 | 参数（名字: 类型 = 默认值） | 返回 |
 | --- | --- | --- |
-| `exportData(options = {})` | `options: GisViewExportDataOptions`：`format`（`'view'` 缺省 / `'input'` 与创建入参同构 / `'new'` new.json 口径 / `'test'` test.json 口径 / `'full'` 标准数据文档）、`parts`（只导 `points` / `lines` / `channels` / `parallelGroups` 里的哪几份）、`points` / `lines` / `channels`（只导指定要素）、`labels: false`（不带标签列）、`extra`（附加到结果上的字段）。`format: 'full'` 时返回的就是文档本身（`GisViewDocument`），没有 `ok` / `counts` / `warnings` 这几列 | `GisViewExportDataResult \| GisViewDocument`（`format: 'full'`） |
-| `exportViewportData(options = {})` | 同 `exportData`（`format` / `parts` / `labels` / `box` / `extra`），另有 `margin: number`（视口外扩多少屏幕 CSS 像素，缺省 0）与 `rect: GisViewBounds`（直接给世界矩形替掉视口）；`points` / `lines` / `channels` 不认 | `GisViewExportViewportResult`（`format: 'full'` 时是 `GisViewDocument` + `viewRect` / `margin`） |
-| `exportStationData(options = {})` | `options: GisViewExportStationDataOptions` 节点记录口径的筛选（`points` 选哪些、`labels` 带不带标签、`extra`） | `GisViewExportStationDataResult` |
-| `exportPointData(options = {})` | `options: GisViewExportFilterOptions`（`points` / `labels` / `extra`） | `GisViewExportPointDataResult` |
-| `exportLineData(options = {})` | `options: GisViewExportFilterOptions`（`lines` / `labels` / `extra`） | `GisViewExportLineDataResult` |
-| `exportChannelData(options = {})` | `options` 同上（`channels` / `labels`） | `GisViewExportChannelDataResult` |
-| `exportParallelGroups(options = {})` | `options?: GisViewExportParallelGroupsOptions`（`all: true` 连没编辑过的也算、`extra`） | `GisViewExportParallelGroupsResult` |
+| `exportData(options = {})` | `options: GisViewExportDataOptions`：`scope`（`'all'` 缺省 / `'viewport'` / `'selection'`，也认 `visible` / `view` / `selected`）、`format`（`'view'` 缺省 / `'input'` / `'new'` / `'test'` / `'full'`）、`parts`（只导 `points` / `lines` / `channels` / `parallelGroups` 里的哪几份）、`points` / `lines` / `channels`（只导指定要素）、`withLines: false`（selection 不要两端都在集合里的线路）、`labels`、`extra`。`format: 'full'` / `'input'` 返回可直接回灌的数据，不夹带 `scope` / `counts` 读数 | `GisViewExportDataResult \| GisViewDocument`（`format: 'full'`） |
 | `exportImage(options = {})` | `options?: GisViewExportImageOptions`：`type`（`'image/png'` / `'image/jpeg'`）、`quality`（JPEG 0 ~ 1）、`scale`（导出倍数）、`background`（底色）、`transparent` | `Promise<string>` |
 | `exportSelection(options = {})` | `options?: GisViewExportSelectionOptions`：`format` / `type` / `quality` / `scale` / `padding`（只导选中要素那一块） | `Promise<GisViewExportSelectionResult>` |
-| `exportSelectionData(options = {})` | `options?: GisViewExportSelectionDataOptions`：`parts`（`points` / `lines` / `channels` / `parallelGroups` 要哪几份，缺省四份都出）、`labels` | `GisViewExportSelectionDataResult` |
 
 #### 筛选
 
 | 方法 | 参数（名字: 类型 = 默认值） | 返回 |
 | --- | --- | --- |
 | `setFilter(filter)` | `filter: GisViewFilterInput \| null` 筛选条件：完整格式 `{ points, lines, cascade, worker }`；只筛节点时可以简写成节点条件本身；传 `null` 等于清空 | `this` |
-| `clearFilter()` | 无 | `this` |
 | `getFilter()` | 无 | `GisViewFilter \| null` |
 | `getFilterResult()` | 无 | `GisViewFilterResult \| null` |
 
@@ -286,7 +302,7 @@
 | `on(name, handler)` | `name: GisViewEventName \| '*'` 事件名（`'dataChange'` / `'labelClick'`… 或 `'*'` 订阅全部）；`handler: (payload, name?) => void` 回调，载荷字段见「事件」一节的表 | `() => void` 取消订阅 |
 | `once(name, handler)` | 同上，只触发一次（回调跑完自动摘掉） | `() => void` 取消订阅 |
 | `off(name, handler?)` | `name` 事件名；`handler?` 只摘掉这一个回调（不传 = 摘掉这个事件的全部） | `number` 摘掉几条 |
-| `use(plugin)` | `plugin: GisViewPlugin`（`view => hook`，与 `options.plugins` 的写法一致）：立即执行一次，返回卸载函数 —— 调它跑插件自己的 `destroy`（重复调用只清一次，实例销毁之后也安全） | `() => void` 卸载 |
+| `use(plugin)` | `plugin: GisViewPlugin`（`(view, context) => hook`，与 `options.plugins` 的写法一致）：立即执行一次，返回卸载函数 —— 调它跑插件自己的 `destroy`（重复调用只清一次，实例销毁之后也安全） | `() => void` 卸载 |
 | `getFeatures()` | 无 | `GisViewFeatureState` |
 | `setFeatures(next)` | `next: GisViewFeaturesInput` 预设名（`'edit'` / `'view'` / `'static'`）、开关表或布尔值 | `this` |
 | `undo()` / `redo()` | 无 | `GisViewHistoryStepResult \| null` |