gis-view-webgl2 0.1.7 → 0.1.8

package/docs/manual/12-/346/240/207/347/255/276/344/270/216/350/243/205/351/245/260.md

@@ -176,9 +176,9 @@ view.updateOptions({
   lineLabel: { draggable: true, editable: true }
 })
 
-view.on('labelClick', payload => view.selectFeatures(payload)) // { kind, index, id, labelId, item, label, parent, offset, state, selected, selection }
+view.on('labelClick', payload => view.selectFeatures(payload)) // { kind, index, id, labelId, item, label, parent, offset, state, selected }
 view.on('labelDrag', payload => {}) // { phase: 'start' | 'move' | 'end', kind, index, id, labelId, item, label, parent, offset, startOffset, delta, state? }
-view.on('labelContextMenu', payload => openMenu(payload)) // 右键标签：{ ...labelClick 那一份, clientX, clientY, originalEvent }
+view.on('labelContextMenu', payload => openMenu(payload)) // 右键标签：{ ...labelClick 那一份, originalEvent }；菜单位置读 originalEvent.clientX / clientY
 view.on('labelDblClick', payload => openEditor(payload)) // 双击标签：载荷同上（originalEvent 是 dblclick）
 view.on('labelChange', payload => {}) // { action: 'update' | 'reset' | 'resetAll' | 'add' | 'remove' | 'restore' | 'addAll' | 'updateAll' | 'removeAll', kind, index, id, labelId?, patch?, state?, removed? }
 ```

package/docs/manual/14-/350/247/206/345/233/276/344/270/216/347/255/233/351/200/211.md

@@ -159,12 +159,12 @@ view.focusOn(['station-1', 'station-2'], { select: true, zoom: true }) // 适配
 view.focusOn('station-1', { zoom: true, maxZoom: 8 }) // 零面积目标也能放大到 8 倍
 view.focusOn({ minX: 116, minY: 39, maxX: 117, maxY: 40 }, { zoom: true, padding: 60 })
 
-// 只挪中心、比例一点都不动：focusOn(target, { center: true })
-view.focusOn([116.4, 39.9], { center: true })              // 世界坐标（数组 / { x, y } 都认）
-view.focusOn('station-1024', { center: true })             // 要素：id / { type, index } / 搜索命中
-view.focusOn({ type: 'channel', channelId: 'channel-a' }, { center: true }) // 通道：取它范围的中心
-view.focusOn({ lngLat: [116.4, 39.9] }, { center: true })  // 配了 GeoJSON 底图时按经纬度
-view.focusOn({ minX: 116, minY: 39, maxX: 117, maxY: 40 }, { center: true }) // 一段范围：取中心
+// 只挪中心、比例一点都不动：不写 zoom / scale 就是缺省行为
+view.focusOn([116.4, 39.9])                       // 世界坐标（数组 / { x, y } 都认）
+view.focusOn('station-1024')                      // 要素：id / { type, index } / 搜索命中
+view.focusOn({ type: 'channel', channelId: 'channel-a' }) // 通道：取它范围的中心
+view.focusOn({ lngLat: [116.4, 39.9] })           // 配了 GeoJSON 底图时按经纬度
+view.focusOn({ minX: 116, minY: 39, maxX: 117, maxY: 40 }) // 一段范围：取中心
 
 // flyTo：目标与选项和 focusOn 完全一致，只多 duration / easing，把相机平滑飞过去
 view.flyTo(hit, { zoom: true, duration: 600, easing: 'ease-in-out' })
@@ -185,7 +185,6 @@ const flying = view.cameraAnimating              // 只读：按钮在「飞向
 | --- | --- |
 | `zoom: true` | 显式要求按目标范围适配视图；不写就只居中、比例不动 |
 | `scale` | 直接设成这个比例，不再按范围适配（优先级高于 `zoom`）；线路 / 通道 / 分组不会在此基础上再自动放大 |
-| `center: true` | 显式只把中心挪过去、比例一点不动（与缺省行为一致，保留旧写法） |
 | `padding` | 按范围适配（`zoom: true`）时四周留白（CSS 像素，缺省 40） |
 | `maxZoom` | 适配（`zoom: true`）时的最大比例：单个节点 / 一条直线没有面积，靠它撑出一个最小范围 |
 | `select: true`（或另给一批写法） | 把这些被聚焦的要素同时变成选中状态（与接口选中同一份 state） |
@@ -280,7 +279,7 @@ createGisView(container, {
 
 1. **视野只由业务范围决定（推荐）**：配 `initialView: { bounds, padding }`（或 `mode: 'center'` + `scale`）把首屏钉在一块业务范围上 —— `bounds` 不跟着数据长，新节点进来包围盒变大也不影响相机；数据分布本来就广时，业务范围与数据边界分开正是想要的。
 2. **新节点不进自动适应**：`fitView()` 只手动调（首屏一次、切数据集一次），`addPoint` / `addPoints` 追加之后组件不会自动适应；要展示新节点就 `focusOn(id, { zoom: true })` 或高亮 / `setDropPreview`，别整幅重适应。
-3. **只平移不改比例**：`setCamera({ center })` 或 `focusOn(id, { center: true })` —— 中心挪过去、`scale` 一点不动，两点之间的屏幕距离就不变。
+3. **只平移不改比例**：`setCamera({ center })` 或 `focusOn(id)` —— 中心挪过去、`scale` 一点不动，两点之间的屏幕距离就不变。
 4. **按「节点间距」而不是「包围盒」算适应**：`focusOn([...几个代表性要素], { zoom: true })` / `zoomToBounds(业务范围)`；也可以给 `minScale` 一个下界，缩到这条线就停住。
 5. **想让节点本身不跟着缩**：`pointZoomScale` / `lineZoomScale` 调小（`0` = 完全不跟随地图缩放），尺寸主要由 `pointSizeScale` / `lineWidthScale` 的常数倍数决定 —— 比例被带跑时至少节点不会一起变小。
 
@@ -598,15 +597,15 @@ console.log(minimapElement?.parentElement === minimapHost) // true
 | --- | --- |
 | `deselect(refs?)` ↔ `selectFeatures(refs, { mode: 'remove' })` | 取消选中的两个入口：`deselect` 是「去掉这几条」的短写法（写法解析完全一样），不给目标就是取消全部（`selectFeatures(null)` / `selectFeatures([])` 同义） |
 | `zoomIn(step?)` / `zoomOut(step?)` ↔ `zoomBy(factor, options?)` | 前者按 `zoomStep`（缺省 1.4）乘 / 除一档（`zoomOut(step)` 就是 `zoomBy(1 / step)`）；要给具体倍数、要指定锚点用 `zoomBy` |
-| `addChannels(items, options?)` ↔ `addChannel(spec, lineData?, group?)` / `addChannel(input, lineItems?)` | 前者是批量版（一次多条通道 / 独立线路，逐条落地但只重排一次、只记一步历史、只发一条事件，每项里的 `lineItems` 照认），后者一次一条 |
-| `addChannel(spec, lineData?, group?)`（新签名，只新建）↔ `addChannelGroupLines(channelId, lineData, groupInfo?)` / `joinChannelGroupLines(channelId, groupId, lineData)` | 新签名只负责「两个节点之间还没有通道」的新建（第二段 / 第三段显式给了才算）；已经有通道时要新加一组 / 并进某一组就走拆出来的这两个方法（语义直说，不必自己拼 `resolution`）；只写 `{ from, to }` 的老调用照旧按方案表分流 |
+| `addChannels(items, options?)` ↔ `addChannel(spec, lineData?, group?, options?)` | 前者是批量版（一次多条通道，逐条落地但只重排一次、只记一步历史、只发一条事件），后者一次一条；两条入口的 `lineData` 与 `options.select` 语义一致 |
+| `addChannel(spec, lineData?, group?, options?)`（只新建）↔ `addChannelGroupLines(channelId, lineData, groupInfo?)` / `joinChannelGroupLines(channelId, groupId, lineData)` | `addChannel` 只负责「两个节点之间还没有通道」的新建；已经有通道时要新加一组 / 并进某一组就走拆出来的这两个方法。两端已有通道时 `addChannel` 整条失败，不再按方案表分流 |
 | `updateChannel(id, { group })`（单数：改一组的信息）↔ `updateChannel(id, { groups })`（复数：整份换分组声明） | 同一份分组数据的两档写法：只改某一组的字段（id 之外的字段 / 骨架 / 成员）用 `group`，整份重拆用 `groups`；两个一起给时以 `groups` 为准（`group` 丢掉并给一条 `warnOnce`） |
-| `addChannel(input, lineItems?)` ↔ `addChannel(input)` / `linePropsByMember` | 第二段与 `linePropsByMember` 同义（一条或一批逐条回线属性）：给了几条就建几条（`circuits` 忽略），同下标两边都写时第二段优先 |
+| `addLine(spec, lineData?, options?)` ↔ `addLines(items, options?)` | 前者按两个节点新建独立线路、用 `lineData` 一次生成多回；后者追加现成的线路数据对象。两者都只碰 `lines`，`channels` 不动 |
 | `getChannelAddOptions(from, to, count?, kind?)` ↔ `getChannelBetween(from, to)` | 同一份通道读数的一宽一窄：方案表要 `count` / `kind` 才能算余量与可选方案，通道读数只回答「有没有通道 / 有几组 / 当前哪组」；界面做「这两个点之间已经有通道」这类判断用窄的那条，不必凑参数 |
-| `addChannel` 顶层 `channelId` / `groupId` / `groupIndex` ↔ `resolution: { type: 'joinGroup', … }` | 同一件事的两种写法（与 `updateLine` 的分组指令同款）：并进已有通道时指定「哪条通道、哪一组」；只给 `channelId` 按这条通道自己的推荐顺序挑（新分组 → 第一个能并的分组）。结果里的 `channelLineIds` 是更新后的完整成员表，见「新增通道」 |
+| `addChannelGroups(channelId, groups, options?)` ↔ 多次 `addChannelGroupLines(channelId, lineData, groupInfo?, options?)` | 前者一次新加多组，只重排一次、只记一步历史；后者一次一组。两边的每组线路数据都写在 `lineData` / `lines`，`lineItems` 已移除 |
 | `project(x, y)` / `unproject(x, y)` ↔ `clientToScreen(clientX, clientY)` / `screenToClient(x, y)` ↔ `clientToWorld(clientX, clientY)` / `worldToClient(x, y)` | 同一套换算链的三档入口：`project` / `unproject` 收**画布 CSS 像素**，`clientTo*` 这一对吃鼠标事件里的 `clientX` / `clientY`（自动减 canvas rect、除宿主缩放）只换到画布像素，再接一层就是世界坐标（`clientToWorld` / `worldToClient`）；经纬度那一对是 `lngLatToScreen` / `screenToLngLat` |
 | `fitView(padding?)` / `applyInitialView()` / `resetView()` / `zoomToBounds(bounds, padding?)` | 视角的四个语义：适应**数据范围**（并记下首次落位）/ 按 `options.initialView` 落位（可反复调用）/ 回到**首次落位那一刻**的相机 / 按给定的世界坐标范围适应 |
-| `focusOn(ref, options?)` ↔ `zoomToBounds(bounds, padding?)` | `focusOn` 认要素（id / 下标 / 搜索命中 / 坐标 / 矩形 / 一批），缺省只按范围中心居中；写 `{ zoom: true }` 才走适应那一条，另带 `center` / `scale` / `maxZoom` / `select` 这些选项 |
+| `focusOn(ref, options?)` ↔ `zoomToBounds(bounds, padding?)` | `focusOn` 认要素（id / 下标 / 搜索命中 / 坐标 / 矩形 / 一批），缺省只按范围中心居中；写 `{ zoom: true }` 才走适应那一条，另带 `scale` / `maxZoom` / `select` 这些选项 |
 | `flyTo(target, options?)` ↔ `focusOn(target, options?)` | 同一套目标与选项解析，区别只在落位方式：`focusOn` 立即改相机，`flyTo` 默认用 450 ms 平滑过去，并多认 `duration` / `easing`；需要随时停在当前帧用 `stopCameraAnimation()` |
 | `pick(x, y)` ↔ `pickAt(clientX, clientY)` | 坐标口径不同：`pick` 收画布 CSS 像素，`pickAt` 直接吃鼠标事件里的客户端坐标（结果里另加 `target` 与 `lngLat`） |
 | `hoverAt(clientX, clientY)` / `clearHover()` / `getHover()` | 三个动作：程序化悬停 / 撤掉并补发 `onHover(null)` / 读当前那一份（`hoverAt` 的返回与 `onHover` 载荷同一份） |

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

@@ -35,8 +35,8 @@
 | `zoomIn(step?)` / `zoomOut(step?)` / `zoomBy(factor, origin?)` | 相对缩放，`origin` 为画布 CSS 像素锚点（缺省视口中心） |
 | `zoomTo(scale, origin?)` | 直接设成指定比例（像素 / 世界单位） |
 | `zoomToBounds(bounds, padding?)` | 把一段世界坐标矩形适应到视图内，退化成一点时只居中不改比例 |
-| `focusOn(target, options?)` | 把视角移到目标上：单条（搜索命中 / 要素 id / `{ type: 'point' \| 'line' \| 'channel', id \| index }` / `{ channelId }` 整条通道 / `{ type: 'group', channelId?, groupId }` / 坐标 / 矩形 / `{ lngLat }`）或**一批**（数组取整体包围盒 —— 搜到三个节点就是这三个点的中心当屏幕中心）；字符串先节点后线路，裸字符串不表示通道，同 id 用 `type` 消歧，分组必须显式写 `type: 'group'`（全局唯一 `groupId` 可省略通道）。**缺省只居中、比例一点不动**；`options.zoom: true` 才按解析出的真实范围适配（节点 / 线路 / 通道 / 分组共用这一条，不额外放大），`scale` 优先级高于 `zoom`。`options` 还认 `center: true`（显式只居中，与缺省一致）、`padding`、`maxZoom`、`select`（顺带选中这批，`mode` 决定怎么并进当前选中集） |
-| `flyTo(target, options?)` | 平滑飞到与 `focusOn` 相同的目标：目标写法与 `zoom` / `scale` / `center` / `padding` / `maxZoom` / `select` / `mode` 完全同义，另认 `duration`（毫秒，缺省 450）与 `easing`（`linear` / `ease-in` / `ease-out` / `ease-in-out` 或 `(progress) => progress`）。中心线性插值、比例按对数插值；`duration <= 0` 或系统要求减少动态效果时立即落位。再次飞行、用户拖拽 / 滚轮或任何程序化改相机都会停在当前帧，不补跳到终点 |
+| `focusOn(target, options?)` | 把视角移到目标上：单条（搜索命中 / 要素 id / `{ type: 'point' \| 'line' \| 'channel', id \| index }` / `{ channelId }` 整条通道 / `{ type: 'group', channelId?, groupId }` / 坐标 / 矩形 / `{ lngLat }`）或**一批**（数组取整体包围盒 —— 搜到三个节点就是这三个点的中心当屏幕中心）；字符串先节点后线路，裸字符串不表示通道，同 id 用 `type` 消歧，分组必须显式写 `type: 'group'`（全局唯一 `groupId` 可省略通道）。**缺省只居中、比例一点不动**；`options.zoom: true` 才按解析出的真实范围适配（节点 / 线路 / 通道 / 分组共用这一条，不额外放大），`scale` 优先级高于 `zoom`。`options` 还认 `padding`、`maxZoom`、`select`（顺带选中这批，`mode` 决定怎么并进当前选中集） |
+| `flyTo(target, options?)` | 平滑飞到与 `focusOn` 相同的目标：目标写法与 `zoom` / `scale` / `padding` / `maxZoom` / `select` / `mode` 完全同义，另认 `duration`（毫秒，缺省 450）与 `easing`（`linear` / `ease-in` / `ease-out` / `ease-in-out` 或 `(progress) => progress`）。中心线性插值、比例按对数插值；`duration <= 0` 或系统要求减少动态效果时立即落位。再次飞行、用户拖拽 / 滚轮或任何程序化改相机都会停在当前帧，不补跳到终点 |
 | `search(keyword \| options)` | 按关键字搜索节点 / 线路 / 通道 / 通道分组并返回命中：`scope` 认复数的 `points` / `lines` / `channels` / `groups`，也认与 `focusOn` 一致的单数别名 `point` / `line` / `channel` / `group`；结果分 `points` / `lines` / `channels` / `groups` 四类，分组命中带 `channelIndex` / `groupId` / `groupIndex`，可直接交给 `focusOn` / `selectFeatures`。**不动视角**：要不要聚焦由调用方自己调 `focusOn`，见「搜索与定位」 |
 | `searchAsync(keyword \| options)` | 同一份口径的异步版：数据量大时把扫描放进 Worker（10 万点 / 10 万线下同步要占主线程 40 ms 上下的那一段），返回 `Promise<GisViewSearchResult>`；结果带 `worker` 与 `stale` 两个字段，见「异步搜索」 |
 | `setCamera(camera)` / `getCamera()` | 读写 `{ center, scale }` |
@@ -72,28 +72,29 @@
 | `mapDataToGeoJson(data, options?)` | `createGeoMapper(options).mapData(data)` 的快捷写法：把 `{ points, lines, channels }` 整份搬到 GeoJSON 坐标，原数据不动；没有 GeoJSON 背景时是 `null` |
 | `pick(x, y)` | 拾取指定画布位置上的要素（`clickable: false` 的要素不会返回） |
 | `pickAt(clientX, clientY)` | 按**浏览器客户端坐标**拾取（就是鼠标事件里的 `clientX` / `clientY`）：与指针事件载荷同一份结果（`type` / `index` / `item` / `distance` / `screen` / `coordinate` 与通道字段），另加 `target`（`'point'` / `'line'` / `'channel'`）与 `lngLat`；命中通道回线时 `group` 是当前组、`groups` 是整条通道的全部分组；没命中返回 `null`。只读，不改选中也不动光标 |
-| `selectAt(clientX, clientY)` | 只有客户端坐标时用它像普通单击一样立即选中命中要素：节点 / 线路直接选中，通道回线按 `channelSelectMode` 摊开；空白或聚合圆返回 `null` 且不改选中。不等待 `selectTrigger: 'dblClick'`，也不派发 `onClick` / `onDblClick`；每次成功命中都发 `onSelect`，选中集实际变化时再发 `onSelectChange`，顺序 `onSelect → onSelectChange`（`cause: 'api'`）。选中通道回线时载荷带当前 `group` / 完整 `groups`，多通道看 `channelContexts`。已知节点 / 线路 id 时直接用 `selectFeatures`，见「按坐标单击选中（selectAt）」 |
+| `selectAt(clientX, clientY)` | 只有客户端坐标时用它像普通单击一样立即选中命中要素：节点 / 线路直接选中，通道回线按 `channelSelectMode` 摊开；空白或聚合圆返回 `null` 且不改选中。不等待 `selectTrigger: 'dblClick'`，也不派发 `onClick` / `onDblClick`；每次成功命中都发 `onSelect`，选中集实际变化时再发 `onSelectChange`，顺序 `onSelect → onSelectChange`（`cause: 'api'`）。选中通道回线时外层带当前 `group` / 完整 `groups` / 本次选中的 `lineIndexes` / `lineIds`，多通道看 `channelContexts`；`items[]` 不挂通道字段。已知节点 / 线路 id 时直接用 `selectFeatures`，见「按坐标单击选中（selectAt）」 |
 | `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 }`，侧边栏「画面里的通道」、按视口统计用它 |
-| `selectFeatures(refs, options?)` | 接口选中（换一份选中集；`selectFeatures(null)` / 空数组就是清空）：`refs` 认节点 / 线路 id、id 数组、`{ type, index }`、通道写法（`{ type: 'channel', channelId }` / `{ channelId, groupId }` / `{ channelId, lineIds }`）、分组写法（`{ type: 'group', channelId?, groupId }`，全局唯一 `groupId` 可省略通道）以及拾取载荷与搜索命中；`options.mode` 给 `'replace'`（缺省，换一份）/ `'add'` / `'toggle'`（在就取消、不在就选上）/ `'remove'`。会同步选中样式与读数；选中集实际变化时按 `onSelect → onSelectChange` 派发（`cause: 'api'`），载荷带同一份通道上下文（单通道摊平，多通道看 `channelContexts`），不发 `onClick` / `onDblClick`，见「接口选中（selectFeatures）与读回选中」 |
+| `selectFeatures(refs, options?)` | 接口选中（换一份选中集；`selectFeatures(null)` / 空数组就是清空）：`refs` 认节点 / 线路 id、id 数组、`{ type, index }`、通道写法（`{ type: 'channel', channelId }` / `{ channelId, groupId }` / `{ channelId, lineIds }`）、分组写法（`{ type: 'group', channelId?, groupId }`，全局唯一 `groupId` 可省略通道）以及拾取载荷与搜索命中；`options.mode` 给 `'replace'`（缺省，换一份）/ `'add'` / `'toggle'`（在就取消、不在就选上）/ `'remove'`。会同步选中样式与读数；选中集实际变化时按 `onSelect → onSelectChange` 派发（`cause: 'api'`），载荷外层带同一份通道上下文（单通道摊平，多通道看 `channelContexts`），`items[]` 不挂通道字段，不发 `onClick` / `onDblClick`，见「接口选中（selectFeatures）与读回选中」 |
 | `selectWaypoint(lineRef, pathIndex?, options?)` | 代码选中一个拐点：`selectWaypoint('line-1', 2)` / `{ lineIndex, pathIndex }` / `{ lineId, pathIndex }`，并同时选中所在线路；有效下标从 `getWaypoints()` 取。传 `null` 只取消拐点选中、不改要素选中集，见「代码选中拐点（selectWaypoint）」 |
 | `deselect(refs?)` | 取消选中：写法与 `selectFeatures` 完全一样，把这些从当前选中集里去掉、其余选中原样留着；不传 / `null` 等于取消全部（也就是 `selectFeatures(null)`），空数组是「没有目标」什么都不做。改变选中集时按 `onSelect → onSelectChange` 派发（`cause: 'api'`；清空时 `onSelect` 载荷为 `null`），见「取消选中（deselect / selectFeatures(null)）」 |
-| `getSelections()` | 读回选中结果 `[{ type, index, item, … }]`（按选中顺序）：要 id 列表 / 个数 / 包围盒看 `getSelectionData()` |
+| `getSelections()` | 读回选中结果 `[{ type, index, item, … }]`（按选中顺序）：通道回线不带通道字段，单条归属用 `getLineChannel(index)`；要 id 列表 / 个数 / 包围盒看 `getSelectionData()` |
+| `getSelectionInfo()` | 选中集轻量计数 `{ ids, count, points, lines, channels }`（通道回线按通道算一个），与 `onSelectChange` 顶层同名字段同口径；按选中集引用缓存，十万级选中下也只是一次读取。指针 / 点击 / 悬停载荷不再重复挂 `selection`，状态栏这类只要计数的读数用它；要要素对象或包围盒再用 `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`），见「接口选中（selectFeatures）与读回选中」 |
+| `getSelectionData()` | 选中集一次取全：读数（`ids` / `count` / `pointCount` / `lineCount` / `channelCount`）加要素本身（`points` / `lines` / `channels`（按通道去重，与 `getData()` 同一批对象）），另有 `items`（与 `getSelections()` 同一份，通道回线不带通道字段）、`pointIndexes` / `lineIndexes` 与 `bounds`（世界包围盒，空选中时 `null`），见「接口选中（selectFeatures）与读回选中」 |
 | `getCascadeHighlight()` | 当前点击级联高亮的读数：`{ origin, scope, points, lines, pointIndexes, lineIndexes }`；没有高亮或 `cascadeHighlight` 关着时返回 `null`。它只读、不改选中集，见「点击级联高亮」 |
 | `selectInBox(box, options?)` | 按画布 CSS 像素矩形框选，等价于 Shift + 拖动（跟随 `shortcuts.boxSelect`）；`options.selectionKinds` 可只覆盖这一次的节点 / 线路 / 通道类型过滤。每次框选操作都发 `onSelect`（空框的载荷为 `null`），选中集实际变化时再发 `onSelectChange`，顺序 `onSelect → onSelectChange`（`cause: 'boxSelect'`）；通道回线的分组字段与鼠标框选同一份 |
 | `beginCopyPoint(options?)` | 开始复制一个节点：给 `id` / `index` 直接出预览（`commit: true` 出预览即落地，`follow: true` 跟随鼠标，`autoCommit: false` 停在预览态），不给来源就是「先点按钮再选节点」模式，见「节点复制」 |
 | `commitPointCopy()` / `cancelPointCopy()` | 落地 / 取消预览中的复制（返回 `end` / `cancel` 载荷） |
-| `updateCopyPoint(patch)` | 改预览节点的数据（等价于回调里的 `payload.update` / `setItem`），返回改完的节点 |
+| `updateCopyPoint(patch)` | 改预览节点的数据（等价于回调里的 `payload.update`），返回改完的节点 |
 | `getPointCopy()` | 当前复制状态：预览中是 `{ phase: 'preview', index, item, source, … }`，等选点时是 `{ phase: 'pick' }`，没有就 `null` |
 | `copyPoint(source?)` | 复制一个节点到它旁边（一步到位）：来源给 id / 下标 / 一份节点数据，不给就用选中的节点（再没有用光标下的）；返回新节点 `{ index, item }` |
 | `copyPoints(sources?, options?)` / `copySelectedPoints(options?)` | **批量复制**（不经过剪贴板）：不给 `sources` 时复制当前选中集（框选之后一次复制整组）；默认只带选中要素 —— 选中线路复制线路、选中通道复制整条通道及回线，并自动补所需端点（`supportSources` / `supportItems` / `supportIndexes`）。显式 `sources` 时只复制这批节点；`lineIndexes` / `channelIndexes` 可再点名，`withLines: true` / `withChannels: true` 才恢复「来源内部全带」的旧口径（写 `false` 则连选中线路 / 通道也不带）。落点按 `coordinate` / `screen` 或 `copy.offset`，`select: true` 复制后选中新节点。返回 `phase: 'batch'` 载荷（`sources` / `items` / `indexes` / `selectedPointCount` / `lines` / `channels` / `count` / `revert()`），复制不了时 `ok: false` + `reason` |
 | `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 }`，见「节点合并」 |
-| `splitPoint(source, parts, options?)` | `mergePoints` 的逆操作：把一个节点拆成两份或更多（第一份接在原下标上、缺省沿用原 id，其余追加到末尾），按每份的 `item` / 顶层字段生成新节点，按 `lines` 分配线路、按 `channels` / `channelFrom` / `channelTo` 分配受影响通道的两端。没显式分配的线路跟第一份；没显式分配的通道端点跟它第一条被分配过的成员回线。线路的 `from` / `to` 与和来源坐标重合的 `start` / `end` / `path` 顶点改到对应新节点；拆完后的自环 / 零长度线路与两端落到同一份的通道删掉，成员全没了的通道也删掉。整次调用只记一条历史、只发一条 `splitPoint` 数据变更，返回的 `changes` 可直接作为后端事务输入；至少两份、坐标必须有效、线路不能重复分配，写错时 `ok: false` 并在 `reason` 说明 |
+| `splitPoint(source, parts, options?)` | `mergePoints` 的逆操作：把一个节点拆成两份或更多（第一份接在原下标上、缺省沿用原 id，其余追加到末尾），按每份的 `item` / 顶层字段生成新节点，按 `lines` 分配线路、按 `channels` / `channelFrom` / `channelTo` 分配受影响通道的两端。没显式分配的线路默认跟第一份；`options.autoLines: 'alternate'` 时按「同一条通道的成员成组、独立线路单条」为单位，轮流分给负载最少的一份（解除合并推荐，通道成员不会被拆散）。没显式分配的通道端点跟它第一条被分配过的成员回线。线路的 `from` / `to` 与和来源坐标重合的 `start` / `end` / `path` 顶点改到对应新节点；拆完后的自环 / 零长度线路与两端落到同一份的通道删掉，成员全没了的通道也删掉。整次调用只记一条历史、只发一条 `splitPoint` 数据变更，返回 `{ autoLines, autoAssignedLines, lineAssignments, changes, ... }`，`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）」 |
@@ -129,22 +130,23 @@
 | `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.from` 预指定起点、只需再点终点；`options` 还支持 `kind`（`'channel'` 新建通道 / `'line'` 新建独立线路，缺省 `'channel'`）/ `circuits`（一次加几条，缺省 1）/ `autoCommit` / `continuous` / `chain` / `name` / `lineId` / `id` / `lineProps` / `linePropsByMember` / `lineItems`（第二段，连同线路一起新建）/ `routing`（`'straight'` / `'orthogonal'`）/ `path`（中间拐点）/ `channelProps` / `channelDraftStyle`（本次草稿的预览样式，含 `dots` / `layer`）/ `handoff`（交接模式：ready 发完收起草稿，自己调 `addChannel` 落地）/ `select`（点中的节点顺手选中）/ `originalEvent`，见「新增通道」 |
