gis-view-webgl2 0.1.7 → 0.1.9

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

@@ -1,6 +1,6 @@
 # 17 参数速查（逐个方法）
 
-> 265 个成员逐个列全：参数、默认值与返回。
+> 273 个成员逐个列全：参数、默认值与返回。
 
 ### 参数速查（逐个方法）
 
@@ -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 已经跑完。
@@ -38,7 +38,7 @@
 | `updateBackground(background?)` | `background?: GisViewBackground` 新的背景层（底色 / 图片 / GeoJSON）；不传等于清掉 | `this` |
 | `getResolvedBackground()` | 无 | `GisViewResolvedBackground` |
 | `getBackgroundLabels()` | 无 | `GisViewResolvedBackgroundLabel[] \| null` |
-| `batch(fn, options?)` | `fn: () => T` 这一批里要做的改动（内部调 `updatePoint` / `updateLine` / `updateData` 都收成一条）；`options.label?: string` 给这一步历史起名 | `fn` 的返回值 |
+| `batch(fn, options?)` | `fn: () => T` 这一批里要做的增删改 / 分组操作（内部调 `patchPoints` / `patchLines` / `updateChannel`、`removePoints` / `removeLines` / `removeChannel`、`splitChannelGroups` / `removeChannelGroup` 等都会收成一条）；`options.label?: string` 给这一步历史起名 | `fn` 的返回值 |
 | `resize()` | 无（改过祖先 `transform: scale` / 容器尺寸后手动同步一次；CSS `zoom` 会自动感知） | `this` |
 | `refresh(options?)` | `options?: { reflow?: boolean }` 传 `false` 只重画一帧（跳过整份重解析：数据没变、只想重画时用）；不传或 `true` 走整份重建 | `this` |
 | `whenRendered()` | 等下一帧画完（Promise）：兑现那一帧的载荷（`frame` 是帧序号，`type` / `changes` / `counts` 说明这一帧带上了哪几次数据变更）；引擎下一次渲染结束时兑现，视图销毁时兑现 `null` | `Promise<GisViewDataRenderedPayload \| null>` |
@@ -58,15 +58,20 @@
 | `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`（回来时数据已经改过、或又搜过一次，这一份不作数了） |
-| `setCamera(camera)` | `camera: Partial<GisViewCamera>` 要改的相机字段 `{ x, y, scale }`（只写一个也行） | `this` |
+| `setCamera(camera)` | `camera: Partial<GisViewCamera>` 要改的相机字段 `{ center, scale }`（只写一个也行） | `this` |
 | `getCamera()` | 无 | `GisViewCamera` |
+| `getScale()` | 无 | `number`：当前比例（像素 / 世界单位），与 `getCamera().scale` 同一份读数 |
+| `setScale(scale, origin?)` | `scale: number` 目标比例；`origin?: [number, number]` 画布 CSS 像素锚点（缺省视口中心） | `this`：立即改比例，受 `minScale` / `maxScale` 夹取 |
+| `getCenter()` | 无 | `[number, number]`：当前视图中心，返回独立副本；改返回值不会动引擎 |
+| `setCenter(center)` | `center: [number, number]` 新的视图中心 | `this`：只移动中心、保留当前比例，可链式调用 |
 | `stopCameraAnimation()` | 无 | `this`：停止当前相机飞行并停在当前帧；没有飞行时是空操作 |
 | `getCameraAnimation()` | 无 | `GisViewCameraAnimation \| null`：`{ active, progress, duration, from, to }`，`progress` 是时间进度（0 ~ 1），没有动画时 `null` |
+| `getIdleTime()` | 无 | `number`：距创建或上一次指针 / 滚轮 / 键盘操作的毫秒数；程序化 API 调用不重置 |
 | `getZoomBaseScale()` | 无 | `number` 缩放联动的基准比例（`pointZoomScale` / `lineZoomScale` 共用那一份；缺省是首次适应视图时的 `camera.scale`） |
 | `setZoomBaseScale(scale?)` | `scale?: number` 新的基准比例；不传取当下相机的比例（把现在这一屏当成「原样大小」） | `this` |
 | `getBounds()` | 无 | `GisViewBounds`：每次返回独立副本；重复调用命中数据包围盒缓存，改点 / 改线 / 追加或拖拽后下一次读数自动重建 |
