gis-view-webgl2 0.1.11 → 0.1.13

package/docs/demos/api-index.js

@@ -7,8 +7,8 @@
  * 源码或文档改过之后重跑一遍；`node docs/steps/check-doc-coverage.mjs` 会对账。
  */
 
-/** { members: 274, methods: 269, properties: 5, options: 100, sections: 16 } */
-export const API_SUMMARY = {"members":274,"methods":269,"properties":5,"options":100,"sections":16}
+/** { members: 283, methods: 278, properties: 5, options: 107, sections: 16 } */
+export const API_SUMMARY = {"members":283,"methods":278,"properties":5,"options":107,"sections":16}
 
 /** 实例成员，按 docs/GisView.md「参数速查」的分组排 */
 export const API_SECTIONS = [
@@ -22,14 +22,18 @@ export const API_SECTIONS = [
 			{ name: "getData", kind: "method", params: "无", returns: "GisViewData", doc: "当前数据副本（点与线两列，含拖拽点之后的最新坐标）；通道声明不在这一份里 —— 读整份配置与数据用 getOptions()（getOptions().channels）、存档 / 回灌用 exportData({ format: 'input' })", examples: [{"group":"配置与数据","code":"// getOptions() / getData()：整份配置 / 整份数据（读到的就是组件内部那一份，只读）\nconst options = view.getOptions()\nconst { points, lines, channels } = view.getData()\n","from":"header"}] },
 			{ name: "updateData", kind: "method", params: "整份换数据：points?: GisViewPoint[] 新的节点数组（不传就不动）；lines?: GisViewLine[] 新的线路数组（不传就不动）；channels?: GisViewChannel[] 给了就连通道声明一起换（切场景一次换完、只发一条 dataChange）。也收单对象写法 updateData({ points, lines, channels })（只换给出的那几列；只换通道声明写 updateData({ channels })）；接口字段先在调用方映射成这三列，见「动态换数据与加载完成」", returns: "this", doc: "整份换数据：只给两个参数时换点与线（通道不动）；给 channels 时连通道一起换（切场景一次换完、只发一条 onDataChange）；也收单对象写法 updateData({ points, lines, channels })，只换给出的那几列 —— 只换通道声明写 updateData({ channels })，只换节点 / 线路写 updateData({ points }) / updateData({ lines })。接口字段先在调用方映射成这三列，见「动态换数据与加载完成」", examples: [{"group":"配置与数据","code":"// updateData(points, lines, channels?)：整份换数据，不传的那一列不动\nview.updateData(nextPoints, nextLines)                 // 只换点与线\nview.updateData(nextPoints, nextLines, nextChannels)   // 切场景一次换完，只发一条 dataChange\nview.updateData({ lines: nextLines, channels: nextChannels })  // 单对象写法：只换给出的那几列\n","from":"header"},{"group":"配置与数据","code":"// 只换一列也走 updateData 的单对象写法（没给的那几列不动）\nview.updateData({ channels: [{ id: 'c1', name: '二号通道', lineIds: ['l1', 'l2'] }] })\nview.updateData({ channels: [] })                      // 清空通道声明\nview.updateData({ points: [{ id: 'a', x: 0, y: 0 }, { id: 'b', x: 400, y: 200 }] })\nview.updateData({ lines: [{ id: 'l1', from: 'a', to: 'b' }] })\n","from":"header"}] },
 			{ name: "importData", kind: "method", params: "input: GisViewDocumentInput：标准文档（format: 'gis-view'）/ 与创建入参同构的数据对象（points / lines / channels / labelStates / view / filter，给哪列出哪列）/ 节点数组；options 可以把某一列（points / lines / channels / labelStates / view / filter）显式点上，checkKeys: false 不点名多余的顶层键", returns: "GisViewImportResult", doc: "整份喂回一份数据 / 一份标准文档（exportData 的五种格式都认，最标准的是 format: 'full' 那一份）：顶层出哪一列就应用哪一列（points / lines / channels / labelStates / view / filter），没出的列一个都不动；只给通道（不带点线）时单独换通道声明，只给 labelStates 时只动标签状态（整份语义）。返回 { ok, reason, applied, counts, warnings }，见「标准数据文档（full）：接收 == 导出」", examples: [{"group":"配置与数据","code":"// importData(input, options?)：标准文档 / 与创建入参同构的对象 / 节点数组都能灌\nview.importData({ format: 'gis-view', points: nextPoints, lines: nextLines, channels: nextChannels })\nview.importData(nextPoints)                            // 只灌节点数组\nview.importData({ points: nextPoints, view: { x: 10, y: 20, scale: 8 } })  // 连视角一起\nconst imported = view.importData(doc, { checkKeys: false })   // → { ok, reason, applied, counts, warnings }\n","from":"header"}] },
-			{ name: "updatePoint", kind: "method", params: "id: string | number 节点 id；patch: Partial<GisViewPoint> 要合并的字段（写 x / y 就是移动，写 null 摘掉这一项；写 visible: false 把这一条从图上收起、写 visible: true 排回来 —— 这一条要连绑定线 / 锚定通道一起重排，因此走整份重推一次，batch() 里一批只推一次）", returns: "this", doc: "定向更新一个节点 / 线路 / 通道并重渲染：单项字段（尺寸、图标、颜色、线宽、通道宽度 / 名称等）直接写补丁；只重排受影响的那一小片（节点 → 绑定线与锚定通道（尺寸 / 图标换过时，锚定通道的宽度一起按新尺寸重排，见「通道与多回线」），线路 → 这一条，通道 → 它的分组与成员），其余要素与缓存一个字节都不动；节点的 visible: false / 改回来会走一次整份重排（这一条要连绑定线、锚定通道与拾取索引一起退场 / 排回去，定向更新那条路落不下；同一个 batch() 里改一批只重排一次）；updateLine 的补丁里还能写 groupId / groupIndex（可配 channelId）顺带把这条回线挪到目标分组，updateChannel 写 groups / lineIds 会顺带改分组并补一条 channelGroups 变更（见「通道分组」）；updateChannel 还能给第三段 linePatches（一条或一批 { id | index, ...字段 }）把「通道声明 + 成员回线各自的字段 / 分组」一次下发 —— 声明先落、再逐条走 updateLine，整次调用只发一条 batch 数据变更、历史里只算一步（见「通道分组」与「逐方法示例」）；第三段里认不出的成员 id 带得起定义（from / to 两端可解析、可用的 path、或通道自己声明了两端）会当场建一条回线并挂进通道，给不出定义才跳过点名；updateLine 的拐点写在 path 上（整条折线，含首尾端点 —— 只写中间拐点用 setLineWaypoints(id, coordinates)），通道里的回线几何由通道骨架推导（path 写了也会被覆盖），改它走 setLineWaypoints / setChannelPath", examples: [{"group":"配置与数据","code":"// updatePoint(id, patch)：合并一个节点的字段；visible 翻面会连绑定线 / 锚定通道一起重排\nview.updatePoint('a', { x: 120, y: 40 })\nview.updatePoint('a', { name: '甲站（改）', status: 2 })\nview.updatePoint('a', { visible: false })              // 从图上收起；写回 true 排回来\n","from":"header"},{"group":"定向改一个要素（一次只动一条）","code":"// updatePoint(id, patch)：只写要改的字段（size / symbol / color…）\nview.updatePoint('a', { size: 12 })\nview.updatePoint('a', { symbol: { kind: 'square' } })\nview.updatePoint('a', { symbol: 'https://example.com/pin.png' })\nview.updatePoint('a', { symbol: null })                         // 回到内置圆\nview.updatePoint('a', { color: '#ff6b35' })\n","from":"header"}] },
-			{ name: "updateLine", kind: "method", params: "id 线路 id；patch: GisViewLinePatch 要合并的字段（path / from / to / color / width / labels… 都能改），还能写三个「分组指令」：groupId（或 groupIndex，可配 channelId）把这条回线挪到目标分组 —— groupId: 'newGroup' 单独拆一组、其余按现有分组 id 并组，走的是 moveChannelLine 那一套；三个字段只是指令，不会写进线路数据、不会出现在 updateLine 的载荷里，挪组成功会先发一条 channelGroups 变更（只给指令时这次调用就只发它）；拐点写在 path 上（整条折线，含首尾端点 —— 只写中间拐点用 setLineWaypoints(id, 中间拐点)），通道里的回线几何由通道骨架推导（path 写了也会被覆盖，改它走 setLineWaypoints / setChannelPath）", returns: "this", doc: "定向更新一个节点 / 线路 / 通道并重渲染：单项字段（尺寸、图标、颜色、线宽、通道宽度 / 名称等）直接写补丁；只重排受影响的那一小片（节点 → 绑定线与锚定通道（尺寸 / 图标换过时，锚定通道的宽度一起按新尺寸重排，见「通道与多回线」），线路 → 这一条，通道 → 它的分组与成员），其余要素与缓存一个字节都不动；节点的 visible: false / 改回来会走一次整份重排（这一条要连绑定线、锚定通道与拾取索引一起退场 / 排回去，定向更新那条路落不下；同一个 batch() 里改一批只重排一次）；updateLine 的补丁里还能写 groupId / groupIndex（可配 channelId）顺带把这条回线挪到目标分组，updateChannel 写 groups / lineIds 会顺带改分组并补一条 channelGroups 变更（见「通道分组」）；updateChannel 还能给第三段 linePatches（一条或一批 { id | index, ...字段 }）把「通道声明 + 成员回线各自的字段 / 分组」一次下发 —— 声明先落、再逐条走 updateLine，整次调用只发一条 batch 数据变更、历史里只算一步（见「通道分组」与「逐方法示例」）；第三段里认不出的成员 id 带得起定义（from / to 两端可解析、可用的 path、或通道自己声明了两端）会当场建一条回线并挂进通道，给不出定义才跳过点名；updateLine 的拐点写在 path 上（整条折线，含首尾端点 —— 只写中间拐点用 setLineWaypoints(id, coordinates)），通道里的回线几何由通道骨架推导（path 写了也会被覆盖），改它走 setLineWaypoints / setChannelPath", examples: [{"group":"配置与数据","code":"// updateLine(id, patch)：合并一条线路的字段；还能写 groupId / groupIndex（可配 channelId）顺带挪组\nview.updateLine('l1', { color: '#f00', width: 3 })\nview.updateLine('l1', { path: [[0, 0], [200, 120], [400, 200]] })   // 拐点写 path：整条折线（含首尾端点）\nview.updateLine('l1', { name: '一线', from: 'a', to: 'b' })        // 属性与端点一起改，只发一条 updateLines\nview.updateLine('l1', { groupId: 'newGroup' })         // 单独拆一组（只给指令时只发 channelGroups）\nview.updateLine('l1', { groupIndex: 0, channelId: 'c1' })          // 挪进指定通道的第 0 组","from":"header"},{"group":"定向改一个要素（一次只动一条）","code":"// updateLine(id, patch) / setLineWaypoints(id, coordinates)\nview.updateLine('l1', { width: 3 })\nview.updateLine('l1', { color: '#f00' })\nview.setLineWaypoints('l1', [[100, 40], [200, 120]])   // 中间拐点（不含首尾两端）\nview.setLineWaypoints('l1', [120, 80])                 // 只留一个拐点\nview.setLineWaypoints('l1', [])                        // 拉直\n","from":"header"}] },
+			{ name: "updatePoint", kind: "method", params: "id: string | number 节点 id；patch: Partial<GisViewPoint> 要合并的字段（写 x / y 就是移动，写 color / size / symbol / strokeColor / strokeWidth 就是改这一条的样式，写 null 摘掉这一项；写 visible: false 把这一条从图上收起、写 visible: true 排回来 —— 这一条要连绑定线 / 锚定通道一起重排，因此走整份重推一次，batch() 里一批只推一次）。命中的 override: true 规则会压住同字段的逐条补丁", returns: "this", doc: "定向更新一个节点 / 线路 / 通道并重渲染：单项字段（尺寸、图标、颜色、线宽、通道宽度 / 名称等）直接写补丁；只重排受影响的那一小片（节点 → 绑定线与锚定通道（尺寸 / 图标换过时，锚定通道的宽度一起按新尺寸重排，见「通道与多回线」），线路 → 这一条，通道 → 它的分组与成员），其余要素与缓存一个字节都不动；节点的 visible: false / 改回来会走一次整份重排（这一条要连绑定线、锚定通道与拾取索引一起退场 / 排回去，定向更新那条路落不下；同一个 batch() 里改一批只重排一次）；updateLine 的补丁里还能写 groupId / groupIndex（可配 channelId）顺带把这条回线挪到目标分组，updateChannel 写 groups / lineIds 会顺带改分组并补一条 channelGroups 变更（见「通道分组」）；updateChannel 还能给第三段 linePatches（一条或一批 { id | index, ...字段 }）把「通道声明 + 成员回线各自的字段 / 分组」一次下发 —— 声明先落、再逐条走 updateLine，整次调用只发一条 batch 数据变更、历史里只算一步（见「通道分组」与「逐方法示例」）；第三段里认不出的成员 id 带得起定义（from / to 两端可解析、可用的 path、或通道自己声明了两端）会当场建一条回线并挂进通道，给不出定义才跳过点名；updateLine 的拐点写在 path 上（整条折线，含首尾端点 —— 只写中间拐点用 setLineWaypoints(id, coordinates)），通道里的回线几何由通道骨架推导（path 写了也会被覆盖），改它走 setLineWaypoints / setChannelPath", examples: [{"group":"配置与数据","code":"// updatePoint(id, patch)：合并一个节点的字段；visible 翻面会连绑定线 / 锚定通道一起重排\nview.updatePoint('a', { x: 120, y: 40 })\nview.updatePoint('a', { name: '甲站（改）', status: 2 })\nview.updatePoint('a', { color: '#ff3b30', size: 18, symbol: '/marker.svg', strokeColor: '#fff', strokeWidth: 2 })  // 改这一条的颜色 / 尺寸 / 图标\nview.updatePoint('a', { symbol: { type: 'svg', path: 'M12 1 L23 12 L12 23 L1 12 Z', viewBox: [0, 0, 24, 24] } })\nview.updatePoint('a', { color: null, size: null, symbol: null })  // 摘掉逐条覆盖，回落到普通规则 / pointStyle\nview.updatePoint('a', { visible: false })              // 从图上收起；写回 true 排回来\n","from":"header"},{"group":"定向改一个要素（一次只动一条）","code":"// updatePoint(id, patch)：只写要改的字段（size / symbol / color…）\nview.updatePoint('a', { size: 12 })\nview.updatePoint('a', { symbol: { kind: 'square' } })\nview.updatePoint('a', { symbol: 'https://example.com/pin.png' })\nview.updatePoint('a', { symbol: null })                         // 回到内置圆\nview.updatePoint('a', { color: '#ff6b35' })\n","from":"header"}] },
+			{ name: "updateLine", kind: "method", params: "id 线路 id；patch: GisViewLinePatch 要合并的字段（path / from / to / color / width / opacity / lineType / decorations / labels… 都能改），还能写三个「分组指令」：groupId（或 groupIndex，可配 channelId）把这条回线挪到目标分组 —— groupId: 'newGroup' 单独拆一组、其余按现有分组 id 并组，走的是 moveChannelLine 那一套；三个字段只是指令，不会写进线路数据、不会出现在 updateLine 的载荷里，挪组成功会先发一条 channelGroups 变更（只给指令时这次调用就只发它）；拐点写在 path 上（整条折线，含首尾端点 —— 只写中间拐点用 setLineWaypoints(id, 中间拐点)），通道里的回线几何由通道骨架推导（path 写了也会被覆盖，改它走 setLineWaypoints / setChannelPath）。命中的 override: true 规则会压住同字段的逐条补丁", returns: "this", doc: "定向更新一个节点 / 线路 / 通道并重渲染：单项字段（尺寸、图标、颜色、线宽、通道宽度 / 名称等）直接写补丁；只重排受影响的那一小片（节点 → 绑定线与锚定通道（尺寸 / 图标换过时，锚定通道的宽度一起按新尺寸重排，见「通道与多回线」），线路 → 这一条，通道 → 它的分组与成员），其余要素与缓存一个字节都不动；节点的 visible: false / 改回来会走一次整份重排（这一条要连绑定线、锚定通道与拾取索引一起退场 / 排回去，定向更新那条路落不下；同一个 batch() 里改一批只重排一次）；updateLine 的补丁里还能写 groupId / groupIndex（可配 channelId）顺带把这条回线挪到目标分组，updateChannel 写 groups / lineIds 会顺带改分组并补一条 channelGroups 变更（见「通道分组」）；updateChannel 还能给第三段 linePatches（一条或一批 { id | index, ...字段 }）把「通道声明 + 成员回线各自的字段 / 分组」一次下发 —— 声明先落、再逐条走 updateLine，整次调用只发一条 batch 数据变更、历史里只算一步（见「通道分组」与「逐方法示例」）；第三段里认不出的成员 id 带得起定义（from / to 两端可解析、可用的 path、或通道自己声明了两端）会当场建一条回线并挂进通道，给不出定义才跳过点名；updateLine 的拐点写在 path 上（整条折线，含首尾端点 —— 只写中间拐点用 setLineWaypoints(id, coordinates)），通道里的回线几何由通道骨架推导（path 写了也会被覆盖），改它走 setLineWaypoints / setChannelPath", examples: [{"group":"配置与数据","code":"// updateLine(id, patch)：合并一条线路的字段；还能写 groupId / groupIndex（可配 channelId）顺带挪组\nview.updateLine('l1', { color: '#f00', width: 3 })\nview.updateLine('l1', { color: '#1e88e5', width: 5, opacity: 0.8, lineType: 'dashed' })  // 逐条改颜色 / 线宽 / 透明度 / 线型\nview.updateLine('l1', { path: [[0, 0], [200, 120], [400, 200]] })   // 拐点写 path：整条折线（含首尾端点）\nview.updateLine('l1', { name: '一线', from: 'a', to: 'b' })        // 属性与端点一起改，只发一条 updateLines\nview.updateLine('l1', { groupId: 'newGroup' })         // 单独拆一组（只给指令时只发 channelGroups）\nview.updateLine('l1', { groupIndex: 0, channelId: 'c1' })          // 挪进指定通道的第 0 组","from":"header"},{"group":"定向改一个要素（一次只动一条）","code":"// updateLine(id, patch) / setLineWaypoints(id, coordinates)\nview.updateLine('l1', { width: 3 })\nview.updateLine('l1', { color: '#f00' })\nview.setLineWaypoints('l1', [[100, 40], [200, 120]])   // 中间拐点（不含首尾两端）\nview.setLineWaypoints('l1', [120, 80])                 // 只留一个拐点\nview.setLineWaypoints('l1', [])                        // 拉直\n","from":"header"}] },
 			{ name: "updateChannel", kind: "method", params: "id 通道 id（也认下标）；patch: Partial<GisViewChannel> 要合并的通道声明字段（lineIds / groups / path / width / nodeWidth…）。补丁里的 lineIds 是这条通道成员的整表 —— 增删线路就是改它：写回声明前与 groups 调和（不在表里的成员从各组剔掉、空组去掉，新成员补进第一组，组剔完回「整条通道一组」）；写完把引擎算出的最终声明（{ id, lineIds, path }）写回数据副本，并补一条 channelGroups 变更（排在 updateChannel 那条之前）。成员表里认不出的 id、找不到的通道、没给补丁的调用各报一句 onWarning。linePatches?: GisViewChannelLinePatch | GisViewChannelLinePatch[] 第三段：要一起下发的成员回线补丁，一条或一批 { id | index, ...字段 }（定位与 updateLine 的 id 同一套解析；其余字段与 updateLine 的补丁完全同一套，含 groupId / groupIndex / channelId 三个分组指令）—— 声明先落、再逐条走 updateLine，整次调用只发一条 batch 数据变更、历史里只算一步；它只改成员回线自己的样式 / 信息与分组归属，不靠它改成员表；不属于这条通道的成员表（lineIds + 各组 lineIds）的条目跳过并报一句 onWarning（同一个条目只提醒一次），认不出来的条目也点名；第三段里认不出的成员 id 带得起定义（from / to 两端可解析、可用的 path、或通道自己声明了两端）会当场建一条回线并挂进通道（走 addLines 那条路），给不出定义才跳过。lineIds?: string | number | Array<string | number> 第四段：单独成参数的成员整表（与第三段必须成对给）—— 表里有、数据里没有的当场建，表里有的逐条改，表里没有了的旧成员直接从数据里删掉（走 removeLines 同一条路，视图跟着少；要只移出、留数据用 removeChannelLines）；空表不当清空用、只给 lineIds 不给线路数组时报一句什么都不做；与第二段的 patch.lineIds 同时写且不一样时以第四段为准（报一句）。成员表缩小时，被移出通道、又不在别的通道上的回线各报一句 onWarning（第二段的 patch.lineIds 走这条：数据留着；它仍然照常绘制，要删用 removeLines）。不传第四段时只改 id 匹配的成员、数量不动", returns: "this", doc: "定向更新一个节点 / 线路 / 通道并重渲染：单项字段（尺寸、图标、颜色、线宽、通道宽度 / 名称等）直接写补丁；只重排受影响的那一小片（节点 → 绑定线与锚定通道（尺寸 / 图标换过时，锚定通道的宽度一起按新尺寸重排，见「通道与多回线」），线路 → 这一条，通道 → 它的分组与成员），其余要素与缓存一个字节都不动；节点的 visible: false / 改回来会走一次整份重排（这一条要连绑定线、锚定通道与拾取索引一起退场 / 排回去，定向更新那条路落不下；同一个 batch() 里改一批只重排一次）；updateLine 的补丁里还能写 groupId / groupIndex（可配 channelId）顺带把这条回线挪到目标分组，updateChannel 写 groups / lineIds 会顺带改分组并补一条 channelGroups 变更（见「通道分组」）；updateChannel 还能给第三段 linePatches（一条或一批 { id | index, ...字段 }）把「通道声明 + 成员回线各自的字段 / 分组」一次下发 —— 声明先落、再逐条走 updateLine，整次调用只发一条 batch 数据变更、历史里只算一步（见「通道分组」与「逐方法示例」）；第三段里认不出的成员 id 带得起定义（from / to 两端可解析、可用的 path、或通道自己声明了两端）会当场建一条回线并挂进通道，给不出定义才跳过点名；updateLine 的拐点写在 path 上（整条折线，含首尾端点 —— 只写中间拐点用 setLineWaypoints(id, coordinates)），通道里的回线几何由通道骨架推导（path 写了也会被覆盖），改它走 setLineWaypoints / setChannelPath", examples: [{"group":"配置与数据","code":"// updateChannel(id, patch)：改通道声明；写 groups / lineIds 会顺带改分组并补一条 channelGroups\nview.updateChannel('c1', { name: '东干线', width: 24 })\nview.updateChannel('c1', { lineIds: ['l1', 'l2'] })    // 换成员：lineIds 是整表（增删都在这一份里；有 groups 时会与分组声明调和）\n","from":"header"},{"group":"配置与数据","code":"// updateChannel(id, patch, linePatches, lineIds?)：第三段一次把「通道声明 + 成员回线各自的字段 / 分组」下发\nview.updateChannel('c1', { name: '东干线', lineIds: ['l1', 'l2'] }, [\n  { id: 'l1', width: 3, color: '#ff8800' },            // 每条：id 或 index 定位，其余字段与 updateLine 同一套\n  { id: 'l2', color: '#00ccff', groupId: 'newGroup' }  // 第三段里也能带分组指令\n])\nview.updateChannel('c1', { name: '东干线' }, { id: 'l1', width: 4 })  // 只改一条：单条写法（不是数组）\nview.updateChannel('c1', { lineIds: ['l1', 'l2', 'l3'] }, [{ id: 'l3', from: 'a', to: 'b' }])\n                                                       // 新 id + 两端：当场建一条回线并挂进 c1（表单整份覆盖成员表常这么用）\n","from":"header"},{"group":"配置与数据","code":"// updateChannel(id, patch, linePatches, lineIds)：第四段 lineIds 是整表对齐 —— 与线路数组一起给，多了建、少了删\nview.updateChannel('c1', { name: '东干线' }, [\n  { id: 'l1', name: '一线', from: 'a', to: 'b' },\n  { id: 'l2', name: '二线', from: 'a', to: 'b' }\n], ['l1', 'l2'])                                       // 表里没有了的旧成员直接从数据里删掉（要只移出用 removeChannelLines）\nview.updateChannel('c1', {}, [{ id: 'l1', width: 4 }]) // 只传线路数组：只改成员回线的字段，数量不动\n","from":"header"},{"group":"配置与数据","code":"// 整份换通道声明（与 updateChannel 的分工：这条全换、点不出某一条）\nview.updateData({ channels: [{ id: 'c1', lineIds: ['l1', 'l2'] }, { id: 'c2', from: 'a', to: 'b' }] })\n","from":"header"},{"group":"定向改一个要素（一次只动一条）","code":"// updateChannel(id, patch)：宽度 / 取宽系数 / 内收 / 切点内收\nview.updateChannel('c1', { width: 24 })\nview.updateChannel('c1', { nodeWidth: 0 })                      // 关掉「按两端节点尺寸取宽」，改用 width\nview.updateChannel('c1', { nodeWidth: 1 })\nview.updateChannel('c1', { inset: 2 })\nview.updateChannel('c1', { tangentInset: 0 })                   // 0 = 切点落在节点边上；null 回默认\n","from":"header"},{"group":"定向改一个要素（一次只动一条）","code":"// updateChannel(id, { name }) / setChannelLineWidth(id, width) / setChannelColors(id, colors)\nview.updateChannel('c1', { name: '东干线' })\nview.updateChannel('c1', { name: null })                        // 摘掉名称\nview.setChannelLineWidth('c1', 3)\nview.setChannelColors('c1', ['#f00', '#0f0'])          // 不够时按顺序循环取\nview.setChannelColors('c1', '#2f6fd0')                 // 只给一个 = 整条通道一个色\n","from":"header"}] },
-			{ name: "patchPoints", kind: "method", params: "entries: GisViewUpdateItemEntry<GisViewPoint> | 数组 要改的节点（写 { id: 'a', name: 'A' } 用 id 定位、{ index: 3, x: 10 } 用下标定位，其余字段就是这一条的补丁）；patch?: Partial<GisViewPoint> 可选：对上面每一批定位统一补一份字段（patchPoints(['a','b'], { status: 1 })）", returns: "GisViewUpdateItemsOutcome<GisViewPoint>", doc: "批量打补丁（只动点到的这几条，不换整份数据）：patchPoints([{ id: 'a', name: 'A' }, { index: 3, x: 10 }]) 一次改几条（id / index 之外的字段就是这一条的补丁），或者 patchPoints(['a', 'b'], { status: 1 }) 把同一份补丁盖到一批定位上（'a' / { index: 2 } 都认）。认不出来的进 skipped、不影响其余条目；返回 { ok, reason, indexes, items, count, skipped }，只记一条历史、只发一条 updatePoints / updateLines 数据变更 —— 十万级批量改不必逐条付事件与历史的代价，见「批量更新（batch）」", examples: [{"group":"配置与数据","code":"// patchPoints(entries, patch?)：批量打补丁 —— 每条自带补丁，或一批定位 + 一份公共补丁\nview.patchPoints([{ id: 'a', name: 'A' }, { index: 1, x: 10 }])\nview.patchPoints(['a', 'b'], { status: 1 })            // → { ok, indexes, items, count, skipped }\n","from":"header"}] },
-			{ name: "patchLines", kind: "method", params: "同 patchPoints，定位的是线路", returns: "GisViewUpdateItemsOutcome<GisViewLine>", doc: "批量打补丁（只动点到的这几条，不换整份数据）：patchPoints([{ id: 'a', name: 'A' }, { index: 3, x: 10 }]) 一次改几条（id / index 之外的字段就是这一条的补丁），或者 patchPoints(['a', 'b'], { status: 1 }) 把同一份补丁盖到一批定位上（'a' / { index: 2 } 都认）。认不出来的进 skipped、不影响其余条目；返回 { ok, reason, indexes, items, count, skipped }，只记一条历史、只发一条 updatePoints / updateLines 数据变更 —— 十万级批量改不必逐条付事件与历史的代价，见「批量更新（batch）」", examples: [{"group":"配置与数据","code":"// patchLines(entries, patch?)：同 patchPoints，定位的是线路\nview.patchLines([{ id: 'l1', width: 4 }, { id: 'l2', color: '#0f0' }])\nview.patchLines(['l1', 'l2'], { color: '#f00' })\n","from":"header"}] },
-			{ name: "updateBackground", kind: "method", params: "background?: GisViewBackground 新的背景层（底色 / 图片 / GeoJSON）；不传等于清掉", returns: "this", doc: "替换背景层", examples: [{"group":"配置与数据","code":"// updateBackground(background?)：换背景层（底色 / 图片 / GeoJSON）；不传等于清掉\nview.updateBackground({ color: '#0d1b2a', image: { src: '/basemap.png' } })\nview.updateBackground()\n","from":"header"}] },
+			{ name: "patchPoints", kind: "method", params: "entries: GisViewUpdateItemEntry<GisViewPoint> | 数组 要改的节点（写 { id: 'a', name: 'A' } 用 id 定位、{ index: 3, x: 10 } 用下标定位，其余字段就是这一条的补丁）；patch?: Partial<GisViewPoint> 可选：对上面每一批定位统一补一份字段（patchPoints(['a','b'], { status: 1 })）", returns: "GisViewUpdateItemsOutcome<GisViewPoint>", doc: "批量打补丁（只动点到的这几条，不换整份数据）：patchPoints([{ id: 'a', name: 'A' }, { index: 3, x: 10 }]) 一次改几条（id / index 之外的字段就是这一条的补丁），或者 patchPoints(['a', 'b'], { status: 1 }) 把同一份补丁盖到一批定位上（'a' / { index: 2 } 都认）。认不出来的进 skipped、不影响其余条目；返回 { ok, reason, indexes, items, count, skipped }，只记一条历史、只发一条 updatePoints / updateLines 数据变更 —— 十万级批量改不必逐条付事件与历史的代价，见「批量更新（batch）」", examples: [{"group":"配置与数据","code":"// patchPoints(entries, patch?)：批量打补丁 —— 每条自带补丁，或一批定位 + 一份公共补丁\nview.patchPoints([{ id: 'a', name: 'A' }, { index: 1, x: 10 }])\nview.patchPoints(['a', 'b'], { color: '#ff3b30', size: 14, symbol: 'square' })  // 一批节点同一份样式补丁\nview.patchPoints(['a', 'b'], { status: 1 })            // → { ok, indexes, items, count, skipped }\n","from":"header"}] },
+			{ name: "patchLines", kind: "method", params: "同 patchPoints，定位的是线路", returns: "GisViewUpdateItemsOutcome<GisViewLine>", doc: "批量打补丁（只动点到的这几条，不换整份数据）：patchPoints([{ id: 'a', name: 'A' }, { index: 3, x: 10 }]) 一次改几条（id / index 之外的字段就是这一条的补丁），或者 patchPoints(['a', 'b'], { status: 1 }) 把同一份补丁盖到一批定位上（'a' / { index: 2 } 都认）。认不出来的进 skipped、不影响其余条目；返回 { ok, reason, indexes, items, count, skipped }，只记一条历史、只发一条 updatePoints / updateLines 数据变更 —— 十万级批量改不必逐条付事件与历史的代价，见「批量更新（batch）」", examples: [{"group":"配置与数据","code":"// patchLines(entries, patch?)：同 patchPoints，定位的是线路\nview.patchLines([{ id: 'l1', width: 4 }, { id: 'l2', color: '#0f0' }])\nview.patchLines(['l1', 'l2'], { color: '#f00', width: 3, lineType: 'dotted' })\n","from":"header"}] },
+			{ name: "updateBackground", kind: "method", params: "background?: GisViewBackground 新的背景层（底色 / 图片 / GeoJSON）；不传等于清掉", returns: "this", doc: "替换背景层", examples: [{"group":"配置与数据","code":"// updateBackground(background?)：换背景层（底色 / 图片 / GeoJSON）；不传等于清掉\nview.updateBackground({ color: '#0d1b2a', image: { src: '/basemap.png' } })\nview.updateBackground({\n  color: '#eef4fb',\n  geoJson: featureCollection,\n  // 图片也可用 corners 摆四角；GeoJSON 用 bounds 把整份几何缩放到目标矩形\n  geoJsonStyle: {\n    aspectScale: 1,\n    bounds: { minX: 0, minY: 0, maxX: 1000, maxY: 600 },\n    rotation: 15\n  }\n})\nview.updateBackground()\n","from":"header"}] },
 			{ name: "getResolvedBackground", kind: "method", params: "无", returns: "GisViewResolvedBackground", doc: "引擎解析后的背景层：{ color, image: { quad, texture, source, opacity }, geoJson: { regions, labels, bounds, rawBounds, fillBuckets, strokeGroups, pointGroups } }，自建缩略图 / 图例 / 取真实范围都用它", examples: [{"group":"配置与数据","code":"// getResolvedBackground() / getBackgroundLabels()：背景层解析后的读数 / GeoJSON 区域文字的清单\nconst background = view.getResolvedBackground()\nconst backgroundLabels = view.getBackgroundLabels()\n","from":"header"}] },
 			{ name: "getBackgroundLabels", kind: "method", params: "无", returns: "GisViewResolvedBackgroundLabel[] | null", doc: "背景 GeoJSON 的区域文字（世界坐标 + 字号 / 颜色 / 偏移），自建覆盖层用", examples: [{"group":"配置与数据","code":"// getResolvedBackground() / getBackgroundLabels()：背景层解析后的读数 / GeoJSON 区域文字的清单\nconst background = view.getResolvedBackground()\nconst backgroundLabels = view.getBackgroundLabels()\n","from":"header"}] },
+			{ name: "beginBackgroundEdit", kind: "method", params: "options?: GisViewBackgroundEditorOptions：aspectLocked（缺省 true，四角等比；false 出八向）、rotation（缺省 false，为 true 时多一个旋转点）、snapAngle（Shift 吸附角，缺省 15）、minSize（缺省 12）、rotationDistance（缺省 30）、fitView / fitPadding、showHint、style、onChange / onEnd。自动打开 backgroundEditing；没有可编辑背景时不做事并报 onWarning", returns: "this", doc: "进入内置背景编辑：移动、四角 / 八向缩放、可选旋转、编辑框与同帧刷新由组件接管；图片写回 image.corners，GeoJSON 写回 geoJsonStyle.bounds + rotation，其它背景字段保留。自动打开 backgroundEditing，没有可编辑背景时只报 onWarning", examples: [{"group":"配置与数据","code":"// beginBackgroundEdit(options?)：进入组件内置的背景编辑器；没有图片 / GeoJSON 背景时只报 warning\nview.beginBackgroundEdit({\n  aspectLocked: true,   // 四角等比；false 出四角 + 四边中点\n  rotation: true,       // 再显示一个旋转点\n  snapAngle: 15,        // Shift 吸附 15°；0 关闭\n  fitView: true,\n  style: { color: '#2f78b7', lineWidth: 1.5, dashed: true, handleSize: 15, handleShape: 'circle' }\n})\n","from":"header"}] },
+			{ name: "updateBackgroundEdit", kind: "method", params: "patch: GisViewBackgroundEditorPatch：配置 aspectLocked / rotation（布尔切旋转点，数字等价 angle）/ snapAngle / minSize / rotationDistance / fitView / fitPadding / showHint / style / onChange / onEnd，几何 center / width / height / angle；返回实例", returns: "this", doc: "运行中改编辑器配置或背景几何：宽高锁 / 旋转点 / 吸附角 / 样式 / center / width / height / angle 都可增量更新；返回实例", examples: [{"group":"配置与数据","code":"// updateBackgroundEdit(patch)：改配置或几何；rotation 布尔切旋转点，数字等价 angle\nview.updateBackgroundEdit({ aspectLocked: false, rotation: true, style: { handleShape: 'square' } })\nview.updateBackgroundEdit({ center: [500, 300], width: 800, height: 450 })\nview.updateBackgroundEdit({ angle: 30 })            // 顺时针 30°；也可写 { rotation: 30 }\nview.updateBackgroundEdit({ fitView: true })        // 把整块背景放回视野\n","from":"header"}] },
+			{ name: "endBackgroundEdit", kind: "method", params: "无", returns: "this", doc: "退出内置编辑、移除覆盖层并恢复进入前的 backgroundEditing；已编辑的背景保留", examples: [{"group":"配置与数据","code":"// endBackgroundEdit()：移除编辑层，保留编辑后的背景，并恢复进入前的 backgroundEditing\nview.endBackgroundEdit()\n","from":"header"}] },
+			{ name: "getBackgroundEdit", kind: "method", params: "无", returns: "GisViewBackgroundEditorState | null", doc: "当前编辑读数（类型 / 中心 / 宽高 / 角度 / 手柄数 / 配置 / 样式）；未开启时 null", examples: [{"group":"配置与数据","code":"// getBackgroundEdit()：当前编辑器读数；没开启返回 null\nconst editorState = view.getBackgroundEdit()\nconsole.log(editorState?.backgroundType, editorState?.center, editorState?.width, editorState?.height, editorState?.rotation)\n","from":"header"}] },
 			{ name: "batch", kind: "method", params: "fn: () => T 这一批里要做的增删改 / 分组操作（内部调 patchPoints / patchLines / updateChannel、removePoints / removeLines / removeChannel、splitChannelGroups / removeChannelGroup 等都会收成一条）；options.label?: string 给这一步历史起名", returns: "fn 的返回值", doc: "批量增删改：回调里的连续改动（patchPoints / patchLines / updateChannel、removePoints / removeLines / removeChannel、分组拆分 / 删除 / 新增等）收成一条 onDataChange（type: 'batch'，changes 按调用顺序列出每一步）与一步历史，options.label 给这一步起名；收尾时筛选只重算一次、标签重排 / 提示框 / 鹰眼图各补一次（onFilter 也只发一条），可以嵌套（只有最外层收尾），见「批量更新」", examples: [{"group":"配置与数据","code":"// batch(fn, options?)：一批改动收成一条数据变更、历史里一步\nview.batch(() => {\n  view.updatePoint('a', { x: 10 })\n  view.updateLine('l1', { width: 2 })\n}, { label: '挪站并加粗' })\n","from":"header"}] },
 			{ name: "resize", kind: "method", params: "无（改过祖先 transform: scale / 容器尺寸后手动同步一次；CSS zoom 会自动感知）", returns: "this", doc: "手动同步尺寸 / 重新应用配置并重绘（refresh({ reflow: false }) 只重画一帧，不重解析数据与配置）；容器尺寸或祖先的 transform: scale 变过之后要调一次 resize() 同步（CSS zoom 会自己感知）", examples: [{"group":"配置与数据","code":"// resize()：容器尺寸变过（祖先 transform: scale、display 切换）之后手动同步一次\nwindow.addEventListener('resize', () => view.resize())\n","from":"header"}] },
 			{ name: "refresh", kind: "method", params: "options?: { reflow?: boolean } 传 false 只重画一帧（跳过整份重解析：数据没变、只想重画时用）；不传或 true 走整份重建", returns: "this", doc: "手动同步尺寸 / 重新应用配置并重绘（refresh({ reflow: false }) 只重画一帧，不重解析数据与配置）；容器尺寸或祖先的 transform: scale 变过之后要调一次 resize() 同步（CSS zoom 会自己感知）", examples: [{"group":"配置与数据","code":"// refresh(options?)：整份重建；refresh({ reflow: false }) 只重画一帧\nview.refresh()\nview.refresh({ reflow: false })\n","from":"header"}] },
@@ -71,6 +75,8 @@ export const API_SECTIONS = [
 			{ name: "getViewRect", kind: "method", params: "无", returns: "GisViewBounds", doc: "当前可视范围的世界坐标矩形；自建缩略图 / 坐标读数用它换算视口框，内置鹰眼图见「鹰眼图」", examples: [{"group":"相机与视图","code":"// getBounds() / getViewRect() / getViewport()：数据范围 / 视口世界矩形 / 画布尺寸读数\nconst dataBounds = view.getBounds()\nconst viewRect = view.getViewRect()\nconst { cssWidth, cssHeight, pixelRatio } = view.getViewport()\n","from":"header"}] },
 			{ name: "isLayoutReady", kind: "method", params: "无", returns: "boolean", doc: "大数据发散渲染（progressiveInit）是否已经铺完；没铺完时标签与拾取只看得到已经画出去的那部分", examples: [{"group":"相机与视图","code":"// isLayoutReady()：容器量到尺寸、首批布局完成没有\nconst layoutReady = view.isLayoutReady()\n","from":"header"}] },
 			{ name: "getMinimapElement", kind: "method", params: "无", returns: "HTMLElement | null 鹰眼图根节点（没配 minimap 时为 null）；外部整图拖动 / 自定义手势用它，配合 minimap.container 可挂到外部宿主", doc: "鹰眼图根节点（没配 minimap 时为 null）：接整图拖动或自定义手势；配合 minimap.container 挂到外部宿主时拿到的仍是同一根节点", examples: [{"group":"相机与视图","code":"// getMinimapElement()：拿鹰眼图根节点做整图拖动 / 自定义手势（没配 minimap 时为 null）\nconst minimapElement = view.getMinimapElement()\n","from":"header"}] },
+			{ name: "getVisualMapElement", kind: "method", params: "无", returns: "HTMLElement | null 内置图例根节点（没配 visualMap 或 enabled: false 时为 null）；挂外部事件或自定义样式从这里拿。interactive: true 时根节点已可直接点选 / 拖动，内置交互优先用 onChange", doc: "内置图例的根节点 / 当前读数：根节点在没配 visualMap 或 enabled: false 时为 null；读数含 type / target / field / domain / colors、交互态 interactive / selectedMode / calculable / selected / range / rangeRatios 与 ticks / pieces，没配时为 null。分段点选 / 区间拖动走 visualMap.onChange，render(context) 可完全自定义；只改图例不会触发引擎场景或标签重排，见「图例（visualMap）」", examples: [{"group":"相机与视图","code":"// getVisualMapElement() / getVisualMap()：内置图例的根节点与当前读数（没配 visualMap 时为 null）\nconst visualMapElement = view.getVisualMapElement()\nconst visualMap = view.getVisualMap()","from":"header"}] },
+			{ name: "getVisualMap", kind: "method", params: "无", returns: "GisViewVisualMapReadout | null 当前图例读数：type / target / field / domain / colors / orient / title / unit、交互态 interactive / selectedMode / calculable / selected / range / rangeRatios 与 ticks / pieces；没配时为 null，调用前会先落下一帧挂起的重画", doc: "内置图例的根节点 / 当前读数：根节点在没配 visualMap 或 enabled: false 时为 null；读数含 type / target / field / domain / colors、交互态 interactive / selectedMode / calculable / selected / range / rangeRatios 与 ticks / pieces，没配时为 null。分段点选 / 区间拖动走 visualMap.onChange，render(context) 可完全自定义；只改图例不会触发引擎场景或标签重排，见「图例（visualMap）」", examples: [{"group":"相机与视图","code":"// getVisualMapElement() / getVisualMap()：内置图例的根节点与当前读数（没配 visualMap 时为 null）\nconst visualMapElement = view.getVisualMapElement()\nconst visualMap = view.getVisualMap()","from":"header"}] },
 			{ name: "getMinimapZoom", kind: "method", params: "无", returns: "number", doc: "读 / 写鹰眼图自身的倍数：set 夹在 minimap.minZoom ~ maxZoom 之间，zoomMinimapBy 以画布 CSS 像素 origin 为锚点缩放（缺省小图中心），没配 minimap 时是空操作", examples: [{"group":"相机与视图","code":"// getMinimapZoom() / setMinimapZoom(zoom) / zoomMinimapBy(factor, origin?)：鹰眼图缩放\nview.setMinimapZoom(4)\nview.zoomMinimapBy(1.25)\nconst minimapZoom = view.getMinimapZoom()\n","from":"header"}] },
 			{ name: "setMinimapZoom", kind: "method", params: "zoom: number 鹰眼图的目标倍数（被 minimap.minZoom / maxZoom 夹住）", returns: "this", doc: "读 / 写鹰眼图自身的倍数：set 夹在 minimap.minZoom ~ maxZoom 之间，zoomMinimapBy 以画布 CSS 像素 origin 为锚点缩放（缺省小图中心），没配 minimap 时是空操作", examples: [{"group":"相机与视图","code":"// getMinimapZoom() / setMinimapZoom(zoom) / zoomMinimapBy(factor, origin?)：鹰眼图缩放\nview.setMinimapZoom(4)\nview.zoomMinimapBy(1.25)\nconst minimapZoom = view.getMinimapZoom()\n","from":"header"}] },
 			{ name: "zoomMinimapBy", kind: "method", params: "factor: number 倍数；origin?: [x, y] 以小图里的哪个点为中心（缺省小图中心）", returns: "this", doc: "读 / 写鹰眼图自身的倍数：set 夹在 minimap.minZoom ~ maxZoom 之间，zoomMinimapBy 以画布 CSS 像素 origin 为锚点缩放（缺省小图中心），没配 minimap 时是空操作", examples: [{"group":"相机与视图","code":"// getMinimapZoom() / setMinimapZoom(zoom) / zoomMinimapBy(factor, origin?)：鹰眼图缩放\nview.setMinimapZoom(4)\nview.zoomMinimapBy(1.25)\nconst minimapZoom = view.getMinimapZoom()\n","from":"header"}] },
@@ -113,17 +119,18 @@ export const API_SECTIONS = [
 			{ name: "getContextAt", kind: "method", params: "x / y 画布 CSS 像素；options?: GisViewContextAtOptions：selection: false 不整理选中集、lngLat: false 不换算经纬度（dragover / 自绘十字线这类每帧来的场合用它省分配）", returns: "GisViewContextAtResult；给了选项时是 GisViewContextAtLightResult（没要的那几项不再生成）", doc: "一个屏幕点（画布 CSS 像素）上的全部读数：screen / world / lngLat / hit / kind（'point' / 'line' / 'channel'）/ selection / selectedItems。自定义右键菜单一次取全，空白处 hit 与 kind 为 null、坐标照样给", examples: [{"group":"坐标、拾取与读数","code":"//（pick / getContextAt / nearestPointsAt 这些吃画布像素的方法先用这一对转；自动处理 canvas rect 与宿主缩放）\nconst [sx, sy] = view.clientToScreen(event.clientX, event.clientY)\nconst [fixedX, fixedY] = view.screenToClient(320, 200)   // 摆 position: fixed 的浮层 / 菜单\n","from":"header"},{"group":"坐标、拾取与读数","code":"// getContextAt(x, y, options?)：右键菜单那种「这儿是什么」的全量读数\nconst context = view.getContextAt(320, 200)\nconst lightContext = view.getContextAt(320, 200, { selection: false, lngLat: false })  // 每帧来的场合省分配\n","from":"header"}] },
 			{ name: "nearestPointsAt", kind: "method", params: "x / y 画布 CSS 像素；options?: GisViewNearestOptions：limit（最多几个，缺省 1）、maxDistance（屏幕像素上限，缺省不限）、withScreen: true 补屏幕坐标", returns: "GisViewNearestPoint[]，按距离从近到远：{ index, item, x, y, radius, distance, distancePx, screen? }；内部走点网格，十万级数据也只碰光标附近的单元格", doc: "/** * 落点附近最近的若干个可见节点。", examples: [{"group":"坐标、拾取与读数","code":"//（pick / getContextAt / nearestPointsAt 这些吃画布像素的方法先用这一对转；自动处理 canvas rect 与宿主缩放）\nconst [sx, sy] = view.clientToScreen(event.clientX, event.clientY)\nconst [fixedX, fixedY] = view.screenToClient(320, 200)   // 摆 position: fixed 的浮层 / 菜单\n","from":"header"},{"group":"坐标、拾取与读数","code":"// nearestPointsAt(x, y, options?) / nearestLineAt(x, y, options?)：离光标最近的节点 / 线路\nconst nearPoints = view.nearestPointsAt(320, 200, { limit: 3, withScreen: true })\nconst nearLine = view.nearestLineAt(320, 200, { maxDistance: 60 })   // 落点比例在 nearLine.position\n","from":"header"}] },
 			{ name: "nearestLineAt", kind: "method", params: "x / y 画布 CSS 像素；options?: GisViewNearestLineOptions：maxDistance（屏幕像素，缺省 40，超出算没命中）、editableOnly: true 只看允许加拐点的线、withScreen: true 补屏幕坐标", returns: "GisViewNearestLine | null：{ index, item, path, distance, distancePx, position, channelId?, groupId?, channelIndex?, screen? }，position 是落点投到线上的沿线比例（0~1），加拐点 / 挂装饰直接当 position 用；附近没线返回 null", doc: "/** * 落点附近最近的一条可见线路。", examples: [{"group":"坐标、拾取与读数","code":"// nearestPointsAt(x, y, options?) / nearestLineAt(x, y, options?)：离光标最近的节点 / 线路\nconst nearPoints = view.nearestPointsAt(320, 200, { limit: 3, withScreen: true })\nconst nearLine = view.nearestLineAt(320, 200, { maxDistance: 60 })   // 落点比例在 nearLine.position\n","from":"header"}] },
-			{ name: "setDropPreview", kind: "method", params: "preview: GisViewDropPreviewInput | null：kind（'point' / 'line' / 'channel' / 'waypoint' / 'decoration' / 'label'，缺省按 item 推断）、screen（画布 CSS 像素）或 world（世界坐标）至少给一个、item 是准备落地的那一份字段（与 addPoint / addLine 同一份）、from（line / channel 的起点）；传 null 清掉预览", returns: "GisViewDropPreview | null 解析后的读数 { kind, screen, world, size, styleSize, radius, color, strokeColor, strokeWidth, opacity, symbol, width, dashed }：走的是与真实要素完全相同的样式链（规则 -> 全局样式 -> 这一份字段），styleSize 与落地后 getPointStyle().size 是同一个数（size 是这一刻画出来的宽度，不悬停 / 不选中时两者相同）", doc: "/** * 拖拽落点预览。", examples: [{"group":"坐标、拾取与读数","code":"// setDropPreview(preview) / getDropPreview()：拖拽落点预览（setDropPreview(null) 清掉）\nview.setDropPreview({ kind: 'point', screen: [320, 200], item: { name: '新站' } })\nconst preview = view.getDropPreview()\nview.setDropPreview(null)\n","from":"header"}] },
+			{ name: "setDropPreview", kind: "method", params: "preview: GisViewDropPreviewInput | null：kind（'point' / 'line' / 'channel' / 'waypoint' / 'decoration' / 'label'，缺省按 item 推断）、screen（画布 CSS 像素）或 world（世界坐标）至少给一个、item 是准备落地的那一份字段（与 addPoint / addLine 同一份）、from（line / channel 的起点）；传 null 清掉预览", returns: "GisViewDropPreview | null 解析后的读数 { kind, screen, world, size, styleSize, radius, color, strokeColor, strokeWidth, opacity, symbol, width, dashed }：走的是与真实要素完全相同的样式链（override 规则 > 这一份字段 > 普通规则 > 全局样式），styleSize 与落地后 getPointStyle().size 是同一个数（size 是这一刻画出来的宽度，不悬停 / 不选中时两者相同）", doc: "/** * 拖拽落点预览。", examples: [{"group":"坐标、拾取与读数","code":"// setDropPreview(preview) / getDropPreview()：拖拽落点预览（setDropPreview(null) 清掉）\nview.setDropPreview({ kind: 'point', screen: [320, 200], item: { name: '新站' } })\nconst preview = view.getDropPreview()\nview.setDropPreview(null)\n","from":"header"}] },
 			{ name: "getDropPreview", kind: "method", params: "无", returns: "GisViewDropPreview | null：当前拖拽落点预览的读数，没有预览时 null", doc: "/** * 拖拽落点预览。", examples: [{"group":"坐标、拾取与读数","code":"// setDropPreview(preview) / getDropPreview()：拖拽落点预览（setDropPreview(null) 清掉）\nview.setDropPreview({ kind: 'point', screen: [320, 200], item: { name: '新站' } })\nconst preview = view.getDropPreview()\nview.setDropPreview(null)\n","from":"header"}] },
 			{ name: "getPoint", kind: "method", params: "ref: GisViewFeatureRef 节点定位：id、下标、{ id } / { index }", returns: "GisViewPointInfo | null", doc: "按 id / 下标 / { id } / { index } 取一个节点：拾取载荷（item / x / y / layer / layerRank）之外再给一份屏幕半径 radius；找不到返回 null。自建读数面板、右键菜单用它，省掉「自己遍历 getData() + 算投影」那一段", examples: [{"group":"坐标、拾取与读数","code":"// getPoint(ref) / getLine(ref) / getChannel(ref)：一个要素的几何读数\nconst pointInfo = view.getPoint('a')\nconst lineInfo = view.getLine('l1')\nconst channelInfo = view.getChannel('c1')\n","from":"header"}] },
-			{ name: "getPointStyle", kind: "method", params: "index: number 节点下标", returns: "GisViewPointStyleSnapshot | null：节点解析后的样式快照 { index, size, symbol, zIndex }，size / symbol 取样式链（节点自身 > 规则 > pointStyle）定下来的那一份，含 sizeScale、不含悬停 / 选中样式与热力倍率；落点预览的读数与它同源", doc: "节点 / 线路解析之后的样式快照：节点的 size / symbol 取样式链（自身 > 规则 > 全局），线路的 width / color / opacity / zIndex 同源；不含悬停 / 选中样式、整体倍率与热力倍率，下标不存在时返回 null。合并节点与鹰眼图沿用主图尺寸时走这一份", examples: [{"group":"坐标、拾取与读数","code":"// getPointStyle(index)：节点解析后的样式快照（样式链定下来的那一份）\nconst pointStyle = view.getPointStyle(0)\n","from":"header"}] },
-			{ name: "getLineStyle", kind: "method", params: "index: number 线路在 lines 里的下标", returns: "GisViewLineStyleSnapshot | null：{ index, width, color, opacity, zIndex }；width 取样式链（线路自身 > 规则 > lineStyle）定下来的原始线宽，不含 lineWidthScale / 缩放联动 / 热力倍率，color 是解析后的 RGBA（0 ~ 1）。局部更新与线路窄样式快路径之后读到的都是最新值；下标不存在时 null", doc: "节点 / 线路解析之后的样式快照：节点的 size / symbol 取样式链（自身 > 规则 > 全局），线路的 width / color / opacity / zIndex 同源；不含悬停 / 选中样式、整体倍率与热力倍率，下标不存在时返回 null。合并节点与鹰眼图沿用主图尺寸时走这一份", examples: [{"group":"坐标、拾取与读数","code":"// getLineStyle(index)：线路解析后的样式快照（原始线宽 / RGBA / 透明度 / 层级）\nconst lineStyle = view.getLineStyle(0) // { index, width, color, opacity, zIndex } 或 null\n","from":"header"}] },
+			{ name: "getPointStyle", kind: "method", params: "index: number 节点下标", returns: "GisViewPointStyleSnapshot | null：节点解析后的样式快照 { index, size, symbol, zIndex }，size / symbol 取样式链（override 规则 > 节点自身 > 普通规则 > pointStyle）定下来的那一份，含 sizeScale、不含悬停 / 选中样式与热力倍率；落点预览的读数与它同源", doc: "节点 / 线路解析之后的样式快照：节点的 size / symbol 取样式链（override 规则 > 自身 > 普通规则 > 全局），线路的 width / color / opacity / zIndex 同源；不含悬停 / 选中样式、整体倍率与热力倍率，下标不存在时返回 null。合并节点与鹰眼图沿用主图尺寸时走这一份", examples: [{"group":"坐标、拾取与读数","code":"// getPointStyle(index)：节点解析后的样式快照（样式链定下来的那一份）\nconst pointStyle = view.getPointStyle(0)\n","from":"header"}] },
+			{ name: "getLineStyle", kind: "method", params: "index: number 线路在 lines 里的下标", returns: "GisViewLineStyleSnapshot | null：{ index, width, color, opacity, zIndex }；width 取样式链（override 规则 > 线路自身 > 普通规则 > lineStyle）定下来的原始线宽，不含 lineWidthScale / 缩放联动 / 热力倍率，color 是解析后的 RGBA（0 ~ 1）。局部更新与线路窄样式快路径之后读到的都是最新值；下标不存在时 null", doc: "节点 / 线路解析之后的样式快照：节点的 size / symbol 取样式链（override 规则 > 自身 > 普通规则 > 全局），线路的 width / color / opacity / zIndex 同源；不含悬停 / 选中样式、整体倍率与热力倍率，下标不存在时返回 null。合并节点与鹰眼图沿用主图尺寸时走这一份", examples: [{"group":"坐标、拾取与读数","code":"// getLineStyle(index)：线路解析后的样式快照（原始线宽 / RGBA / 透明度 / 层级）\nconst lineStyle = view.getLineStyle(0) // { index, width, color, opacity, zIndex } 或 null\n","from":"header"}] },
 			{ name: "getLine", kind: "method", params: "ref 线路定位（同上）", returns: "GisViewLineInfo | null", doc: "取一条线路：拾取载荷 + path / bounds / color / width（与 listLines() 的一项同一份口径），通道回线还带 channelId / groupId / channelIndex；找不到返回 null", examples: [{"group":"坐标、拾取与读数","code":"// getPoint(ref) / getLine(ref) / getChannel(ref)：一个要素的几何读数\nconst pointInfo = view.getPoint('a')\nconst lineInfo = view.getLine('l1')\nconst channelInfo = view.getChannel('c1')\n","from":"header"}] },
 			{ name: "getChannel", kind: "method", params: "ref 通道定位：通道 id 或下标", returns: "GisViewChannelSnapshot | null", doc: "取一条通道：数据那一份（index / item / id）+ 成员表（lineIndexes / skeleton / offsets / paths）+ 分组上下文 context（几组 / 当前哪组 / 每组拐点数）、from / to / anchored / spacing；找不到返回 null", examples: [{"group":"坐标、拾取与读数","code":"// getPoint(ref) / getLine(ref) / getChannel(ref)：一个要素的几何读数\nconst pointInfo = view.getPoint('a')\nconst lineInfo = view.getLine('l1')\nconst channelInfo = view.getChannel('c1')\n","from":"header"}] },
 			{ name: "listPoints", kind: "method", params: "options?: GisViewListOptions：indexes（只看这几个下标）、inView: boolean（只要当前视口里的）、withScreen: boolean（连屏幕坐标一起给）、visibleOnly: boolean（跳过隐藏的）、limit: number（最多几条）", returns: "GisViewListedPoint[]", doc: "按条件列节点快照 { index, item, x, y, radius, layerRank, screen? }：选项见 GisViewListOptions（indexes / inView / limit / withScreen / visibleOnly），可见判定与 isPointVisible 是同一份", examples: [{"group":"坐标、拾取与读数","code":"// listPoints(options?) / listLines(options?)：按条件列一批\nconst listedPoints = view.listPoints({ limit: 5, withScreen: true })\nconst listedLines = view.listLines({ inView: true, limit: 200 })\n","from":"header"}] },
 			{ name: "getClusters", kind: "method", params: "无", returns: "GisViewCluster[]。当前展示组（含 count: 1 的单成员），screen 按当前相机现算；聚合关掉时是空表", doc: "当前点聚合的展示组 GisViewCluster[]：按数据顺序返回，含 count: 1 的单成员与 count > 1 的聚合圆；每项带 id / pointIndexes / pointIds / 世界坐标 coordinate / 当前屏幕坐标 screen / 半径 radius / 包围盒 bounds。原始 points 与 getData() 不变，聚合关掉时返回空表", examples: [{"group":"坐标、拾取与读数","code":"// getClusters() / getPointCluster()：读当前点聚合展示组与配置\nview.updateOptions({ pointCluster: { radius: 64, minPoints: 3, maxZoom: 2.5 } })\nconst clusterGroups = view.getClusters()\nconst clusteredOnly = clusterGroups.filter(group => group.count > 1)\nconst clusterState = view.getPointCluster()   // { enabled, radius, minPoints, maxZoom, active }\nview.updateOptions({ pointCluster: false })   // 关掉聚合，原始点全部恢复\n","from":"header"}] },
 			{ name: "getPointCluster", kind: "method", params: "无", returns: "GisViewPointClusterReadout | null。归一化配置 { enabled, radius, minPoints, maxZoom, active }，超过 maxZoom 后 active 为 false", doc: "当前点聚合配置的归一化读数 GisViewPointClusterReadout | null：{ enabled, radius, minPoints, maxZoom, active }，active 说明当前缩放档是否仍在聚合（超过 maxZoom 后为 false）；引擎未就绪时为 null", examples: [{"group":"坐标、拾取与读数","code":"// getClusters() / getPointCluster()：读当前点聚合展示组与配置\nview.updateOptions({ pointCluster: { radius: 64, minPoints: 3, maxZoom: 2.5 } })\nconst clusterGroups = view.getClusters()\nconst clusteredOnly = clusterGroups.filter(group => group.count > 1)\nconst clusterState = view.getPointCluster()   // { enabled, radius, minPoints, maxZoom, active }\nview.updateOptions({ pointCluster: false })   // 关掉聚合，原始点全部恢复\n","from":"header"}] },
 			{ name: "getPointSpacing", kind: "method", params: "无", returns: "GisViewPointSpacing：count / minDistance / maxDistance / nearest / farthest。距离都是当前相机比例下的 CSS 像素，与 fitSpacing 同一套口径；最近 / 最远各带两端 { id, index, item } 与同口径的 distance，筛选 / 隐藏后的节点不参与", doc: "当前可见节点的最近正距离与最远距离 GisViewPointSpacing：minDistance / maxDistance 与 nearest / farthest.distance 都是当前相机比例下的 CSS 像素，和 fitSpacing 同一套口径；nearest / farthest 各带两端节点 { id, index, item }。筛选 / 隐藏后的节点不参与；少于两个可见节点时为 null，全部重合时最近为 null、最远为 0", examples: [{"group":"坐标、拾取与读数","code":"// getPointSpacing()：最近 / 最远可见节点的中心距（CSS 像素，和 fitSpacing 同口径）\nconst spacing = view.getPointSpacing()\nif (spacing.nearest) {\n  console.log('最近', spacing.nearest.from.id, spacing.nearest.to.id, spacing.nearest.distance, 'px')\n  console.log('世界距离', spacing.nearest.distance / view.getScale())\n}\nif (spacing.farthest) {\n  console.log('最远', spacing.farthest.from.id, spacing.farthest.to.id, spacing.farthest.distance, 'px')\n}","from":"header"}] },
+			{ name: "getPointsSpacing", kind: "method", params: "refs: GisViewFeatureRef | GisViewFeatureRef[]：一个或一组节点引用，支持 id / 下标 / { id } / { index }；重复引用去重，非法引用忽略", returns: "GisViewPointSpacing：只统计显式传入的节点（筛选 / 隐藏不影响），count / minDistance / maxDistance / nearest / farthest 与 getPointSpacing() 同形，距离为当前相机比例下的 CSS 像素；少于两个有效节点时两列为 null，全部重合时最近为 null、最远为 0", doc: "指定一组节点的整体最近正距离与最远距离 GisViewPointSpacing，口径与 getPointSpacing() 相同：refs 可传单个或数组的 id / 下标 / { id } / { index }，重复引用去重、非法引用忽略；只统计显式传入的节点，筛选 / 隐藏不影响。少于两个有效节点时两列为 null，全部重合时最近为 null、最远为 0", examples: [{"group":"坐标、拾取与读数","code":"// getPointsSpacing(refs)：指定一组节点的整体中心距（CSS 像素；筛选 / 隐藏不影响）\nconst groupSpacing = view.getPointsSpacing(['a', { index: 2 }, { id: 'b' }])\nif (groupSpacing.nearest) {\n  console.log('组内最近', groupSpacing.nearest.from.id, groupSpacing.nearest.to.id, groupSpacing.minDistance, 'px')\n}\nconsole.log('组内最远', groupSpacing.maxDistance, 'px', '世界距离', groupSpacing.maxDistance / view.getScale())\n","from":"header"}] },
 			{ name: "listLines", kind: "method", params: "同 listPoints（inView / withScreen / limit…）", returns: "GisViewListedLine[]", doc: "按条件列线路快照 { index, item, path, bounds, color, width, channelId?, groupId?, channelIndex?, screen? }：选项与 listPoints 同一套；通道回线给的是骨架推导出来的那条折线（跟图上画的一致）", examples: [{"group":"坐标、拾取与读数","code":"// listPoints(options?) / listLines(options?)：按条件列一批\nconst listedPoints = view.listPoints({ limit: 5, withScreen: true })\nconst listedLines = view.listLines({ inView: true, limit: 200 })\n","from":"header"}] },
 			{ name: "forEachPointInView", kind: "method", params: "rect: GisViewBounds 世界坐标矩形（一般直接给 getViewRect() 的返回值）；visit: (index, item, x, y, radius) => void | false 逐个回调，返回 false 提前结束", returns: "void。只遍历矩形里的可见节点（数据顺序、不建中间数组）：与 listPoints({ inView: true }) 同一份可见判定，但不生成清单 —— 放大看一小片时不会去碰整份数据", doc: "/** * 只遍历落在给定世界矩形（{ minX, minY, maxX, maxY }）里的可见节点，逐个回调 * (index, item, x, y, radius)。", examples: [{"group":"坐标、拾取与读数","code":"// forEachPointInView(rect, visit)：只遍历视口里的节点，不建中间数组；回调返回 false 提前结束\nview.forEachPointInView(view.getViewRect(), (index, item, x, y, radius) => {\n  readout.push(`${item.name}：半径 ${radius.toFixed(1)}px`)\n})\n","from":"header"}] },
 			{ name: "getVisibleData", kind: "method", params: "无", returns: "GisViewData", doc: "过滤之后的数据副本（points / lines）", examples: [{"group":"坐标、拾取与读数","code":"// getVisibleData() / isPointVisible(index)：筛选之后的整份数据 / 某个节点在不在图上\nconst visibleData = view.getVisibleData()\nconst shown = view.isPointVisible(0)\n","from":"header"}] },
@@ -133,9 +140,9 @@ export const API_SECTIONS = [
 			{ name: "clearChangedChannels", kind: "method", params: "refs?: GisViewFeatureRef | GisViewFeatureRef[] 记成新基准的通道（id / 下标 / { id } / { index }，写法与 removePoints 一致）；不传 / null 全部对账，空数组无操作", returns: "this", doc: "通道变化对账：把当前声明记成新基准（发完接口告诉组件「这些已经同步过了」）：不传 / null 全部对账，传一个或一批（写法与 removePoints 一致）只清这些，认不出来的跳过并记一条提醒；返回实例本身", examples: [{"group":"拐点与通道","code":"// getChangedChannels(options?) / clearChangedChannels(refs?)：通道变化对账\nview.updateChannel('c1', { name: '东干线' })\nview.addChannelGroupWaypoint('c1', 'c1', [200, 120])       // 拐点变化入账（单组通道的组 id 就是通道 id）\nconst changedChannels = view.getChangedChannels()          // [{ index, id, item, groups, reasons, … }]\nconsole.log(changedChannels[0]?.reasons)                    // ['waypoints'] / ['members'] / ['visibility']…\nconst waypointOnly = view.getChangedChannels({ reasons: ['waypoints'], ignoreGroups: true })\nview.clearChangedChannels('c1')                            // 发完接口对账这一条；不传 = 全部对账\n","from":"header"}] },
 			{ name: "getChangedLines", kind: "method", params: "options?: GisViewChangedLineOptions：reasons?: GisViewChangedLineReason[] 只返回 path / endpoints / visibility / fields 中的指定原因（[] = 空表）", returns: "GisViewChangedLine[]：相对上次线路对账变了哪些线路，每项给 { index, id, item, path, start, end, from, to, visible, pathChanged, endpointsChanged, visibilityChanged, fieldsChanged, fields, reasons }；新加只补账、删除清账，读本身不改基准", doc: "线路变化对账：相对上次对账（建视图 / 整份换线路 / 上一次 clearChangedLines）path / start / end、from / to、可见性或其余声明字段变过的线路。每项带 { index, id, item, path, start, end, from, to, visible, pathChanged, endpointsChanged, visibilityChanged, fieldsChanged, fields, reasons }；options.reasons 可写 path / endpoints / visibility / fields。新加线路只补账不报，删除线路（含 removeChannel 连带删除）同步清账；通道骨架变化不算线路变化，见「线路变化对账」", examples: [{"group":"拐点与通道","code":"// getChangedLines(options?) / clearChangedLines(refs?)：只有节点和线路时也能独立对账\nview.updateLine('l1', { name: '东联络线' })\nconst changedLines = view.getChangedLines()                 // [{ index, id, item, path, from, to, reasons, … }]\nconsole.log(changedLines[0]?.reasons)                       // ['fields'] / ['path'] / ['endpoints'] / ['visibility']\nconst pathOnly = view.getChangedLines({ reasons: ['path'] })\nview.clearChangedLines('l1')                               // 发完接口对账这一条；不传 = 全部对账\n","from":"header"}] },
 			{ name: "clearChangedLines", kind: "method", params: "refs?: GisViewFeatureRef | GisViewFeatureRef[] 记成新基准的线路（写法与 removePoints 一致）；不传 / null 全部对账，空数组无操作", returns: "this", doc: "线路变化对账：不传 / null 全部对账，传一个或一批（写法与 removePoints 一致）只清这些，空数组无操作；认不出来的跳过并记一条提醒，返回实例本身", examples: [{"group":"拐点与通道","code":"// getChangedLines(options?) / clearChangedLines(refs?)：只有节点和线路时也能独立对账\nview.updateLine('l1', { name: '东联络线' })\nconst changedLines = view.getChangedLines()                 // [{ index, id, item, path, from, to, reasons, … }]\nconsole.log(changedLines[0]?.reasons)                       // ['fields'] / ['path'] / ['endpoints'] / ['visibility']\nconst pathOnly = view.getChangedLines({ reasons: ['path'] })\nview.clearChangedLines('l1')                               // 发完接口对账这一条；不传 = 全部对账\n","from":"header"}] },
-			{ name: "setFeatureVisible", kind: "method", params: "kind: GisViewVisibilityKind（'point' / 'line' / 'channel'）；refs: GisViewVisibilityRefs 单个 / 一批 id 或下标，也认 'selection'（通道按选中回线的归属取整条）；visible: boolean", returns: "GisViewSetVisibilityOutcome：{ ok, reason, kind, visible, indexes, ids, items, skipped }；只改数据的 visible，整次调用一条历史、一条 batch 数据变更", doc: "统一隐藏 / 显示节点、线路或通道：只改数据里的 visible，不删要素，分组 / 拐点 / 编辑状态都保留。kind 收 point / line / channel，refs 收单个或一批 id / 下标 / { id } / { index }，也认 'selection'（通道按选中回线的归属取整条）；hideFeatures / showFeatures 是 false / true 的快捷写法。整次调用收成一条历史与一条 batch 数据变更，返回 { ok, reason, kind, visible, indexes, ids, items, skipped }；认不出的引用逐条进 skipped，不影响其余条目", examples: [{"group":"配置与数据","code":"// setFeatureVisible(kind, refs, visible) / hideFeatures(kind, refs) / showFeatures(kind, refs)：只改 visible，不删数据\nconst hiddenChannel = view.hideFeatures('channel', 'c1')  // 'point' / 'line' / 'channel'，refs 单个 / 数组 / 'selection'\nview.showFeatures('channel', 'c1')                        // 成员回线、分组、拐点原样回来\nview.setFeatureVisible('point', ['a', 'b'], false)        // 一批节点一次收起（一条历史、一条 batch）\nconsole.log(hiddenChannel.ok, hiddenChannel.indexes, hiddenChannel.skipped)\n","from":"header"}] },
-			{ name: "hideFeatures", kind: "method", params: "同上，等价于 setFeatureVisible(kind, refs, false)", returns: "同上", doc: "统一隐藏 / 显示节点、线路或通道：只改数据里的 visible，不删要素，分组 / 拐点 / 编辑状态都保留。kind 收 point / line / channel，refs 收单个或一批 id / 下标 / { id } / { index }，也认 'selection'（通道按选中回线的归属取整条）；hideFeatures / showFeatures 是 false / true 的快捷写法。整次调用收成一条历史与一条 batch 数据变更，返回 { ok, reason, kind, visible, indexes, ids, items, skipped }；认不出的引用逐条进 skipped，不影响其余条目", examples: [{"group":"配置与数据","code":"// setFeatureVisible(kind, refs, visible) / hideFeatures(kind, refs) / showFeatures(kind, refs)：只改 visible，不删数据\nconst hiddenChannel = view.hideFeatures('channel', 'c1')  // 'point' / 'line' / 'channel'，refs 单个 / 数组 / 'selection'\nview.showFeatures('channel', 'c1')                        // 成员回线、分组、拐点原样回来\nview.setFeatureVisible('point', ['a', 'b'], false)        // 一批节点一次收起（一条历史、一条 batch）\nconsole.log(hiddenChannel.ok, hiddenChannel.indexes, hiddenChannel.skipped)\n","from":"header"}] },
-			{ name: "showFeatures", kind: "method", params: "同上，等价于 setFeatureVisible(kind, refs, true)（隐藏后原样恢复）", returns: "同上", doc: "统一隐藏 / 显示节点、线路或通道：只改数据里的 visible，不删要素，分组 / 拐点 / 编辑状态都保留。kind 收 point / line / channel，refs 收单个或一批 id / 下标 / { id } / { index }，也认 'selection'（通道按选中回线的归属取整条）；hideFeatures / showFeatures 是 false / true 的快捷写法。整次调用收成一条历史与一条 batch 数据变更，返回 { ok, reason, kind, visible, indexes, ids, items, skipped }；认不出的引用逐条进 skipped，不影响其余条目", examples: [{"group":"配置与数据","code":"// setFeatureVisible(kind, refs, visible) / hideFeatures(kind, refs) / showFeatures(kind, refs)：只改 visible，不删数据\nconst hiddenChannel = view.hideFeatures('channel', 'c1')  // 'point' / 'line' / 'channel'，refs 单个 / 数组 / 'selection'\nview.showFeatures('channel', 'c1')                        // 成员回线、分组、拐点原样回来\nview.setFeatureVisible('point', ['a', 'b'], false)        // 一批节点一次收起（一条历史、一条 batch）\nconsole.log(hiddenChannel.ok, hiddenChannel.indexes, hiddenChannel.skipped)\n","from":"header"}] },
+			{ name: "setFeatureVisible", kind: "method", params: "kind: GisViewVisibilityKind（'point' / 'line' / 'channel' / 'group'）；refs: GisViewVisibilityRefs 单个 / 一批 id 或下标，也认 'selection'（通道按选中回线的归属取整条、分组按归属取整组）。分组引用支持 { channelId | channelIndex, groupId | groupIndex }、{ id } 与全局唯一的裸分组 id；visible: boolean", returns: "GisViewSetVisibilityOutcome：{ ok, reason, kind, visible, indexes, ids, items, groups, skipped }。普通三类的 indexes 是数据下标、ids 是要素 id；group 的 indexes 是通道下标、ids 是分组 id、groups 是分组快照。只改数据的 visible，整次调用一条历史、一条 batch 数据变更", doc: "统一隐藏 / 显示节点、线路、通道或通道分组：只改数据里的 visible，不删要素，分组 / 拐点 / 编辑状态都保留。kind 收 point / line / channel / group；refs 收单个或一批 id / 下标 / { id } / { index }，也认 'selection'（通道按选中回线的归属取整条，分组按归属取整组）。分组的引用还可写 { channelId | channelIndex, groupId | groupIndex }、{ id }，或全局唯一的裸分组 id。hideFeatures / showFeatures 是 false / true 的快捷写法。整次调用收成一条历史与一条 batch 数据变更，返回 { ok, reason, kind, visible, indexes, ids, items, groups, skipped }：前三种 indexes 是数据下标、ids 是要素 id；group 的 indexes 是通道下标、ids 是分组 id、groups 是分组快照。认不出的引用逐条进 skipped，不影响其余条目，见「节点、线路、通道与分组的批量显隐」", examples: [{"group":"配置与数据","code":"// setFeatureVisible(kind, refs, visible) / hideFeatures(kind, refs) / showFeatures(kind, refs)：只改 visible，不删数据\nconst hiddenChannel = view.hideFeatures('channel', 'c1')  // 'point' / 'line' / 'channel' / 'group'，refs 单个 / 数组 / 'selection'\nview.showFeatures('channel', 'c1')                        // 成员回线、分组、拐点原样回来\nview.setFeatureVisible('point', ['a', 'b'], false)        // 一批节点一次收起（一条历史、一条 batch）\nview.hideFeatures('line', ['l1', 'l2'])                   // 只收这两条线，通道声明不动\nconst hiddenGroup = view.hideFeatures('group', { channelId: 'c1', groupId: 'c1::2' })\nview.hideFeatures('group', ['c1::2', { channelIndex: 0, groupIndex: 1 }])","from":"header"}] },
+			{ name: "hideFeatures", kind: "method", params: "同上，等价于 setFeatureVisible(kind, refs, false)", returns: "同上", doc: "统一隐藏 / 显示节点、线路、通道或通道分组：只改数据里的 visible，不删要素，分组 / 拐点 / 编辑状态都保留。kind 收 point / line / channel / group；refs 收单个或一批 id / 下标 / { id } / { index }，也认 'selection'（通道按选中回线的归属取整条，分组按归属取整组）。分组的引用还可写 { channelId | channelIndex, groupId | groupIndex }、{ id }，或全局唯一的裸分组 id。hideFeatures / showFeatures 是 false / true 的快捷写法。整次调用收成一条历史与一条 batch 数据变更，返回 { ok, reason, kind, visible, indexes, ids, items, groups, skipped }：前三种 indexes 是数据下标、ids 是要素 id；group 的 indexes 是通道下标、ids 是分组 id、groups 是分组快照。认不出的引用逐条进 skipped，不影响其余条目，见「节点、线路、通道与分组的批量显隐」", examples: [{"group":"配置与数据","code":"// setFeatureVisible(kind, refs, visible) / hideFeatures(kind, refs) / showFeatures(kind, refs)：只改 visible，不删数据\nconst hiddenChannel = view.hideFeatures('channel', 'c1')  // 'point' / 'line' / 'channel' / 'group'，refs 单个 / 数组 / 'selection'\nview.showFeatures('channel', 'c1')                        // 成员回线、分组、拐点原样回来\nview.setFeatureVisible('point', ['a', 'b'], false)        // 一批节点一次收起（一条历史、一条 batch）\nview.hideFeatures('line', ['l1', 'l2'])                   // 只收这两条线，通道声明不动\nconst hiddenGroup = view.hideFeatures('group', { channelId: 'c1', groupId: 'c1::2' })\nview.hideFeatures('group', ['c1::2', { channelIndex: 0, groupIndex: 1 }])","from":"header"}] },
+			{ name: "showFeatures", kind: "method", params: "同上，等价于 setFeatureVisible(kind, refs, true)（隐藏后原样恢复）", returns: "同上", doc: "统一隐藏 / 显示节点、线路、通道或通道分组：只改数据里的 visible，不删要素，分组 / 拐点 / 编辑状态都保留。kind 收 point / line / channel / group；refs 收单个或一批 id / 下标 / { id } / { index }，也认 'selection'（通道按选中回线的归属取整条，分组按归属取整组）。分组的引用还可写 { channelId | channelIndex, groupId | groupIndex }、{ id }，或全局唯一的裸分组 id。hideFeatures / showFeatures 是 false / true 的快捷写法。整次调用收成一条历史与一条 batch 数据变更，返回 { ok, reason, kind, visible, indexes, ids, items, groups, skipped }：前三种 indexes 是数据下标、ids 是要素 id；group 的 indexes 是通道下标、ids 是分组 id、groups 是分组快照。认不出的引用逐条进 skipped，不影响其余条目，见「节点、线路、通道与分组的批量显隐」", examples: [{"group":"配置与数据","code":"// setFeatureVisible(kind, refs, visible) / hideFeatures(kind, refs) / showFeatures(kind, refs)：只改 visible，不删数据\nconst hiddenChannel = view.hideFeatures('channel', 'c1')  // 'point' / 'line' / 'channel' / 'group'，refs 单个 / 数组 / 'selection'\nview.showFeatures('channel', 'c1')                        // 成员回线、分组、拐点原样回来\nview.setFeatureVisible('point', ['a', 'b'], false)        // 一批节点一次收起（一条历史、一条 batch）\nview.hideFeatures('line', ['l1', 'l2'])                   // 只收这两条线，通道声明不动\nconst hiddenGroup = view.hideFeatures('group', { channelId: 'c1', groupId: 'c1::2' })\nview.hideFeatures('group', ['c1::2', { channelIndex: 0, groupIndex: 1 }])","from":"header"}] },
 			{ name: "isPointVisible", kind: "method", params: "index: number 节点下标", returns: "boolean。在不在图上（被筛选 / visible: false 或发散渲染还没铺到的都算 false）", doc: "某个下标的节点当前在不在图上：被筛选 / visible: false 隐藏掉的不算，初始化发散渲染还没排到的那部分也不算", examples: [{"group":"坐标、拾取与读数","code":"// getVisibleData() / isPointVisible(index)：筛选之后的整份数据 / 某个节点在不在图上\nconst visibleData = view.getVisibleData()\nconst shown = view.isPointVisible(0)\n","from":"header"}] },
 			{ name: "getElementBounds", kind: "method", params: "keys: GisViewFeatureKey[] 要素定位数组（{ type, id } / { type, index } / 裸 id）", returns: "GisViewBounds | null", doc: "一批要素 GisViewFeatureKey[]（{ type: 'point' | 'line', index }，getSelections() 的结果可以直接传）的世界包围盒 { minX, minY, maxX, maxY }；一个都没对上返回 null（数据已经换过）", examples: [{"group":"坐标、拾取与读数","code":"// getElementBounds(keys) / getViewState()：一批要素的包围盒 / 一次取全视图读数\nconst box = view.getElementBounds(view.getSelections())\nconst state = view.getViewState()","from":"header"}] },
 			{ name: "getViewState", kind: "method", params: "无", returns: "GisViewViewState", doc: "一次取全的读数快照：camera / viewport / viewRect / layoutReady / selection / selectionIds / filter / filterResult / pointer / stats，自建状态栏与「布局铺好了没」的判断用它", examples: [{"group":"坐标、拾取与读数","code":"// getElementBounds(keys) / getViewState()：一批要素的包围盒 / 一次取全视图读数\nconst box = view.getElementBounds(view.getSelections())\nconst state = view.getViewState()","from":"header"}] },
@@ -153,6 +160,8 @@ export const API_SECTIONS = [
 			{ name: "getSelectionData", kind: "method", params: "无", returns: "GisViewSelectionData：{ ids, count, pointCount, lineCount, channelCount, points, lines, channels, items, pointIndexes, lineIndexes, bounds }（bounds 是世界包围盒，空选中时 null；items 的线路不带通道字段，channels 是去重后的所属通道）", doc: "选中集一次取全：读数（ids / count / pointCount / lineCount / channelCount）加要素本身（points / lines / channels（按通道去重，与 getData() 同一批对象）），另有 items（与 getSelections() 同一份，通道回线不带通道字段）、pointIndexes / lineIndexes 与 bounds（世界包围盒，空选中时 null），见「接口选中（selectFeatures）与读回选中」", examples: [{"group":"选中、复制与合并","code":"// getSelections() / getSelectionInfo() / getSelectionData() / isSelected(ref)：读回选中\nconst picks = view.getSelections()\nconst info = view.getSelectionInfo()                   // { ids, count, points, lines, channels }\nconst selection = view.getSelectionData()              // { ids, count, points, lines, channels, bounds, … }\nconst selected = view.isSelected('a')\n","from":"header"}] },
 			{ name: "getCascadeHighlight", kind: "method", params: "无", returns: "GisViewCascadeHighlightInfo | null：当前点击级联高亮的来源、范围与节点 / 线路读数 { origin, scope, points, lines, pointIndexes, lineIndexes }，不改变选中集", doc: "当前点击级联高亮的读数：{ origin, scope, points, lines, pointIndexes, lineIndexes }；没有高亮或 cascadeHighlight 关着时返回 null。它只读、不改选中集，见「点击级联高亮」", examples: [{"group":"选中、复制与合并","code":"// getCascadeHighlight()：读点击级联高亮（与选中集分开；没有高亮时为 null）\nconst cascade = view.getCascadeHighlight()             // { origin, scope, points, lines, pointIndexes, lineIndexes }\nview.updateOptions({\n  cascadeHighlight: {\n    scope: 'points',\n    triggerOnClick: true,\n    triggerOnMultiSelect: false,\n    triggerOnBoxSelect: true,\n    clearOnEmptyClick: true\n  }\n})\nview.on('cascadeHighlight', payload => console.log(payload?.pointIndexes, payload?.lineIndexes))\n","from":"header"}] },
 			{ name: "selectInBox", kind: "method", params: "box: GisViewRect 画布 CSS 像素矩形 { x, y, width, height }（与手动框选同一套坐标）；options?: GisViewSelectInBoxOptions：selectionKinds 临时覆盖这一次保留哪几类（'point' / 'line' / 'channel' / 'lineEndpoints' / 'channelEndpoints'、数组、'all' / true / false / null，不写沿用全局 selectionKinds），originalEvent 原样带进 onSelect。空框不会选中任何要素", returns: "this（每次框选都发 onSelect，空框为 null；集合变化时再发 onSelectChange，顺序 onSelect → onSelectChange，cause 为 boxSelect）", doc: "按画布 CSS 像素矩形框选，等价于 Shift + 拖动（跟随 shortcuts.boxSelect）；options.selectionKinds 可只覆盖这一次的节点 / 线路 / 通道类型过滤，也支持 'lineEndpoints' / 'channelEndpoints' 要求两端节点都在框内。每次框选操作都发 onSelect（空框的载荷为 null），选中集实际变化时再发 onSelectChange，顺序 onSelect → onSelectChange（cause: 'boxSelect'）；通道回线的分组字段与鼠标框选同一份", examples: [{"group":"选中、复制与合并","code":"// selectInBox(box, options?)：用矩形框选（画布 CSS 像素，与手动框选同一套判定）\nview.selectInBox({ x: 40, y: 40, width: 320, height: 200 })\nview.selectInBox({ x: 40, y: 40, width: 320, height: 200 }, { selectionKinds: ['line', 'channel'] })\nview.selectInBox({ x: 40, y: 40, width: 320, height: 200 }, { selectionKinds: ['lineEndpoints', 'channelEndpoints'] }) // 两端节点都在框内才命中\n","from":"header"}] },
+			{ name: "clearSelectionBox", kind: "method", params: "无：收起当前保留的框选矩形；只动矩形，不改变选中集，也不发选中回调", returns: "this", doc: "收起当前保留的框选矩形 / 读当前矩形：clearSelectionBox() 只动框，不改变选中集；getSelectionBox() 返回画布 CSS 像素的 { x, y, width, height } 副本，没有框时返回 null。保留框由 selectionBoxPersistent 打开，见「框选」", examples: [{"group":"选中、复制与合并","code":"// selectionBoxPersistent / clearSelectionBox() / getSelectionBox()：框选后保留矩形，并手动收起\nview.updateOptions({ boxSelect: true, draggable: true, selectionBoxPersistent: true })\nview.selectInBox({ x: 40, y: 40, width: 320, height: 200 })\nconst retainedBox = view.getSelectionBox()                 // 画布 CSS 像素；没有框时为 null\nview.clearSelectionBox()                                   // 只收框，不改选中集\n","from":"header"}] },
+			{ name: "getSelectionBox", kind: "method", params: "无", returns: "GisViewRect | null：保留框的画布 CSS 像素矩形（已归整为左上角 + 宽高），没有时为 null", doc: "收起当前保留的框选矩形 / 读当前矩形：clearSelectionBox() 只动框，不改变选中集；getSelectionBox() 返回画布 CSS 像素的 { x, y, width, height } 副本，没有框时返回 null。保留框由 selectionBoxPersistent 打开，见「框选」", examples: [{"group":"选中、复制与合并","code":"// selectionBoxPersistent / clearSelectionBox() / getSelectionBox()：框选后保留矩形，并手动收起\nview.updateOptions({ boxSelect: true, draggable: true, selectionBoxPersistent: true })\nview.selectInBox({ x: 40, y: 40, width: 320, height: 200 })\nconst retainedBox = view.getSelectionBox()                 // 画布 CSS 像素；没有框时为 null\nview.clearSelectionBox()                                   // 只收框，不改选中集\n","from":"header"}] },
 			{ name: "beginCopyPoint", kind: "method", params: "options: GisViewCopyStartOptions：id / index / item 三选一给来源，都不给就进入「下一次点选节点」模式；coordinate / screen 是落点（缺省按 copy.offset）；follow 让预览跟指针；autoCommit 覆盖 copy.autoCommit；commit: true 出预览即落地；via / originalEvent 原样带回。必须配置 copy（enabled 不为 false），否则返回 null。预览节点插在 points 末尾且不带 id，不会把绑定源 id 的线路 / 通道带过去", returns: "GisViewPointCopyPayload | null：phase: 'start' 的预览载荷；来源认不出来时返回 null", doc: "开始复制一个节点：给 id / index 直接出预览（commit: true 出预览即落地，follow: true 跟随鼠标，autoCommit: false 停在预览态），不给来源就是「先点按钮再选节点」模式，见「节点复制」", examples: [{"group":"选中、复制与合并","code":"// beginCopyPoint(options) / getPointCopy() / updateCopyPoint(patch) / commitPointCopy() / cancelPointCopy()\nview.updateOptions({ copy: { enabled: true, autoCommit: false } })  // API 复制入口要先开 copy 配置\nview.beginCopyPoint({ id: 'a', coordinate: [40, 30] })             // 出预览并钉在世界坐标 [40, 30]\nview.beginCopyPoint({ id: 'a', follow: true })                     // 预览跟着指针走（autoCommit 缺省停住）\nview.beginCopyPoint()                                              // 先点按钮再选节点（点中下一个节点当来源）\nview.updateCopyPoint({ name: '新节点' })                            // 字段级改预览节点（落点仍由 coordinate / 指针决定）\nconst copyEnd = view.commitPointCopy()                              // 落地：返回 end 载荷；没有预览时为 null\nview.cancelPointCopy()                                              // 取消：预览撤掉，数据与历史不动\nconst copyState = view.getPointCopy()                  // 当前预览 / 选点态（没有就是 null）\n","from":"header"}] },
 			{ name: "commitPointCopy", kind: "method", params: "无：把当前复制预览落地，先发 commit、落地后发 end；commit 阶段载荷里的 cancel() 可以拦住这次复制", returns: "GisViewPointCopyPayload | null：成功的 end 载荷；没有预览或已被取消时为 null", doc: "落地 / 取消预览中的复制（返回 end / cancel 载荷）", examples: [{"group":"选中、复制与合并","code":"// beginCopyPoint(options) / getPointCopy() / updateCopyPoint(patch) / commitPointCopy() / cancelPointCopy()\nview.updateOptions({ copy: { enabled: true, autoCommit: false } })  // API 复制入口要先开 copy 配置\nview.beginCopyPoint({ id: 'a', coordinate: [40, 30] })             // 出预览并钉在世界坐标 [40, 30]\nview.beginCopyPoint({ id: 'a', follow: true })                     // 预览跟着指针走（autoCommit 缺省停住）\nview.beginCopyPoint()                                              // 先点按钮再选节点（点中下一个节点当来源）\nview.updateCopyPoint({ name: '新节点' })                            // 字段级改预览节点（落点仍由 coordinate / 指针决定）\nconst copyEnd = view.commitPointCopy()                              // 落地：返回 end 载荷；没有预览时为 null\nview.cancelPointCopy()                                              // 取消：预览撤掉，数据与历史不动\nconst copyState = view.getPointCopy()                  // 当前预览 / 选点态（没有就是 null）\n","from":"header"}] },
 			{ name: "cancelPointCopy", kind: "method", params: "无：撤掉预览并补一条 cancel，数据与历史不动", returns: "GisViewPointCopyPayload | null：取消载荷；没有预览时为 null", doc: "落地 / 取消预览中的复制（返回 end / cancel 载荷）", examples: [{"group":"选中、复制与合并","code":"// beginCopyPoint(options) / getPointCopy() / updateCopyPoint(patch) / commitPointCopy() / cancelPointCopy()\nview.updateOptions({ copy: { enabled: true, autoCommit: false } })  // API 复制入口要先开 copy 配置\nview.beginCopyPoint({ id: 'a', coordinate: [40, 30] })             // 出预览并钉在世界坐标 [40, 30]\nview.beginCopyPoint({ id: 'a', follow: true })                     // 预览跟着指针走（autoCommit 缺省停住）\nview.beginCopyPoint()                                              // 先点按钮再选节点（点中下一个节点当来源）\nview.updateCopyPoint({ name: '新节点' })                            // 字段级改预览节点（落点仍由 coordinate / 指针决定）\nconst copyEnd = view.commitPointCopy()                              // 落地：返回 end 载荷；没有预览时为 null\nview.cancelPointCopy()                                              // 取消：预览撤掉，数据与历史不动\nconst copyState = view.getPointCopy()                  // 当前预览 / 选点态（没有就是 null）\n","from":"header"}] },
@@ -325,7 +334,7 @@ export const API_SECTIONS = [
 			{ name: "on", kind: "method", params: "name: GisViewEventName | '*' 事件名（'dataChange' / 'labelClick'… 或 '*' 订阅全部）；handler: (payload, name?) => void 回调，载荷字段见「事件」一节的表", returns: "() => void 取消订阅", doc: "订阅事件（与 options 里的回调同一条，可以挂多条）：返回取消订阅的函数；'*' 订阅全部事件，回调拿到 (载荷, 事件名)，见「事件订阅」", examples: [{"group":"事件、开关与历史","code":"// on(name, handler) / once(name, handler) / off(name, handler?)：订阅（'*' 订阅全部）\nconst offData = view.on('dataChange', payload => sync(payload))\nview.on('*', (payload, name) => log(name, payload))\nview.once('dataRendered', payload => { loading = false })\nview.off('dataChange')                // 摘掉这个事件的全部回调\nview.off('dataChange', sync)          // 只摘掉这一个（返回摘掉几条）\n","from":"header"}] },
 			{ name: "once", kind: "method", params: "与 on 同一套事件名与载荷；只触发一次，回调跑完自动摘掉。返回的取消函数可提前撤销；即使提前取消，重复调用也安全", returns: "() => void 取消订阅", doc: "订阅事件（与 options 里的回调同一条，可以挂多条）：返回取消订阅的函数；'*' 订阅全部事件，回调拿到 (载荷, 事件名)，见「事件订阅」", examples: [{"group":"事件、开关与历史","code":"// on(name, handler) / once(name, handler) / off(name, handler?)：订阅（'*' 订阅全部）\nconst offData = view.on('dataChange', payload => sync(payload))\nview.on('*', (payload, name) => log(name, payload))\nview.once('dataRendered', payload => { loading = false })\nview.off('dataChange')                // 摘掉这个事件的全部回调\nview.off('dataChange', sync)          // 只摘掉这一个（返回摘掉几条）\n","from":"header"}] },
 			{ name: "off", kind: "method", params: "name 事件名（也认 '*'）；handler? 只摘掉这一个回调，不传 = 摘掉这个事件的全部订阅", returns: "number 摘掉几条（没摘到返回 0）", doc: "取消订阅：不传 handler 就摘掉这个事件的全部订阅，返回摘掉几条", examples: [{"group":"事件、开关与历史","code":"// on(name, handler) / once(name, handler) / off(name, handler?)：订阅（'*' 订阅全部）\nconst offData = view.on('dataChange', payload => sync(payload))\nview.on('*', (payload, name) => log(name, payload))\nview.once('dataRendered', payload => { loading = false })\nview.off('dataChange')                // 摘掉这个事件的全部回调\nview.off('dataChange', sync)          // 只摘掉这一个（返回摘掉几条）\n","from":"header"}] },
-			{ name: "use", kind: "method", params: "plugin: GisViewPlugin（(view, context) => hook，与 options.plugins 的写法一致）：立即执行一次，返回卸载函数 —— 调它跑插件自己的 destroy（重复调用只清一次，实例销毁之后也安全）", returns: "() => void 卸载", doc: "运行时挂一个插件（写法与 options.plugins 里的一项一致）：调用即执行，返回幂等的卸载函数（跑插件自己的 destroy），见「插件」", examples: [{"group":"事件、开关与历史","code":"// use(plugin)：运行时挂插件（立即执行一次，返回卸载函数）\nconst dispose = view.use((view, context) => ({ destroy() { /* 插件自己的清理；context.apiVersion 当前为 1 */ } }))\ndispose()\n","from":"header"}] },
+			{ name: "use", kind: "method", params: "plugin: GisViewPlugin（(view, context) => hook，与 options.plugins 的写法一致）：立即执行一次，返回卸载函数 —— 调它中止 signal、跑旧写法的 destroy，再执行 context.onCleanup / on / registerCommand 登记的清理（重复调用只清一次，实例销毁之后也安全）", returns: "() => void 卸载", doc: "运行时挂一个插件（写法与 options.plugins 里的一项一致）：调用即执行，返回幂等的卸载函数（中止 signal、跑旧写法的 destroy、执行 context 自动清理），见「插件」", examples: [{"group":"事件、开关与历史","code":"// use(plugin)：运行时挂插件（立即执行一次，返回卸载函数）\nconst dispose = view.use((view, context) => {\n  context.on('selectChange', payload => console.log('选中变了：', payload.count))\n  context.registerCommand('toggleInspector', () => view.updateOptions({ tooltip: false }))\n  context.onCleanup(() => { /* context 未管理的资源在这里收尾；context.apiVersion 当前为 1 */ })\n})\ndispose()\n","from":"header"}] },
 			{ name: "registerCommand", kind: "method", params: "name: string 命令名（会 trim，同名覆盖）；handler: GisViewCommandHandler<Payload, Value> 同步处理函数 (payload, context) => Value，context 是冻结的 { view, name }。名字为空 / handler 不是函数只报 warning、不注册；视图销毁后注册不生效", returns: "() => void 幂等注销；同名已被后来者覆盖时不会误删新命令", doc: "注册一个实例命令：handler(payload, context) 同步执行，context 是冻结的 { view, name }；同名覆盖，返回幂等的注销函数，旧卸载函数不会误删后来注册的同名命令，见「实例命令」", examples: [{"group":"事件、开关与历史","code":"// registerCommand(name, handler) / executeCommand(name, payload?) / listCommands()：实例级业务命令\nconst disposeCommand = view.registerCommand('focusHighestLoad', (payload = {}, context) => {\n  const threshold = Number(payload.threshold ?? 0.8)\n  const target = view.getData().points\n    .filter(point => Number(point.max_loading_rate ?? 0) >= threshold)\n    .sort((left, right) => Number(right.max_loading_rate ?? 0) - Number(left.max_loading_rate ?? 0))[0]\n  if (!target) return { focused: false, threshold }\n  context.view.focusOn(target.id, { select: true, zoom: true, maxZoom: 12 })\n  return { focused: true, id: target.id, command: context.name }\n})\nconst commandResult = view.executeCommand('focusHighestLoad', { threshold: 0.85 })\nconst commandNames = view.listCommands()   // ['focusHighestLoad']\ndisposeCommand()                           // 幂等卸载；同名覆盖时不会误删新命令\n","from":"header"}] },
 			{ name: "executeCommand", kind: "method", params: "name: string 命令名；payload?: unknown 原样交给 handler", returns: "GisViewCommandResult<Value>：{ ok: true, name, value } / { ok: false, name, reason }（未注册 / 名字非法 / handler 抛错）", doc: "执行实例命令：成功给 { ok: true, name, value }；名字非法 / 未注册 / handler 抛错给 { ok: false, name, reason }，见「实例命令」", examples: [{"group":"事件、开关与历史","code":"// registerCommand(name, handler) / executeCommand(name, payload?) / listCommands()：实例级业务命令\nconst disposeCommand = view.registerCommand('focusHighestLoad', (payload = {}, context) => {\n  const threshold = Number(payload.threshold ?? 0.8)\n  const target = view.getData().points\n    .filter(point => Number(point.max_loading_rate ?? 0) >= threshold)\n    .sort((left, right) => Number(right.max_loading_rate ?? 0) - Number(left.max_loading_rate ?? 0))[0]\n  if (!target) return { focused: false, threshold }\n  context.view.focusOn(target.id, { select: true, zoom: true, maxZoom: 12 })\n  return { focused: true, id: target.id, command: context.name }\n})\nconst commandResult = view.executeCommand('focusHighestLoad', { threshold: 0.85 })\nconst commandNames = view.listCommands()   // ['focusHighestLoad']\ndisposeCommand()                           // 幂等卸载；同名覆盖时不会误删新命令\n","from":"header"}] },
 			{ name: "listCommands", kind: "method", params: "无", returns: "string[] 当前注册的命令名（按注册顺序；同名覆盖不改变位置）", doc: "当前注册着哪些实例命令（按注册顺序；同名覆盖不改变原来的位置）", examples: [{"group":"事件、开关与历史","code":"// registerCommand(name, handler) / executeCommand(name, payload?) / listCommands()：实例级业务命令\nconst disposeCommand = view.registerCommand('focusHighestLoad', (payload = {}, context) => {\n  const threshold = Number(payload.threshold ?? 0.8)\n  const target = view.getData().points\n    .filter(point => Number(point.max_loading_rate ?? 0) >= threshold)\n    .sort((left, right) => Number(right.max_loading_rate ?? 0) - Number(left.max_loading_rate ?? 0))[0]\n  if (!target) return { focused: false, threshold }\n  context.view.focusOn(target.id, { select: true, zoom: true, maxZoom: 12 })\n  return { focused: true, id: target.id, command: context.name }\n})\nconst commandResult = view.executeCommand('focusHighestLoad', { threshold: 0.85 })\nconst commandNames = view.listCommands()   // ['focusHighestLoad']\ndisposeCommand()                           // 幂等卸载；同名覆盖时不会误删新命令\n","from":"header"}] },
@@ -393,6 +402,7 @@ export const API_OPTIONS = [
 	{ name: "pointRules", type: "GisViewPointRule[] / GisViewLineRule[]", defaultValue: "[]", doc: "批量样式规则：按属性给点 / 线批量配色、改大小、换符号，见「批量样式规则」" },
 	{ name: "lineRules", type: "GisViewPointRule[] / GisViewLineRule[]", defaultValue: "[]", doc: "批量样式规则：按属性给点 / 线批量配色、改大小、换符号，见「批量样式规则」" },
 	{ name: "heatmap", type: "GisViewHeatmap | null", defaultValue: "无", doc: "热力图：按业务字段的数值到渐变色带上取颜色，并可按同一个值缩放节点大小 / 线宽，作用对象可选节点 / 线路 / 通道；不配（或 null）就是关的，见「热力图」" },
+	{ name: "visualMap", type: "GisViewVisualMap | null", defaultValue: "无", doc: "图例：参考 ECharts visualMap，把热力图的色带画成带刻度的连续尺（ruler / continuous）或分段色块（piecewise）。不配 / null / enabled: false 时零 DOM；默认跟随 heatmap 的字段、自动值域与颜色，也能独立给字段 / 值域 / 颜色 / 外部容器。不写 target 时展示值域取第一类有数值的启用目标，交互门控覆盖 heatmap 的全部启用目标；显式写才限定为一类，见「图例（visualMap）」" },
 	{ name: "effects", type: "GisViewEffectsInput", defaultValue: "关", doc: "动画效果（全局缺省）：线路上的跑动图标（line，ECharts lines.effect 那一类）与节点上的扩散涟漪（point，effectScatter 那一类），逐要素用 points[].effect / lines[].effect 覆盖；没配就是关的，但「只在数据里逐条配了 effect」的场景照样会动。false 或 { enabled: false } 是一处关掉（谁都别动）；运行时有 updateOptions({ effects }) / getEffects() / getLineEffects()，见「动画效果（effects）」" },
 	{ name: "lineDirection", type: "GisViewLineDirectionInput", defaultValue: "关（null）", doc: "线路方向箭头（全局缺省）：沿线摆一串静态箭头，朝向跟着线路切向走（起点 / from 那一端 → 终点，reverse 指回上游），按弧长等分、缺省每条线只在中点一个；逐条线路用 lines[].direction 覆盖，写法与 effects 同构（true 用全局、对象逐字段覆盖、false / null 关掉），见「线路方向箭头（lineDirection）」" },
 	{ name: "prebake", type: "GisViewPrebakeOptions | true", defaultValue: "关", doc: "贴图符号预热：把「这次画面会出现什么」提前告诉组件 —— 两种写法：combos 逐组合（精确，getSymbolCombos() 收出来的那份）/ symbols × pointColors × sizes 与 lineColors × 线路动画图标 全排列（省事，颜色与尺寸由同一个字段决定时会多烤很多）—— 第一帧之前就烤好，画到它们时命中的是现成的贴图（省掉解码 + 光栅化那一下）；组合数与数据量无关，不配就是从前那条按需路径。读数 getPrebake() / getSymbolCombos()、手动再烤一遍 runPrebake()，见「贴图符号预热（prebake）」" },
@@ -421,15 +431,18 @@ export const API_OPTIONS = [
 	{ name: "pointZoomScale", type: "number", defaultValue: "1 / 0", doc: "两组系数各管一件事，不重复：pointSizeScale / lineWidthScale 是与地图无关的整体放大（常数倍数，屏幕上的大小因此恒定），pointZoomScale / lineZoomScale 是「跟随地图缩放」的指数（0 表示不跟随，1 表示与地图同倍率放大，0.5 是地图放大 4 倍、要素放大 2 倍），绘制尺寸是两者相乘；zoomBaseScale 是联动基准，缺省取首次适应视图时的比例" },
 	{ name: "lineZoomScale", type: "number", defaultValue: "1 / 0", doc: "两组系数各管一件事，不重复：pointSizeScale / lineWidthScale 是与地图无关的整体放大（常数倍数，屏幕上的大小因此恒定），pointZoomScale / lineZoomScale 是「跟随地图缩放」的指数（0 表示不跟随，1 表示与地图同倍率放大，0.5 是地图放大 4 倍、要素放大 2 倍），绘制尺寸是两者相乘；zoomBaseScale 是联动基准，缺省取首次适应视图时的比例" },
 	{ name: "zoomBaseScale", type: "number", defaultValue: "1 / 0", doc: "两组系数各管一件事，不重复：pointSizeScale / lineWidthScale 是与地图无关的整体放大（常数倍数，屏幕上的大小因此恒定），pointZoomScale / lineZoomScale 是「跟随地图缩放」的指数（0 表示不跟随，1 表示与地图同倍率放大，0.5 是地图放大 4 倍、要素放大 2 倍），绘制尺寸是两者相乘；zoomBaseScale 是联动基准，缺省取首次适应视图时的比例" },
-	{ name: "fitSpacing", type: "boolean | GisViewFitSpacingOptions", defaultValue: "关", doc: "适应视图的节点间距兜底：true 用最小中心距模式（默认 24 CSS 像素）；对象在 minDistance / maxDistance 中二选一，同时给出时只启用 maxDistance，maxZoom 是相对普通适应比例的上限（0 表示不限）；只在首次默认适应与 fitView() 生效，远处孤立点允许落到视口外，见「适应视图的节点间距（fitSpacing）」" },
+	{ name: "fitSpacing", type: "boolean | GisViewFitSpacingOptions", defaultValue: "关", doc: "适应视图的节点间距兜底：true 把最近节点中心距精确设为 24 CSS 像素；对象在 minDistance（精确屏距，可放大也可缩小）/ maxDistance（最远距离上限，只压低比例）中二选一，同时给出时只启用 maxDistance；maxZoom 仅为旧配置兼容保留，不再限制距离；只在首次默认适应与 fitView() 生效，远处孤立点允许落到视口外，见「适应视图的节点间距（fitSpacing）」" },
 	{ name: "boxSelect", type: "boolean", defaultValue: "false", doc: "是否允许按住框选快捷键（shortcuts.boxSelect，默认 Shift）拖动鼠标框选要素；缺省关，写 boxSelect: true 或 features: { boxSelect: true } 才开。框选默认只收节点，selectionKinds 可把线路 / 通道也纳入" },
 	{ name: "multiSelect", type: "boolean", defaultValue: "false", doc: "多选开关：打开后不用按修饰键，直接单击节点 / 线路就取反累加选中（与按住 shortcuts.multiSelect 点击同一套行为、同一个 multiSelectStyle；取反那一下不经过 onClick，onSelectChange.action.type 是 toggleSelect）；缺省关，关着时多选走框选（boxSelect）与按住多选快捷键（默认 Ctrl / ⌘）。运行时 updateOptions({ multiSelect }) 切换只重画一帧、不重排场景" },
+	{ name: "toggleSelect", type: "boolean", defaultValue: "false", doc: "再次选中即取消：打开后普通单击已选中的节点 / 线路 / 通道会取消，selectTrigger: 'dblClick' 下再次双击取消，Ctrl / ⌘ 先选中后再普通单击也取消；取反时 onClick.action.type 与 onSelectChange.action.type 都是 toggleSelect。缺省关，运行时 updateOptions({ toggleSelect }) 只重画一帧、不重排场景，见「选中与拐点」" },
 	{ name: "selectTrigger", type: "'click' | 'dblClick'", defaultValue: "'click'", doc: "选中触发方式：click 第一次单击就改选中集；dblClick 第一下只派发 onClick，等双击判定命中的第二下才改选中集，并同时派发 onClick 与 onDblClick。Ctrl / ⌘ 多选与 multiSelect 在双击模式下同样等第二下才取反。运行时走 updateOptions({ selectTrigger })，只重画一帧、不重排场景" },
 	{ name: "selectionKinds", type: "GisViewSelectionKindsInput", defaultValue: "无（框选只收节点；Ctrl 多选收节点 / 线路 / 通道）", doc: "框选与 Ctrl / 多选点击的类型过滤：'point' 节点、'line' 通道外的独立线路、'channel' 通道回线；另有 'lineEndpoints' / 'channelEndpoints'，只在框选时要求线路 / 通道两端节点都在框内。可写数组任意组合，'all' / true 全开，false / null 全关。通道回线只归 channel 管，通道外的线路只归 line 管；通道回线仍按 channelSelectMode 摊开。不写时保留旧口径；普通单选与 select / selectFeatures 不受它限制。运行时走 updateOptions({ selectionKinds })，见「框选」与「选择类型过滤」" },
-	{ name: "selectionBoxStyle", type: "GisViewSelectionBoxStyle", defaultValue: "蓝底 0.16 透明 + 1px 蓝框", doc: "框选矩形的填充与边框：fill、fillOpacity、stroke、strokeWidth" },
+	{ name: "selectionBoxStyle", type: "GisViewSelectionBoxStyle", defaultValue: "蓝底 0.16 透明 + 1px 蓝框", doc: "框选矩形的样式：fill / fillOpacity / stroke / strokeWidth，以及 DOM 渲染用的 render: 'div' / className / borderStyle / radius；canvas 模式不画线型与圆角，见「框选」" },
+	{ name: "selectionBoxPersistent", type: "boolean", defaultValue: "false", doc: "框选结束后是否保留选框：打开后拖动保留框会整组平移框内选中节点，线路与通道跟随；选中集变化、清空、关闭开关或调用 clearSelectionBox() 时收起。要用它同时打开 boxSelect 和 draggable，见「框选」的「保留框与整组拖动」" },
 	{ name: "selectionOnTop", type: "boolean", defaultValue: "true", doc: "选中的节点 / 拖动中的整组 / 待确认合并的目标节点，以及选中线路所在的整条通道，是否画在所有要素之上（与 zIndex 无关），见「选中 / 拖动的层级」" },
 	{ name: "channelSelectMode", type: "'line' | 'group' | 'channel'", defaultValue: "'line'", doc: "通道选中模式：点中通道里的一条回线时选中什么 —— 'line' 只选这一条、'group' 连它所在的分组一起、'channel' 整条通道（所有分组的回线）；通道以外的线路永远只选自己。普通点选与 Ctrl / ⌘ + 点击加点共用这一档高亮范围；Ctrl / ⌘ + 点击在 group / channel 下按整批取反；切换走 updateOptions({ channelSelectMode })，只重画一帧、不重排场景，见「通道选中模式」" },
 	{ name: "channelWaypointDragMode", type: "'parallel' | 'vertex'", defaultValue: "'parallel'", doc: "分组拐点拖动模式：'parallel' 沿用共用骨架 + 平行偏移（和原有逻辑一致），'vertex' 只平移当前分组同一 pathIndex 的拐点，其他拐点与分组不动；普通线路始终只动自己。vertex 的结果写进 groups[].waypointOffsets，切换走 updateOptions({ channelWaypointDragMode })，下一次拖动生效，见「分组拐点拖动模式」" },
+	{ name: "channelHiddenLineLayout", type: "'preserve' | 'center'", defaultValue: "'preserve'", doc: "隐藏部分回线 / 分组后车道怎么排：'preserve' 保留原车道槽位，剩余回线不挪位；'center' 只把当前可见回线按原顺序压成连续槽位，再在通道宽度内重新居中。运行时走 updateOptions({ channelHiddenLineLayout })，见「隐藏回线后的车道」" },
 	{ name: "waypointEditable", type: "boolean", defaultValue: "false", doc: "是否允许编辑线路拐点（按住加点快捷键 shortcuts.addWaypoint（默认 Ctrl / ⌘）+ 点击添加、拖动移动、双击或删除快捷键删除），单条线可用 waypointEditable 覆盖；缺省关，写 waypointEditable: true 或 features: { waypoint: true } 才开。false（以及 features: { waypoint: false }）会同时关闭新增、移动与删除，没有只关其中一项的细分开关；shortcuts.addWaypoint 仍只决定加点的组合键" },
 	{ name: "waypointVisibility", type: "'selected' | 'always'", defaultValue: "'selected'", doc: "拐点显示时机：selected 只显示选中线路（以及刚加过拐点的线路）的拐点，always 全部显示" },
 	{ name: "waypointStyle", type: "GisViewPointStyle", defaultValue: "无", doc: "拐点（线路 path 的中间顶点）的默认 / 选中样式，支持配置：字段与节点样式同款；缺省是白底蓝圈的 9px 圆点，waypointSelectStyle 没配时选中拐点用内置强调环，见「线路拐点」的「拐点样式」小节" },
@@ -438,6 +451,9 @@ export const API_OPTIONS = [
 	{ name: "gridColor", type: "string", defaultValue: "rgba(120, 150, 190, 0.32)", doc: "网格颜色" },
 	{ name: "gridSize", type: "number", defaultValue: "96", doc: "网格线的屏幕目标间距，实际步长吸附到 1 / 2 / 5 × 10^n" },
 	{ name: "showGrid", type: "boolean", defaultValue: "false", doc: "是否绘制网格：与其它功能开关同一条口径，缺省关，写 showGrid: true 才画" },
+	{ name: "networkVisible", type: "boolean", defaultValue: "true", doc: "网架整体显隐：false 时节点、线路、通道、装饰、动画、标签与框选框一起不画，只保留背景、网格与自定义 WebGL 层；数据、选中与历史都不动，拾取 / 框选 / queryRect 也不再命中网架，适合先铺网架再添加背景" },
+	{ name: "networkOpacity", type: "number", defaultValue: "1", doc: "网架整体不透明度（夹在 0 ~ 1）：在每类要素自身 opacity 之后再乘一层，节点、线路、通道、装饰、动画与标签一起变淡，背景不受影响。0 只是画面上看不见，拾取仍按网架存在；要完全收起请用 networkVisible: false" },
+	{ name: "backgroundEditing", type: "boolean", defaultValue: "false", doc: "背景编辑模式：true 时节点、线路、通道的悬停、点击、选中、拖拽、拐点编辑、框选、右键与数据快捷键全部停用，仍保留滚轮缩放与 fitView，方便让网架和背景一起缩放后只移动 / 旋转 / 缩放背景；缺省 false，可用 updateOptions() 随时开关" },
 	{ name: "interactive", type: "boolean", defaultValue: "（缺省全关）", doc: "查看类交互的「详细配置手动打开」写法：写 true 打开拖拽平移 / 滚轮缩放 / 右键回调（等价 pan / zoom / contextMenu 三个开关），不写就是全关" },
 	{ name: "preventContextMenu", type: "boolean", defaultValue: "true", doc: "组件接住右键时是否收掉浏览器的系统菜单（contextmenu 的默认行为）：contextMenu 开着（或 interactive: true / features: 'view'）时组件才接右键，接住时一律 preventDefault()，点 / 线 / 空白 / 通道都一样；想让系统菜单自己弹就写 false（onContextMenu 照常发）。右键整个不接时（contextMenu 缺省关）系统菜单自然照弹" },
 	{ name: "clickable", type: "boolean", defaultValue: "（缺省全关）", doc: "查看类交互的「详细配置手动打开」写法：写 true 打开悬停高亮与点击选中（等价 hover / select 两个开关），要素自身可用 clickable: false 逐个关掉" },
@@ -448,8 +464,8 @@ export const API_OPTIONS = [
 	{ name: "copy", type: "GisViewCopyOptions", defaultValue: "缺省关", doc: "复制节点（写了这份配置才算开，enabled: false 显式关掉）：enabled 开关、offset 落点偏移（默认 [28, 24] 像素）、autoCommit（交互入口落地前是否自动确认：不写就是落地，false 停在预览态等 commitPointCopy() / 载荷里的 payload.commit()）、idPrefix（默认 copy-）、createId / createItem 定制复制品，见「节点复制」" },
 	{ name: "remove", type: "GisViewRemoveOptions", defaultValue: "缺省关", doc: "删除选中的拐点 / 线路 / 节点（写了这份配置才算开，enabled: false 显式关掉）：enabled 开关、scope（confirm() 不带参数时的缺省范围：'lines' 只删选中的回线 / 'groups' 连所在分组 / 'channels' 连整条通道，缺省 'lines'）、confirm（不写停在 pending 等使用方裁决 / false 直接删 / 函数自行裁决，支持 Promise）。Delete 键与 requestRemove() 都先出一份「要删什么、连带什么」的载荷，确认之后才动数据；删节点会连挂在它身上的线路与被它锚定的通道一起删，见「删除（remove）」" },
 	{ name: "merge", type: "GisViewMergeOptions", defaultValue: "缺省关", doc: "合并节点（写了这份配置才算开，enabled: false 显式关掉）：enabled 开关、trigger 触发时机（'collision' 两个节点半径相碰 / 'center' 拖动节点中心进入目标节点区域）、distance 额外像素容差、confirm（不写停在 pending 等使用方裁决 / false 直接合并 / 函数自行裁决）、channelGroups（'keep' 各自保留分组 / 'merge' 合成一个分组）、maxKeys 选哪些字段取双方最高、createItem 定制合并结果，见「节点合并」" },
-	{ name: "minScale", type: "number", defaultValue: "0.002 / 20000", doc: "缩放范围（像素 / 世界单位）" },
-	{ name: "maxScale", type: "number", defaultValue: "0.002 / 20000", doc: "缩放范围（像素 / 世界单位）" },
+	{ name: "minScale", type: "number", defaultValue: "0.002 / 1000000000", doc: "缩放范围（像素 / 世界单位）；缺省上限足够覆盖经纬度等小量纲数据，显式值仍优先" },
+	{ name: "maxScale", type: "number", defaultValue: "0.002 / 1000000000", doc: "缩放范围（像素 / 世界单位）；缺省上限足够覆盖经纬度等小量纲数据，显式值仍优先" },
 	{ name: "fitPadding", type: "number", defaultValue: "48", doc: "适应视图时四周留白（CSS 像素）；留白比画布还大时按「内容至少留 48px」反过来压留白，不会把内容挤成一个点" },
 	{ name: "fitOnInit", type: "boolean", defaultValue: "true", doc: "首次拿到数据时自动适应视图；配了 initialView 时以它为准（false 只关掉「适应」，initialView 仍然生效，见「初始视图」）" },
 	{ name: "center", type: "GisViewCoordinate", defaultValue: "无", doc: "首屏中心 [x, y] / { x, y }，是 initialView.center 的顶层简写；显式给出非空 initialView 时以那一份为准" },
@@ -459,7 +475,7 @@ export const API_OPTIONS = [
 	{ name: "statsInterval", type: "number", defaultValue: "250", doc: "onStats 的最小间隔（毫秒），0 表示每帧都发" },
 	{ name: "idleTimeout", type: "number", defaultValue: "0（关闭）", doc: "用户操作空闲阈值（毫秒）：根节点上这么久没有指针 / 滚轮 / 键盘活动就发一次 onIdle / idle；每个空闲段只触发一次，恢复操作后重新计时" },
 	{ name: "renderEmitInterval", type: "number", defaultValue: "400", doc: "onRender 的节流间隔（毫秒），0 与 onStats 同拍（再配上 statsInterval: 0 就是每帧一条）" },
-	{ name: "plugins", type: "GisViewPlugin[]", defaultValue: "[]", doc: "插件：(view, context) => hook，返回的 destroy 在实例销毁时倒序回调，见「插件」" },
+	{ name: "plugins", type: "GisViewPlugin[]", defaultValue: "[]", doc: "插件：(view, context) => hook；context 提供 signal / 自动清理，返回的 destroy 在实例销毁时倒序回调，见「插件」" },
 	{ name: "zoomStep", type: "number", defaultValue: "1.4", doc: "zoomIn() / zoomOut() 的步进倍率" },
 	{ name: "width", type: "number | string", defaultValue: "容器尺寸", doc: "画布尺寸，数字按 CSS 像素处理" },
 	{ name: "height", type: "number | string", defaultValue: "容器尺寸", doc: "画布尺寸，数字按 CSS 像素处理" },

package/docs/demos/demos.js

@@ -29,16 +29,24 @@ export const DEMO_GROUPS = [
 ]
 
 export const DEMOS = [
-	{
-		id: 'basic',
-		title: '基础视图',
-		group: 'basic',
-		blurb: '点 / 线 / 通道最少的起手式：一份数据进来、相机出去，拾取与读数都摆在台面上。',
-		doc: DOC_GUIDE,
-		component: () => import('./BasicDemo.vue')
-	},
-	{
-		id: 'labels',
+	{
+		id: 'basic',
+		title: '基础视图',
+		group: 'basic',
+		blurb: '点 / 线 / 通道最少的起手式：一份数据进来、相机出去，拾取与读数都摆在台面上。',
+		doc: DOC_GUIDE,
+		component: () => import('./BasicDemo.vue')
+	},
+	{
+		id: 'background',
+		title: '背景与网架',
+		group: 'basic',
+		blurb: '先铺网架再添加图片或 GeoJSON：组件内置背景编辑器接管拖动、四角 / 八向缩放与可选旋转；锁比例时四角等比缩放，解锁后八个缩放手柄，开启旋转再多一个顶部旋转点。编辑框颜色、线宽、虚线、手柄尺寸与形状可经 beginBackgroundEdit / updateBackgroundEdit 现场调整；背景编辑模式锁住网架交互但保留滚轮整体缩放，也能一键隐藏或压淡网架。',
+		doc: DOC_VIEW,
+		component: () => import('./BackgroundDemo.vue')
+	},
+	{
+		id: 'labels',
 		title: '标签交互',
 		group: 'interact',
 		blurb: '标签点选 / 拖拽 / 右键菜单（编辑、改位置、删除），以及用一套 API 给选中集批量加标签。',
@@ -63,12 +71,12 @@ export const DEMOS = [
 	},
 	{
 		id: 'style',
-		title: '样式与规则',
-		group: 'style',
-		blurb: '按属性配色、规则 JSON 现场改、逐点样式与选中高亮的优先级，改完立刻重画。',
-		doc: DOC_GUIDE,
-		component: () => import('./StyleDemo.vue')
-	},
+		title: '样式与规则',
+		group: 'style',
+		blurb: '按属性配色、规则 JSON 现场改、单 / 多节点与线路补丁、详情查询，以及悬停 / 选中 / 多选 / 框选 / 级联始终压过规则的交互优先级。',
+		doc: DOC_GUIDE,
+		component: () => import('./StyleDemo.vue')
+	},
 	{
 		id: 'hover-tooltip',
 		title: '悬停与提示',
@@ -81,7 +89,7 @@ export const DEMOS = [
 		id: 'channel',
 		title: '通道与数据',
 		group: 'data',
-		blurb: '通道分组拆合、拐点增删拖，以及整份 groups / path 覆盖的假接口联调（版本号、opId 幂等、失败重试）；另带定向更新与整份数据导出 / 回灌。',
+		blurb: '通道分组拆合、拐点增删拖、通道内指定回线显隐、节点 / 线路 / 通道 / 分组单条与批量显隐，以及隐藏回线车道 preserve / center 对照；另带整份 groups / path 覆盖的假接口联调与数据导出 / 回灌。',
 		doc: DOC_API,
 		component: () => import('./ChannelDemo.vue')
 	},
@@ -201,7 +209,7 @@ export const DEMOS = [
 		id: 'full',
 		title: '综合示例（全功能）',
 		group: 'full',
-		blurb: '所有面板都在这一个演示里：十万级数据、热力图、鹰眼图、通道编辑、历史与快捷键。',
+		blurb: '所有面板都在这一个演示里：十万级数据、热力图、鹰眼图、通道编辑、历史与快捷键；框选还能保留矩形、框内拖动整组平移，并切到 DOM 框演示线型 / 圆角 / className。',
 		doc: { href: docsBase, label: '文档中心' },
 		component: () => import('./GisViewDemo.vue')
 	}

package/docs/demos/gis-view-demo/demo.css

@@ -1228,3 +1228,79 @@
 .gis-view-demo .gis-demo-events span {
 	font-variant-numeric: tabular-nums;
 }
+
+/* 保留框的 className 演示：引擎负责位置 / 填充 / 边框，使用方只接管额外外观 */
+.gis-view-demo .gis-view__selection-box.demo-retained-box {
+	box-shadow: 0 10px 28px rgb(47 111 208 / 20%);
+}
+
+.gis-view-demo .gis-view__selection-box.demo-retained-box::after {
+	position: absolute;
+	top: -24px;
+	right: -1px;
+	padding: 3px 7px;
+	border-radius: 6px;
+	background: #2f6fd0;
+	color: #fff;
+	content: '保留框 · 框内拖动';
+	font-size: 11px;
+	font-weight: 600;
+	letter-spacing: 0.02em;
+	white-space: nowrap;
+}
+
+/* visualMap 完全自定义渲染：图例根节点只负责定位，内容与交互全部由 render(context) 接管 */
+.gis-view-demo .demo-visual-map-custom {
+	display: flex;
+	flex-direction: column;
+	gap: 7px;
+	min-width: 190px;
+}
+
+.gis-view-demo .demo-visual-map-custom__readout {
+	color: #526b8d;
+	font-size: 11px;
+	font-variant-numeric: tabular-nums;
+}
+
+.gis-view-demo .demo-visual-map-custom__actions {
+	display: flex;
+	flex-wrap: wrap;
+	gap: 4px;
+}
+
+.gis-view-demo .demo-visual-map-custom__piece {
+	display: inline-flex;
+	align-items: center;
+	gap: 5px;
+	margin: 0;
+	padding: 3px 6px;
+	border: 1px solid rgb(31 53 80 / 18%);
+	border-radius: 4px;
+	background: #fff;
+	color: #1f3550;
+	font: inherit;
+	font-size: 11px;
+	cursor: pointer;
+}
+
+.gis-view-demo .demo-visual-map-custom__piece:hover {
+	border-color: rgb(47 120 183 / 45%);
+	background: rgb(47 120 183 / 8%);
+}
+
+.gis-view-demo .demo-visual-map-custom__piece:focus-visible {
+	outline: 2px solid rgb(47 120 183 / 55%);
+	outline-offset: 1px;
+}
+
+.gis-view-demo .demo-visual-map-custom__piece[aria-pressed='false'] {
+	opacity: 0.46;
+}
+
+.gis-view-demo .demo-visual-map-custom__swatch {
+	width: 10px;
+	height: 10px;
+	flex: none;
+	border-radius: 2px;
+}