-| `getAddChannelDraft()` | 当前新增通道草稿（两个节点的信息与可选方案），没有草稿时为 `null` |
+| `beginAddChannel(options?)` | 进入「新增通道」：缺省点两个节点选起点 / 终点，或由 `options.from` 预指定起点、只需再点终点。`options` 支持 `autoCommit` / `continuous` / `chain` / `singleChannel` / `existingChannel` / `groupId` / `groupIndex` / `circuits` / `name` / `lineId` / `id` / `lineProps` / `linePropsByMember` / `lineData`（第二段）/ `routing` / `path` / `channelProps` / `channelDraftStyle` / `handoff` / `select`（只选中点中的节点）/ `originalEvent`。入口固定为通道语义；旧 `kind` 与 `lineItems` 不再生效。 |
+| `beginAddLine(options?)` | 进入「新增线路」：与 `beginAddChannel` 共用拾取 / 预览 / 连续新增，入口固定为线路语义；不写 `existingChannel` 时只新建独立线路，显式写 `existingChannel: 'newGroup' / 'joinGroup' / 'auto'` 且两端已有通道时才把新回线挂进已有通道。旧 `beginAddChannel({ kind: 'line' })` 已移除，见「10 通道编辑与新增」。 |
+| `getAddChannelDraft()` | 当前新增草稿（两个节点的信息、可选方案与 `lineData`），没有草稿时为 `null` |
 | `updateAddChannelStyle(patch?)` | 字段级合并当前草稿的预览样式（`color` / `width` / `dot` / `dotColor` / `dots` / `layer` / `arrow` / `arrowSize` / `arrowPositions` / `arrowReverse` / `arrowColor` / `circuitSpacing` / `opacity` / `customDraw`）；传 `null` 回到全局 `channelDraftStyle`，没有草稿时什么也不做 |