@@ -149,11 +154,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'` / `'lineEndpoints'` / `'channelEndpoints'`、数组、`'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` |
@@ -167,9 +173,9 @@
 | `pastePoint(options = {})` | `options: GisViewPasteOptions`：`screen` / `coordinate`（落在哪里，缺省光标位置）、`offset`（屏幕像素偏移）、`select`（粘贴后选中新节点）、`label` / `via` / `originalEvent`；单节点且快照里没有内部线路 / 通道时仍走原预览，其余走整组落地 | `GisViewCopyItem \| GisViewBatchCopyPayload \| null` |
 | `pastePoints(options = {})` | `options` 同上；强制整组粘贴（单节点也走批量路），返回带 `count` / `indexes` / `lines` / `channels` / `revert()` 的完整载荷 | `GisViewBatchCopyPayload \| null` |
 | `getPointClipboard()` | 无 | `GisViewClipboardItem \| null` |
-| `mergePoints(source, target, options = {})` | `source: GisViewPointRef` 被并入的节点（并完就没了）、`target: GisViewPointRef` 接收的节点、`options?: { originalEvent?: Event \| null; item?: GisViewPoint }`：`item` 可以给一份已经改好的合并结果（确认阶段改过 `payload.item` 之后就是它） | `GisViewMergeOutcome` |
+| `mergePoints(source, target, options = {})` | `source: GisViewPointRef` 被并入的节点（并完就没了）、`target: GisViewPointRef` 接收的节点、`options?: { originalEvent?: Event \| null; item?: GisViewPoint }`：`item` 可以给一份已经改好的业务字段结果（确认阶段改过 `payload.item` 之后就是它）；未给 `item` 时只对 `merge.maxKeys` 列出的字段取双方最高值（缺省空表，全部字段取保留节点，数组 / 逗号字符串均可）；最终 `id`、坐标与 `mergeInfo` 由组件维护 | `GisViewMergeOutcome`：保留节点写完整 `mergeInfo`，受影响通道写轻量 `mergeInfo` |
 | `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[] \| null` 省略 / `null` / `[]` 且节点带 `mergeInfo` 时自动解除合并，传数组时至少两份，每份可直接写节点字段或放进 `item`，并用 `lines` / `channels` / `channelFrom` / `channelTo` 分配线路与通道端点；`options?: GisViewSplitPointOptions`：`keepSourceId`（缺省 `true`，第一份沿用来源 id）/ `label` / `select`（缺省 `false`，不选中结果且保留无关选中；`true` 选中全部结果节点）/ `autoLines?: 'first' \| 'alternate'`（缺省 `first` 跟第一份；`alternate` 按「通道成组、独立线路单条」轮流给负载最少的一份，手工拆分推荐） | `GisViewSplitPointOutcome`：`{ ok, reason, source, items, indexes, pointIds, linesChanged, removedLines, removedLineIds, removedLineIndexes, channelsChanged, removedChannels, removedChannelIds, autoLines, autoAssignedLines, lineAssignments, autoRestored, mergeSourceIds, skipped, changes }`；自动解除时 `autoRestored: true`、`mergeSourceIds` 给恢复的来源 id；`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 +214,23 @@
 | `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` |
+| `getDirectConnections(pointIds)` | `pointIds: string \| number \| Array<string \| number>` 一组节点 id（单条也收）；只查集合内部的直接边，两端必须能查到节点，去重后少于两个返回空表 | `GisViewDirectConnection[]`：`type` 为 `'channel'` / `'line'` 的联合；每项带 `from` / `to`（`{ id, index, item }`）与 `item`，通道项有 `channelId` / `channelIndex` / `lineIds`，线路项有 `lineId` / `lineIndex`；空结果严格为 `[]` |
+| `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` |
@@ -267,7 +275,7 @@
 | `getLabelStates(kind?)` | `kind?: 'point' \| 'line'` 只看一类（不传两类都给） | `GisViewLabelState[]` |
 | `getLabels(kind, ref?)` | `kind: 'point' \| 'line'` 看哪一类；`ref?: GisViewFeatureRef` 看哪一个要素（不传 = 给「有标签的要素」清单） | `GisViewLabelListItem[] \| null` / `GisViewItemLabelsInfo[]` |
 | `setLabelContent(content, options = {})` | `content: GisViewLabelContent \| GisViewLineLabelContent \| null` 新内容（模板串 `{字段}` / 函数 / `null` 回到默认）；`options: GisViewSetLabelContentOptions` `kind` 缺省 `'point'`（`'line'` / `'both'`）、`labelId` 缺省 `'default'`（`'*'` 换配置里的每一条） | `this` |
