gis-view-webgl2 0.1.7 → 0.1.9

package/docs/manual/18-/351/200/220/346/226/271/346/263/225/347/244/272/344/276/213.md

@@ -135,7 +135,7 @@ const frame = await view.whenRendered()
 view.updateData(nextPoints, nextLines)
 await view.whenDataRendered()
 
-// snapshotScene(options?)：一次取全画布读数 / 数据快照（矢量导出、单测都用它）
+// snapshotScene(options?)：一次取全画布读数 / 数据快照（矢量导出、单测都用它；raisedLines 是抬层线路）
 const snapshot = view.snapshotScene()
 const white = view.snapshotScene({ background: '#ffffff' })
 
@@ -178,7 +178,7 @@ view.focusOn({ type: 'line', id: 'a' })
 view.focusOn({ type: 'channel', channelId: 'c1' })     // 通道也可以直接写 { channelId: 'c1' }
 view.focusOn({ type: 'group', channelId: 'c1', groupId: 'c1::2' })
 view.focusOn({ type: 'group', groupId: 'global-group' }) // groupId 全局唯一时可省略通道
-view.focusOn([120, 80], { center: true })              // 显式只居中（与缺省一致）
+view.focusOn([120, 80])                                // 缺省只居中、比例不动
 view.focusOn({ lngLat: [116.4, 39.9] })
 
 // flyTo(target, options?)：与 focusOn 同一套目标解析，平滑飞过去
@@ -201,9 +201,25 @@ const asyncHits = await view.searchAsync('甲站')       // 大表走 Worker；s
 
 // setCamera(camera) / getCamera()：读写相机（只写一个字段也行）
 view.setCamera({ scale: 10 })
-view.setCamera({ x: 200, y: 120 })
+view.setCamera({ center: [200, 120] })
 const camera = view.getCamera()
 
+// getCenter() / setCenter(center)：只读写视图中心（setCenter 保留当前比例，返回实例）
+const center = view.getCenter() // [x, y] 的副本
+center[0] += 100                 // 改副本不会移动视图
+view.setCenter([116.4, 39.9])
+
+// getScale()：读当前比例（与 getCamera().scale 同一份数）
+const scale = view.getScale()
+
+// setScale(scale, origin?)：立即改比例；origin 是画布 CSS 像素锚点，缺省视口中心
+view.setScale(3)
+view.setScale(3, [320, 180])
+
+// getIdleTime()：距创建或上一次指针 / 滚轮 / 键盘操作的毫秒数
+const idleTime = view.getIdleTime()
+view.updateOptions({ idleTimeout: 60000, onIdle: ({ idleTime }) => console.log(idleTime) })
+
 // stopCameraAnimation() / getCameraAnimation()：停止飞行 / 读当前飞行读数（没有动画时为 null）
 const flight = view.getCameraAnimation() // { active, progress, duration, from, to }
 view.stopCameraAnimation()                 // 停在当前帧，不补跳到终点
@@ -384,8 +400,9 @@ view.deselect('a')
 view.deselect(['a', 'b'])
 view.deselect()
 
-// getSelections() / getSelectionData() / isSelected(ref)：读回选中
+// getSelections() / getSelectionInfo() / getSelectionData() / isSelected(ref)：读回选中
 const picks = view.getSelections()
+const info = view.getSelectionInfo()                   // { ids, count, points, lines, channels }
 const selection = view.getSelectionData()              // { ids, count, points, lines, channels, bounds, … }
 const selected = view.isSelected('a')
 
@@ -405,11 +422,13 @@ view.on('cascadeHighlight', payload => console.log(payload?.pointIndexes, payloa
 // selectInBox(box, options?)：用矩形框选（画布 CSS 像素，与手动框选同一套判定）
 view.selectInBox({ x: 40, y: 40, width: 320, height: 200 })
 view.selectInBox({ x: 40, y: 40, width: 320, height: 200 }, { selectionKinds: ['line', 'channel'] })
+view.selectInBox({ x: 40, y: 40, width: 320, height: 200 }, { selectionKinds: ['lineEndpoints', 'channelEndpoints'] }) // 两端节点都在框内才命中
 
 // selectionKinds：框选与 Ctrl / multiSelect 点击的类型过滤（数组任意组合；'all' / true 全开，false / null 全关）
 view.updateOptions({ selectionKinds: ['point', 'line'] })   // 只收节点与通道外线路
 view.updateOptions({ selectionKinds: 'channel' })           // 只收通道回线（再按 channelSelectMode 摊开）
 view.updateOptions({ selectionKinds: ['point', 'line', 'channel'] })
+view.updateOptions({ selectionKinds: ['lineEndpoints'] })   // 框选：两端节点都在框内的独立线路
 
 // beginCopyPoint(options) / getPointCopy() / updateCopyPoint(patch) / commitPointCopy() / cancelPointCopy()
 view.updateOptions({ copy: { enabled: true, autoCommit: false } })  // API 复制入口要先开 copy 配置
@@ -438,17 +457,26 @@ const clipboard = view.getPointClipboard()
 // mergePoints(source, target, options?)：把 source 并进 target（接口调用，不做确认）
 const merged = view.mergePoints('a', 'b')
 const mergedCustom = view.mergePoints('a', 'b', { item: { name: '合并结果', size: 12 } })
+console.log(merged.item?.mergeInfo?.sourceIds)          // 保留节点上的来源 id；只有 merge.maxKeys 列出的字段取最高，缺省全部取保留端
 
 // mergeSelectedPoints(options?)：框选 / 多选之后一次并完（目标缺省挑绑定线路最多的那个）
 const mergedAll = view.mergeSelectedPoints()
 view.mergeSelectedPoints({ target: 'b', sources: ['a', 'c'], force: true })
 
-// splitPoint(source, parts, options?)：把一个节点拆成多份（mergePoints 的逆操作）
+// splitPoint(source)：有 mergeInfo 时自动解除合并（省略 parts / null / [] 等价）
+const autoRestored = view.splitPoint('b', null, { label: '解除合并（自动恢复）' })
+console.log(autoRestored.autoRestored, autoRestored.mergeSourceIds, autoRestored.changes)
+// 默认不选中结果；需要选中全部恢复节点时写 splitPoint('b', null, { select: true })
+
+// splitPoint(source, parts, options?)：手工拆成多份（mergePoints 的逆操作）
 const splitResult = view.splitPoint('a', [
   { x: 0, y: 0, name: '甲站（主）' },                    // 第一份沿用原下标 / id
-  { x: 80, y: 40, name: '甲站（东）', lines: ['l1'] }    // 显式分给第二份；未分配的线路跟第一份
-], { label: '拆分甲站' })
-console.log(splitResult.pointIds, splitResult.linesChanged, splitResult.changes)
+  { x: 80, y: 40, name: '甲站（东）', lines: ['l1'] }    // 显式分给第二份
+], { autoLines: 'alternate', label: '解除合并' })
+// options.autoLines: 'first'（缺省，未分配的线路跟第一份）| 'alternate'
+// alternate：同一条通道的成员成组、独立线路单条，轮流给负载最少的一份，解除合并推荐
+console.log(splitResult.pointIds, splitResult.autoAssignedLines, splitResult.lineAssignments)
+console.log(splitResult.autoLines, splitResult.changes) // lineAssignments 每项带 index / pointId / lineIds / lineCount
 
 // getPointMerge() / resolvePointMerge(confirmed?, options?) / commitPointMerge() / revertPointMerge()
 const pendingMerge = view.getPointMerge()              // 待确认的那一份载荷（没有就是 null）
@@ -564,10 +592,9 @@ view.runChannelAction('split', { lineId: 'l2' })
 view.addChannelGroupWaypoint('c1', 'c1::2', [200, 120])
 view.removeChannelGroupWaypoint('c1', 'c1::2', 1)
 