-| `continueAddChannel(options?)` | 开下一段草稿：连续模式落地时内部自动调（发 `phase: 'restart'`），也可以手动调；草稿已经退出时按 `options` 重新进来 |
+| `continueAddChannel(options?)` | 开下一段草稿：连续模式落地时内部自动调（发 `phase: 'restart'`），也可以手动调；草稿已经退出时按通道入口重新进来。只续配置，不能把当前段切换成线路；旧 `kind` 不生效。 |
 | `cancelAddChannel()` | 取消新增通道（草稿期间按 Esc 等价，会补一条 `phase: 'cancel'`） |
 | `endAddChannel()` | 结束新增通道：静默收掉视图上的示例假通道 / 线路（不补 `cancel` 事件），数据一个字节都不改 —— 结束事件里决定「不新建了」就用它 |
-| `commitAddChannel(input?, options?)` | 把已 `ready` 的草稿落到数据上。`input` 有五类：不传（用草稿 `preferred`）、旧 resolution（字符串，或只含 `type` / `groupId` / `groupIndex` / `channelId` 的对象）、直接线路对象（有 `from` / `to` / `path` / `kind: 'line'` 等线路形状）、直接通道对象（必须有 `lineIds`，缺省新建通道）、容器 `{ channel?, line?, lines?, lineData?, lineItems?, channelGroups?, group?, channelProps?, lineProps?, resolution?, ... }`。对象字段优先、没写的沿用草稿；`line` 缺省表示独立线路，`lines` 才是成员回线表；直接通道对象缺省新建，直接线路对象缺省按独立线路落地，要并进已有分组必须用容器并显式写 `resolution`。`options?: { auto?, continuous?, originalEvent? }` 只影响本次事件与连续草稿。方案读数不能整条回传，只取 `{ type, groupId, groupIndex, channelId }`。完整字段优先级与示例见「10 通道编辑与新增」的 `commitAddChannel` / 对象直传 |
+| `commitAddChannel(input?, options?)` | 把已 `ready` 的草稿落到数据上。第一个参数只接受一个容器对象：`{ channel?, line?, lines? / lineData?, channelGroups? / group?, lineProps?, linePropsByMember?, channelProps?, path?, routing?, resolution?, from?, to?, name?, id? }`；字符串、数组和旧顶层分派字段（`kind` / `circuits` / `channelId` / `groupId` / `lineId` / `lineItems` / `lineIds` 等）都明确失败。`options?: { auto?, continuous?, originalEvent?, select? }`；`select: true` 才选中落地的新回线。完整优先级见「10 通道编辑与新增」。 |
 | `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` 的批量版：一次新增多条通道 / 独立线路（每条是新签名或旧写法，逐条各自认；每项的 `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` 的分工是后者走「通道 / 草稿」那一套 |