-| `updateLabel(kind, ref, patch)` | `kind` 哪一类；`ref` 哪个要素；`patch: GisViewLabelPatch` 要改的项：`labelId`（改哪一条，缺省 `'default'`）、`content` / `html` / `position` / `style`（增量合并）/ `offset` / `visibility` / `parallel` / `hidden`，写 `null` 回到默认 | `GisViewLabelState \| null` |
+| `updateLabel(kind, ref, patch)` | `kind` 哪一类；`ref` 哪个要素；`patch: GisViewLabelPatch` 要改的项：`labelId`（改哪一条，缺省 `'default'`）、`content` / `html` / `position` / `style`（增量合并）/ `offset` / `visibility` / `parallel` / `hidden` / `zIndex` / `followNodeZIndex` / `zoomScale`，写 `null` 回到默认 | `GisViewLabelState \| null` |
 | `addLabel(kind, ref, definition = {}, labelId?)` | `kind` / `ref` 同上；`definition: GisViewItemLabel` 一条标签的定义（与配置里同一套写法：`content` / `position` / `offset` / `style` / `html`…）；`labelId?: string` 指定 id（缺省自动取 `note1` / `note2`…） | `GisViewLabelState \| null` |
 | `removeLabel(kind, ref, labelId?)` | `kind` / `ref`；`labelId?: string` 删哪一条（缺省 `'default'`） | `GisViewRemoveLabelResult \| null` |
 | `addLabels(kind, refs, definition = {}, options = {})` | `kind`；`refs: GisViewLabelRef \| 数组` 批量定位（单个 / 数组 / `'all'` / `'visible'` / `'selection'`，线路还认 `{ channel }` / `{ group }`）；`definition` 一条定义、定义数组，或 `(item, index) => 定义`；`options: { labelId?, overwrite? }` 已有同 id 的缺省跳过、`overwrite: true` 覆盖 | `GisViewAddLabelsResult` |
@@ -305,7 +313,7 @@
 
 | 方法 | 参数（名字: 类型 = 默认值） | 返回 |
 | --- | --- | --- |
-| `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'`） |
+| `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`（只导指定要素）、`selectionKinds`（仅 `viewport`，支持 `lineEndpoints` / `channelEndpoints`）、`withLines: false`（selection 不要两端都在集合里的线路）、`labels`、`extra`。`format: 'full'` / `'input'` 返回可直接回灌的数据，不夹带 `scope` / `counts` 读数 | `GisViewExportDataResult \| GisViewDocument`（`format: 'full'`） |
 | `exportImage(options = {})` | `options?: GisViewExportImageOptions`：`type`（`'image/png'` / `'image/jpeg'` / `'image/webp'` / `'svg'`）、`quality`（JPEG / WebP 0 ~ 1）、`scale`（导出倍数；SVG 只影响宽高）、`scope`（`'viewport'` 缺省 / `'all'` 全部内容）、`padding`（`scope: 'all'` 的留白，缺省 24）、`background`（缺省带背景 / `false` 或 `'none'` 透明 / 颜色字符串换底色）、`includeLabels`（缺省 `true`）、`download`（`true` 或文件名） | `Promise<string>`（data URL） |
 | `exportSelection(options = {})` | `options?: GisViewExportSelectionOptions`：`format` / `type` / `quality` / `scale` / `padding`（只导选中要素那一块） | `Promise<GisViewExportSelectionResult>` |