gis-view-webgl2 0.1.4 → 0.1.5

package/docs/manual/03-/351/205/215/347/275/256/351/241/271.md

@@ -26,7 +26,7 @@
 | `channelTangentInset` | `number \| null` | `null` | 两端切点往节点里收多少 CSS 像素：缺省（`null`）按成员回线里最粗那条的线宽收，线因此不会从节点边缘探出去；`0` 表示切点正好落在节点边上，**负数外收**（切点往节点外让、回线整段比节点宽）；单个通道可用 `tangentInset` 覆盖；内收两侧合计最多收掉节点宽度的 40%，外收单侧最多让出 50% |
 | `channelMaxGroups` | `number` | `0` | 一条通道最多几个分组（`0` 表示不限）：新增通道时用来判断还能不能变成新分组，见「新增通道」 |
 | `channelGroupMaxLines` | `number` | `0` | 一个分组最多几条回线（`0` 表示不限）：新增通道时用来判断还能不能并进某一组，见「新增通道」 |
-| `channelDraftStyle` | `GisViewChannelDraftStyle` | 蓝色 2px + 两端圆点，箭头关闭 | 新增通道草稿预览的全局样式：`color` / `width` / `dot` / `dotColor` / `arrow` / `arrowSize` / `arrowPositions` / `arrowReverse` / `arrowColor` / `circuitSpacing` / `opacity` / `customDraw`；`beginAddChannel({ channelDraftStyle })` 可按这一次草稿覆盖，`updateAddChannelStyle(patch)` 可在草稿期间增量修改 |
+| `channelDraftStyle` | `GisViewChannelDraftStyle` | 蓝色 2px + 两端圆点，箭头关闭 | 新增通道草稿预览的全局样式：`color` / `width` / `dot` / `dotColor` / `dots`（`false` 关示例点，或 `{ show, size, color, shape, from, to }` 分端配置；示例点固定在点中的节点中心）/ `layer`（`'above'` 默认，`'below-points'` 让示例线 / 箭头 / `customDraw` 位于真实节点之下）/ `arrow` / `arrowSize` / `arrowPositions` / `arrowReverse` / `arrowColor` / `circuitSpacing` / `opacity` / `customDraw`；`beginAddChannel({ channelDraftStyle })` 可按这一次草稿覆盖，`updateAddChannelStyle(patch)` 可在草稿期间增量修改 |
 | `webglLayers` | `GisViewWebGLLayer[]` | `[]` | WebGL 自定义绘制层：每层提供 `draw({ gl, canvas, viewport, camera, frame, project, unproject, requestRender })`，在内置内容之后按 `order` 绘制；运行时也可用 `addWebGLLayer` / `updateWebGLLayer` / `removeWebGLLayer` 维护 |
 | `background` | `GisViewBackground` | 浅色底 | 背景层，支持底色、图片与 GeoJSON |
 | `pointStyle` | `GisViewPointStyle` | 见下 | 点的默认样式，可被单个点覆盖；运行时按字段合并用 `updatePointStyle(patch)`（`updateOptions({ pointStyle })` 是整份换） |
@@ -43,7 +43,7 @@
 | `labelStates` | `GisViewLabelState[]` | 无 | 标签的运行时状态（`getLabelStates()` 的那一份：拖出来的偏移、改过的内容与样式、运行时加的标签、隐藏覆盖）：创建时喂回来就回显，等价于创建之后调 `setLabelStates(states)`；`updateOptions({ labelStates })` 同样认。`exportData({ format: 'input' })` 的结果里就叫 `labelStates`，存档 → 回灌直接接上 |
 | `graphics` | `GisViewGraphic[]` | 无 | 与节点无关的扩展图形：按世界坐标放 SVG 路径 / 图片 / Canvas，支持锚点、偏移、旋转、透明度、`zIndex` 与 `scaleWithView`；位于画布之上、标签之下，运行时用 `addGraphic` / `addGraphics` / `updateGraphic` / `removeGraphic` / `clearGraphics` 增删改，见「扩展图形（graphic）」 |
 | `tooltip` | `GisViewTooltipOptions` | 无 | 悬停提示：点 / 线 / 通道分别配置内容，见「悬浮提示」 |