+| `getChannelBetween(from, to)` | 两个节点之间的通道读数（只读）：有通道时 `hasChannel: true`，`channelId` / `channelIndex` / `groupCount` / `currentGroupId` 与 `groups` / `group` / `channel`（id / name / lineIds / 分组明细）都给全；没有通道时 `hasChannel: false`、`channel: null`、`groups: []`，端点认不出来返回 `null` |
+| `addChannel(spec, lineData?, group?, options?)` | 程序化**只新建**通道：第一段 `{ from, to, name?, id?, channelProps?, path?, routing?, lineData?, group? }`，第二段线路数据按每项 id 建 `lineIds`，第三段可选分组信息（`{ id?, lineIds?, path? }`）。两端已有通道时整条失败（`reason` 指路 `addChannelGroupLines` / `joinChannelGroupLines`）。`options?: { emit?, select? }`，缺省不选中新回线。 |
+| `addChannelGroupLines(channelId, lineData?, groupInfo?, options?)` | 给已有通道**新加一组**回线：第二段按每项 id 建回线，`groupInfo`（`{ id?, groupId?, path?, ... }`）给新分组的 id 与中间拐点，缺省 `${通道 id}::N`、不带拐点；`options?: { emit?, select? }`，缺省不选中 |
+| `addChannelGroups(channelId, groups, options?)` | 给已有通道**一次新加多组**回线：`groups` 每项 `{ id?, groupId?, path?, lineData? \| lines?, ... }`；旧 `lineItems` 会让整批明确失败且不写数据。逐组落地但只记一步历史、只发一条 `addChannelGroups` 数据变更；`options?: { emit?, label?, select? }` |
+| `joinChannelGroupLines(channelId, groupId?, lineData?, options?)` | 把新回线**并进已有通道的某一组**：第二段线路数据，`groupId` 认分组 id 也认序号（从 0 起、按声明顺序），不传就挑第一个还有余量的分组；`options?: { emit?, select? }` |
+| `addChannels(input, options?)` | `addChannel` 的批量版：一次新建多条通道（每项写法同 `addChannel`），逐条落地但只重排一次场景、只记一步历史、只发一条 `addChannels` 数据变更；返回 `{ ok, count, results, lineIds, channelIds, items }`，失败条目在各自 `reason` 里说明；`options?: { emit?, select? }`，`select` 一次选中全部成功的新回线 |
+| `addLine(spec, lineData?, options?)` | 程序化新增独立线路：`spec` 为 `{ from, to, name?, id?, lineProps?, path?, routing?, lineData? }`，第二段每条按自己的 id 建；不碰任何通道。落地走追加式引擎路径，已有通道声明时也能增量加线；`options?: { emit?, select? }`，缺省不选中 |
+| `addPoint(item, options?)` / `addPoints(items, options?)` / `addLines(items, options?)` | 把**现成的数据对象**追加到末尾（批量导入、从别处拷过来、按坐标补几条）：老数据一条不动，返回 `{ ok, count, indexes, items }`（`addPoint` 另有单条的 `index` / `item`）；`options?: { emit?, select? }`，`select: true` 选中这次新加的要素，缺省不选中 |
 | `removeLine(lineId)` | 移除一条线路（撤销刚落地的新增线路）：挂在通道上的回线会从通道声明里一起摘掉，通道空了整条删掉，返回 `{ ok, line, lineId, index, channelId, removedChannel }` |
 | `removeLines(lineIds)` | 一次移除多条线路（传数组或单条 id）：通道声明与分组跟着收拾、删空的通道整条走，返回 `{ ok, lineIds, indexes, lines, entries, removedChannels }` |
 | `removeChannel(channelId)` | 移除整条通道：它名下的回线一条条摘掉，返回 `{ ok, channelId, lineIds, lines, removedChannel }` |