-// beginAddChannel(options?) / getAddChannelDraft() / updateAddChannelStyle(patch?) / continueAddChannel(options?)
+// beginAddChannel(options?) / beginAddLine(options?) / getAddChannelDraft() / updateAddChannelStyle(patch?) / continueAddChannel(options?)
 // commitAddChannel(input?, options?) / cancelAddChannel() / endAddChannel()
 view.beginAddChannel({
-  kind: 'channel',
   circuits: 3,
   channelDraftStyle: {
     color: '#2f6fd0', width: 2.5, arrow: true, arrowSize: 14, arrowPositions: [0, 0.5, 1],
@@ -582,70 +609,93 @@ const draft = view.getAddChannelDraft()                // 草稿读数（跟随
 view.updateAddChannelStyle({ arrowPositions: [0.25, 0.75], arrowReverse: true }) // 字段级合并，只改箭头
 view.updateAddChannelStyle(null)                       // 回到全局 channelDraftStyle
 
+// 草稿的 select 只决定点节点时是否顺手选中节点；缺省 false
+view.beginAddChannel({ from: 'station-a', select: true })
+// 这一段最终落地几条回线由 circuits / lineData 决定；落地后是否选中新回线由 commitAddChannel 的 options.select 决定
+view.commitAddChannel({}, { select: true })
+
+// 单一通道 / 已有通道策略：singleChannel 只约束 beginAddChannel
+view.beginAddChannel({ from: 'station-a', singleChannel: true }) // 两端已有通道 -> plan.blocked，commit 发 phase: 'blocked'
+view.beginAddChannel({ from: 'station-a', existingChannel: 'newGroup' })
+view.beginAddChannel({ from: 'station-a', existingChannel: 'joinGroup', groupId: 'c1::2' })
+view.beginAddChannel({ from: 'station-a', existingChannel: 'joinGroup', groupIndex: 1 })
+view.beginAddChannel({ from: 'station-a', existingChannel: 'auto' }) // 有新分组余量就新分组，否则并组
+
+// beginAddLine：入口固定为线路语义；缺省独立线路，显式 existingChannel 且已有通道时才挂进通道
+view.beginAddLine({ from: 'station-a' })
+view.beginAddLine({ from: 'station-a', existingChannel: 'newGroup' })
+view.beginAddLine({ from: 'station-a', existingChannel: 'joinGroup', groupId: 'c1::2' })
+// 旧 beginAddChannel({ kind: 'line' }) 已移除；线路入口只认 beginAddLine
+
 // commitAddChannel 只负责把已 ready 的草稿落地；没有草稿的程序化新增用 addChannel / addLine。
 // 下面每个 commit 例子都假设当前草稿已经重新 ready；实际连续调用请逐段 begin / 点选。
-// 五类入参：无参、旧 resolution、直接线路、直接通道（必须有 lineIds）、容器（channel / line / lines / ...）。
 // 1. 无参：沿用草稿的 preferred（newChannel / newGroup / joinGroup / newLine）
 view.commitAddChannel()
 
-// 2. 旧 resolution：字符串或只含 type / groupId / groupIndex / channelId 的对象
-view.commitAddChannel('newChannel')
-view.commitAddChannel({ type: 'joinGroup', groupId: 'c1::2', groupIndex: 1, channelId: 'c1' })
+// 2. 只改落点：所有 commitAddChannel 入参都写在一个容器对象里
+view.commitAddChannel({ resolution: 'newChannel' })
+view.commitAddChannel({ resolution: { type: 'joinGroup', groupId: 'c1::2', groupIndex: 1, channelId: 'c1' } })
 
 // 3. 从 ready 的方案读数里选一条：只取四个定位字段，不能把整条 option 回传。
-//    整条 option 还带 enabled / count / lineCount / lineIds，可能被误识别成直接通道或容器。
+//    整条 option 还带 enabled / count / lineCount / lineIds，只取 resolution 需要的子集。
 view.updateOptions({
   onChannelDraft: payload => {
     if (payload.phase !== 'ready' || payload.blocked) return
     const chosen = payload.options.find(option => option.enabled && option.type === 'joinGroup')
     if (!chosen) return
     const result = view.commitAddChannel({
-      type: chosen.type,
-      groupId: chosen.groupId,
-      groupIndex: chosen.groupIndex,
-      channelId: chosen.channelId
+      resolution: {
+        type: chosen.type,
+        groupId: chosen.groupId,
+        groupIndex: chosen.groupIndex,
+        channelId: chosen.channelId
+      }
     })
     console.log(result.ok, result.reason, result.lineIds)
   }
 })
 
-// 4. 直接线路对象：没有 lineIds，但至少写 from / to / path / kind: 'line' 之一。
-//    业务字段和 lineProps 都透传到新线路；path 是中间拐点（不含首尾）。
+// 4. 独立线路对象放在 line 里：from / to、业务字段与 lineProps 都透传到新线路；
+//    path 是中间拐点（不含首尾）。线路对象不要直接放在顶层。
 view.commitAddChannel({
-  id: 'new-line',
-  name: '对象线路',
-  from: 'station-a',
-  to: 'station-b',
-  path: [[116.72, 39.91], [116.86, 39.95]],
-  color: '#ff7a45',             // 直接业务字段 → lineProps
-  width: 3,
-  lineType: 'dashed',
-  voltageLevel: '10kV',
-  lineProps: { opacity: 0.9 }   // 合并顺序：业务字段 → 自己的 lineProps
+  line: {
+    id: 'new-line',
+    name: '对象线路',
+    from: 'station-a',
+    to: 'station-b',
+    color: '#ff7a45',
+    width: 3,
+    lineType: 'dashed',
+    voltageLevel: '10kV',
+    lineProps: { opacity: 0.9 }
+  },
+  path: [[116.72, 39.91], [116.86, 39.95]]
 })
 
-// 5. 直接通道对象：必须写 lineIds；每个 id 生成一条回线，groups 是分组声明。
-//    id 只决定通道 id，不是回线 id 种子；并进已有通道要改用容器 + resolution。
+// 5. 通道对象放在 channel 里：lineIds 的每个 id 生成一条回线，groups 是分组声明。
+//    id 只决定通道 id，不是回线 id 种子；并进已有通道要显式写 resolution。
 view.commitAddChannel({
-  id: 'new-channel', name: '对象通道', from: 'station-a', to: 'station-b',
-  lineIds: ['new-channel-1', 'new-channel-2'],
-  groups: [
-    { id: 'new-group-1', lineIds: ['new-channel-1'], path: [[116.75, 39.86]] },
-    { id: 'new-group-2', lineIds: ['new-channel-2'], path: [[116.75, 39.98]] }
-  ],
-  width: 28,
-  lineProps: { color: '#2f6fd0', lineType: 'dashed' },
-  owner: '运维一班'             // 其余字段 → channelProps
+  channel: {
+    id: 'new-channel', name: '对象通道', from: 'station-a', to: 'station-b',
+    lineIds: ['new-channel-1', 'new-channel-2'],
+    groups: [
+      { id: 'new-group-1', lineIds: ['new-channel-1'], path: [[116.75, 39.86]] },
+      { id: 'new-group-2', lineIds: ['new-channel-2'], path: [[116.75, 39.98]] }
+    ],
+    width: 28,
+    owner: '运维一班'
+  },
+  lineProps: { color: '#2f6fd0', lineType: 'dashed' }
 })
 
 // 6. 容器写法：一段一段覆盖草稿，没写的继续用草稿。
-//    lines / lineData / lineItems 同义，优先级 lines > lineData > lineItems，给了几条就建几条。
+//    lines / lineData 同义，优先级 lines > lineData，给了几条就建几条。
 view.commitAddChannel({
   resolution: 'newChannel',
   from: 'station-a',
   to: 'station-b',
   channel: { id: 'container-channel', name: '容器通道', nodeWidth: 1 },
-  lines: [
+  lineData: [
     { id: 'n-1', color: '#dd4b2e', width: 2.2, name: '一回' },
     'n-2',
     { id: 'n-3', color: '#2ea36b', voltageLevel: '10kV' }
@@ -654,52 +704,56 @@ view.commitAddChannel({
     { id: 'container-channel::1', lineIds: ['n-1', 'n-2'] },
     { id: 'container-channel::2', lineIds: ['n-3'], path: [[116.78, 39.96]] }
   ],
-  routing: 'orthogonal',       // 只有容器这一层的 routing 会改走线
-  path: [[116.78, 39.9]],      // 中间拐点，不含两端
-  lineProps: { opacity: 0.9 }, // 容器合并：草稿 → 顶层 → line.lineProps → 逐条
-  channelProps: { width: 36 }  // 最后覆盖新通道字段
+  routing: 'orthogonal',
+  path: [[116.78, 39.9]],
+  lineProps: { opacity: 0.9 },
+  channelProps: { width: 36 }
 })
 
-// 7. 只给 channel.lineIds 当种子：没有 lines / line / lineData / lineItems 时，每个 id 建一条回线
+// 7. 只给 channel.lineIds 当种子：没有 lines / line / lineData 时，每个 id 建一条回线
 view.commitAddChannel({
   channel: { id: 'seed-channel', from: 'station-a', to: 'station-b', lineIds: ['seed-1', 'seed-2'] },
   lineProps: { color: '#2f6fd0', width: 2 }
 })
 
-// 8. 空数组不覆盖草稿：lines / lineData / lineItems 给 [] 时，沿用草稿的 lineItems / circuits
+// 8. 空数组不覆盖草稿：lineData / lines 给 [] 时，沿用草稿的 lineData / circuits
 view.commitAddChannel({ channel: { id: 'draft-lines' }, lines: [] })
 
-// 9. 覆盖端点 / id / 名称 / 路由：顶层字段优先，lineId 是多回时自动展开的 id 种子
+// 9. 覆盖端点 / id / 名称 / 路由：顶层字段优先，id 是线路 id 种子
 view.commitAddChannel({
-  from: 'station-c', to: 'station-d', name: '改道联络线',
-  lineId: 'rerouted', lines: [{ id: 'rerouted-1' }, { id: 'rerouted-2' }],
+  from: 'station-c', to: 'station-d', name: '改道联络线', id: 'rerouted',
+  lineData: [{ id: 'rerouted-1' }, { id: 'rerouted-2' }],
   routing: 'orthogonal', path: [[116.9, 39.9]]
 })
 
-// 10. 并进已有通道 / 分组：直接通道默认新建，所以用容器并显式写 resolution
+// 10. 并进已有通道 / 分组：显式写 resolution
 view.commitAddChannel({
   resolution: { type: 'joinGroup', groupId: 'c1::2' },
-  lines: [{ id: 'join-1', color: '#dd4b2e' }, { id: 'join-2', color: '#2ea36b' }],
+  lineData: [{ id: 'join-1', color: '#dd4b2e' }, { id: 'join-2', color: '#2ea36b' }],
   lineProps: { width: 2.4 }
 })
 
-// 11. 第二参数只管本次收尾：continuous: false 强制结束；originalEvent 原样带回重开的草稿
-view.commitAddChannel(undefined, { continuous: false, originalEvent: null })
+// 11. 第二参数只管本次收尾与选中：continuous: false 强制结束，select: true 才选中新回线
+view.commitAddChannel(undefined, { continuous: false, originalEvent: null, select: true })
 const commitResult = view.commitAddChannel()
 console.log(commitResult.ok, commitResult.kind, commitResult.lineIds, commitResult.channelLineIds)
 
-view.continueAddChannel({ kind: 'line' })              // 连续模式下开下一段（也能换这一段加什么）
+// 连续模式只续草稿配置，不能把这一段切换成线路；要线路请重新 beginAddLine
+view.continueAddChannel({ from: 'station-b' })
 view.cancelAddChannel()                                // 取消（Esc / 右键等价）
 
-// 交接模式：两个节点选完发完 ready，假通道当场收掉，使用方自己走 addChannel
+// 交接模式：两个节点选完发完 ready，假通道当场收掉，使用方自己走 addChannel。
+// 新增回线缺省不选中；这里显式传 options.select: true。
 view.beginAddChannel({ handoff: true })
 view.updateOptions({
   onChannelDraft: payload => {
     if (payload.phase === 'ready') {
-      view.addChannel({ from: payload.from.id, to: payload.to.id, name: '手填通道' }, [
-        { id: 'm-1', color: '#dd4b2e' },
-        { id: 'm-2', color: '#2ea36b' }
-      ])
+      view.addChannel(
+        { from: payload.from.id, to: payload.to.id, name: '手填通道' },
+        [{ id: 'm-1', color: '#dd4b2e' }, { id: 'm-2', color: '#2ea36b' }],
+        undefined,
+        { select: true }
+      )
     }
   }
 })
@@ -714,27 +768,55 @@ if (between?.hasChannel) {
   console.log(between.channelId, between.groupCount, between.groups.map(group => group.id), between.currentGroupId)
 }
 
-// addChannel(spec, lineData?, group?) / addChannels(input, options?) / addChannelGroups(channelId, groups, options?) / addLine(input)：程序化新增
-const channelAdd = view.addChannel({ from: 'a', to: 'b', name: '二号通道', path: [[200, 120]] }, [{ id: 'm-1' }, { id: 'm-2' }])
-const manyChannels = view.addChannels([{ from: 'a', to: 'b', circuits: 1 }, { from: 'b', to: 'a', circuits: 2, kind: 'line' }])
+// getDirectConnections(pointIds)：只取这组节点之间的直接通道 / 线路（不走中间节点；没有就是 []）
+const directConnections = view.getDirectConnections(['a', 'b'])
+for (const connection of directConnections) {
+  if (connection.type === 'channel') {
+    console.log('通道', connection.channelId, connection.lineIds, connection.from.id, connection.to.id)
+  }
+  else {
+    console.log('线路', connection.lineId, connection.from.id, connection.to.id)
+  }
+}
+
+// addChannel(spec, lineData?, group?, options?) / addChannels(input, options?)
+// addChannelGroupLines(channelId, lineData?, group?, options?) / joinChannelGroupLines(channelId, groupId?, lineData?, options?)
+// addChannelGroups(channelId, groups, options?) / addLine(spec, lineData?, options?)：程序化新增
+// 所有入口缺省都不改变选中集；只有 options.select: true 才选中这一次新建的回线。
+const channelAdd = view.addChannel(
+  { from: 'a', to: 'b', name: '二号通道', path: [[200, 120]] },
+  [{ id: 'm-1' }, { id: 'm-2' }],
+  undefined,
+  { select: true }
+)
+const manyChannels = view.addChannels([
+  { from: 'a', to: 'b', name: '三号通道', lineData: [{ id: 'm-3' }, { id: 'm-4' }] },
+  { from: 'b', to: 'a', name: '四号通道', lineData: ['m-5'] }
+])
+console.log(channelAdd.lineIds, manyChannels.lineIds)
+
+// 独立线路：第二段 lineData 给几条就建几条；只碰 lines，不碰 channels
+const lineAdd = view.addLine(
+  { from: 'c', to: 'd', name: '三回' },
+  [
+    { id: 'wl-1', name: '第一回', color: '#dd4b2e', width: 5 },
+    { id: 'wl-2', color: '#2ea36b' }
+  ],
+  { select: true }
+)
+console.log(lineAdd.lineIds, lineAdd.channelId) // channelId 为 null：独立线路不挂通道
+
+// 已有通道：新加一组 / 并进某一组（语义直说，不用自己拼 resolution）
+const addedGroup = view.addChannelGroupLines('c1', [{ id: 'm-6' }], { id: 'c1::3' }, { select: true })
+const joined = view.joinChannelGroupLines('c1', 'c1::2', [{ id: 'm-7' }])
+console.log(addedGroup.channelLineIds, joined.channelLineIds) // 更新后这条通道的完整成员表
+
+// 一次加多组：每组写 lineData / lines，lineItems 已移除；缺省不选中
 const manyGroups = view.addChannelGroups('c1', [
-  { id: 'c1::4', path: [[130, 70]], lineData: [{ id: 'm-7' }, { id: 'm-8' }] },
-  { path: [[150, 90]], lines: ['m-9'] }
+  { id: 'c1::4', path: [[130, 70]], lineData: [{ id: 'm-8' }, { id: 'm-9' }] },
+  { path: [[150, 90]], lines: ['m-10'] }
 ])
 console.log(manyGroups.count, manyGroups.lineIds, manyGroups.groupIds)
-const lineAdd = view.addLine({ from: 'a', to: 'b', name: '三回' })
-// 第二段 lineItems：连同线路一起新建（一条或一批逐条属性），给了几条就建几条（circuits 忽略）
-const withLines = view.addChannel({ from: 'c', to: 'd', name: '三号通道' }, [
-  { id: 'wl-1', name: '第一回', color: '#dd4b2e', width: 5 },
-  { id: 'wl-2', color: '#2ea36b' }
-])
-// 并进已有通道：resolution 或顶层简写（channelId / groupId / groupIndex）
-view.addChannel({ from: 'a', to: 'b', resolution: { type: 'joinGroup', groupId: 'c1::1' } })
-const joined = view.addChannel({ from: 'a', to: 'b', channelId: 'c1', groupIndex: 0 })   // 旧写法：取这条通道的第 0 组
-// 已经有通道时用拆出来的两条（语义直说，不用自己拼 resolution）
-view.addChannelGroupLines('c1', [{ id: 'm-5' }], { id: 'c1::3' })     // 新加一组
-view.joinChannelGroupLines('c1', 'c1::2', [{ id: 'm-6' }])            // 并进某一组（序号 1 也认）
-console.log(joined.channelLineIds)   // 更新后这条通道的完整成员表（lineIds）
 
 // removeLine(lineId) / removeLines(lineIds) / removeChannel(channelId)：删线路 / 删多条 / 删整条通道
 view.removeLine('l1')
@@ -851,6 +933,10 @@ view.updateLabel('point', 'a', { style: { color: '#f60' } })
 view.updateLabel('point', 'a', { labelId: 'volt', content: '{vn_kv} kV' })
 view.updateLabel('line', 'l1', { labelId: 'note1', hidden: true })
 view.updateLabel('point', 'a', { position: 'bottom', offset: [0, 6], visibility: 'always' })
+view.updateLabel('point', 'a', { followNodeZIndex: true })       // 跟随节点样式链的 zIndex
+view.updateLabel('point', 'a', { zIndex: 30 })                  // 显式层级压过跟随
+view.updateLabel('line', 'l1', { zIndex: 10, zoomScale: 1 })    // 线路标签层级 + 字号随地图缩放
+view.updateLabel('point', 'a', { zIndex: null, zoomScale: null }) // 回到配置默认
 
 // addLabel(kind, ref, definition, labelId?) / removeLabel(kind, ref, labelId?)
 const addedLabel = view.addLabel('point', 'a', { content: '{name} 备注', position: 'bottom' })
@@ -934,6 +1020,7 @@ view.clearWebGLLayers()                            // 清空全部自定义层
 // exportData(options?)：统一入口 —— scope 选范围（all / viewport / selection），parts 选分项，format 选口径
 const viewFormat = view.exportData()                                  // 全量 + view 口径（缺省）
 const inViewport = view.exportData({ scope: 'viewport', margin: 24 }) // 视口内，可外扩 24 屏幕像素
+const endpointsOnly = view.exportData({ scope: 'viewport', selectionKinds: ['lineEndpoints', 'channelEndpoints'] }) // 两端节点都在视口内
 const picked = view.exportData({ scope: 'selection', parts: ['station', 'channel'], withLines: true })
 const fullDoc = view.exportData({ format: 'full' })    // 标准数据文档：整份喂回 createGisView / importData 就回到这一屏
 const testFormat = view.exportData({ format: 'test', parts: ['line', 'waypoint'] })

package/docs/manual/19-/350/257/273/346/225/260/344/270/216/346/213/226/346/213/275/351/242/204/350/247/210.md

@@ -36,7 +36,7 @@ canvas.addEventListener('contextmenu', (event) => {
 
 `GisViewListOptions` 的几个筛选条件是「与」的关系：`indexes`（只看这几个下标）、`inView`（`true` 按当前视口，或者直接给一份世界矩形 `{ minX, minY, maxX, maxY }`）、`limit`（最多几条）、`visibleOnly`（缺省 `true`：被筛选 / `visible: false` 隐藏掉的不算）、`withScreen`（补一份画布 CSS 像素坐标）。都不给就是「全部可见的」；十万级数据下这套方法适合面板读数、导出与校验，别逐帧调。
 
-`listPoints()` 用的就是引擎画点那一份可见判定（旧版单独暴露的 `getVisiblePoints()` 并进了这一条）：`radius` / 图层号 / 屏幕坐标这些几何读数都在它给的条目里。`focusOn()` 只移动相机、不改数据：缺省（以及显式 `{ center: true }`）只居中、比例不动，`{ zoom: true }` 才按目标范围适配，`{ select: true }` 顺带把这批选上，传一批目标（数组）就是整体居中。
+`listPoints()` 用的就是引擎画点那一份可见判定（旧版单独暴露的 `getVisiblePoints()` 并进了这一条）：`radius` / 图层号 / 屏幕坐标这些几何读数都在它给的条目里。`focusOn()` 只移动相机、不改数据：缺省只居中、比例不动，`{ zoom: true }` 才按目标范围适配，`{ select: true }` 顺带把这批选上，传一批目标（数组）就是整体居中。
 
 `getPointStyle()` / `getLineStyle()` 给的是**当前解析结果**：节点看尺寸 / 图标 / 层级，线路看原始线宽 / RGBA / 透明度 / 层级；悬停 / 选中样式、整体倍率、热力倍率都不算在里面。逐条自己写死的字段优先于规则与全局样式，所以用它们对账「预览里多大、落地后多大」或者鹰眼图的小图尺寸时，不需要自己重跑样式链。
 

package/docs/manual/20-/346/200/247/350/203/275/344/270/216/345/244/247/346/225/260/346/215/256.md

@@ -56,13 +56,15 @@ const stats = view.getStats()              // clusterCount / clusterPointCount /
 10 万点 + 10 万线（含通道）在 `docs/demos/GisViewDemo.vue` 里可以直接切到，交互路径上没有按总量线性增长的循环：
 
 - **高密度纯文本标签画布化**：强制显示档（`labelOptimize` 未开、`denseMode` 未激活）下，节点层或线路层里能画布的纯文本标签达到 **1024** 条时，默认 `labelRender: 'auto'` 会让该层改用一张 `.gis-view__label-canvas`，不再为每条标签建 `div`。要求优化档也走画布时显式写 `labelRender: 'canvas'`：不设数量阈值，`maxCount` / `when` / `scanLimit` 仍照常截断，避让、换锚点与沿线滑动直接使用画布尺寸，不创建也不测量 DOM。HTML、函数返回元素、可拖拽 / 可编辑及超出 Canvas 样式能力的标签始终留在同层 DOM，因此画布与少量 DOM 可以混排；`labelRender: 'dom'` 可强制回退逐条 DOM。画布路径另有文字测量缓存（同字体 / 样式 / 文案只量一次）、交互期 `requestAnimationFrame` 合并重绘与屏外标签裁剪，连续平移 / 缩放时不会因多次指针事件重复清画布。`selftest-labels.html` 用 1100 条纯文本验证字宽只测一次、连续 5 次缩放只重绘 1 次、显式画布在优化档遵守 `maxCount: 200`，以及线路标签 6 条全部进画布；另覆盖混入 `html: true` 时只保留那一条 DOM、切回 `dom`、再切回 `auto` 的节点回收与 SVG 导出。
+- **标签层级、节点遮挡与缩放字号**：跟随节点层级（`followNodeZIndex`）的点标签需要知道哪些更高层节点压住了自己的盒子。覆盖层为此按需建立一张 64px 屏幕网格，只收有效 `zIndex > 0` 的视口内节点；引擎没有任何非 0 节点层时整趟扫描直接跳过。判定只在标签真正参与排版时发生，被盖住的标签不占避让网格、不计 `maxCount`；`updatePoint` / `patchPoints` 会比对被改节点的层号、屏幕半径与坐标，必要重排时被改节点自己没标签也会补一次。`zoomScale` 的字号计算每轮只问一次相机，缩放指数共用 `Math.pow` 结果，交互期按 0.1px 量化后只改变换，停手再按真实字号校正盒子与避让，避免缩放过程中反复重排整屏标签。Canvas 标签仅在同层出现倒序时才排序，已有序时直接复用上一轮顺序。
+- **选中线路抬层**：`selectionOnTop` 没有把选中线路插进普通的逐线循环，而是把线路实例、阴影、圆头、高亮与热力光晕各自拆成「普通段 + 抬层段」；只在抬层集合真的变化时重铺线路批次，集合内容相同（只换了一份引用）不会把十万条线重算一遍。两端节点单独进抬层点集合，绘制次序因此固定为普通节点 → 抬层线路 → 抬层端点，不需要为每条线动态调整节点层号。
 - 拾取与框选共用网格索引：点走按数据范围重建的均匀网格，线走随线段重建的 `createSegmentGrid`，每次交互只遍历光标附近的候选，耗时与总量基本脱钩，`getStats().pickMs` 是随手可读的实测值（10 万规模下热态约 0.2 ~ 0.3 ms / 次）。线段按格线步进登记进它真正穿过的格子（早期按包围盒填格，一条斜跨全图的线会占掉上万格、只好整条丢进「超长线」单，而十万条线里绝大多数都是这种，于是每次拾取都要重算十万条的距离）；剩下的长线只记一条包围盒，查询时按盒子先筛一遍。10 万点 / 10 万线的合成数据里（随机配对、长线极密），500 次 `pick` 从 3530 ms 降到 164 ms（0.3 ms / 次）。
 - 拖动时「哪些线跟着这个点走」按需建索引：`collectDragLinks` 从前每次都把全部线路的端点与组内成员逐个比一遍，10 万点 / 12 万线下这一步占总 CPU 的 27%，是拖动路径上唯一还按总量线性付费的循环。现在线路超过 `LINE_BIND_TOLERANCE_SCAN_LIMIT`（2048）条时改用一张线路归属表（按 `from` / `to` 的 id 与端点坐标建，整份换数据 / 增删线 / 改绑定才重建，只改坐标就地把那一条换掉），只对命中的候选逐字段判定 —— 十万级拖动降到 CPU 的 1% 以下，单条 `updatePoint`（改名这类不动几何的改动）55 → 3.3 ms（稳态 0.02 ms）。线路不多时保留原来的浮点容差扫描（行为与从前逐字不差）；索引那条路只认 id 绑定与坐标精确相等 —— 这个量级坐标都是同一份来源算出来的，容差是给手写数据留的余量。
 - 视口里的线路改走线段网格：线路标签排版这类「只看屏幕里这一片」的路径（`forEachLineInView`）原先要把每条线的包围盒过一遍，10 万级 + 标签的 CPU profile 里它占 47 ~ 58%。现在线路超过 `LINE_VIEW_GRID_MIN_LINES`（2048）条、且估计出来的候选线段只占总数的 1/32 以内（`LINE_VIEW_GRID_COST_SHARE`）时改查拾取用的那张线段网格，再逐条按包围盒确认；候选排回要素下标顺序，脏线与没有线段的退化线单独补一遍，访问顺序与判定口径与整份扫描逐行相同。网格脏着（正在拖线 / 改线）或线路不多时照旧整份扫描。
 - 视口里的节点遍历也先查点网格：`forEachPointInView` 在节点超过 `POINT_VIEW_GRID_MIN_POINTS`（2048）、点网格不脏且估计候选不足总数的 1/32（`POINT_VIEW_GRID_COST_SHARE`）时，只查视口覆盖的格子、把候选排回数据顺序再逐个精确判定；网格脏着（刚改过数据 / 拖拽中）或视口几乎铺满时仍走整份扫描，避免为了省一趟遍历先付出建网格和排序的成本。`createPointGrid.estimate(..., stopAfter)` 与查询共用同一套格子口径，传 `stopAfter` 时一旦超过阈值立即返回，只判断候选是否过密时不必扫完视口里的全部格子；框选线路则复用已有的 `forEachLineInView`，不再为每条候选线复制路径 / 包围盒 / 颜色快照。
 - 数据包围盒读数改为缓存：整份解析本来已经顺路算出点与线的范围，`getBounds()` 直接接住这一份；定向改点 / 改线、拖拽、追加要素与复制预览只把缓存标脏，下一次真被问到时才用点坐标和每条线的 `line.bounds` 重建，不再逐顶点重扫。`getBounds()` 每次返回独立副本，调用方就地修改不会污染下一次读数；追加到原范围之外、拖出边界这类增量也会立即失效。10 万点 + 10 万线（每条 10 顶点）实测连续 10 次 `getBounds()`：优化前 **5.2 ~ 6.6 ms / 次**，优化后 **0.00 ms / 次**；改一个点后缓存重建一次 **3.6 ms**，读数正确。
 - 悬停、选中、拖拽只做增量更新：选中集合用点 / 线两张下标 `Set` 维护，样式变化按要素下标重新解析，顶点与实例数据就地改写后按「实例槽位」上传，不重建整批缓冲。
-- 选中事件的通道分组读数一次成型：同一条通道的 `groups` 只构造一份，`onSelect` / `onSelectChange` 与载荷顶层共享对象引用，不深拷贝；单通道不再额外生成 `channelContexts`，`items[]` 里的回线只保留 `channelId` / `channelIndex` / `groupId` / `groupIndex` 标量，不逐条重复挂 `group` / `groups`。单通道也不会先构造随后丢弃的 `lineIndexes` / `lineIds`，这两份只在多通道 `channelContexts` 里按选中顺序补一次。通道重建时顺手按 `channelIndex` 收好分组状态与组序号，后续悬停 / 选中查同通道分组和组号都是 O(1)，不再每次筛整张通道表；构造一条通道的全部分组读数从 O(组数 × 通道数) 降为 O(组数)。`selectFeatures` 对同内容、同顺序的重设会在引擎刷新和 `describeSelection` 之前直接返回；事件本身只在选中操作 / 选中集变化时发生，不进入逐帧渲染路径。
+- 选中事件的通道上下文只在外层出现一次：同一条通道的 `groups` 只构造一份，`onSelect` / `onSelectChange` 与载荷顶层共享对象引用，不深拷贝；单通道把通道 / 当前组与本次选中的 `lineIndexes` / `lineIds` 摊平到顶层，不再额外生成 `channelContexts`，多通道才使用 `channelContexts`。`items[]` 里的回线完全不挂 `channelId` / `channelIndex` / `groupId` / `groups` 等通道字段，十万级选中时不为每条线路重复写同一份归属。组件侧按载荷外层的 `lineIndexes` 一次建立“线路下标 → 通道”缓存；选中数组换新时按引用失效，其他改动路径用引擎 O(1) 的 `getLineChannel()` 补建，`getSelectionInfo()`、复制与 `getSelectionData()` 直接查表，不再逐条 `describe()`。通道重建时顺手按 `channelIndex` 收好分组状态与组序号，后续悬停 / 选中查同通道分组和组号都是 O(1)；构造一条通道的全部分组读数从 O(组数 × 通道数) 降为 O(组数)。指针载荷先展开拾取结果再补 `action` / 光标读数，不再把 `type` / `index` / `item` 和整个结果各写一遍；`selection`、按键 / 修饰键、`clientX` / `clientY` 这类可再取得的读数不再每条事件复制一份，`lngLat` 也改为就地补字段。`selectFeatures` 对同内容、同顺序的重设会在引擎刷新和 `describeSelection` 之前直接返回；事件本身只在选中操作 / 选中集变化时发生，不进入逐帧渲染路径。
 - 状态样式就地更新：悬停 / 选中样式只改颜色、大小、描边时按实例槽位覆盖，不重建整批；符号换成 / 换出贴图、阴影条数变化这类批次结构变化才回退整批重排。哪些要素当前真的按状态样式画过另有一份记账（`stateStyledSignatures`），整体重建后立刻重算，取消选中时按它精确还原本体样式，不会留下残留。
 - 动效只维护真正的动画线路：`lineEffectRuns` 让每帧的动点循环只遍历配了 `effect` 的线路，路径就地变化时只重算这一条的总长与包围盒；普通线路再多，也不会进入动画的逐帧扫描。
 - 热力图的要素采样与密度烘焙分开缓存：坐标 / 权重 / 显隐变化才重新采集，核参数 / 色带变化复用采样重烤，`density.opacity` 与 `layer` 只改绘制；拖动期间延迟到停手统一补烤。
@@ -106,8 +108,8 @@ const stats = view.getStats()              // clusterCount / clusterPointCount /
 - **运动期保持全分辨率**：`interactionNoMsaa` 的非 MSAA 后备缓冲只换抗锯齿与细线画法，不降低 viewport / 后备存储尺寸。相机拖动、滚轮、`zoomBy` / `setCamera` / 飞行与尺寸倍率变化的帧都按画布实际像素绘制，整幅贴回保持 1:1，停手 160 ms 后恢复 MSAA 静态帧。上一轮曾按整帧间隔把运动帧降到 **0.65× / 0.5×** 再线性放大贴回，实测会让缩放 / 移动中的画面短暂模糊，现已整体移除；与之配套的 `drawWidth` / `drawHeight` / `framePixelRatio`、`u_offsetScale` 和 UV 裁剪也一并删除。尺寸倍率连续变化仍复用 160 ms 的 `scaleMotion` 窗口，暂停符号贴图重烤与预烤，停手后再对齐当前尺寸档；这部分只省重烤，不改变当前帧分辨率。最终全分辨率基准（1280×800，无头 Chrome + ANGLE / AMD D3D11，`quality: 'high'`，三次运行取中位）：10 万点 / 5 万线缩放 p50 **23.2 ms**、p95 **28.6 ms**，平移 **16.7 / 18.2 ms**；10 万点 / 10 万线缩放 **42.6 / 46.3 ms**，平移 **16.7 / 24.5 ms**。`selftest-perf.html` 另有回归断言记录每次 `gl.viewport`，人为拉长运动帧间隔时也必须始终等于画布全尺寸。
 - **片元管线专用化（为什么此前「感觉没提升多少」）**：之前的优化主要落在相机排帧、聚合脏标记、整份重排与符号预烤上；10 万线交互的 CPU profile 约 **98.6% idle**、`render` 自身约 **0.1%**，说明主线程不是瓶颈。真正剩余的是每条可见线在 GPU 上重复执行虚线取模 / `smoothstep` / 光晕分支的填充成本。`shaders.js` 现在给交互期 `gl.LINES` 一条只输出颜色的 `THIN_LINE_FRAGMENT_SHADER`，并给「全实线、无光晕」的四边形批次一条 `SOLID_LINE_FRAGMENT_SHADER`：跳过虚线取模、`smoothstep` 与光晕分支，只保留颜色与（非 MSAA 帧的）边缘覆盖率；有虚线或热力光晕的批次仍走通用片元。`engine.js` 的 `drawLineBatch` 按批选择，`refreshLineThinLedger` 同时给出是否全实线；线宽、端点圆头、全分辨率与停稳后的 MSAA 静态帧都不变。实测（1280×800，无头 Chrome + ANGLE / AMD D3D11，`quality: 'high'`）：10 万点 / 5 万线缩放 p50 **23.2 → 16.7 ms**、p95 **28.6 → 16.8 ~ 16.9 ms**；10 万点 / 10 万线缩放三次中位 p50 **42.6 → 18.0 ms**、p95 **46.3 → 21.4 ms**。16 ~ 18 ms 已接近 60Hz 帧节拍，剩余成本仍是 GPU 填充率；细线快路径的实际门槛是**最大半宽 ≤ 0.6 设备像素且无虚线**（dpr = 1 时约 1.2px 线宽），2px 实线不会走 `gl.LINES`，但轻量四边形片元仍把同一 10 万线场景从约 **82.4 → 63.9 ms**。要继续明显提速，方向是减少可见线段数或屏幕覆盖面积，而不是继续抠 JS。
 
-- 框选提交（`pointerup`）只做必要的工作：选中集每次同步整份换新，抬层集合因此只比引用（没有拖动 / 合并这类额外抬层时直接引用选中集本身，空集合三处共用一份），撤销选中与「同内容再框一次」不再逐个搬 / 逐个比 3.4 万个下标；组件层的选中集读数（id 表、键集合、点 / 线 / 通道条数）在一趟循环里收好并按数组引用缓存，`selectionInfo()` / `selectChanged()` / `selectChange` 载荷直接取现成的；选中集的存活校验走 `isKeyAlive` 的键查表，不再为每个键造对象、投影一次；抬层欠下的整份重排记在 `raiseLayoutPending` 上、由 `flushRaiseLayout` 在下一帧渲染之前补，`pointerup` 回调里不再同步排十万级场景。实测（10 万点 / 10 万线）：框住 3.4 万个节点的 `pointerup` 48.7 → 15.7 ms（框小一些的几轮 9.5 / 6.5 / 6.8 ms），提交后第一帧 19.5 ~ 24.2 → 15.6 / 6.7 ~ 9.5 ms。
-- 整份重排（`layoutScene`）也少扫几趟十万条：点 glyph 从对象池里复用（逐字段就地改写，不再每轮造十万个对象）、圆点实例用 `writeCircleGlyph` 直写进 `prepareInstances` 的批次数组（不再逐条造 `circleFromGlyph` 的中间对象）；没有线路装饰 / 没有跑动动画 / 没有节点阴影 / 没有逐要素状态样式时，各自的十万级空扫直接跳过（`hasLineDecorations` / `hasLineEffects` / `hasPointShadows`，节点侧另有 `hasPointStateStyles()`）；细线快路径的账本只在「线宽或虚线开关真的变了」时才标脏；`zIndex` 分层只有一层（绝大多数场景）时不再重铺点顺序。同一份 10 万级的 CPU profile 里 `syncRaiseSets` 6.2 → 0 ms、`buildLineEffectGlyphs` 3.69 → 0 ms、`buildLineDecorationGlyphs` 1.66 → 0.62 ms、`thinLineBatchEligible` 2.2 → 0 ms。
+- 框选提交（`pointerup`）只做必要的工作：选中集每次同步整份换新，抬层集合因此只比引用（没有拖动 / 合并这类额外抬层时直接引用选中集本身，空集合三处共用一份），撤销选中与「同内容再框一次」不再逐个搬 / 逐个比 3.4 万个下标；组件层的选中集读数（id 表、键集合、点 / 线 / 通道条数）在一趟循环里收好并按数组引用缓存，`getSelectionInfo()` / `selectChanged()` / `selectChange` 载荷直接取现成的；选中集的存活校验走 `isKeyAlive` 的键查表，不再为每个键造对象、投影一次；抬层欠下的整份重排记在 `raiseLayoutPending` 上、由 `flushRaiseLayout` 在下一帧渲染之前补，`pointerup` 回调里不再同步排十万级场景。实测（10 万点 / 10 万线）：框住 3.4 万个节点的 `pointerup` 48.7 → 15.7 ms（框小一些的几轮 9.5 / 6.5 / 6.8 ms），提交后第一帧 19.5 ~ 24.2 → 15.6 / 6.7 ~ 9.5 ms。
+- 整份重排（`layoutScene`）也少扫几趟十万条：点 glyph 从对象池里复用（逐字段就地改写，不再每轮造十万个对象）、圆点实例用 `writeCircleGlyph` 直写进 `prepareInstancesForLayout` 的批次数组（不再逐条造 `circleFromGlyph` 的中间对象）；没有线路装饰 / 没有跑动动画 / 没有节点阴影 / 没有逐要素状态样式时，各自的十万级空扫直接跳过（`hasLineDecorations` / `hasLineEffects` / `hasPointShadows`，节点侧另有 `hasPointStateStyles()`）；细线快路径的账本只在「线宽或虚线开关真的变了」时才标脏；`zIndex` 分层只有一层（绝大多数场景）时不再重铺点顺序。同一份 10 万级的 CPU profile 里 `syncRaiseSets` 6.2 → 0 ms、`buildLineEffectGlyphs` 3.69 → 0 ms、`buildLineDecorationGlyphs` 1.66 → 0.62 ms、`thinLineBatchEligible` 2.2 → 0 ms。
 - 定向更新的线路标签候选复用：`updatePoint` / `patchPoints` 只改节点侧（补丁没动坐标 / id、筛选也没开）时，线路标签层接着用上一轮收好的候选 —— 视口矩形、画布尺寸与「上一轮显示过的下标集合」逐项核对（定义对象是缓存键），十万条线的视口扫描整个省掉；改线路内容 / 挪节点 / 换 id / 筛选联动时判据返回 `undefined`，照旧整层重扫。10 万点 / 10 万条长线 + 两层标签（DOM 75 条）实测单次 `updatePoint` p50 **4.7 → 1.7 ms**，CPU profile 采样 531 → 226、`forEachLineInView` 从热点清单消失。
 - 超长线段换更粗的一层网格：线段网格原来给「一层里铺不下的长线」只记一条包围盒、查询按盒子先筛，长线密布时几乎等于全量重算；现在每层格子边长 ×4，粗层同样只登记线段真正穿过的格子（跨层 stamp 去重），候选从「包围盒相交」变成「几何上真的经过光标附近」。10 万条随机长线实测一次查询的候选 11101 → **2210** 条、`pick` p50 / p95 / 平均 **0.9 / 6.2 / 1.90 → 0.3 / 1.7 / 0.53 ms**；代价是极限数据集建网格 16.3 → 41.6 ms、堆内存多约 26 MB（短线为主的数据集不变）。
 - **补点 / 删点不再因为「场景没铺完」回落整份重建**：发散渲染（见《实现原理》15.46）欠着账时，`addPoint` / `addPoints` / `addLines` 原先一律回落整份重解析（几十毫秒），「删一条 → 立刻补一条」这种最常见的串操作因此每一轮都付整份的钱。现在补点这一趟自己把没铺完的那一轮停掉、只补末尾这几条，再按新的解析结果重开一轮；删除那一趟同理（15.89）。5 万点 / 3 万线实测：稳态 `addPoint` 0.4 ~ 1.3 ms，「删一条 → 立刻补一条」29.7 → **1.3 ~ 6.4 ms**。纯删点这一趟还整段跳过通道解析（通道声明逐条没变、没删到回线与锚点时，骨架与全部回线折线照用上一轮的），选中通道时抬层集合也改成按内容比对（内容没变就不再重铺十万条线的批次）。导出这条链顺手切了三刀（空标签表先判空、节点坐标不造中间对象、折线端点共用一个取值回调）：50k 点 + 30k 线全量 `exportData()` 中位 22.1 → 21.6 ms、`exportData({ scope: 'viewport' })` 36.7 → 32.5 ms（首跑那一次 36 ~ 38 ms 是 id 表与 JIT 冷着，跑第二遍就落回 20 ms 上下）。

package/docs/manual/21-/350/257/264/346/230/216/344/270/216/345/270/270/350/247/201/351/227/256/351/242/230.md

@@ -78,13 +78,13 @@
 **密度场那一层怎么看都糊成一片 / 看不出色带？** 先看三个数：`threshold`（门槛，抬到 0.15 ~ 0.3 就只留热点，参考图那种「大片浅色 + 白心」就是把门槛抬起来）、`gamma`（对比度，大于 1 把色带一圈圈收在热核外面）、`max`（`'auto'` 是分位膝盖，长尾数据别写死成场的峰值）。再看 `radiusRatio`：太小色斑会碎成一堆点、太大就糊成一整片，缺省 5.5% 是「一眼能看出色斑」的档。数据本身也要有疏密差别 —— 均匀铺满一屏的网格数据，密度场本来就该是平的。
 
 **没有通道，能只用点和线吗？**
-可以。`channels` 是可选声明，省略或写 `channels: []` 都能正常运行；`lines` 自己的 `path` / `from` / `to`、`direction`、`lineType` 与新增 / 选中 / 拐点编辑都不依赖通道。交互新增用 `beginAddChannel({ kind: 'line' })`，程序化用 `addLine` / `addLines`，不会往 `channels` 写任何东西。`?demo=connect` 就是从 `channels: []` 开始的纯点 + 线示例。
+可以。`channels` 是可选声明，省略或写 `channels: []` 都能正常运行；`lines` 自己的 `path` / `from` / `to`、`direction`、`lineType` 与新增 / 选中 / 拐点编辑都不依赖通道。交互新增用 `beginAddLine()`，程序化用 `addLine` / `addLines`，不会往 `channels` 写任何东西。`?demo=connect` 就是从 `channels: []` 开始的纯点 + 线示例。
 
 **怎么加一条不挂通道的线路？**
-`view.addLine({ from, to })`（等价于 `addChannel({ from, to, kind: 'line' })`），走交互就是 `beginAddChannel({ kind: 'line' })`。它只往 `lines` 里加一条（或 `circuits` 条）普通线路，`channels` 声明一个字节都不动 —— `getChannels()` 里不会出现它，之后也不用担心它被通道分组、拆分、整条通道删除这些操作牵连。反过来 `beginAddChannel()` / `addChannel()` 是新建通道：新签名只负责新建，已经存在通道时要加一组 / 并进某一组用 `addChannelGroupLines` / `joinChannelGroupLines`（旧写法的 `addChannel` 仍按方案表分流）。
+`view.addLine({ from, to })` 新增一条独立线路，走交互就是 `beginAddLine()`；要一次加多回就传第二段 `lineData`（例如 `view.addLine({ from, to }, [{ id: 'l-1' }, { id: 'l-2' }])`）。它只往 `lines` 里加普通线路，`channels` 声明一个字节都不动 —— `getChannels()` 里不会出现它，之后也不用担心它被通道分组、拆分、整条通道删除这些操作牵连。`addLine` 缺省不改变选中集，需要选中新线时传 `{ select: true }`。反过来 `beginAddChannel()` / `addChannel()` 是新建通道：`addChannel` 只负责新建，已经存在通道时要加一组 / 并进某一组用 `addChannelGroupLines` / `joinChannelGroupLines`。
 
 **怎么一次给通道加多回？**
-`circuits` 就是「这一次加几条」：`beginAddChannel({ kind: 'channel', circuits: 3 })` / `addChannel({ from, to, circuits: 3 })`（旧写法），新建线路也一样（`addLine({ from, to, circuits: 2 })` 一次两条）。方案表的余量按它算 —— 加 3 回时只剩 2 回余量的分组会置灰，`reason` 写清「只剩 2 回余量，本次要加 3 回」；落地回执里 `lines` / `lineIds` 是这一批线，`onChannelDraft` 的 `commit` 载荷里也一样，`removeLine` 一条条摘掉就行（demo 的「移除上一条新增」就是整批摘）。
+通道草稿和 `commitAddChannel` 用 `circuits` 表示「这一次加几条」；程序化 `addChannel` / `addLine` 的新版入口用第二段 `lineData` 的长度表示回数。例如 `addChannel({ from, to }, [{ id: 'l-1' }, { id: 'l-2' }, { id: 'l-3' }])` 一次建三回，独立线路写成 `addLine({ from, to }, ['l-1', 'l-2'])`。方案表的余量按本次条数算 —— 加 3 回时只剩 2 回余量的分组会置灰，`reason` 写清「只剩 2 回余量，本次要加 3 回」；落地回执里 `lines` / `lineIds` 是这一批线，`onChannelDraft` 的 `commit` 载荷里也一样，`removeLine` 一条条摘掉就行（demo 的「移除上一条新增」就是整批摘）。这些入口缺省都不选中新回线，`options.select: true` 才会选中。
 
 **鹰眼图的节点大小 / 范围 / 框选怎么调？**
 节点大小：`inheritRules` 打开（默认）时，小图取主图最终解析出的尺寸，再乘「小图视口 ÷ 主图视口」的较小比例 —— 只看两边 CSS 视口宽高，不随主图相机倍数变化；仍嫌大就调小图自己的 `pointSizeScale`，或配自己的 `pointRules` / `pointStyle` 接管尺寸。范围：`extent: 'auto'` 默认取数据 ∪ 底图且**不随相机收窄**；想要外围内容消失后跟着收窄才打开 `extentFollowCamera`。框选：`dragAction: 'box'` 不需要打开 `zoomable`，关闭缩放也能在空白处直接框；`zoomable: 'follow'` 是整体范围跟随主图，跟手动缩放 `true` 互斥。
@@ -142,7 +142,10 @@
 先分清卡的是哪一半：`getStats().frameMs` 量的是引擎自己那一趟（算变换、攒实例、写缓冲、发绘制），十万级下它常年 0.1 ~ 0.8 ms；真正花时间的是**填充率** —— 十万个节点加十几万条线铺满一屏，光栅化与浏览器合成都由 GPU（没有 GPU 时是软件光栅）扛，这一半不在 `frameMs` 里。于是按顺序看四件事：① **总覆盖量**（线的屏幕总长 × 宽度 × 条数，再算上互相重叠）—— 同样 10 万点，网格邻居线（19.9 万条、线短不叠）拖动 p50 只要 7 ms，而「每 5 个点连一条到 0 号点」的长线在圆心附近叠十几层，p50 就是 194 ~ 208 ms；② **MSAA** —— 同一份几何实测 MSAA 4× 是关掉时的近 5 倍（`antialias: false`，软件光栅下引擎已经自动关），读数看 `getStats().antialias`；交互期与动画期还有更省事的一档 `interactionNoMsaa`（缺省开：拖动 / 缩放与动画在跑的那些帧画进不带 MSAA 的后备贴图、收尾整幅贴回，停手 / 停帧后照旧走 MSAA）—— 十万级实测交互期单帧 133 → 36.6 ms、拖动 p50 130 → 16 ~ 22 ms、动画帧 212 → 53 ms，读数看 `getStats().noMsaa`；③ 交互期默认走**细线快路径**（`interactionThinLines`）：最大半宽 ≤ 0.6 设备像素（dpr = 1 时约 1.2px 线宽）且没有虚线时，拖动 / 缩放期间改用 `gl.LINES` 画，实测 p50 194 ~ 208 ms → 132 ~ 139 ms、同一窗口帧数 13 → 19 ~ 24，读数看 `getStats().thinLines`；2px 实线不会走这一档，但全实线四边形另有轻量片元；④ 画质档的杠杆是**分辨率**，`fast` 档按 0.75× 渲染（画布像素少一半），同一画面实测 156 → 92 ms/帧，自动档还看整帧间隔（连续画帧时掉到 40fps 以下就逐档往下掉）；高分屏 / 全屏下按 `maxCanvasPixels`（缺省 400 万像素预算）压渲染倍率、或把窗口开小，都是直接减填充量。见「画质」与「大数据量」。
 
 **一次改很多要素，回调被刷屏、历史被撑爆？**
-把这一段包进 `view.batch(fn, { label })`：收尾只发一条 `type: 'batch'` 的 `onDataChange`（`changes` 按顺序列出每一步），历史里也只占一步，见「批量更新」。
+把这一段包进 `view.batch(fn, { label })`：收尾只发一条 `type: 'batch'` 的 `onDataChange`（`changes` 按顺序列出每一步），历史里也只占一步。场站 / 线路直接用 `patchPoints` / `patchLines` / `removePoints` / `removeLines`，通道与分组把逐条 `updateChannel` / `removeChannel` / `splitChannelGroups` / `removeChannelGroup` 放进同一个 `batch` 即可，见「批量更新」里的增删改配方。
+
+**解除合并之后为什么没有默认选中恢复出来的节点？**
+这是现在的缺省口径：`splitPoint(source, ...)` 的 `options.select` 默认为 `false`，只把来源节点本身从选中集里摘掉，恢复 / 拆分出来的节点不选中，其它无关选中也不动。旧 Demo 在调用后又手动 `selectFeatures()`，看起来像组件默认选中。需要保持「解除后继续编辑这批节点」时显式传 `select: true`，例如 `view.splitPoint('hub', null, { select: true })`；手工拆分同样支持。
 
 **配置写了没反应，控制台也不报错？**
 听着 `onWarning`（或 `view.on('warning', …)`）：配置项的键写错、功能预设 / 画质档位拼错、订阅了不存在的事件名都会点名说一句，同一个错只提醒一次，见「配置提醒」。
@@ -182,12 +185,12 @@
 | 覆盖层 | `GisViewLabelOptions`、`GisViewLineLabelOptions`、`GisViewItemLabel`、`GisViewLabelState`、`GisViewLabelPatch`、`GisViewSetLabelContentOptions`、`GisViewLabelListItem`、`GisViewItemLabelsInfo`、`GisViewRemoveLabelResult`、`GisViewSetLabelStatesResult`、`GisViewLabelChangePayload`、`GisViewLabelDragPayload`、`GisViewLabelClickPayload`、`GisViewLabelPointerPayload`、`GisViewLabelRef`、`GisViewLabelTarget`、`GisViewLabelBatchEntry`、`GisViewLabelRemoveEntry`、`GisViewLabelBatchSkip`、`GisViewAddLabelsResult`、`GisViewUpdateLabelsResult`、`GisViewRemoveLabelsResult`、`GisViewLineDecoration`、`GisViewTooltipOptions`、`GisViewLabelPayload`、`GisViewLineLabelPayload` |
 | 筛选 | `GisViewFilter`、`GisViewFilterInput`、`GisViewFilterShorthand`、`GisViewFilterResult`、`GisViewFilterCascade`、`GisViewFilterMode`、`GisViewFilterWorkerOptions` |
 | 大数据展示模式 | `GisViewDenseMode`、`GisViewDenseModeOptions`、`GisViewDenseModeInput`、`GisViewDenseState` |
-| 通道 | `GisViewChannelInput`、`GisViewChannelBuildOptions`、`GisViewChannelBuild`、`GisViewChannelInfo`、`GisViewChannelGroupInfo`、`GisViewChannelGroupWaypoints`、`GisViewChannelGroupLineWaypoints`、`GisViewChannelMember`、`GisViewChannelContext`、`GisViewChannelAddPlan`、`GisViewChannelBetween`、`GisViewChannelAddOption`、`GisViewChannelAddInput`、`GisViewChannelAddCommitInput`、`GisViewChannelAddResult`、`GisViewChannelDraftOptions`、`GisViewChannelDraftPayload`、`GisViewChannelLineMoveTarget`、`GisViewChannelLineMoveResult`、`GisViewRemoveLineResult`、`GisViewRemoveChannelResult`、`GisViewRemoveLinesResult`、`GisViewChannelInView`、`GisViewChannelAction`、`GisViewChannelActionId`、`GisViewChannelDraftStyle`、`GisViewChannelDraftDots`、`GisViewChannelDraftDotStyle`、`GisViewChannelWaypointDragMode`、`createChannels`、`CHANNEL_DEFAULT_COLORS` |
+| 通道 | `GisViewChannelInput`、`GisViewChannelBuildOptions`、`GisViewChannelBuild`、`GisViewChannelInfo`、`GisViewChannelGroupInfo`、`GisViewChannelGroupWaypoints`、`GisViewChannelGroupLineWaypoints`、`GisViewChannelMember`、`GisViewChannelContext`、`GisViewChannelAddPlan`、`GisViewChannelBetween`、`GisViewChannelAddOption`、`GisViewChannelAddSpec`、`GisViewLineAddSpec`、`GisViewChannelLineData`、`GisViewChannelAddGroup`、`GisViewChannelAddResolution`、`GisViewChannelAddCommitInput`、`GisViewChannelAddResult`、`GisViewChannelDraftOptions`、`GisViewChannelDraftPayload`、`GisViewChannelLineMoveTarget`、`GisViewChannelLineMoveResult`、`GisViewRemoveLineResult`、`GisViewRemoveChannelResult`、`GisViewRemoveLinesResult`、`GisViewChannelInView`、`GisViewChannelAction`、`GisViewChannelActionId`、`GisViewChannelDraftStyle`、`GisViewChannelDraftDots`、`GisViewChannelDraftDotStyle`、`GisViewChannelWaypointDragMode`、`createChannels`、`CHANNEL_DEFAULT_COLORS` |
 | 事件载荷 | `GisViewPickResult`、`GisViewPickAtResult`、`GisViewRectQueryResult`、`GisViewSelectionInfo`、`GisViewSelectedItems`、`GisViewSelectPayload`、`GisViewClickPayload`、`GisViewPointerPayload、GisViewCascadeHighlightScope、GisViewCascadeHighlightOptions、GisViewCascadeHighlightInput、GisViewCascadeHighlightEntry、GisViewCascadeHighlightOrigin、GisViewCascadeHighlightInfo`、`GisViewPointerAction`、`GisViewPointerActionType`、`GisViewPointerTarget`、`GisViewPointerModifiers`、`GisViewWaypointActionData`、`GisViewLabelActionData`、`GisViewHoverPayload`、`GisViewCursorPayload`、`GisViewPointDragPayload`、`GisViewDragPointChange`、`GisViewDragLineChange`、`GisViewPointCopyPayload`、`GisViewPointCopyState`、`GisViewPointMergePayload`、`GisViewMergeImpact`、`GisViewMergeResult`、`GisViewMergeFailure`、`GisViewWaypointPayload`、`GisViewWaypointInfo`、`GisViewWaypointKey`、`GisViewParallelGroup`、`GisViewReadyPayload`、`GisViewEngineStats`、`GisViewEngineHeatDensity`、`GisViewDataChangeType`、`GisViewDataChangePayload`、`GisViewSelectChangePayload`、`GisViewShortcutPayload`、`GisViewRenderPayload`、`GisViewAddItemsResult`、`GisViewAddPointResult` |
 | 快捷键与复制 / 合并 / 删除 | `GisViewShortcuts`、`GisViewShortcut`、`GisViewShortcutAction`、`GisViewCopyOptions`、`GisViewCopyContext`、`GisViewCopyStartOptions`、`GisViewPasteOptions`、`GisViewCopyItem`、`GisViewClipboardItem`、`GisViewMergeOptions`、`GisViewMergeContext`、`GisViewPointStyleSnapshot`、`GisViewPointRef`、`GisViewMergeResult`、`GisViewMergeFailure`、`GisViewMergeOutcome`、`GisViewRemovePointsOutcome`、`GisViewRemoveSelectedOutcome`、`GisViewRemoveOptions`、`GisViewRemoveScope`、`GisViewRemovePayload`、`GisViewRemoveResult`、`GisViewRemoveOutcome`、`GisViewRemoveFailure`、`GisViewRemoveAction`、`GisViewRemovePoint`、`GisViewRemoveLine`、`GisViewRemoveWaypoint`、`GisViewRemoveGroup`、`GisViewRemoveChannel`、`GisViewRemoveCounts`、`GisViewChannelSelectMode`、`GisViewUpdateItemsOutcome`、`GisViewUpdateItemEntry` |
 | 相机与视图 | `GisViewCamera`、`GisViewViewport`、`GisViewFocusOptions`、`GisViewFocusTarget`、`GisViewExportImageOptions`、`GisViewExportSelectionOptions`、`GisViewExportSelectionResult` |
 | 导出数据 | `GisViewExportScope`、`GisViewExportPart`、`GisViewExportDataOptions`、`GisViewExportDataResult`、`GisViewFeatureRef`、`GisViewExportFilterOptions`、`GisViewExportMeta`、`GisViewExportedLabel`、`GisViewStationRecord`、`GisViewPointRecord`、`GisViewLineRecord`、`GisViewChannelRecord`、`GisViewExportFormat`、`GisViewBuiltinExportFormat`、`GisViewExportFormatContext`、`GisViewExportFormatAdapter` |
-| 开关 / 历史 / 事件 | `GisViewFeatureName`、`GisViewFeatures`、`GisViewFeatureState`、`GisViewFeaturePreset`、`GisViewFeaturesInput`、`GisViewSelectTrigger`、`FEATURE_NAMES`、`FEATURE_PRESETS`、`FEATURE_PRESET_NAMES`、`FEATURE_EDIT_NAMES`、`featureDefault`、`normalizeFeatures`、`featureOn`、`hasForcedFeatures`、`GisViewHistoryOptions`、`GisViewHistoryState`、`GisViewHistoryEntry`、`GisViewHistoryRecord`、`GisViewHistoryOp`、`GisViewHistoryOpEntry`、`GisViewHistoryRecorder`、`GisViewHistoryHost`、`GisViewHistoryPayload`、`GisViewHistoryStepResult`、`GisViewHistoryAction`、`GisViewHistoryCollection`、`createGisHistory`、`normalizeHistoryOptions`、`applyHistoryOps`、`DEFAULT_HISTORY_LIMIT`、`HISTORY_COLLECTIONS`、`GisViewEventMap`、`GisViewEventName`、`GisViewEventNameInput`、`GisViewEventWildcard`、`GisViewEventListener`、`GisViewAnyEventListener`、`GisViewEventBus`、`GisViewEventBusHost`、`createGisEventBus`、`EVENT_NAMES` |
+| 开关 / 历史 / 事件 | `GisViewFeatureName`、`GisViewFeatures`、`GisViewFeatureState`、`GisViewFeaturePreset`、`GisViewFeaturesInput`、`GisViewSelectTrigger`、`FEATURE_NAMES`、`FEATURE_PRESETS`、`FEATURE_PRESET_NAMES`、`featureDefault`、`normalizeFeatures`、`featureOn`、`hasForcedFeatures`、`GisViewHistoryOptions`、`GisViewHistoryState`、`GisViewHistoryEntry`、`GisViewHistoryRecord`、`GisViewHistoryOp`、`GisViewHistoryOpEntry`、`GisViewHistoryRecorder`、`GisViewHistoryHost`、`GisViewHistoryPayload`、`GisViewHistoryStepResult`、`GisViewHistoryAction`、`GisViewHistoryCollection`、`createGisHistory`、`normalizeHistoryOptions`、`applyHistoryOps`、`DEFAULT_HISTORY_LIMIT`、`HISTORY_COLLECTIONS`、`GisViewEventMap`、`GisViewEventName`、`GisViewEventNameInput`、`GisViewEventWildcard`、`GisViewEventListener`、`GisViewAnyEventListener`、`GisViewEventBus`、`GisViewEventBusHost`、`createGisEventBus`、`EVENT_NAMES` |
 | 动画效果与预热 | `GisViewLineEffect`、`GisViewLineEffectInput`、`GisViewPointEffect`、`GisViewPointEffectInput`、`GisViewEffectsOptions`、`GisViewEffectsInput`、`GisViewEffectsReadout`、`GisViewLineEffectReadout`、`GisViewPointEffectReadout`、`GisViewPrebakeOptions`、`GisViewPrebakeCombo`、`GisViewPrebakeReadout`、`GisViewSymbolCombos`、`PREBAKE_COMBO_KEYS`、`LINE_EFFECT_DEFAULTS`、`LINE_EFFECT_KEYS`、`POINT_EFFECT_DEFAULTS`、`POINT_EFFECT_KEYS`、`EFFECT_OPTION_KEYS`、`PREBAKE_OPTION_KEYS`、`normalizeLineEffect`、`normalizePointEffect`、`normalizeEffectsOptions`、`normalizePrebakeCombo`、`normalizePrebakeOptions`、`isEffectConfig`、`isEffectsExplicitlyOff`、`wrapPhase`、`phaseSeed`、`polylineLength`、`samplePolyline`、`lineEffectDistance`、`pointEffectPhase`、`sameLineEffect`、`samePointEffect` |
 | 坐标与映射 | `GisViewGeoProjection`、`GisViewGeoMapper`、`GisViewGeoMapperOptions`、`GisViewPointerState`、`GisViewResolvedGeoJson`、`createGeoProjection`、`createGeoMapper` |
 | 搜索 | `GisViewSearchOptions`、`GisViewSearchScope`、`GisViewSearchScopeInput`、`GisViewSearchHit`、`GisViewSearchGroupItem`、`GisViewSearchResult`、`GisViewVisiblePoint` |