-| `minimap` | `GisViewMinimapOptions \| null` | 无 | 内置鹰眼图：位置、尺寸、节点 / 线路 / 视口框三份样式与交互都可配，`extent` 决定小图按数据范围还是「数据 ∪ 底图」铺（默认 `auto`，GeoJSON 底图不会缩成一个点），`zoomable` 打开后小图自身可整体放大缩小（空白处拖动可以平移小图或直接框选让主图显示过去，每格倍率 `zoomStep`），通道还能只画一根；小图同样支持规则（`pointRules` / `lineRules`，缺省沿用主图规则的颜色与层级），可以只画某几层（`levels`）、关掉分层叠画（`layered`）、按三组系数给节点与线路定尺寸（整体倍数 `pointSizeScale` / `lineWidthScale`、跟随小图倍数 `pointZoomScale` / `lineZoomScale`（只在小图自身倍数 ≠ 1 时起作用）、跟随主视图地图倍数 `pointMapZoomScale` / `lineMapZoomScale`），视口框与框选矩形的颜色 / 背景 / 边框 / 圆角也能配（`boxStyle` / `selectStyle`），`extent` 还能直接写死一份世界范围、容器可加 `className` / `style`、`layers` 按 `placement` 分数据前 / 数据后、段内按 `order` 拆出多层自绘内容（旧 `draw` 钩子仍兼容并排在最后）、`onInteraction` 在手势结束时给出类型 / 世界坐标 / 相机、`maxPixelRatio` 限制备份倍率上限，不配则不产生任何 DOM，见「鹰眼图」 |
+| `minimap` | `GisViewMinimapOptions \| null` | 无 | 内置鹰眼图：位置、尺寸、节点 / 线路 / 视口框三份样式与交互都可配，`extent` 决定小图按数据范围还是「数据 ∪ 底图」铺（默认 `auto`，GeoJSON 底图不会缩成一个点），`extentFollowCamera` 默认 `false`、打开后才允许 `auto` 范围随相机收窄。`zoomable` 三态互斥：`false` 关闭、`true` 手动缩放小图自身、`'follow'` 让整体范围跟随主图（`followZoomScale` 是主图倍数的指数，跟随模式下 `setMinimapZoom` / `zoomMinimapBy` 不抢控制权）；空白处拖动可平移小图或直接框选让主图显示过去（`dragAction`，`box` 不依赖缩放，手动模式下 Ctrl / ⌘ 才切换动作），每格倍率 `zoomStep`。通道还能只画一根；小图同样支持规则（`pointRules` / `lineRules`，缺省沿用主图规则的颜色、层级、最终节点尺寸与图标、样式链线宽，节点 / 线路尺寸按两边视口比例缩放且不受主图相机倍数影响），可以只画某几层（`levels`）、关掉分层叠画（`layered`）、按三组系数给节点与线路定尺寸（整体倍数 `pointSizeScale` / `lineWidthScale` 对自有与继承要素都生效；跟随小图倍数 `pointZoomScale` / `lineZoomScale` 在小图自身放大时也作用于继承要素；跟随主视图地图倍数 `pointMapZoomScale` / `lineMapZoomScale` 只作用于自有规则 / 样式），视口框与框选矩形的颜色 / 背景 / 边框 / 圆角也能配（`boxStyle` / `selectStyle`），`extent` 还能直接写死一份世界范围、容器可加 `className` / `style`、`layers` 按 `placement` 分数据前 / 数据后、段内按 `order` 拆出多层自绘内容（旧 `draw` 钩子仍兼容并排在最后）、`onInteraction` 在手势结束时给出类型 / 世界坐标 / 相机、`maxPixelRatio` 限制备份倍率上限，不配则不产生任何 DOM，见「鹰眼图」 |
 | `filter` | `GisViewFilterInput \| null` | 无 | 初始筛选条件，等价于创建之后调用 `setFilter`；`mode` 缺省 `'hide'`，写 `'remove'` 则删除不命中的要素，见「筛选」 |
 | `filterWorker` | `boolean \| GisViewFilterWorkerOptions` | `{ threshold: 20000 }` | 筛选是否用 Web Worker 计算：默认点 + 线总数超过阈值才用，`false` 表示始终同步算 |
 | `searchWorker` | `boolean \| GisViewSearchWorkerOptions` | `{ threshold: 20000 }` | [异步搜索](14-视图与筛选.md#搜索与定位)是否用 Web Worker 计算：默认点 + 线总数超过阈值才用，`false` 表示 `searchAsync` 也同步算；同步的 `search` 一直在主线程算，不受这一项影响 |
@@ -1004,7 +1004,7 @@ view.setFilter(null)     // 清掉筛选
 
 - **类型**：`GisViewMinimapOptions | null`
 - **默认值**：无
-- **说明**：内置鹰眼图：位置、尺寸、节点 / 线路 / 视口框三份样式与交互都可配，`extent` 决定小图按数据范围还是「数据 ∪ 底图」铺（默认 `auto`，GeoJSON 底图不会缩成一个点），`zoomable` 打开后小图自身可整体放大缩小（空白处拖动可以平移小图或直接框选让主图显示过去，每格倍率 `zoomStep`），通道还能只画一根；小图同样支持规则（`pointRules` / `lineRules`，缺省沿用主图规则的颜色与层级），可以只画某几层（`levels`）、关掉分层叠画（`layered`）、按三组系数给节点与线路定尺寸（整体倍数 `pointSizeScale` / `lineWidthScale`、跟随小图倍数 `pointZoomScale` / `lineZoomScale`（只在小图自身倍数 ≠ 1 时起作用）、跟随主视图地图倍数 `pointMapZoomScale` / `lineMapZoomScale`），视口框与框选矩形的颜色 / 背景 / 边框 / 圆角也能配（`boxStyle` / `selectStyle`），`extent` 还能直接写死一份世界范围、容器可加 `className` / `style`、`layers` 按 `placement` 分数据前 / 数据后、段内按 `order` 拆出多层自绘内容（旧 `draw` 钩子仍兼容并排在最后）、`onInteraction` 在手势结束时给出类型 / 世界坐标 / 相机、`maxPixelRatio` 限制备份倍率上限，不配则不产生任何 DOM，见「鹰眼图」
+- **说明**：内置鹰眼图：位置、尺寸、节点 / 线路 / 视口框三份样式与交互都可配；`position` / `margin` 定角落，`offset` 相对角落动态移动整张图，`container` 可挂到外部 `div`（`getMinimapElement()` 取根节点做整图拖动）。`extent` 决定小图按数据范围还是「数据 ∪ 底图」铺（默认 `auto`，GeoJSON 底图不会缩成一个点），`extentFollowCamera` 默认 `false`、打开后才允许 `auto` 范围随相机收窄，避免外围要素消失时包围盒与视口框跳动。`zoomable` 三态互斥：`false` 关闭、`true` 手动缩放小图自身、`'follow'` 让整体范围跟随主图（`followZoomScale` 是主图倍数的指数；跟随模式下 `setMinimapZoom` / `zoomMinimapBy` 不抢控制权，`zoom` 是基准倍数）；空白处拖动可平移小图或直接框选让主图显示过去（`dragAction`，`box` 不依赖缩放，手动模式下 Ctrl / ⌘ 才切换动作），每格倍率 `zoomStep`。通道关闭 `channelCircuits` 时按当前可见成员逐顶点平均成一根居中代表线；小图同样支持规则（`pointRules` / `lineRules`，缺省沿用主图规则的颜色 / 层级、最终节点尺寸与图标及样式链线宽，节点 / 线路尺寸按两边视口比例缩放且不受主图相机倍数影响），可以只画某几层（`levels`）、关掉分层叠画（`layered`）、按三组系数给节点与线路定尺寸（整体倍数 `pointSizeScale` / `lineWidthScale` 对自有与继承要素都生效；跟随小图倍数 `pointZoomScale` / `lineZoomScale` 在小图自身放大时也作用于继承要素；跟随主视图地图倍数 `pointMapZoomScale` / `lineMapZoomScale` 只作用于自有规则 / 样式），视口框与框选矩形的颜色 / 背景 / 边框 / 圆角也能配（`boxStyle` / `selectStyle`），`backgroundStyle` 显式设置时接管画布底色，`extent` 还能直接写死一份世界范围、容器可加 `className` / `style`、`layers` 按 `placement` 分数据前 / 数据后、段内按 `order` 拆出多层自绘内容（旧 `draw` 钩子仍兼容并排在最后）、`onInteraction` 在手势结束时给出类型 / 世界坐标 / 相机、`maxPixelRatio` 限制备份倍率上限，不配则不产生任何 DOM，见「鹰眼图」
 - **参考**：见「鹰眼图」一节，子字段在那里的表里逐个展开
 
 ```js
@@ -1014,6 +1014,14 @@ createGisView(container, {
 		width: 220,
 		height: 130,
 		position: 'bottom-right',
+		offset: [0, 0],
+		container: '#minimap-host',
+		backgroundStyle: 'rgba(255, 255, 255, 0.92)',
+		extent: 'auto',
+		extentFollowCamera: false,
+		dragAction: 'box',
+		zoomable: 'follow',
+		followZoomScale: 0.8,
 		levels: [1, 5, 20],
 		pointStyle: { color: '#2f6fed' },
 		layers: [

package/docs/manual/09-/351/200/232/351/201/223/344/270/216/345/244/232/345/233/236/347/272/277.md

@@ -241,7 +241,7 @@ Demo 的「通道与数据」页直接接了两类假接口：通道分组拐点
 
 - **加点 / 删点 / 拖点只作用于同一分组**：同一分组共用一条骨架，其余分组的线路不动。
 - 分组结果会写回 `channels[].groups`（`{ id?, lineIds, path?, waypointOffsets? }`），下次 `updateOptions` / 换数据按它重建；也可以一开始就手写 `groups` 而不是 `lineIds` + `path`。
-- `getChannelMembers()` 与鹰眼图都按分组各成一份：`channelCircuits: false` 时每个分组各画偏移最靠中间的那一根回线。
+- `getChannelMembers()` 与鹰眼图都按分组各成一份：`channelCircuits: false` 时每个分组把当前可见成员逐顶点平均成一根居中代表线（双回线落在两根正中间，三回线落在中间那条）。
 
 ---
 

package/docs/manual/10-/351/200/232/351/201/223/347/274/226/350/276/221/344/270/216/346/226/260/345/242/236.md

@@ -102,6 +102,8 @@ view.beginAddChannel({ from: { id: 'station-a' }, select: true })
 view.continueAddChannel({ from: 'station-c', kind: 'line' }) // 连续新增的下一段也能换指定起点
 ```
 
+> `beginAddChannel` / `continueAddChannel` 只支持预指定 **起点** `from`，没有 `to`。`beginAddChannel({ from: 'station-a', to: 'station-b' })` 里的 `to` 会被忽略：起点已经选好，仍要再点一次终点才能进入 `ready`。想完全程序化地指定两端并落地，用 `addChannel` / `addLine`，不要先开草稿。
+
 **直线 / 正交折线（`routing` / `path`）**：`beginAddChannel()` / `continueAddChannel()` 新增 `routing: 'straight' | 'orthogonal'` 与 `path`。`routing` 缺省 `'straight'`；写 `'orthogonal'` 且没有有效中间拐点时，组件自动补一个「先横后纵」的拐点 `[to.x, from.y]`。`path` 是**中间拐点**（不含两端），写了有效拐点就按它走，此时不会再追加自动拐点；草稿与 `commitAddChannel` / `addLine` / `addChannel` 共用同一份路由解析，预览和落地的折线完全一致。`onChannelDraft` / `onChannelDraftClick` 载荷里也带 `routing` / `path`，两端选好后 `path` 是实际会落地的中间拐点。
 
 | 字段 | 类型 | 缺省 | 说明 |
@@ -162,7 +164,7 @@ view.beginAddChannel()
 **取消、默认添加，或自行落地**：选完两个节点后草稿只是预览，除非 `autoCommit: true`，否则数据一个字节都不动。三种收尾方式：
 
 - `cancelAddChannel()`：收起草稿并补一条 `phase: 'cancel'`；`endAddChannel()` 静默收起。两者都不写数据。
-- `commitAddChannel()`：按推荐方案（或传入的 `resolution`）走内置落地，草稿里的 `routing` / `path` 会一起交给 `applyChannelAdd`。
+- `commitAddChannel()`：按推荐方案（或传入的 `resolution` / 新增线路 / 通道对象）走内置落地，草稿里的 `routing` / `path` 会一起交给 `applyChannelAdd`；对象字段优先，见下文「对象直传」。
 - `addLines()` / `addChannels()`：绕开提交，用草稿读数自己落地。独立线路写完整 `path`；通道只把 `path` 当中间拐点。落地后调用 `endAddChannel()` 收起假通道。
 
 ```js
@@ -302,7 +304,7 @@ view.addLine({ from: 'station-a', to: 'station-b' }, [{ id: 'n-1' }, { id: 'n-2'
 | `lineItems` | `GisViewChannelLineItems` | 无 | 连同线路一起新建的一条 / 一批；给了几条就建几条 |
 | `routing` | `'straight' \| 'orthogonal'` | `'straight'` | 直连，或自动补一个先横后纵的拐点 |
 | `path` | `GisViewCoordinate[]` | 无 | 中间拐点（不含两端）；有效时优先于 `routing` 的自动拐点 |
-| `channelDraftStyle` | `GisViewChannelDraftStyle` | 全局 `channelDraftStyle` | 本次草稿的预览样式，草稿结束即丢弃 |
+| `channelDraftStyle` | `GisViewChannelDraftStyle` | 全局 `channelDraftStyle` | 本次草稿的预览样式，草稿结束即丢弃；含两端示例点 `dots` 与示例线路层级 `layer`，见下文「示例点与层级」 |
 | `handoff` | `boolean` | `false` | `ready` 发完就收掉假通道，由使用方自己落地；与 `autoCommit` 同给时先自动落地 |
 | `select` | `boolean` | `false` | 点节点时同步进选中集（走 `onSelect` / `onSelectChange`）；预指定 `from` 时起点当场选中 |
 | `channelProps` | `Partial<GisViewChannel>` | 无 | 新通道透传字段（宽度、节点宽度、偏移方式…） |
@@ -332,7 +334,16 @@ view.updateOptions({
       console.log(payload.from.id, payload.to.id, payload.options, payload.preferred)
       // blocked 为 true 时只能放弃，reason 说明原因（同一个节点 / 已有通道的每个方案都不可用）
       // 手动提交：resolution 缺省用 preferred，也可以给 { type: 'joinGroup', groupId }
-      view.commitAddChannel(payload.options.find(option => option.type === 'joinGroup' && option.enabled))
+      const chosen = payload.options.find(option => option.type === 'joinGroup' && option.enabled)
+      if (chosen) {
+        // 方案读数是 { type, enabled, count, lineIds, ... }，不能整条回传；只取 resolution 认识的四个键
+        view.commitAddChannel({
+          type: chosen.type,
+          groupId: chosen.groupId,
+          groupIndex: chosen.groupIndex,
+          channelId: chosen.channelId
+        })
+      }
     }
     if (payload.phase === 'commit') {
       // 落地结果：line 是写进 lines 的新回线（已自动选中）
@@ -365,6 +376,415 @@ const plan = view.getChannelAddOptions('station-a', 'station-b')
 - **移除新增**：`removeLine(lineId)` 把刚落地的这条回线从数据里摘掉，通道声明（`lineIds` 与 `groups`）一起改，通道一条回线都不剩就整条删掉；`removeChannel(channelId)` 整条通道一起删。两个方法都返回结果对象（`{ ok, line / lineIds, channelId, removedChannel, reason? }`），并且已经处理好选中下标 —— 删掉线路之后 `getSelections()` 不会指到别的线上。
 - `getAddChannelDraft()` 读当前草稿（没有草稿时为 `null`）；方案表也可以直接问：`getChannelAddOptions(from, to, count?, kind?)`，实例层按节点 id、引擎层同名方法按下标；只要「这两个点之间到底有没有通道 / 有几组」的读数（不做方案判断）用 `getChannelBetween(from, to)` —— 有通道时 `hasChannel: true`、`channel` / `groups` / `groupCount` / `currentGroupId` 与方案表同一份，没有通道时 `hasChannel: false` / `channel: null` / `groups: []`，端点认不出来返回 `null`。
 
+**示例点与层级（`channelDraftStyle`）**
+
+`channelDraftStyle.dots` 控制草稿两端的示例点：缺省 `true` 按 `dot` / `dotColor` 画，`false` 两个都不画；写成对象可统一设置 `show` / `size` / `color` / `shape`（`'circle'` 或 `'square'`），再用 `dots.from` / `dots.to` 分别覆盖某一端。示例点始终画在**真正点中的节点中心**，不会跟着多回线的法线偏移跑到节点旁边；`dots: false` 只关示例点，预览线仍在。
+
+`channelDraftStyle.layer` 决定示例线路画在真实节点的哪一侧：`'above'`（默认）连同箭头 / `customDraw` 一起压在真实节点上；`'below-points'` 先画示例线、箭头与 `customDraw`，再把真实节点整层盖上去，示例线因此位于实际节点层级之下。示例点不受这个开关影响，始终在真实节点之后绘制，保证两端仍看得见。
+
+#### `commitAddChannel`：签名、全部传参与五种写法
+
+```ts
+commitAddChannel(input?, options?): GisViewChannelAddResult
+
+input?:
+  | 'auto' | 'newChannel' | 'newGroup' | 'joinGroup' | 'newLine'
+  | { type?: 'newChannel' | 'newGroup' | 'joinGroup' | 'newLine'; groupId?: string | number; groupIndex?: number; channelId?: string | number }
+  | GisViewLine                         // 直接线路对象
+  | GisViewChannel                      // 直接通道对象（必须有 lineIds）
+  | GisViewChannelAddCommitInput        // 容器写法
+  | undefined | null
+
+options?: {
+  auto?: boolean
+  continuous?: boolean
+  originalEvent?: Event | null
+}
+```
+
+**调用前提**：它只负责把当前草稿落地，不能替代 `addChannel` / `addLine` 做无草稿的程序化新增。调用前必须已经按下面的顺序走到 `ready`：
+
+1. `beginAddChannel(options?)` 进入草稿，或由 `continueAddChannel(options?)` 开出下一段。
+2. 通过点击选好起点 / 终点；写了 `options.from` 时起点已预选，只需再点终点。草稿配置只支持 `from`，没有 `to`；写 `{ from, to }` 时 `to` 会被忽略。
+3. `getAddChannelDraft()` 返回 `phase: 'ready'`，且 `plan`、`from`、`to` 都有值；`onChannelDraft` 也会收到同一次 `ready`。
+4. 调 `commitAddChannel(...)`。成功后草稿结束、新回线自动选中；连续模式则在原地重开下一段。
+
+以下两条任一不满足时不会写数据：
+
+| 情况 | 返回 | 草稿 |
+| --- | --- | --- |
+| 功能开关 `channelDraft` 关着 | `{ ok: false, reason: '新增通道已被功能开关关闭' }` | 保留 |
+| 没有草稿、仍在 `start` / `from` / `pick`，或没有可选方案 | `{ ok: false, reason: '还没有选好两个节点' }` | 保留 |
+
+**五种写法一览**。识别顺序是：先认无参 / 旧 resolution；其余对象先看有没有容器键，有就按容器处理；没有容器键再按 `lineIds` 或线路形状识别直接对象；实在认不出的对象最后仍交回 `resolution`。所以只要写成下列任一形状，就不需要先调 `addLine` / `addChannel`：
+
+| 写法 | 识别条件 | 缺省落地方式 | 典型用途 |
+| --- | --- | --- | --- |
+| 无参 | `input` 为 `undefined` / `null` | 用草稿的 `preferred` 方案 | 接受界面推荐的「新通道 / 新分组 / 并入某组」 |
+| 旧 resolution | 字符串；或只含非 `undefined` 的 `type` / `groupId` / `groupIndex` / `channelId` 的对象 | 按方案表挑一条；`'auto'` 的优先级是 `newChannel → newGroup → joinGroup` | 让用户明确选「新通道 / 新分组 / 并入哪组」 |
+| 直接线路对象 | 普通对象、没有 `lineIds` 数组，且至少有一个：`kind: 'line'`、`path` 数组、`from`、`to`、`start`、`end` | 按独立线路落地，不走通道方案表 | 最后一步直接把业务线路对象交给组件 |
+| 直接通道对象 | 普通对象且 `Array.isArray(lineIds)`；同时不能再出现容器键 `channel` / `line` / `lines` / `lineData` / `lineItems` / `channelGroups` / `group` / `channelProps` / `resolution` | 缺省 `resolution: 'newChannel'`；`lineIds` 是回线 id 种子，`groups` 是分组声明 | 一次写入一条新通道及其全部成员 |
+| 容器对象 | 出现任一容器键：`channel` / `line` / `lines` / `lineData` / `lineItems` / `channelGroups` / `group` / `channelProps` / `resolution`；只写 `lineProps` 也会按容器处理 | 各段分别覆盖草稿；`resolution` 不写时沿用草稿推荐方案 | 需要逐条回线字段、显式覆盖 `routing`，或把通道提交到已有分组 |
+
+> 空对象 `{}` 不是「新建通道」，会按旧 resolution 交给方案表（通常得到「指定的通道 / 分组没有可用方案」）。想接受推荐方案请直接不传参。直接线路对象里的 `start` / `end` 只参与形状识别，**不会**替代 `from` / `to`；要让落地点与草稿不同，请写 `from` / `to`。
+
+**旧 resolution 的字符串与对象**
+
+| `resolution` | 行为 |
+| --- | --- |
+| 不写 / `null` / `'auto'` | 依次找可用的 `newChannel` → `newGroup` → `joinGroup`；前一个不可用就退下一个。独立线路草稿直接按 `newLine` 落地 |
+| `'newChannel'` | 新建通道；两个节点之间已经有通道时找不到同类型可用方案，返回 `ok: false` |
+| `'newGroup'` | 在已有通道里新加一组；没有通道、组数已满或回数余量不够时失败 |
+| `'joinGroup'` | 并入一个可用的已有分组；不带 `groupId` 时沿用方案表挑中的那一组 |
+| `'newLine'` | 只在 `kind: 'line'`（独立线路草稿）时有效；普通通道草稿传它会失败 |
+| `{ type, groupId?, groupIndex?, channelId? }` | 按字段逐项收窄；`type` 缺省时，只写 `groupId` / `groupIndex` 会自动当作 `joinGroup` |
+| `{ groupId }` / `{ groupIndex }` | `joinGroup` 的简写。二者都写时以 `groupId` 为准 |
+| `{ channelId }` | 在指定通道内按「新分组 → 第一个能并的分组」挑；没有已有通道时 `channelId` 只是新通道 id，不会当成并组 |
+| `payload.options.find(option => option.enabled)` | **不能整条回传**。方案读数还带 `enabled` / `count` / `lineCount` / `lineIds`，不满足旧 resolution 的「只含四个键」条件；只取 `{ type, groupId, groupIndex, channelId }` 这个子集 |
+
+```js
+// 1. 接受推荐方案
+const accepted = view.commitAddChannel()
+
+// 2. 明确要「新建通道」或「并进某个分组」
+view.commitAddChannel('newChannel')
+view.commitAddChannel({ type: 'joinGroup', groupId: 'corridor-1::2' })
+
+// 3. 让界面把用户点中的那条方案交回来（只取 resolution 认识的字段）
+view.updateOptions({
+  onChannelDraft: payload => {
+    if (payload.phase === 'ready' && !payload.blocked) {
+      const chosen = payload.options.find(option => option.enabled && option.type === 'joinGroup')
+      if (chosen) {
+        const result = view.commitAddChannel({
+          type: chosen.type,
+          groupId: chosen.groupId,
+          groupIndex: chosen.groupIndex,
+          channelId: chosen.channelId
+        })
+        console.log(result.ok, result.lineIds, result.channelLineIds)
+      }
+    }
+  }
+})
+```
+
+> `ready` 里的 `option` 是**方案读数**，不是可直接回传的 `resolution`。建议固定只取四个定位字段；整条传进来时，带 `lineIds` 的方案可能被识别成直接通道对象，其余带容器键的对象也可能走成容器，而不是按方案表选组。
+
+#### 直接线路对象：字段怎么分、`path` 怎么算
+
+直接线路对象面向「最后一步已经有一份线路业务数据」的场景。它不要求先建独立线路草稿；只要当前草稿已经 `ready`，传入对象就会按 `kind: 'line'` 落地一条不挂通道的线路。
+
+| 对象字段 | 去向 | 说明 |
+| --- | --- | --- |
+| `from` / `to` | 新线路两端 | 覆盖草稿两端；必须是数据里真实存在的节点 id。两端相同会按方案表给出 `blocked` 原因 |
+| `id` | 新回线 id 种子 | 与 `options.lineId` 同义；与已有线路撞车时自动改成 `-1` / `-2` |
+| `name` | 新线路名 | 不写时沿用草稿名（草稿缺省按两端节点生成） |
+| `path` | **中间拐点** | 和草稿的 `path` 同一口径：首尾仍由 `from` / `to` 覆盖；要整条现成折线请用容器里的 `lines: [{ id, path: [首, …, 尾] }]` |
+| `lineProps` | 额外线路字段 | 最后合并，优先级高于对象上的普通业务字段 |
+| 其余字段（`color` / `width` / `lineType` / `voltageLevel`…） | `lineProps` | 原样透传到每一条新回线，可参与热力图、提示、筛选 |
+| `kind` | 只用于识别 | 写 `'line'` 可让一个没有 `from` / `to` / `path` 的对象也按独立线路解释 |
+
+```js
+// 直接把业务对象交给草稿提交：虚线、颜色、线宽和自定义字段都会写进新线路
+const result = view.commitAddChannel({
+  id: 'drop-line-1',
+  name: '备用联络线',
+  from: 'station-a',
+  to: 'station-b',
+  color: '#ff7a45',
+  width: 3,
+  lineType: 'dashed',
+  voltageLevel: '10kV',
+  // 中间拐点，不含首尾；首尾仍是 station-a / station-b 的坐标
+  path: [[116.72, 39.91], [116.86, 39.95]]
+})
+
+console.log(result.ok)        // true
+console.log(result.kind)      // 'line'
+console.log(result.lineIds)   // ['drop-line-1']
+console.log(result.channelId) // null
+```
+
+#### 直接通道对象：`lineIds`、`groups` 与样式怎么写
+
+直接通道对象适合「一次给全通道 + 成员」。识别它的硬条件是 `lineIds` 必须是数组；没有 `lineIds` 的对象即使写了 `groups`，也只会被当成旧 resolution 或无法识别的对象。
+
+| 对象字段 | 去向 | 说明 |
+| --- | --- | --- |
+| `lineIds` | 新回线 id 种子 | 每个 id 生成一条新回线；`lineIds` 为空数组时回线数量回落到草稿的 `circuits` / `lineItems`，不会清空草稿 |
+| `groups` | 分组声明 | 等价于容器的 `channelGroups`；组的 `lineIds` 应使用这次生成的成员 id。第一组不写成员时拿本次全部回线，其余空组会被丢掉 |
+| `id` | 新通道 id | 只决定新通道的身份；回线 id 一律来自 `lineIds`，这个 `id` 不参与逐条回线的 id 或前缀 |
+| `name` | 通道名与新线路名 | 新线路没有逐条 `name` 时一起使用 |
+| `from` / `to` | 新通道两端 | 覆盖草稿；实际回线端点也按它落 |
+| `path` | 通道骨架的中间拐点 | 不含两端；分组各自写了 `path` 时以分组那一份为准 |
+| `lineProps` | 全部新回线的公共字段 | 直接通道对象自己的 `lineProps` 会生效，优先级低于每一条逐条字段；容器写法里的 `channel.lineProps` **不合并**，见下文容器优先级 |
+| 其余字段（`width` / `nodeWidth` / `inset` / `tooltip` / `customCode`…） | `channelProps` | 原样写到新通道上 |
+
+```js
+// 通道对象：两个 lineIds 各生成一条回线；groups 把它们分成两组
+view.commitAddChannel({
+  id: 'object-channel-1',
+  name: '东侧双回',
+  from: 'station-a',
+  to: 'station-b',
+  lineIds: ['object-line-1', 'object-line-2'],
+  groups: [
+    { id: 'object-channel-1::1', lineIds: ['object-line-1'], path: [[116.75, 39.86]] },
+    { id: 'object-channel-1::2', lineIds: ['object-line-2'], path: [[116.75, 39.98]] }
+  ],
+  width: 28,
+  nodeWidth: 1,
+  offsetMode: 'tangent',
+  lineProps: { color: '#2f6fd0', width: 2.4, lineType: 'dashed' },
+  owner: '运维一班'
+})
+```
+
+> 直接通道对象的回数只由 `lineIds` 决定；`lineIds: []` 时回落到草稿的 `lineItems` / `circuits`。直接通道对象上另外写的 `circuits` 不会改回数，它会作为普通通道字段收进 `channelProps`；要覆盖本次回数，请用容器顶层 `circuits`，或在 `beginAddChannel` 时配置。
+>
+> `groups[].lineIds` 应写本次 `lineIds` / `lines` 真正生成的回线 id。写了不存在的 id 不会让整次提交失败：组件会报 warning，并在声明落地前按本次成员表调和（剔掉不属于本次的回线、把没落组的成员补进第一组）。
+
+> **直接通道对象缺省按新通道提交**。要在提交对象的同时并进已有分组，必须换成容器写法并写 `resolution`，例如 `{ resolution: { type: 'joinGroup', groupId: 'corridor-1::2' }, lines: [...] }`。直接把 `resolution` 塞进「带 `lineIds` 的通道对象」会把它识别成容器，顶层 `lineIds` 不再作为通道成员使用。
+
+#### 容器对象：逐段覆盖与精确优先级
+
+容器是表达能力最完整的一种写法。所有段都可省略，写了哪一段就覆盖哪一段，没写的继续沿用当前草稿：
+
+| 容器键 | 类型 | 作用 |
+| --- | --- | --- |
+| `channel` | `GisViewChannel` | 新通道声明：`id` / `name` / `from` / `to` / `path` / `lineIds` / `groups` 与业务字段 |
+| `line` | `GisViewLine` | 一条独立线路；缺省把本次 `kind` 定成 `'line'`，不是「只含一条的 `lines`」。只有同时显式写 `kind: 'channel'` 时，它才作为一条成员回线挂进通道 |
+| `lines` | 一条或一批线路数据 | 逐条回线字段，支持对象、裸字符串 / 数字 id；**给了几条就建几条** |
+| `lineData` / `lineItems` | 同上 | `lines` 的兼容别名；三者同时写时的优先级是 `lines > lineData > lineItems` |
+| `channelGroups` / `group` | 一组或整份分组声明 | `channelGroups` 优先于 `group`；都写时以 `channelGroups` 为准 |
+| `channelProps` | `Partial<GisViewChannel>` | 最后覆盖新通道字段，优先级高于 `channel` 上的普通字段 |
+| `lineProps` | `Partial<GisViewLine>` | 公共回线字段；合并顺序是草稿 `lineProps` → 容器顶层 `lineProps` → `line.lineProps`，最后被逐条 `lines[i]` 覆盖。`channel.lineProps` 在容器里不参与合并 |
+| `resolution` | 旧 resolution 的字符串 / 对象 | 不写时：有 `channel` 按 `newChannel`，否则沿用草稿推荐方案 |
+| `kind` | `'channel' \| 'line'` | 显式改这一条是通道还是独立线路 |
+| `from` / `to` / `path` / `routing` | 同草稿 | 顶层端点、中间拐点与走线方式；`routing` 只认容器这一层 |
+| `circuits` | `number` | 没有有效 `lines` 时一次建几回；有 `lines` 时按条数（`circuits` 被忽略） |
+| `id` / `lineId` | 线路 id 种子 | `lineId` 优先；通道 id 请写在 `channel.id` 或 `channelId` |
+| `channelId` / `channelName` | 通道 id / 名称 | `channelId` 在无已有通道时是新通道 id；已有通道时是并组筛选条件 |
+
+> 容器顶层只有 `channelGroups` / `group` 是分组键；裸写 `groups` 不会被读取。分组直接写在 `channel.groups`，或用 `channelGroups` / `group`。
+
+**逐字段优先级（从高到低）**：
+
+| 目标字段 | 优先级 |
+| --- | --- |
+| `from` / `to` | 容器顶层 → `channel` → `line` → `lineItems` 里第一个对象项 → 草稿。前面的裸字符串 / 数字 id 跳过，不贡献端点 |
+| `path`（中间拐点） | 容器顶层 → `line` → `channel` → 草稿 |
+| `routing` | 容器顶层 → 草稿（直接线路 / 直接通道对象没有这一层） |
+| 分组 | `channelGroups` → `group` → `channel.groups` → 不声明（新通道只建一组，组 id 用通道 id） |
+| 逐条回线 | `lines` → `lineData` → `lineItems` → `line` → `channel.lineIds.map(id => ({ id }))` → 草稿 |
+| 线路公共字段（直接线路对象） | 对象上的普通业务字段 → 对象自己的 `lineProps` |
+| 线路公共字段（容器） | 草稿 `lineProps` → 容器顶层 `lineProps` → `line.lineProps` → 逐条 `lines[i]`；**不读 `channel.lineProps`** |
+| 通道字段 | 草稿 `channelProps` → `channel` 上的业务字段 → 容器 `channelProps` |
+| 名称 | 容器 `name` → `channelName` / `channel.name` → `line.name` → 草稿名称 |
+| `resolution` | 容器 `resolution` → 直接通道对象固定 `newChannel` → 草稿 `preferred` |
+
+**空数组的规则**：`lines: []`、`lineData: []`、`lineItems: []` **不会清空**草稿里已有的逐条回线，而是沿用草稿。想放弃草稿里的线路，重新 `beginAddChannel()`（不要传 `lineItems`）或改用 `addLine` / `addChannel` 自行落地。
+
+```js
+// 容器写法：通道声明、两条回线、分组、样式、走线方式一次给全
+view.commitAddChannel({
+  resolution: 'newChannel',
+  from: 'station-a',
+  to: 'station-b',
+  channel: {
+    id: 'container-channel-1',
+    name: '容器通道',
+    nodeWidth: 1,
+    width: 32,
+    customCode: 'CH-001' // 不在通道保留键里的字段会进 channelProps
+  },
+  lines: [
+    { id: 'container-line-1', color: '#dd4b2e', width: 2.2, name: '一回' },
+    { id: 'container-line-2', color: '#2ea36b', width: 2.2, name: '二回', voltageLevel: '10kV' }
+  ],
+  channelGroups: [
+    { id: 'container-channel-1::1', lineIds: ['container-line-1'], path: [[116.78, 39.88]] },
+    { id: 'container-channel-1::2', lineIds: ['container-line-2'], path: [[116.78, 39.96]] }
+  ],
+  routing: 'straight',
+  lineProps: { opacity: 0.9 },
+  channelProps: { tooltip: false }
+})
+```
+
+**只给种子、逐条字段另写**：`channel.lineIds` 不会被 `lines` 覆盖成通道成员表 —— 容器里的 `lines` 才是本次新建的回线；`channel.lineIds` 只在没有 `lines` 时提供 id 种子。下面的结果是两条回线、一条新通道：
+
+```js
+view.commitAddChannel({
+  channel: {
+    id: 'seed-channel',
+    from: 'station-a',
+    to: 'station-b',
+    lineIds: ['seed-line-1', 'seed-line-2']
+  },
+  lineProps: { color: '#2f6fd0', width: 2 }
+})
+```
+
+**逐条回线用 `lines` / `lineData` / `lineItems`**：它们接受单对象、对象数组，也接受裸 id。每个对象里的 `id` 就是回线 id；不写 id 时按「通道 id-序号」自动编号，撞车自动加后缀：
+
+```js
+view.commitAddChannel({
+  channel: { id: 'mixed-channel', from: 'station-a', to: 'station-b' },
+  lines: [
+    { id: 'mixed-1', color: '#dd4b2e', width: 2 },
+    'mixed-2',
+    { id: 'mixed-3', lineType: 'dotted', label: '三回' }
+  ],
+  group: { id: 'mixed-group', path: [[116.8, 39.9]] }
+})
+```
+
+#### 覆盖草稿的端点、路由、名称与 id
+
+对象字段覆盖草稿，未写的继续用草稿。最常改的是这四组：
+
+```js
+// 端点 / 名称 / 线路 id 种子全部由容器覆盖
+view.commitAddChannel({
+  from: 'station-c',
+  to: 'station-d',
+  name: '改道后的联络线',
+  lineId: 'rerouted-line',
+  lines: [{ id: 'rerouted-line', color: '#7c4dff' }],
+  routing: 'orthogonal'
+})
+
+// 只改公共线路字段，其余（含推荐方案、circuits、端点、名称）全部沿用草稿
+view.commitAddChannel({ lineProps: { width: 3.5, opacity: 0.8 } })
+
+// 只改通道字段：通道对象的 lineIds 仍按当前草稿回线数生成
+view.commitAddChannel({
+  channel: { id: 'styled-channel', from: 'station-a', to: 'station-b', nodeWidth: 0.8 },
+  channelProps: { width: 40, offsetMode: 'inset', inset: 0.2 }
+})
+```
+
+- `routing: 'orthogonal'` 只在**容器顶层**生效；直接线路 / 直接通道对象上的 `routing` 会进业务字段，不会改变走线。
+- 顶层 `path` 会盖过 `line.path` / `channel.path`；没有顶层 `path` 时才依次看线路、通道和草稿。
+- `lineId` 只是 id 种子：一次多条时自动展开成 `lineId-1` / `lineId-2`；每条自己的 `lines[i].id` 优先级更高。
+- `from` / `to` 可以覆盖草稿端点，但必须能在当前数据里找到；找不到时返回 `{ ok: false, reason: '找不到这两个节点' }`，草稿保留。
+
+#### 提交已有通道 / 已有分组：必须显式写 `resolution`
+
+直接通道对象默认新建通道。要可预期地并进已有通道 / 指定分组，换成容器写法并在顶层显式写 `resolution`；容器不写时只是沿用草稿推荐方案，不能保证一定是并组。并组时成员由 `lines` 给出，`channel` 段不再负责新建：
+
+```js
+// 并进已有通道的指定分组
+const joined = view.commitAddChannel({
+  resolution: { type: 'joinGroup', groupId: 'corridor-1::2' },
+  lines: [
+    { id: 'join-line-1', color: '#dd4b2e' },
+    { id: 'join-line-2', color: '#2ea36b' }
+  ],
+  lineProps: { width: 2.4 }
+})
+
+console.log(joined.ok)            // true
+console.log(joined.channelId)     // 'corridor-1'
+console.log(joined.groupId)       // 'corridor-1::2'
+console.log(joined.channelLineIds) // 并完之后这条通道的完整成员表
+```
+
+- `resolution: 'newGroup'` 必须在已有通道的前提下才可用；新组的 id / 拐点用 `channelGroups` 或 `group` 给。
+- 只写 `channelId` / `groupId` / `groupIndex` 也能作为旧简写，但它们只有在两个节点之间已经有通道时才按并组解释。
+- `channelProps` 只在新建通道时写进新通道；并进已有分组时不会改已有通道的字段，需要改通道请另调 `updateChannel`。
+
+```js
+// 旧简写：两个对象字段等价
+view.commitAddChannel({ type: 'joinGroup', groupId: 'corridor-1::2' })
+view.commitAddChannel({ groupId: 'corridor-1::2' })
+
+// 只指定通道，让组件按「新分组 → 能并的分组」挑
+view.commitAddChannel({ channelId: 'corridor-1' })
+```
+
+#### 连续新增、自动提交与事件
+
+第二参数只在一次提交里生效：
+
+| 字段 | 类型 | 缺省 | 说明 |
+| --- | --- | --- | --- |
+| `auto` | `boolean` | `false` | 只标记本次事件是自动提交；不等于 `beginAddChannel({ autoCommit: true })`。`autoCommit` 由组件内部用 `commitAddChannel('auto', { auto: true })` 提交 |
+| `continuous` | `boolean` | 跟草稿的 `continuous` | 显式 `false` 强制本次落地后结束草稿；`true` 只在草稿本来就是连续模式时有效 |
+| `originalEvent` | `Event \| null` | `null` | 连续模式重开草稿时带回去，供下一次草稿回调使用 |
+
+```js
+// 连续新增：本次落地后直接开下一段，并以上一段终点为下一段起点
+view.beginAddChannel({ continuous: true, chain: true, kind: 'channel' })
+
+view.updateOptions({
+  onChannelDraft: payload => {
+    if (payload.phase === 'ready' && !payload.blocked) {
+      view.commitAddChannel(undefined, { continuous: true, originalEvent: payload.originalEvent })
+    }
+  },
+  onChannelDraftClick: payload => {
+    if (payload.phase === 'commit') {
+      console.log('已落地', payload.lineIds, '下一段是否重开', payload.restarted)
+    }
+  }
+})
+
+// 本次之后收手；即使草稿配了 continuous: true，也不会再开下一段
+view.commitAddChannel(undefined, { continuous: false })
+```
+
+提交成功时发一条 `onChannelDraft` / `channelDraft`（`phase: 'commit'`）；失败时发 `phase: 'blocked'`，并且：非连续模式下草稿同样会结束，连续模式下会照常重开一段让用户继续试。事件载荷常用字段如下：
+
+| 字段 | 含义 |
+| --- | --- |
+| `phase` | `'commit'` / `'blocked'` |
+| `auto` / `autoCommit` | 本次是否自动提交 / 草稿是否开了自动提交 |
+| `continuous` / `chain` / `restarted` | 提交后是否重开、是否继承上一段终点、是否真的重开了 |
+| `kind` / `circuits` | 本次加通道还是独立线路、落地几条 |
+| `from` / `to` / `plan` / `options` | 实际端点、方案表与全部方案 |
+| `blocked` / `reason` | 是否失败与原因 |
+| `resolution` | 实际选中的方案 |
+| `line` / `lineId` / `lines` / `lineIds` | 新回线（`line` / `lineId` 是第一条） |
+| `channelId` / `groupId` / `channelLineIds` | 新通道 / 分组与通道完整成员表（独立线路为 `null`） |
+| `lineIndex` | 第一条新回线在 `lines` 里的下标；失败事件里按 `-1` 兜底 |
+| `routing` / `path` | 本次落地用的走线方式与中间拐点 |
+
+#### 返回值与错误处理
+
+`GisViewChannelAddResult` 与 `addChannel` / `addLine` 共用：
+
+| 字段 | 成功时 | 失败时 |
+| --- | --- | --- |
+| `ok` | `true` | `false` |
+| `reason` | 无 | 说明原因（未 ready、找不到节点、方案不可用、端点相同…） |
+| `plan` | 本次方案表 | 能算出方案表时一并带回，供界面重新选择 |
+| `resolution` | 实际方案；独立线路是 `newLine` | 无 |
+| `kind` / `circuits` | `'channel' / 'line'`、回数 | 无 |
+| `line` / `lineId` / `lines` / `lineIds` | 新回线与 id（多回时 `line` 是第一条） | 无 |
+| `lineIndex` | 第一条新回线的下标 | 无 |
+| `channelId` / `groupId` | 新通道 / 分组；独立线路分别为 `null` / `null` | 无 |
+| `channelLineIds` | 通道落地后的完整成员表；独立线路为 `null` | 无 |
+| `channelIndex` | 新通道或并进通道的下标；独立线路为 `-1` | 通常不返回；事件载荷失败时按 `-1` 兜底 |
+
+```js
+const result = view.commitAddChannel({ groupId: 'not-exist' })
+if (!result.ok) {
+  console.warn(result.reason)                  // 例如：找不到通道 / 指定分组没有可用方案
+  console.table(result.plan?.options ?? [])    // 每条方案为什么不可用
+  // 失败时草稿是否结束取决于 continuous：非连续模式收起，连续模式重开下一段
+}
+```
+
+常见失败原因：
+
+- **未 ready**：先完成两次点选，或 `beginAddChannel({ from })` 后补点终点。
+- **功能关闭**：`features: { channelDraft: false }` 时提交直接拒绝。
+- **节点找不到 / 端点相同**：`from` / `to` 覆盖成不存在的 id，或两端指到同一个节点。
+- **方案不可用**：已有通道组数已满、目标分组余量不足，或者 `resolution` 指向不存在的通道 / 分组。
+
 **给已有通道加线路 / 删除线路**
 
 | 想做什么 | 方法 | 要点 |