@@ -201,7 +203,7 @@
 
 返回 `this` 的方法都可以链式调用；返回其它值的方法（`get*` / `list*` / `export*` / `search` / `pick*` / `add*` / `remove*` / `copy*` / `merge*` / `locate*` 这些）在下面的「参数速查」里都标了返回类型。
 
-**怎么确认「组件到底有哪些属性和方法」**：上面那张表按功能分组介绍，下面的「参数速查」把实例的**每个成员逐个列全**（当前 265 个：260 个方法 + `el` / `canvas` / `gl` / `cameraAnimating` / `dataVersion` 五个属性），`options` 表列全 96 个键，数据字段表列全 250 个字段。这三份清单不靠手抄 —— 它们直接对着源码与类型对账：
+**怎么确认「组件到底有哪些属性和方法」**：上面那张表按功能分组介绍，下面的「参数速查」把实例的**每个成员逐个列全**（当前 266 个：261 个方法 + `el` / `canvas` / `gl` / `cameraAnimating` / `dataVersion` 五个属性），`options` 表列全 96 个键，数据字段表列全 250 个字段。这三份清单不靠手抄 —— 它们直接对着源码与类型对账：
 
 - `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 参数速查（逐个方法）
 
-> 265 个成员逐个列全：参数、默认值与返回。
+> 267 个成员逐个列全：参数、默认值与返回。
 
 ### 参数速查（逐个方法）
 
@@ -14,7 +14,7 @@
 
 - **同步方法返回 `this` 时可链式调用**：所有 `update*` / `set*` / `add*` / `remove*`、选中与视角方法都先完成本地状态更新再返回实例；需要结果时用相邻的 `get*` / `list*` 读回。少数返回数组、对象或 `null` 的方法在「返回」列单独标出。
 - **数据写入只发一次通知**：`updatePoint`、`updateLine`、`patch*`、`add*`、`remove*` 等每次成功改数据都会发一条对应的 `dataChange`（底层统一为 `updatePoints` / `updateLines` / `updateChannels` 等类型）并落一步历史；在 `batch()` 里连续调用会合并成一条。`emit: false` 只写数据、不发通知，适合宿主自己在保存成功后统一刷新。
-- **选中方法会同步选中集**：`selectFeatures` / `selectWaypoint` / `selectInBox` 先更新引擎选中态，再同步 `getSelections()`、`getSelectionData()` 与 `isSelected()`。点击、`selectFeatures` / `deselect` / `selectAt` / `focusOn({ select })`、`selectInBox` 改的都是同一份选中 state。真实操作（点击 / Ctrl 取反 / 框选 / `selectAt`）每次成功操作都发 `onSelect`；按引用接口（`selectFeatures` / `deselect` / `focusOn({ select })`）只在实际改变时发。`onSelectChange` 覆盖所有来源且只在集合变化时发，顺序固定为 `onSelect → onSelectChange`。接口路径不会派发 `onClick` / `onDblClick`，`cause` 为 `'api'` 或 `'boxSelect'`；选中通道时两条载荷都带单通道摊平的 `channelId` / `group` / `groups`，多通道看 `channelContexts`。没有命中任何目标时不会凭空选中，`selectWaypoint(null)` 只清拐点、不动要素选中集。
+- **选中方法会同步选中集**：`selectFeatures` / `selectWaypoint` / `selectInBox` 先更新引擎选中态，再同步 `getSelections()`、`getSelectionData()` 与 `isSelected()`。点击、`selectFeatures` / `deselect` / `selectAt` / `focusOn({ select })`、`selectInBox` 改的都是同一份选中 state。真实操作（点击 / Ctrl 取反 / 框选 / `selectAt`）每次成功操作都发 `onSelect`；按引用接口（`selectFeatures` / `deselect` / `focusOn({ select })`）只在实际改变时发。`onSelectChange` 覆盖所有来源且只在集合变化时发，顺序固定为 `onSelect → onSelectChange`。接口路径不会派发 `onClick` / `onDblClick`，`cause` 为 `'api'` 或 `'boxSelect'`；选中通道时两条载荷都在外层带 `channelId` / `group` / `groups` / 本次选中的 `lineIndexes` / `lineIds`（单通道摊平，多通道看 `channelContexts`），`items[]` 里的线路不挂通道字段。没有命中任何目标时不会凭空选中，`selectWaypoint(null)` 只清拐点、不动要素选中集。
 - **视角方法会更新相机**：`focusOn` / `flyTo` / `zoomTo` / `setCamera` / `fitView` 成功落到目标范围后更新 `getCamera()`，并触发 `onCameraChange`；目标认不出来、视口尚未量出或参数非法时保持当前相机。`focusOn` 缺省只居中、不改比例；`flyTo` 只是同一条目标解析的平滑版，飞行中用户拖拽 / 滚轮、再次飞行或任何程序化改相机都会停在当前帧。`zoom` / `scale` / `center` / `padding` / `maxZoom` 只影响这一次调用，不会改写持久配置。
 - **只读方法返回快照或副本**：`getSelectionData()`、`getFilter()`、`getStats()`、`snapshotScene()`、`listPoints()` / `listLines()` 返回的是调用当时的读数，不会随后续数据变更自动更新；需要最新值就再调一次。对象型字段的含义以 `types.d.ts` 同名接口为准。
 - **失败是可控的**：找不到 id / 下标越界 / 不支持的写法会跳过这一条，能返回 `null` 或 `{ ok: false, reason }` 的就按对应签名返回；需要排查时订阅 `onWarning`。异步筛选 / 搜索通过完成事件、`getFilterResult()` / 搜索结果或返回的 Promise 取结果，不要在调用下一行假定 Worker 已经跑完。
@@ -58,8 +58,8 @@
 | `zoomBy(factor, origin?)` | `factor: number` 缩放倍数（`> 1` 放大、`< 1` 缩小）；`origin?: [number, number]` 缩放中心（画布 CSS 像素，缺省画布中心） | `this` |
 | `zoomTo(scale, origin?)` | `scale: number` 目标缩放值（世界单位 → CSS 像素的比例）；`origin?: [x, y]` 缩放中心 | `this` |
 | `zoomToBounds(bounds, padding?)` | `bounds: GisViewBounds` 要装进画面的世界矩形 `[minX, minY, maxX, maxY]`（也认 `{ minX, minY, maxX, maxY }`）；`padding?: number` 四周留白 | `this` |
-| `focusOn(target, options?)` | `target: GisViewFocusTargets` 要对准的东西：id / `{ type: 'point' \| 'line' \| 'channel' \| 'group', id \| index }` / `{ channelId }`（整条通道）/ `{ type: 'group', channelId?, groupId }` / `[x, y]` 坐标 / 矩形 / `{ lngLat }` / `{ center }`，或者**一批**（数组取整体包围盒）。字符串按「先节点、再线路」，裸字符串不能表示通道；同 id 用显式 `type` 消歧，分组必须用 `type: 'group'`（`groupId` 全局唯一时可省略 `channelId`）。**缺省只居中、比例一点不动**；`options.zoom: true` 才按解析出的真实范围适配，四类目标共用这一条、没有额外放大倍率；`scale` 优先级高于 `zoom`，`maxZoom` 只给单点 / 单线这类零面积目标补最小范围。`options?: GisViewFocusOptions`：`zoom: true` 显式适配、`scale` 直接给比例、`center: true` 显式只居中（与缺省一致）、`padding` 要四周留白（CSS 像素，缺省 40）、`maxZoom` 限制这次适配的最大比例、`select` 顺带选中（`true` 选这次目标，也可另给一批写法）、`mode` 决定怎么并进当前选中集。目标认不出来或参数非法时什么都不做 | `this`（相机更新后发 `onCameraChange`；`select` 生效时另发 `onSelect` / `onSelectChange`） |
-| `flyTo(target, options?)` | 目标与世界坐标解析、`zoom` / `scale` / `center` / `padding` / `maxZoom` / `select` / `mode` 均与 `focusOn` 同义。`options?: GisViewFlyOptions` 另认 `duration`（毫秒，缺省 450；`<= 0` 立即落位）与 `easing`（`'linear'` / `'ease-in'` / `'ease-out'` / `'ease-in-out'`，缺省 `'ease-in-out'`，也可给自定义 `(progress) => eased`）。中心线性、比例按对数插值；系统 `prefers-reduced-motion: reduce` 时立即落位。再次 `flyTo`、用户拖拽 / 滚轮、`setCamera` / `centerOn` / `zoom*` / `fitView` / `resetView` / `applyInitialView` 都会停在当前帧 | `this`（相机变化时发 `onCameraChange`；`select` 生效时另发选中事件） |
+| `focusOn(target, options?)` | `target: GisViewFocusTargets` 要对准的东西：id / `{ type: 'point' \| 'line' \| 'channel' \| 'group', id \| index }` / `{ channelId }`（整条通道）/ `{ type: 'group', channelId?, groupId }` / `[x, y]` 坐标 / 矩形 / `{ lngLat }` / `{ center }`，或者**一批**（数组取整体包围盒）。字符串按「先节点、再线路」，裸字符串不能表示通道；同 id 用显式 `type` 消歧，分组必须用 `type: 'group'`（`groupId` 全局唯一时可省略 `channelId`）。**缺省只居中、比例一点不动**；`options.zoom: true` 才按解析出的真实范围适配，四类目标共用这一条、没有额外放大倍率；`scale` 优先级高于 `zoom`，`maxZoom` 只给单点 / 单线这类零面积目标补最小范围。`options?: GisViewFocusOptions`：`zoom: true` 显式适配、`scale` 直接给比例、`padding` 要四周留白（CSS 像素，缺省 40）、`maxZoom` 限制这次适配的最大比例、`select` 顺带选中（`true` 选这次目标，也可另给一批写法）、`mode` 决定怎么并进当前选中集。目标认不出来或参数非法时什么都不做 | `this`（相机更新后发 `onCameraChange`；`select` 生效时另发 `onSelect` / `onSelectChange`） |
+| `flyTo(target, options?)` | 目标与世界坐标解析、`zoom` / `scale` / `padding` / `maxZoom` / `select` / `mode` 均与 `focusOn` 同义。`options?: GisViewFlyOptions` 另认 `duration`（毫秒，缺省 450；`<= 0` 立即落位）与 `easing`（`'linear'` / `'ease-in'` / `'ease-out'` / `'ease-in-out'`，缺省 `'ease-in-out'`，也可给自定义 `(progress) => eased`）。中心线性、比例按对数插值；系统 `prefers-reduced-motion: reduce` 时立即落位。再次 `flyTo`、用户拖拽 / 滚轮、`setCamera` / `centerOn` / `zoom*` / `fitView` / `resetView` / `applyInitialView` 都会停在当前帧 | `this`（相机变化时发 `onCameraChange`；`select` 生效时另发选中事件） |
 | `flyToCamera(camera, options?)` | `camera: GisViewCameraTarget` 直接给相机目标 `{ center?, scale? }`：没写 center / scale 的那一项沿用当前相机，不经过要素解析，也不改选中与数据；`options?: GisViewFlyCameraOptions` 的 `duration` / `easing` 与 `flyTo` 同义。中心 / 比例插值、减少动态效果、用户手势取消都走同一条相机动画 | `this`（相机变化时发 `onCameraChange`；目标非法时保持当前相机） |
 | `search(input)` | `input: string \| GisViewSearchOptions` 关键字，或 `{ keyword, scope, fields, limit }` 这类选项。`scope` 可选 `'points'` / `'lines'` / `'channels'` / `'groups'`，也认与 `focusOn` 一致的单数别名 `'point'` / `'line'` / `'channel'` / `'group'` 及数组；省略或写错时四类全搜。`limit` 对每一类分别计数。返回的 `groups` / `hits` 带分组命中（`channelIndex` / `groupId` / `groupIndex`，`item` 是轻量快照）—— **只返回结果、不动视角**，要定位就自己调 `focusOn(result.hits, …)` | `GisViewSearchResult`：`keyword` / `scope` / `points` / `lines` / `channels` / `groups` / `hits` / `total` / `truncated` / `durationMs` |
 | `searchAsync(input)` | 同上；分组范围的当前轻量快照会随请求交给 Worker | `Promise<GisViewSearchResult>`：多一个 `worker`（是不是在 Worker 里算的）与 `stale`（回来时数据已经改过、或又搜过一次，这一份不作数了） |
@@ -149,11 +149,12 @@
 | `selectFeatures(refs, options = {})` | `refs: GisViewSelectionRefs` 要选中的东西：节点 / 线路 id、id 数组、`{ type, index }`、通道写法（`{ type: 'channel', channelId \| channelIndex }`，可再给 `groupIds` / `lineIds` / `lineIndexes` 取子集）、分组写法（`{ type: 'group', channelId?, groupId }`，`groupId` 全局唯一时可省略通道）、拾取载荷 / 搜索命中，传 `null` / 空数组等于清空一份新的选中集。认不出来的条目逐条跳过；`options?: GisViewSelectOptions` 只有 `mode`：`'replace'` 缺省换一份、`'add'` 追加、`'toggle'` 在就取消 / 不在就选上、`'remove'` 去掉 | `this`（选中真的变了才按 `onSelect → onSelectChange` 发，`cause` 为 `api`；载荷带通道上下文） |
 | `selectWaypoint(lineRef, pathIndex?, options = {})` | `lineRef` 线路 id、`lines` 下标或 `{ lineIndex, pathIndex }` / `{ lineId, pathIndex }` 对象；`pathIndex?: number` 必须是 `getWaypoints()` 给出的可编辑中间拐点下标（首尾端点不算，通常直接从读数里取）；`options?: GisViewSelectOptions` 的 `mode` 决定所在线路怎么并进当前选中集（缺省 `replace`）。有效拐点会同时选中线路；线路不存在 / 下标非法 / 拐点不可见时只清拐点选中，不猜位置；传 `null` 也只清拐点，不改要素选中集 | `this` |
 | `deselect(refs = null)` | `refs?: GisViewSelectionRefs` 要取消的东西（写法与 `selectFeatures` 一致：节点 / 通道 / 线路 / 混合一批）；不传 / `null` 等于取消全部（= `selectFeatures(null)`），空数组是「没有目标」什么都不做 | `this`（选中真的变了才按 `onSelect → onSelectChange` 发，`cause` 为 `api`；清空时 `onSelect` 载荷为 `null`） |
-| `getSelections()` | 无 | `GisViewPickResult[]` |
+| `getSelections()` | 无 | `GisViewPickResult[]`：选中项原始读数；通道回线不带 `channelId` / `channelIndex` / `groupId` / `groups`，单条归属用 `getLineChannel(index)` |
+| `getSelectionInfo()` | 无 | `GisViewSelectionInfo`：`{ ids, count, points, lines, channels }`，通道回线按通道算一个；与 `onSelectChange` 顶层同口径并按键集合引用缓存 |
 | `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`） |
+| `getSelectionData()` | 无 | `GisViewSelectionData`：`{ ids, count, pointCount, lineCount, channelCount, points, lines, channels, items, pointIndexes, lineIndexes, bounds }`（`bounds` 是世界包围盒，空选中时 `null`；`items` 的线路不带通道字段，`channels` 是去重后的所属通道） |
 | `getCascadeHighlight()` | 无 | `GisViewCascadeHighlightInfo \| null`：当前点击级联高亮的来源、范围与节点 / 线路读数 `{ origin, scope, points, lines, pointIndexes, lineIndexes }`，不改变选中集 |
-| `selectInBox(box, options = {})` | `box: GisViewRect` **画布 CSS 像素**矩形 `{ x, y, width, height }`（与手动框选同一套坐标）；`options?: GisViewSelectInBoxOptions`：`selectionKinds` 临时覆盖这一次保留哪几类（`'point'` / `'line'` / `'channel'`、数组、`'all'` / `true` / `false` / `null`，不写沿用全局 `selectionKinds`），`originalEvent` 原样带进 `onSelect`；第二段也兼容旧的 Event 写法。空框不会选中任何要素 | `this`（每次框选都发 `onSelect`，空框为 `null`；集合变化时再发 `onSelectChange`，顺序 `onSelect → onSelectChange`，`cause` 为 `boxSelect`） |
+| `selectInBox(box, options = {})` | `box: GisViewRect` **画布 CSS 像素**矩形 `{ x, y, width, height }`（与手动框选同一套坐标）；`options?: GisViewSelectInBoxOptions`：`selectionKinds` 临时覆盖这一次保留哪几类（`'point'` / `'line'` / `'channel'`、数组、`'all'` / `true` / `false` / `null`，不写沿用全局 `selectionKinds`），`originalEvent` 原样带进 `onSelect`。空框不会选中任何要素 | `this`（每次框选都发 `onSelect`，空框为 `null`；集合变化时再发 `onSelectChange`，顺序 `onSelect → onSelectChange`，`cause` 为 `boxSelect`） |
 | `beginCopyPoint(options = {})` | `options: GisViewCopyStartOptions`：`id` / `index` / `item` 三选一给来源，都不给就进入「下一次点选节点」模式；`coordinate` / `screen` 是落点（缺省按 `copy.offset`）；`follow` 让预览跟指针；`autoCommit` 覆盖 `copy.autoCommit`；`commit: true` 出预览即落地；`via` / `originalEvent` 原样带回。必须配置 `copy`（`enabled` 不为 `false`），否则返回 `null`。预览节点插在 `points` 末尾且不带 id，不会把绑定源 id 的线路 / 通道带过去 | `GisViewPointCopyPayload \| null`：`phase: 'start'` 的预览载荷；来源认不出来时返回 `null` |
 | `commitPointCopy()` | 无：把当前复制预览落地，先发 `commit`、落地后发 `end`；`commit` 阶段载荷里的 `cancel()` 可以拦住这次复制 | `GisViewPointCopyPayload \| null`：成功的 `end` 载荷；没有预览或已被取消时为 `null` |
 | `cancelPointCopy()` | 无：撤掉预览并补一条 `cancel`，数据与历史不动 | `GisViewPointCopyPayload \| null`：取消载荷；没有预览时为 `null` |
@@ -169,7 +170,7 @@
 | `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` 可直接作为后端事务输入 |
+| `splitPoint(source, parts, options = {})` | `source: GisViewPointRef` 要拆的节点；`parts: GisViewSplitPointPart[]` 至少两份，每份可直接写节点字段或放进 `item`，并用 `lines` / `channels` / `channelFrom` / `channelTo` 分配线路与通道端点；`options?: GisViewSplitPointOptions`：`keepSourceId`（缺省 `true`，第一份沿用来源 id）/ `label` / `autoLines?: 'first' \| 'alternate'`（缺省 `first` 跟第一份；`alternate` 按「通道成组、独立线路单条」轮流给负载最少的一份，解除合并推荐） | `GisViewSplitPointOutcome`：`{ ok, reason, source, items, indexes, pointIds, linesChanged, removedLines, removedLineIds, removedLineIndexes, channelsChanged, removedChannels, removedChannelIds, autoLines, autoAssignedLines, lineAssignments, skipped, changes }`；`lineAssignments` 每项 `{ index, pointId, lineIds, lineCount }`；`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` |
 | `commitPointMerge()` | 无：收掉「已确认、数据已由使用方并好」的合并状态；`mergePoints` / `resolvePointMerge` 的正常路径由组件自己调用，只有完全自建合并落地流程时才手动调 | `boolean`：真的收掉了一个待确认合并为 `true`，没有可收的状态为 `false` |
@@ -208,21 +209,22 @@
 | `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` 草稿配置：`from`（预指定起点，下一步只选终点）/ `kind` / `circuits` / `autoCommit` / `continuous` / `chain` / `name` / `lineId` / `id` / `lineProps` / `linePropsByMember` / `lineItems`（第二段）/ `routing` / `path`（中间拐点）/ `channelProps` / `channelDraftStyle`（本次草稿的预览样式，含 `dots` 与 `layer`）/ `handoff`（交接模式）/ `select`（点中的节点顺手选中，走 `onSelect` 那一套）/ `originalEvent` | `this`（只负责那条示例假通道，真正新增走 `commitAddChannel` / `addChannel`） |
+| `beginAddChannel(options = {})` | `options?: GisViewChannelDraftOptions` 草稿配置：`from`（预指定起点，下一步只选终点）/ `circuits` / `singleChannel`（已有通道时缺省按 `block` 失败）/ `existingChannel?: 'block' \| 'newGroup' \| 'joinGroup' \| 'auto'` / `groupId` / `groupIndex`（`joinGroup` 的目标分组，序号从 0 起，都写以 `groupId` 为准）/ `autoCommit` / `continuous` / `chain` / `name` / `lineId` / `id` / `lineProps` / `linePropsByMember` / `lineData`（第二段）/ `routing` / `path`（中间拐点）/ `channelProps` / `channelDraftStyle`（本次草稿的预览样式，含 `dots` 与 `layer`）/ `handoff`（交接模式）/ `select`（点中的节点顺手选中，走 `onSelect` 那一套）/ `originalEvent`；入口固定为通道语义，旧 `kind` / `lineItems` 已移除且不会生效 | `this`（只负责那条示例假通道，真正新增走 `commitAddChannel` / `addChannel`） |
+| `beginAddLine(options = {})` | `options?: GisViewChannelDraftOptions` 与 `beginAddChannel` 同一套草稿配置，`kind` 恒为 `line`；不写 `existingChannel` 时只加独立线路，显式 `existingChannel: 'newGroup' \| 'joinGroup' \| 'auto'` 且两端已有通道时把新回线挂进通道；`joinGroup` 可写 `groupId` / `groupIndex`，`singleChannel` 不生效 | `this`（真正新增走 `commitAddChannel` / `addLine`） |
 | `getAddChannelDraft()` | 无 | `GisViewChannelDraftPayload \| null` |
 | `updateAddChannelStyle(patch = {})` | `patch?: GisViewChannelDraftStyle \| null` 字段级合并的预览样式（箭头位置 / 多回线间距 / 两端 `dots` / 层级 `layer` / 自绘等）；传 `null` 回到全局 `channelDraftStyle` | `this` |
-| `continueAddChannel(options = {})` | `options?: GisViewChannelDraftOptions` 开下一段草稿（写法与 `beginAddChannel` 一致，不传就沿用这一段原来的） | `this` |
+| `continueAddChannel(options = {})` | `options?: GisViewChannelDraftOptions` 开下一段草稿（写法与 `beginAddChannel` 一致，不传就沿用这一段原来的；可以改 `singleChannel` / `existingChannel` / `groupId` / `groupIndex` 等配置，但不能切换通道 / 线路入口） | `this` |
 | `cancelAddChannel()` | 无 | `this`（收掉草稿并补一条 `phase: 'cancel'`） |
 | `endAddChannel()` | 无 | `this`（静默收掉视图上的示例假通道 / 线路，数据不动、不补事件） |
-| `commitAddChannel(input?, options?)` | `input?: GisViewChannelAddResolution \| GisViewChannel \| GisViewLine \| GisViewChannelAddCommitInput`，五种写法：① 不传 / `null` = 用草稿 `preferred`；② 旧 resolution：字符串或只含非 `undefined` 的 `type` / `groupId` / `groupIndex` / `channelId` 的对象；③ 直接线路对象：没有 `lineIds` 数组，且写了 `kind: 'line'` / `path` / `from` / `to` / `start` / `end` 之一，业务字段与自己的 `lineProps` 透传到新线路；④ 直接通道对象：`Array.isArray(lineIds)` 且没有容器键，`lineIds` 逐条作新回线 id 种子、`groups` 作分组声明、自己的 `lineProps` 对所有新回线生效，其余字段进 `channelProps`，缺省 `resolution: 'newChannel'`；⑤ 容器：出现 `channel` / `line` / `lines` / `lineData` / `lineItems` / `channelGroups` / `group` / `channelProps` / `resolution` 任一键（只写 `lineProps` 也算）。容器里 `line` 缺省是独立线路，`lines` 是成员表（给了几条建几条，空数组沿用草稿）；`channel.lineIds` 只在没有 `lines` 时当种子。字段优先级：`from` / `to` = 顶层 → `channel` → `line` → `lineItems` 第一个对象项（裸 id 跳过）→ 草稿；`path` = 顶层 → `line` → `channel` → 草稿；分组 = `channelGroups` → `group` → `channel.groups`；容器 `lineProps` = 草稿 → 顶层 → `line.lineProps` → 逐条，**不读 `channel.lineProps`**；`channelProps` = 草稿 → `channel` 业务字段 → 顶层 `channelProps`。直接线路 / 直接通道对象默认新建，要并进已有分组必须用容器并显式写 `resolution`。`options?: { auto?: boolean; continuous?: boolean; originalEvent?: Event \| null }`：`auto` 只标记自动提交，`continuous: false` 强制本次后结束，`originalEvent` 带回重开的草稿。`ready` 的方案对象不能整条回传，只取 `{ type, groupId, groupIndex, channelId }` 子集。调用前草稿必须 `ready`，否则不写数据；没有草稿的程序化新增用 `addChannel` / `addLine`。完整示例见「10 通道编辑与新增」与「18 逐方法示例」 | `GisViewChannelAddResult` |
+| `commitAddChannel(input?, options?)` | `input?: GisViewChannelAddCommitInput`，只接受一个容器对象；不传 / `null` 用草稿的推荐方案。字段：`channel?`（通道对象与 `groups`）/ `line?`（独立线路对象）/ `lines?` 或 `lineData?`（成员回线表）/ `channelGroups?` 或 `group?`（分组声明）/ `lineProps?` / `linePropsByMember?` / `channelProps?` / `path?` / `routing?` / `resolution?` / `from?` / `to?` / `name?` / `id?`。`lines` 与 `lineData` 同义且 `lines` 优先，空数组沿用草稿；`channel.lineIds` 只在线路表缺省时当回线 id 种子。字段优先级：`from` / `to` = 顶层 → `channel` → `line` → `lines` 第一个对象项 → 草稿；`path` = 顶层 → `line` → `channel` → 草稿；分组 = `channelGroups` → `group` → `channel.groups`；`lineProps` = 草稿 → 顶层 → `line.lineProps` → 逐条；`channelProps` = 草稿 → `channel` 业务字段 → 顶层 `channelProps`。`resolution` 收 `'auto'` / `'newChannel'` / `'newGroup'` / `'joinGroup'` / `'newLine'` 或 `{ type, groupId?, groupIndex?, channelId? }`。旧顶层分派字段（`kind` / `circuits` / `channelId` / `groupId` / `lineId` / `lineItems` / `lineIds` / `start` / `end` 等）明确失败。`options?: { auto?: boolean; continuous?: boolean; originalEvent?: Event \| null; select?: boolean }`；`select: true` 才选中这次新建的全部回线，缺省不动选中集。调用前草稿必须 `ready`；没有草稿的程序化新增用 `addChannel` / `addLine` | `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` / `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` 同一套写法；`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` |
+| `addChannel(channel, lineData?, group?, options?)` | `channel: GisViewChannelAddSpec` 通道信息 `{ from, to, name?, id?, channelProps?, path?, routing?, lineData?, group? }`（后两个是第二 / 第三段写在对象上的别名）；`lineData?: GisViewChannelLineData` 线路数组（`Partial<GisViewLine>` / `string` / `number` 的一条或一批，按每项 id 建 `lineIds`）；`group?: GisViewChannelAddGroup \| GisViewChannelAddGroup[]` 可选分组信息 `{ id?, lineIds?, path? }`；`options?: { emit?: boolean; select?: boolean }`，缺省不选中。只新建通道：两端已有通道时整条失败；旧 `circuits` / `resolution` / `kind` / `channelId` / `lineItems` 等入参已移除。`path` 是中间拐点，通道只写骨架拐点 | `GisViewChannelAddResult`（`channelLineIds` 是落地后通道的完整成员表） |
+| `addChannelGroupLines(channelId, lineData?, group?, options?)` | `channelId` 目标通道 id；`lineData?: GisViewChannelLineData` 这次新建的线路数组（按每项 id 建回线）；`group?: GisViewChannelAddGroup` 新分组信息 `{ id?, path? }`（缺省 `${通道 id}::N`、不带拐点）；`options?: { emit?: boolean; select?: boolean }` | `GisViewChannelAddResult` |
+| `addChannelGroups(channelId, groups, options = {})` | `channelId` 目标通道 id；`groups: GisViewChannelAddGroupInput \| GisViewChannelAddGroupInput[]` 每项 `{ id?, groupId?, path?, lineData? \| lines? }`（线路数据与 `addChannel` 第二段同一份写法，`lineItems` 已移除）；`options?: { emit?: boolean; label?: string; select?: boolean }`，`emit: false` 只落地不通知 | `GisViewAddChannelGroupsResult` |
+| `joinChannelGroupLines(channelId, groupId, lineData?, options?)` | `channelId` 目标通道 id；`groupId?: string \| number` 并进哪一组（认分组 id 也认序号，从 0 起；不传挑第一个还有余量的分组）；`lineData?: GisViewChannelLineData` 这次新建的线路数组；`options?: { emit?: boolean; select?: boolean }` | `GisViewChannelAddResult` |
+| `addChannels(input, options?)` | `input: GisViewChannelAddSpec \| GisViewChannelAddSpec[]` 一条或一批声明（每条与 `addChannel` 第一段同一套写法，可在项内写 `lineData` / `group`；`routing: 'orthogonal'` 自动正交折线，`path` 是中间拐点）；`options?: { emit?: boolean; select?: boolean }`，`emit: false` 只改数据不发 `dataChange`，缺省不选中 | `GisViewAddChannelsResult` |
+| `addLine(input, lineData?, options?)` | `input: GisViewLineAddSpec` 独立线路 `{ from, to, name?, id?, lineProps?, path?, routing?, lineData? }`；第二段 `GisViewChannelLineData` 与 `addChannel` 的线路数组同一份 —— 每项可以只写一个 id（裸字符串 / 数字按 `{ id }` 收）、写对象给逐条字段，不写就按 `from-to-序号` 自动编号；`options?: { emit?: boolean; select?: boolean }`，缺省不选中。旧 `circuits` / `kind` / `lineItems` / 通道字段已移除 | `GisViewChannelAddResult` |
 | `removeLine(lineId)` | `lineId: string \| number` 要删的线路 id | `GisViewRemoveLineResult` |
 | `removeLines(lineIds)` | `lineIds: string \| number \| 数组` 一次删多条 | `GisViewRemoveLinesResult` |
 | `removeChannel(channelId)` | `channelId` 通道 id | `GisViewRemoveChannelResult` |