gis-view-webgl2 0.1.11 → 0.1.13

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

@@ -34,6 +34,7 @@
 | `lineStyle` | `GisViewLineStyle` | 见下 | 线的默认样式，可被单条线覆盖；运行时按字段合并用 `updateLineStyle(patch)` |
 | `pointRules` / `lineRules` | `GisViewPointRule[]` / `GisViewLineRule[]` | `[]` | 批量样式规则：按属性给点 / 线批量配色、改大小、换符号，见「批量样式规则」 |
 | `heatmap` | `GisViewHeatmap \| null` | 无 | 热力图：按业务字段的数值到渐变色带上取颜色，并可按同一个值缩放节点大小 / 线宽，作用对象可选节点 / 线路 / 通道；不配（或 `null`）就是关的，见「热力图」 |
+| `visualMap` | `GisViewVisualMap \| null` | 无 | 图例：参考 ECharts `visualMap`，把热力图的色带画成带刻度的连续尺（`ruler` / `continuous`）或分段色块（`piecewise`）。不配 / `null` / `enabled: false` 时零 DOM；默认跟随 `heatmap` 的字段、自动值域与颜色，也能独立给字段 / 值域 / 颜色 / 外部容器。不写 `target` 时展示值域取第一类有数值的启用目标，交互门控覆盖 `heatmap` 的全部启用目标；显式写才限定为一类，见「图例（visualMap）」 |
 | `effects` | `GisViewEffectsInput` | 关 | 动画效果（全局缺省）：线路上的跑动图标（`line`，ECharts `lines.effect` 那一类）与节点上的扩散涟漪（`point`，`effectScatter` 那一类），逐要素用 `points[].effect` / `lines[].effect` 覆盖；没配就是关的，但「只在数据里逐条配了 `effect`」的场景照样会动。`false` 或 `{ enabled: false }` 是**一处关掉**（谁都别动）；运行时有 `updateOptions({ effects })` / `getEffects()` / `getLineEffects()`，见「动画效果（effects）」 |
 | `lineDirection` | `GisViewLineDirectionInput` | 关（`null`） | 线路方向箭头（全局缺省）：沿线摆一串静态箭头，朝向跟着线路切向走（起点 / `from` 那一端 → 终点，`reverse` 指回上游），按弧长等分、缺省每条线只在中点一个；逐条线路用 `lines[].direction` 覆盖，写法与 `effects` 同构（`true` 用全局、对象逐字段覆盖、`false` / `null` 关掉），见「线路方向箭头（lineDirection）」 |
 | `prebake` | `GisViewPrebakeOptions \| true` | 关 | 贴图符号预热：把「这次画面会出现什么」提前告诉组件 —— 两种写法：`combos` 逐组合（精确，`getSymbolCombos()` 收出来的那份）/ `symbols × pointColors × sizes` 与 `lineColors × 线路动画图标` 全排列（省事，颜色与尺寸由同一个字段决定时会多烤很多）—— 第一帧之前就烤好，画到它们时命中的是现成的贴图（省掉解码 + 光栅化那一下）；组合数与数据量无关，不配就是从前那条按需路径。读数 `getPrebake()` / `getSymbolCombos()`、手动再烤一遍 `runPrebake()`，见「贴图符号预热（prebake）」 |
@@ -55,15 +56,18 @@
 | `lineMultiSelectStyle` | `GisViewLineStyle` | 无 | 多选命中时的线样式，缺省与 `lineSelectStyle` 一致，单条线可用 `multiSelectStyle` 覆盖；框选出来的线路仍走 `lineSelectStyle`（线路没有单独的框选样式） |
 | `defaultHighlight` | `boolean` | `false` | 没有配置状态样式时是否仍用尺寸 / 宽度增幅与强调环画出内置强调；默认 `false`（不配样式就不改变外观），设为 `true` 可退回旧行为 |
 | `pointSizeScale` / `lineWidthScale`、`pointZoomScale` / `lineZoomScale`、`zoomBaseScale` | `number` | `1` / `0` | 两组系数各管一件事，不重复：`pointSizeScale` / `lineWidthScale` 是与地图无关的整体放大（常数倍数，屏幕上的大小因此恒定），`pointZoomScale` / `lineZoomScale` 是「跟随地图缩放」的指数（0 表示不跟随，1 表示与地图同倍率放大，0.5 是地图放大 4 倍、要素放大 2 倍），绘制尺寸是两者相乘；`zoomBaseScale` 是联动基准，缺省取首次适应视图时的比例 |
-| `fitSpacing` | `boolean \| GisViewFitSpacingOptions` | 关 | 适应视图的节点间距兜底：`true` 用最小中心距模式（默认 `24` CSS 像素）；对象在 `minDistance` / `maxDistance` 中二选一，同时给出时只启用 `maxDistance`，`maxZoom` 是相对普通适应比例的上限（`0` 表示不限）；只在首次默认适应与 `fitView()` 生效，远处孤立点允许落到视口外，见「适应视图的节点间距（fitSpacing）」 |
+| `fitSpacing` | `boolean \| GisViewFitSpacingOptions` | 关 | 适应视图的节点间距兜底：`true` 把最近节点中心距精确设为 `24` CSS 像素；对象在 `minDistance`（精确屏距，可放大也可缩小）/ `maxDistance`（最远距离上限，只压低比例）中二选一，同时给出时只启用 `maxDistance`；`maxZoom` 仅为旧配置兼容保留，不再限制距离；只在首次默认适应与 `fitView()` 生效，远处孤立点允许落到视口外，见「适应视图的节点间距（fitSpacing）」 |
 | `boxSelect` | `boolean` | `false` | 是否允许按住框选快捷键（`shortcuts.boxSelect`，默认 Shift）拖动鼠标框选要素；**缺省关**，写 `boxSelect: true` 或 `features: { boxSelect: true }` 才开。框选默认只收节点，`selectionKinds` 可把线路 / 通道也纳入 |
 | `multiSelect` | `boolean` | `false` | 多选开关：打开后不用按修饰键，直接单击节点 / 线路就取反累加选中（与按住 `shortcuts.multiSelect` 点击同一套行为、同一个 `multiSelectStyle`；取反那一下不经过 `onClick`，`onSelectChange.action.type` 是 `toggleSelect`）；**缺省关**，关着时多选走框选（`boxSelect`）与按住多选快捷键（默认 Ctrl / ⌘）。运行时 `updateOptions({ multiSelect })` 切换只重画一帧、不重排场景 |
+| `toggleSelect` | `boolean` | `false` | 再次选中即取消：打开后普通单击已选中的节点 / 线路 / 通道会取消，`selectTrigger: 'dblClick'` 下再次双击取消，Ctrl / ⌘ 先选中后再普通单击也取消；取反时 `onClick.action.type` 与 `onSelectChange.action.type` 都是 `toggleSelect`。缺省关，运行时 `updateOptions({ toggleSelect })` 只重画一帧、不重排场景，见「选中与拐点」 |
 | `selectTrigger` | `'click' \| 'dblClick'` | `'click'` | 选中触发方式：`click` 第一次单击就改选中集；`dblClick` 第一下只派发 `onClick`，等双击判定命中的第二下才改选中集，并同时派发 `onClick` 与 `onDblClick`。Ctrl / ⌘ 多选与 `multiSelect` 在双击模式下同样等第二下才取反。运行时走 `updateOptions({ selectTrigger })`，只重画一帧、不重排场景 |
 | `selectionKinds` | `GisViewSelectionKindsInput` | 无（框选只收节点；Ctrl 多选收节点 / 线路 / 通道） | 框选与 Ctrl / 多选点击的类型过滤：`'point'` 节点、`'line'` 通道外的独立线路、`'channel'` 通道回线；另有 `'lineEndpoints'` / `'channelEndpoints'`，只在框选时要求线路 / 通道两端节点都在框内。可写数组任意组合，`'all'` / `true` 全开，`false` / `null` 全关。通道回线只归 `channel` 管，通道外的线路只归 `line` 管；通道回线仍按 `channelSelectMode` 摊开。不写时保留旧口径；普通单选与 `select` / `selectFeatures` 不受它限制。运行时走 `updateOptions({ selectionKinds })`，见「框选」与「选择类型过滤」 |
-| `selectionBoxStyle` | `GisViewSelectionBoxStyle` | 蓝底 0.16 透明 + 1px 蓝框 | 框选矩形的填充与边框：`fill`、`fillOpacity`、`stroke`、`strokeWidth` |
+| `selectionBoxStyle` | `GisViewSelectionBoxStyle` | 蓝底 0.16 透明 + 1px 蓝框 | 框选矩形的样式：`fill` / `fillOpacity` / `stroke` / `strokeWidth`，以及 DOM 渲染用的 `render: 'div'` / `className` / `borderStyle` / `radius`；canvas 模式不画线型与圆角，见「框选」 |
+| `selectionBoxPersistent` | `boolean` | `false` | 框选结束后是否保留选框：打开后拖动保留框会整组平移框内选中节点，线路与通道跟随；选中集变化、清空、关闭开关或调用 `clearSelectionBox()` 时收起。要用它同时打开 `boxSelect` 和 `draggable`，见「框选」的「保留框与整组拖动」 |
 | `selectionOnTop` | `boolean` | `true` | 选中的节点 / 拖动中的整组 / 待确认合并的目标节点，以及选中线路所在的整条通道，是否画在所有要素之上（与 `zIndex` 无关），见「选中 / 拖动的层级」 |
 | `channelSelectMode` | `'line' \| 'group' \| 'channel'` | `'line'` | 通道选中模式：点中通道里的一条回线时选中什么 —— `'line'` 只选这一条、`'group'` 连它所在的分组一起、`'channel'` 整条通道（所有分组的回线）；通道以外的线路永远只选自己。普通点选与 Ctrl / ⌘ + 点击加点共用这一档高亮范围；Ctrl / ⌘ + 点击在 `group` / `channel` 下按整批取反；切换走 `updateOptions({ channelSelectMode })`，只重画一帧、不重排场景，见「通道选中模式」 |
 | `channelWaypointDragMode` | `'parallel' \| 'vertex'` | `'parallel'` | 分组拐点拖动模式：`'parallel'` 沿用共用骨架 + 平行偏移（和原有逻辑一致），`'vertex'` 只平移当前分组同一 `pathIndex` 的拐点，其他拐点与分组不动；普通线路始终只动自己。`vertex` 的结果写进 `groups[].waypointOffsets`，切换走 `updateOptions({ channelWaypointDragMode })`，下一次拖动生效，见「分组拐点拖动模式」 |
+| `channelHiddenLineLayout` | `'preserve' \| 'center'` | `'preserve'` | 隐藏部分回线 / 分组后车道怎么排：`'preserve'` 保留原车道槽位，剩余回线不挪位；`'center'` 只把当前可见回线按原顺序压成连续槽位，再在通道宽度内重新居中。运行时走 `updateOptions({ channelHiddenLineLayout })`，见「隐藏回线后的车道」 |
 | `waypointEditable` | `boolean` | `false` | 是否允许编辑线路拐点（按住加点快捷键 `shortcuts.addWaypoint`（默认 Ctrl / ⌘）+ 点击添加、拖动移动、双击或删除快捷键删除），单条线可用 `waypointEditable` 覆盖；**缺省关**，写 `waypointEditable: true` 或 `features: { waypoint: true }` 才开。`false`（以及 `features: { waypoint: false }`）会同时关闭新增、移动与删除，没有只关其中一项的细分开关；`shortcuts.addWaypoint` 仍只决定加点的组合键 |
 | `waypointVisibility` | `'selected' \| 'always'` | `'selected'` | 拐点显示时机：`selected` 只显示选中线路（以及刚加过拐点的线路）的拐点，`always` 全部显示 |
 | `waypointStyle` / `waypointSelectStyle` | `GisViewPointStyle` | 无 | 拐点（线路 `path` 的中间顶点）的默认 / 选中样式，**支持配置**：字段与节点样式同款；缺省是白底蓝圈的 9px 圆点，`waypointSelectStyle` 没配时选中拐点用内置强调环，见「线路拐点」的「拐点样式」小节 |
@@ -71,6 +75,9 @@
 | `gridColor` | `string` | `rgba(120, 150, 190, 0.32)` | 网格颜色 |
 | `gridSize` | `number` | `96` | 网格线的屏幕目标间距，实际步长吸附到 1 / 2 / 5 × 10^n |
 | `showGrid` | `boolean` | `false` | 是否绘制网格：与其它功能开关同一条口径，**缺省关**，写 `showGrid: true` 才画 |
+| `networkVisible` | `boolean` | `true` | 网架整体显隐：`false` 时节点、线路、通道、装饰、动画、标签与框选框一起不画，只保留背景、网格与自定义 WebGL 层；数据、选中与历史都不动，拾取 / 框选 / `queryRect` 也不再命中网架，适合先铺网架再添加背景 |
+| `networkOpacity` | `number` | `1` | 网架整体不透明度（夹在 0 ~ 1）：在每类要素自身 `opacity` 之后再乘一层，节点、线路、通道、装饰、动画与标签一起变淡，背景不受影响。`0` 只是画面上看不见，拾取仍按网架存在；要完全收起请用 `networkVisible: false` |
+| `backgroundEditing` | `boolean` | `false` | 背景编辑模式：`true` 时节点、线路、通道的悬停、点击、选中、拖拽、拐点编辑、框选、右键与数据快捷键全部停用，仍保留滚轮缩放与 `fitView`，方便让网架和背景一起缩放后只移动 / 旋转 / 缩放背景；缺省 `false`，可用 `updateOptions()` 随时开关 |
 | `interactive` | `boolean` | （缺省全关） | 查看类交互的「详细配置手动打开」写法：写 `true` 打开拖拽平移 / 滚轮缩放 / 右键回调（等价 `pan` / `zoom` / `contextMenu` 三个开关），不写就是全关 |
 | `preventContextMenu` | `boolean` | `true` | 组件接住右键时是否收掉浏览器的系统菜单（`contextmenu` 的默认行为）：`contextMenu` 开着（或 `interactive: true` / `features: 'view'`）时组件才接右键，接住时一律 `preventDefault()`，点 / 线 / 空白 / 通道都一样；想让系统菜单自己弹就写 `false`（`onContextMenu` 照常发）。右键整个不接时（`contextMenu` 缺省关）系统菜单自然照弹 |
 | `clickable` | `boolean` | （缺省全关） | 查看类交互的「详细配置手动打开」写法：写 `true` 打开悬停高亮与点击选中（等价 `hover` / `select` 两个开关），要素自身可用 `clickable: false` 逐个关掉 |
@@ -81,7 +88,7 @@
 | `copy` | `GisViewCopyOptions` | 缺省关 | 复制节点（**写了这份配置才算开**，`enabled: false` 显式关掉）：`enabled` 开关、`offset` 落点偏移（默认 `[28, 24]` 像素）、`autoCommit`（交互入口落地前是否自动确认：不写就是落地，`false` 停在预览态等 `commitPointCopy()` / 载荷里的 `payload.commit()`）、`idPrefix`（默认 `copy-`）、`createId` / `createItem` 定制复制品，见「节点复制」 |
 | `remove` | `GisViewRemoveOptions` | 缺省关 | 删除选中的拐点 / 线路 / 节点（**写了这份配置才算开**，`enabled: false` 显式关掉）：`enabled` 开关、`scope`（`confirm()` 不带参数时的缺省范围：`'lines'` 只删选中的回线 / `'groups'` 连所在分组 / `'channels'` 连整条通道，缺省 `'lines'`）、`confirm`（不写停在 `pending` 等使用方裁决 / `false` 直接删 / 函数自行裁决，支持 Promise）。Delete 键与 `requestRemove()` 都先出一份「要删什么、连带什么」的载荷，确认之后才动数据；删节点会连挂在它身上的线路与被它锚定的通道一起删，见「删除（remove）」 |
 | `merge` | `GisViewMergeOptions` | 缺省关 | 合并节点（**写了这份配置才算开**，`enabled: false` 显式关掉）：`enabled` 开关、`trigger` 触发时机（`'collision'` 两个节点半径相碰 / `'center'` 拖动节点中心进入目标节点区域）、`distance` 额外像素容差、`confirm`（不写停在 `pending` 等使用方裁决 / `false` 直接合并 / 函数自行裁决）、`channelGroups`（`'keep'` 各自保留分组 / `'merge'` 合成一个分组）、`maxKeys` 选哪些字段取双方最高、`createItem` 定制合并结果，见「节点合并」 |
-| `minScale` / `maxScale` | `number` | `0.002` / `20000` | 缩放范围（像素 / 世界单位） |
+| `minScale` / `maxScale` | `number` | `0.002` / `1000000000` | 缩放范围（像素 / 世界单位）；缺省上限足够覆盖经纬度等小量纲数据，显式值仍优先 |
 | `fitPadding` | `number` | `48` | 适应视图时四周留白（CSS 像素）；留白比画布还大时按「内容至少留 48px」反过来压留白，不会把内容挤成一个点 |
 | `fitOnInit` | `boolean` | `true` | 首次拿到数据时自动适应视图；配了 `initialView` 时以它为准（`false` 只关掉「适应」，`initialView` 仍然生效，见「初始视图」） |
 | `center` | `GisViewCoordinate` | 无 | 首屏中心 `[x, y]` / `{ x, y }`，是 `initialView.center` 的顶层简写；显式给出非空 `initialView` 时以那一份为准 |
@@ -91,7 +98,7 @@
 | `statsInterval` | `number` | `250` | `onStats` 的最小间隔（毫秒），`0` 表示每帧都发 |
 | `idleTimeout` | `number` | `0`（关闭） | 用户操作空闲阈值（毫秒）：根节点上这么久没有指针 / 滚轮 / 键盘活动就发一次 `onIdle` / `idle`；每个空闲段只触发一次，恢复操作后重新计时 |
 | `renderEmitInterval` | `number` | `400` | `onRender` 的节流间隔（毫秒），`0` 与 `onStats` 同拍（再配上 `statsInterval: 0` 就是每帧一条） |
-| `plugins` | `GisViewPlugin[]` | `[]` | 插件：`(view, context) => hook`，返回的 `destroy` 在实例销毁时倒序回调，见「插件」 |
+| `plugins` | `GisViewPlugin[]` | `[]` | 插件：`(view, context) => hook`；`context` 提供 signal / 自动清理，返回的 `destroy` 在实例销毁时倒序回调，见「插件」 |
 | `zoomStep` | `number` | `1.4` | `zoomIn()` / `zoomOut()` 的步进倍率 |
 | `width` / `height` | `number \| string` | 容器尺寸 | 画布尺寸，数字按 CSS 像素处理 |
 | `pixelRatio` | `number` | `devicePixelRatio` | 手动指定设备像素比（夹在 0.5 ~ 3）；宿主缩放（CSS `zoom` / `transform: scale`）的比例会乘在它上面，合计夹在 0.5 ~ 4 |
@@ -111,15 +118,15 @@
 | 分组 | 字段 |
 | --- | --- |
 | 总开关与历史 | `features` · `history` |
-| 数据与背景 | `points` · `lines` · `channels` · `pointCluster` · `background` |
-| 通道几何 | `channelWidth` · `channelInset` · `channelNodeWidth` · `channelTangentInset` · `channelMaxGroups` · `channelGroupMaxLines` · `channelSimplify` · `channelDraftStyle` · `channelSelectMode` · `channelWaypointDragMode` |
-| 样式与规则 | `pointStyle` · `lineStyle` · `pointRules` / `lineRules` · `heatmap` · `effects` · `lineDirection` · `prebake` · `label` · `labelOptimize` · `labelRender` · `lineLabel` · `labelStates` · `tooltip` · `pointSizeScale` / `lineWidthScale`、`pointZoomScale` / `lineZoomScale`、`zoomBaseScale` · `cursorStyle` · `gridColor` · `gridSize` · `showGrid` |
-| 状态样式与选中 | `pointHoverStyle` / `pointSelectStyle` · `lineHoverStyle` / `lineSelectStyle` · `pointMultiSelectStyle` / `pointBoxSelectStyle` · `lineMultiSelectStyle` · `defaultHighlight` · `selectionBoxStyle` · `selectionOnTop` · `waypointStyle` / `waypointSelectStyle` |
-| 交互开关 | `boxSelect` · `multiSelect` · `selectTrigger` · `waypointEditable` · `waypointVisibility` · `interactive` · `preventContextMenu` · `clickable` · `draggable` · `liveDrag` · `lineFollowsNode` · `shortcuts` · `copy` · `remove` · `merge` |
+| 数据与背景 | `points` · `lines` · `channels` · `pointCluster` · `background` · `backgroundEditing` |
+| 通道几何 | `channelWidth` · `channelInset` · `channelNodeWidth` · `channelTangentInset` · `channelMaxGroups` · `channelGroupMaxLines` · `channelSimplify` · `channelDraftStyle` · `channelSelectMode` · `channelWaypointDragMode` · `channelHiddenLineLayout` |
+| 样式与规则 | `pointStyle` · `lineStyle` · `pointRules` / `lineRules` · `heatmap` · `effects` · `lineDirection` · `prebake` · `label` · `labelOptimize` · `labelRender` · `lineLabel` · `labelStates` · `tooltip` · `pointSizeScale` / `lineWidthScale`、`pointZoomScale` / `lineZoomScale`、`zoomBaseScale` · `cursorStyle` · `gridColor` · `gridSize` · `showGrid` · `networkVisible` · `networkOpacity` |
+| 状态样式与选中 | `pointHoverStyle` / `pointSelectStyle` · `lineHoverStyle` / `lineSelectStyle` · `pointMultiSelectStyle` / `pointBoxSelectStyle` · `lineMultiSelectStyle` · `defaultHighlight` · `selectionBoxStyle` · `selectionBoxPersistent` · `selectionOnTop` · `waypointStyle` / `waypointSelectStyle` |
+| 交互开关 | `boxSelect` · `multiSelect` · `toggleSelect` · `selectTrigger` · `waypointEditable` · `waypointVisibility` · `interactive` · `preventContextMenu` · `clickable` · `draggable` · `liveDrag` · `lineFollowsNode` · `shortcuts` · `copy` · `remove` · `merge` |
 | 视图与相机 | `minScale` / `maxScale` · `fitPadding` · `fitOnInit` · `center` / `scale` · `initialView` · `zoomStep` |
 | 画质与渲染 | `quality` · `width` / `height` · `pixelRatio` · `maxCanvasPixels` · `antialias` · `interactionThinLines` · `interactionNoMsaa` · `renderer` · `webglLayers` |
 | 大数据（筛选 / 搜索 / 读数） | `denseMode` · `filter` · `filterWorker` · `searchWorker` · `progressiveInit` · `statsInterval` · `idleTimeout` · `renderEmitInterval` |
-| 外部界面与集成 | `minimap` · `plugins` · `ariaLabel` |
+| 外部界面与集成 | `minimap` · `visualMap` · `plugins` · `ariaLabel` |
 
 ### 总开关与历史
 
@@ -222,7 +229,7 @@ const { active, radius } = view.getPointCluster()    // 当前缩放档是否仍
 
 - **类型**：`GisViewBackground`
 - **默认值**：浅色底
-- **说明**：背景层，支持底色、图片与 GeoJSON
+- **说明**：背景层，支持底色、图片与 GeoJSON。图片可用 `image.corners` 指定（含旋转后的）四个角；GeoJSON 可用 `geoJsonStyle.bounds` 把整份底图独立缩放、平移到目标世界矩形，并用 `geoJsonStyle.rotation` 绕目标矩形中心顺时针旋转，原始 GeoJSON 不用改
 - **参考**：见「背景层」一节，子字段在那里的表里逐个展开
 - **示例**：
 
@@ -231,7 +238,11 @@ createGisView(container, {
 	background: {
 		color: '#0d1b2a',
 		image: { src: '/map.png', bounds: [0, 0, 1000, 600] },
-		geoJson: { type: 'FeatureCollection', features: [...] }
+		geoJson: { type: 'FeatureCollection', features: [...] },
+		geoJsonStyle: {
+			bounds: { minX: 0, minY: 0, maxX: 1000, maxY: 600 },
+			rotation: 15
+		}
 	}
 })
 ```
@@ -320,6 +331,25 @@ view.updateOptions({ channelSimplify: false })   // 关闭后全部回线恢复
 - **说明**：分组拐点拖动模式。`'parallel'` 沿用共用骨架 + 平行偏移，拖动时拐角处的相邻顶点可能随 miter 一起微调；`'vertex'` 只把当前分组同一 `pathIndex` 的拐点按相同世界增量平移，组内每条回线都跟着这个序号走，其他拐点与其它分组保持不动。普通线路不受这一项影响；`'vertex'` 的结果写进 `groups[].waypointOffsets`（键按含首尾端点的骨架序号算，只认中间拐点），切换走 `updateOptions({ channelWaypointDragMode })`，下一次拖动生效。切换模式不会清掉已有偏移；要恢复纯平行骨架，重写分组声明并带上当前 `path`、省略 `waypointOffsets`
 - **参考**：见「分组拐点拖动模式（channelWaypointDragMode）」与「分组拐点：把某一组拉走」
 
+#### `channelHiddenLineLayout`
+
+- **类型**：`'preserve' | 'center'`
+- **默认值**：`'preserve'`
+- **说明**：隐藏部分回线或整个分组后的车道排布。`'preserve'` 保留整条通道原来的槽位，隐藏的回线不改变其余回线的位置；`'center'` 只把当前真正可见的回线按声明顺序压成连续槽位，再按通道宽度重新居中，所以两条回线隐藏一条后，剩下那条会落到中线。隐藏分组、逐条 `visible: false`、端点缺失与筛选隐藏都按「当前不可见」参与这一档判断；被 `channelSimplify` 折叠的组不参与车道分配。运行时 `updateOptions({ channelHiddenLineLayout })` 会重算通道车道
+- **参考**：见「09 通道与多回线」的「隐藏回线后的车道（channelHiddenLineLayout）」
+- **示例**：
+
+```js
+createGisView(container, {
+  channels: [{ id: 'c1', lineIds: ['l1', 'l2'] }],
+  channelHiddenLineLayout: 'center'
+})
+
+view.hideFeatures('line', 'l1')                       // 剩下的 l2 重新居中
+view.updateOptions({ channelHiddenLineLayout: 'preserve' }) // 改回保留原车道
+view.showFeatures('line', 'l1')
+```
+
 ### 样式与规则
 
 #### `pointStyle`
@@ -352,14 +382,17 @@ view.updateLineStyle({ width: 3 })
 
 - **类型**：`GisViewPointRule[]` / `GisViewLineRule[]`
 - **默认值**：`[]`
-- **说明**：批量样式规则：按属性给点 / 线批量配色、改大小、换符号，见「批量样式规则」
+- **说明**：批量样式规则：按属性给点 / 线批量配色、改大小、换符号。普通规则只补要素自身没写的字段，但始终高于 `pointStyle` / `lineStyle`；单条规则写 `override: true` 时压过要素自身字段，仍低于状态样式与热力图。见「批量样式规则」
 - **参考**：见「批量样式规则」一节，子字段在那里的表里逐个展开
 - **示例**：
 
 ```js
 createGisView(container, {
 	pointRules: [{ when: { kind: 'station' }, style: { symbol: 'square', color: '#e0653a' } }],
-	lineRules: [{ when: { voltage: { gte: 500 } }, style: { color: '#ff3b30', width: 3 } }]
+	lineRules: [
+		{ when: { voltage: { gte: 500 } }, style: { color: '#ff3b30', width: 3 } },
+		{ when: { status: 'fault' }, override: true, style: { color: '#ff3b30', width: 4 } }
+	]
 })
 ```
 
@@ -375,6 +408,45 @@ createGisView(container, { heatmap: { field: 'load', radius: 26, colors: ['#2f6f
 view.updateOptions({ heatmap: { enabled: false } })   // 关掉回正常配色
 ```
 
+#### `visualMap`
+
+- **类型**：`GisViewVisualMap | null`
+- **默认值**：无
+- **说明**：内置图例。参考 ECharts 的 `visualMap`，把热力图的色带画成带刻度的连续尺（`type: 'ruler'`，`'continuous'` 同义）或分段色块（`type: 'piecewise'`）。配置对象本身就是开关；不写 / `null` / `enabled: false` 时不挂任何 DOM。默认跟随 `heatmap` 的字段、自动值域、色带与透明度。不配 `target` 时不会把门控缩成第一类：展示值域按 `point → line → channel` 取第一个真正有数值的启用目标，选区却门控全部启用目标（同一 `field`）；例如节点缺热力字段、线路 / 通道有值时，图例显示线路 / 通道值域，同时仍能隐藏落选节点、独立线路与通道。显式 `target` 才限定只作用这一类。没有 `heatmap` 也可以按自己的 `field` 扫数据画独立图例。默认只读、不参与画布拾取；写 `interactive: true` 后内置分段点选与连续尺区间拖动，并把当前选区同步到热力层。默认继承主图热力的鹰眼图同步门控，显式 `minimap.heatmap` 仍独立。`outOfRange` 决定落选值怎么处理：`'heatmap'`（缺省）只退热力、网架恢复普通样式；`'network'` 把对应节点 / 独立线路 / 通道从画布、拾取和鹰眼中隐藏；`'none'` 不做内置门控，只保留 `onChange`。三种模式都不删除数据、不改筛选或通道声明。`onChange` 返回当前选择供额外业务联动，`render(context)` 可完全接管图例内容；只改图例本身时只重画这一层，不触发无关场景重排。读数用 `getVisualMap()`，根节点用 `getVisualMapElement()`
+- **参考**：见「图例（visualMap）」一节，子字段、`ruler` / `piecewise` 写法、交互 / 自定义渲染、外部容器与性能说明都在那里
+- **示例**：
+
+```js
+const view = createGisView(container, {
+	points,
+	heatmap: { field: 'load', density: false, glow: false },
+	visualMap: {
+		type: 'ruler',
+		interactive: true,
+		outOfRange: 'network',
+		title: '负荷',
+		unit: 'kW',
+		position: 'bottom-left',
+		tickCount: 5,
+		onChange: ({ range, source }) => console.log('区间', range, source)
+	}
+})
+
+// 分段图例：写自己的字段 / 值域也能完全独立于 heatmap
+view.updateOptions({
+	visualMap: {
+		type: 'piecewise',
+		field: 'score',
+		domain: [0, 100],
+		pieces: [
+			{ lt: 60, label: '低' },
+			{ gte: 60, lt: 85, label: '中' },
+			{ gte: 85, color: '#dd4b2e', label: '高' }
+		]
+	}
+})
+```
+
 #### `effects`
 
 - **类型**：`GisViewEffectsInput`
@@ -421,7 +493,7 @@ view.updateOptions({ prebake: { combos: view.getSymbolCombos().combos } })
 
 - **类型**：`GisViewLabelOptions | GisViewLabelOptions[]`
 - **默认值**：无
-- **说明**：节点标签：内容 / 位置 / 显隐 / 避让 / 层级 / 缩放字号 / 拖动与编辑都可配，**写数组就是同一个节点上多条标签**，与 `lineLabel` 共用一套避让网格。`zIndex` 显式指定标签层级；`followNodeZIndex: true` 时取节点样式链（节点自身 > 规则 > `pointStyle`）的 `zIndex`，并让更高层节点图标压住这条标签；`zoomScale` 是字号随地图缩放的指数（`0` 固定屏幕字号、`1` 与地图同倍率），见「节点标签」
+- **说明**：节点标签：内容 / 位置 / 显隐 / 避让 / 层级 / 缩放字号 / 拖动与编辑都可配，**写数组就是同一个节点上多条标签**，与 `lineLabel` 共用一套避让网格。`zIndex` 显式指定标签层级；`followNodeZIndex: true` 时取节点样式链（`override` 规则 > 节点自身 > 普通规则 > `pointStyle`）的 `zIndex`，并让更高层节点图标压住这条标签；`zoomScale` 是字号随地图缩放的指数（`0` 固定屏幕字号、`1` 与地图同倍率），见「节点标签」
 - **参考**：见「节点标签」一节，子字段在那里的表里逐个展开
 
 #### `labelOptimize`
@@ -490,7 +562,7 @@ view.clearGraphics()
 
 - **类型**：`boolean | GisViewFitSpacingOptions`
 - **默认值**：关
-- **说明**：适应视图的节点间距兜底。普通适应按数据包围盒铺满，远处多一个孤立点就会把比例压小、主体节点挤成一团；打开后先按普通规则算出适应比例，再用**可见节点最近的正中心距**反推更高的比例（最近距离达到 `minDistance` 为止）。`maxDistance` 是另一种距离模式：最远一对节点的屏幕距离超过上限就把比例压低，适合只回显少量场站等稀疏数据。`minDistance` / `maxDistance` **二选一**，同时给出时只按 `maxDistance` 计算，`minDistance` 不参与，不会在一次适应里同时放大和压低。**只改比例，不改中心**：相机中心仍取普通适应的包围盒中心，最近节点对并列时不挑中点、不跳视点。`maxZoom` 是相对普通适应比例的上限，`0` 表示不限；最后仍受 `minScale` / `maxScale` 约束。重合坐标不算有效间距，少于两个不同位置时不调整。显式写了 `initialView.scale` / `zoom` 时以显式值为准；运行时 `updateOptions` 不会当场移动相机，需要再调 `fitView()`
+- **说明**：适应视图的节点间距兜底。距离先按节点中心的世界坐标计算 `d_world = sqrt(dx² + dy²)`，再乘当前 `camera.scale` 得到 CSS 像素。`minDistance` 是**精确模式**：按 `targetScale = minDistance / 最近正 d_world` 直接反推比例，普通适应得到的节点更疏时会缩小、更密时会放大，所以把 `minDistance` 改小也会真的缩小画面；不再受普通适应比例或 `maxZoom` 截断。`maxDistance` 是**上限模式**：按 `min(普通适应比例, maxDistance / 最远 d_world)` 压低比例，只会让画面更小，适合只回显少量场站等稀疏数据。最近距离取不同坐标节点的最小正距离（重合点不算），最远距离用凸包直径求真正的远点对。`minDistance` / `maxDistance` **二选一**，同时给出时只按 `maxDistance` 计算，不会在一次适应里同时放大和压低。**只改比例，不改中心**：相机中心仍取普通适应的包围盒中心，最近节点对并列时不挑中点、不跳视点。最后仍受 `minScale` / `maxScale` 夹取（显式把 `maxScale` 压小时，任何间距目标都会停在那条上限）；`maxZoom` 仅为兼容旧配置保留，不再影响两种距离模式。可用 `getPointSpacing()` 读当前可见节点，或用 `getPointsSpacing(refs)` 读指定节点组。显式写了 `initialView.scale` / `zoom` 时以显式值为准；运行时 `updateOptions` 不会当场移动相机，需要再调 `fitView()`
 - **参考**：见「适应视图的节点间距（fitSpacing）」一节
 
 #### `cursorStyle`
@@ -518,6 +590,53 @@ view.clearGraphics()
 - **默认值**：`false`
 - **说明**：是否绘制网格：与其它功能开关同一条口径，**缺省关**，写 `showGrid: true` 才画
 
+#### `networkVisible`
+
+- **类型**：`boolean`
+- **默认值**：`true`
+- **说明**：网架整体显隐。写 `false` 时节点、线路、通道、装饰、动画、标签与框选框一起跳过绘制，只保留背景、网格和 `webglLayers`；`pick` / `pickAt` / `nearestPointsAt` / `nearestLineAt` / 框选 / `queryRect` 也不再命中网架。它只改展示，不改数据、选中、历史或相机；适合先渲染网架、再添加并拖动背景，调好背景后写回 `true`
+- **参考**：见「背景层」一节；完整交互见演示「背景与网架」（`?demo=background`）
+- **示例**：
+
+```js
+view.updateOptions({ networkVisible: false })  // 一键完全隐藏网架，背景与网格照常
+view.updateOptions({ networkVisible: true })   // 恢复节点、线路、通道、动画与标签
+```
+
+#### `networkOpacity`
+
+- **类型**：`number`
+- **默认值**：`1`
+- **说明**：网架整体不透明度，夹在 0 ~ 1。在每类要素自身 `opacity` 之后再乘一层，节点、线路、通道、装饰、动画与标签一起变淡，背景、网格和 `webglLayers` 不受影响；适合压淡网架以突出底图。`0` 只让画面看不见，拾取仍按网架存在；要完全隐藏请同时用 `networkVisible: false`
+- **参考**：见「背景层」一节与演示「背景与网架」（`?demo=background`）
+- **示例**：
+
+```js
+view.updateOptions({ networkOpacity: 0.3 })    // 网架压到 30%，背景保持原样
+view.updateOptions({ networkOpacity: 1 })      // 恢复逐要素原始不透明度
+```
+
+#### `backgroundEditing`
+
+- **类型**：`boolean`
+- **默认值**：`false`
+- **说明**：背景编辑模式。打开后节点、线路、通道的悬停、点击、选中、拖拽、拐点编辑、框选、右键与数据快捷键全部停用，鼠标光标固定为普通箭头；滚轮缩放与 `fitView` 仍可用，因此网架和背景会作为一个整体放大缩小。这个配置只负责锁住网架交互，不改背景、数据、选中、历史或相机，键盘快捷键里仅保留 `shortcuts.fitView`。要让组件同时提供移动、四角 / 八向缩放与可选旋转，用内置背景编辑器：`beginBackgroundEdit()` 会自动打开本项，`updateBackgroundEdit()` 改配置或几何，`getBackgroundEdit()` 读当前状态，`endBackgroundEdit()` 退出并恢复进入前的值。没有编辑器时仍可像以前一样由使用方界面自行写回 `updateBackground()`
+- **参考**：见「视图与筛选」的「背景层」与演示「背景与网架」（`?demo=background`）
+- **示例**：
+
+```js
+// 内置编辑器：自动打开 backgroundEditing，锁比例四角、解锁八向、可选旋转
+view.beginBackgroundEdit({ aspectLocked: true, rotation: true, fitView: true })
+view.updateBackgroundEdit({ rotation: false, style: { color: '#f97316', lineWidth: 2, dashed: false } })
+const state = view.getBackgroundEdit()             // { center, width, height, rotation, handleCount, ... }
+view.endBackgroundEdit()                           // 退出并恢复进入前的 backgroundEditing
+
+// 只锁交互、自己实现编辑界面（背景数据仍由使用方写回）
+view.updateOptions({ backgroundEditing: true })
+view.updateBackground({ geoJson, geoJsonStyle: { bounds, rotation: 15 } })
+view.updateOptions({ backgroundEditing: false })
+```
+
 ### 状态样式与选中
 
 #### `pointHoverStyle` / `pointSelectStyle`
@@ -554,7 +673,7 @@ createGisView(container, {
 
 - **类型**：`boolean | GisViewCascadeHighlightOptions`
 - **默认值**：关
-- **说明**：点击级联高亮，和选中集是两份互不污染的状态。点节点时亮自身、直接相连的线路和另一端节点；点线路 / 通道回线时只亮两端节点。直接选中的节点 / 线路始终走选中样式，只有邻接项套 `pointStyle` / `lineStyle`。变化会通过 `onCascadeHighlight` / `cascadeHighlight` 事件给出，读数用 `getCascadeHighlight()`
+- **说明**：点击级联高亮，和选中集是两份互不污染的状态。点节点时亮自身、直接相连的线路和另一端节点；点线路 / 通道回线时只亮两端节点。直接选中的节点 / 线路始终走选中样式，只有邻接项套 `pointStyle` / `lineStyle`。变化会通过 `onCascadeHighlight` / `cascadeHighlight` 事件给出，读数用 `getCascadeHighlight()`；通过 `toggleSelect` / Ctrl 取反 / `deselect` / `selectFeatures` 的 remove 或清空取消选中时，级联同步收掉
 - **参考**：见「点击级联高亮」一节
 - **子字段**：
 
@@ -608,8 +727,66 @@ createGisView(container, {
 
 - **类型**：`GisViewSelectionBoxStyle`
 - **默认值**：蓝底 0.16 透明 + 1px 蓝框
-- **说明**：框选矩形的填充与边框：`fill`、`fillOpacity`、`stroke`、`strokeWidth`
-- **参考**：见「框选」一节，子字段在那里的表里逐个展开
+- **说明**：框选矩形的样式。`render` 缺省为 `'canvas'`，直接画在 WebGL 里；写 `'div'` 会在画布上方挂一个 DOM 元素，除颜色 / 透明度 / 边框宽度外还支持线型、圆角与自定义类名。DOM 元素带固定类名 `.gis-view__selection-box`，`className` 会追加在它后面；它不接管指针，拖动仍由画布处理
+- **参考**：见「08 选中与拐点」的「框选」与「保留框与整组拖动」
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `fill` | `string` | `#2f6fd0` | 矩形填充色 |
+| `fillOpacity` | `number` | `1` | 再乘到填充色自身透明度上的比例（0 ~ 1） |
+| `stroke` | `string` | `#2f6fd0` | 边框颜色 |
+| `strokeWidth` | `number` | `1` | 边框宽度（CSS 像素）；`0` 不画边框 |
+| `render` | `'canvas' \| 'div'` | `'canvas'` | `'div'` 挂 DOM 元素；`'canvas'` 画进 WebGL，线型恒为实线、圆角恒为 0 |
+| `className` | `string` | 无 | 仅 `div` 模式；追加到 `.gis-view__selection-box`，用来整体覆盖背景 / 边框 / 阴影 |
+| `borderStyle` | `'solid' \| 'dashed' \| 'dotted'` | `'solid'` | 仅 `div` 模式；canvas 模式忽略 |
+| `radius` | `number` | `0` | 仅 `div` 模式；圆角 CSS 像素，负数按 0 处理 |
+
+- **示例**：
+
+```js
+view.updateOptions({
+  boxSelect: true,
+  selectionBoxPersistent: true,
+  selectionBoxStyle: {
+    render: 'div',
+    className: 'my-selection-box',
+    fill: '#eef4ff',
+    fillOpacity: 0.3,
+    stroke: '#f59e0b',
+    strokeWidth: 2,
+    borderStyle: 'dashed',
+    radius: 8
+  }
+})
+```
+
+```css
+/* 自定义类名追加在 .gis-view__selection-box 后面；位置由组件写，外观可整体接管 */
+.gis-view__selection-box.my-selection-box {
+  box-shadow: 0 4px 16px rgb(47 111 208 / 18%);
+}
+```
+
+#### `selectionBoxPersistent`
+
+- **类型**：`boolean`
+- **默认值**：`false`
+- **说明**：框选结束后是否保留选框。打开后，非空框选会留下矩形；在框内按下并拖动一个可拖动的已选节点，会把框内选中的全部节点按同一世界坐标增量平移，绑定线路、通道骨架与回线一起跟随，框本身按屏幕增量同步移动。拖动整框不参与节点合并；在框内按下但不拖动也不会把选中集清掉。需要同时打开 `boxSelect` 与 `draggable`
+- **收起时机**：选中集发生变化（重新框选、点击别的要素、`selectFeatures` / `deselect` 改变集合）、点击空白 / Esc 清空、把本项改回 `false`、实例销毁，或调用 `clearSelectionBox()`。`clearSelectionBox()` 只收矩形、不改选中集；`getSelectionBox()` 读当前矩形（画布 CSS 像素，`{ x, y, width, height }`，没有时为 `null`）
+- **参考**：见「08 选中与拐点」的「保留框与整组拖动」
+- **示例**：
+
+```js
+const view = createGisView(container, {
+  boxSelect: true,
+  draggable: true,
+  selectionBoxPersistent: true
+})
+
+view.selectInBox({ x: 40, y: 40, width: 260, height: 180 })
+console.log(view.getSelectionBox()) // { x: 40, y: 40, width: 260, height: 180 }
+view.clearSelectionBox()            // 只收框；框里的节点仍保持选中
+```
 
 #### `selectionOnTop`
 
@@ -658,6 +835,19 @@ createGisView(container, { multiSelect: true })   // 单击即取反累加，不
 // 按住快捷键的老写法照旧：Ctrl + 点击
 ```
 
+#### `toggleSelect`
+
+- **类型**：`boolean`
+- **默认值**：`false`
+- **说明**：再次选中即取消。打开后，普通单击已选中的节点 / 线路 / 通道回线会把它从选中集移除；按住 Ctrl / ⌘ 先选中，再普通单击同一要素也同样取消。通道回线按 `channelSelectMode` 取消单条 / 整组 / 整条；命中的分组或通道已经完整选中时，即使处于 `line` 模式也整组 / 整条取消，避免只删一条后仍像通道未取消。`selectionKinds` 只约束框选与 Ctrl / 多选，不拦截这里的取消。`selectTrigger: 'click'` 下双击仍按一次操作处理，第一下取反、第二下保持；`selectTrigger: 'dblClick'` 下由第二下取反，再次双击取消。取反生效时 `onClick.action.type` 与 `onSelectChange.action.type` 都是 `'toggleSelect'`，同一次点击产生的级联高亮也一起收掉。与 `multiSelect` 同时打开时沿用多选的累加取反口径；缺省关，运行时可用 `updateOptions({ toggleSelect })` 切换
+- **参考**：见「[08 选中与拐点](08-选中与拐点.md#点击选中与-dblclick)」
+- **示例**：
+
+```js
+createGisView(container, { toggleSelect: true })
+view.updateOptions({ toggleSelect: false })   // 关掉后再次单击保持选中
+```
+
 #### `selectTrigger`
 
 - **类型**：`'click' | 'dblClick'`（也认 `doubleClick` / `double` 两种别名）
@@ -675,7 +865,7 @@ view.updateOptions({ selectTrigger: 'click' })
 
 - **类型**：`GisViewSelectionKindsInput`
 - **默认值**：无（框选只收节点；Ctrl 多选仍收节点 / 线路 / 通道）
-- **说明**：限定框选与 Ctrl（⌘）/ `multiSelect` 点击能选中哪几类要素。`'point'` 是节点、`'line'` 是通道外的独立线路、`'channel'` 是通道回线；`'lineEndpoints'` / `'channelEndpoints'` 是框选专用的另一种口径，要求线路 / 通道自己的两端节点都落在框内，纯 `path`、缺失端点与自环跳过。数组可任意组合，`'all'` / `true` 五档全开，`false` / `null` 全关；新旧线路 / 通道口径并存时取并集。通道回线只受 `channel` 管、通道外的线路只受 `line` 管；选中通道回线时仍按 `channelSelectMode` 决定只选这一条 / 一组 / 整条通道。端点口径不会顺带选中两端节点，也不依赖 `point` 是否开启。**不写时保持旧口径**：框选只收节点，Ctrl / 多选点击收节点与线路；显式写 `selectionKinds` 后框选按完整过滤、Ctrl / 多选点击只认互斥的 `point` / `line` / `channel`。普通单击与 `select` / `selectFeatures` 接口不受限制；`selectInBox(box, { selectionKinds })` 可一次性覆盖。
+- **说明**：限定框选与 Ctrl（⌘）/ `multiSelect` 点击能选中哪几类要素。`'point'` 是节点、`'line'` 是通道外的独立线路、`'channel'` 是通道回线；`'lineEndpoints'` / `'channelEndpoints'` 是框选专用的另一种口径，要求线路 / 通道自己的两端节点都落在框内，纯 `path`、缺失端点与自环跳过。数组可任意组合，`'all'` / `true` 五档全开，`false` / `null` 全关；新旧线路 / 通道口径并存时取并集。通道回线只受 `channel` 管、通道外的线路只受 `line` 管；选中通道回线时仍按 `channelSelectMode` 决定只选这一条 / 一组 / 整条通道。端点口径不会顺带选中两端节点，也不依赖 `point` 是否开启。**不写时保持旧口径**：框选只收节点，Ctrl / 多选点击收节点与线路；显式写 `selectionKinds` 后框选按完整过滤、Ctrl / 多选点击只认互斥的 `point` / `line` / `channel`。普通单击、`toggleSelect` 的再次点击取消与 `select` / `selectFeatures` 接口不受限制；`selectInBox(box, { selectionKinds })` 可一次性覆盖。
 - **参考**：见「08 选中与拐点」的「框选」与「选择类型过滤（selectionKinds）」
 - **示例**：
 
@@ -834,8 +1024,8 @@ view.getChannel('ch-1')            // impact.channelIds 里的 id 按它查通
 #### `minScale` / `maxScale`
 
 - **类型**：`number`
-- **默认值**：`0.002` / `20000`
-- **说明**：缩放范围（像素 / 世界单位）
+- **默认值**：`0.002` / `1000000000`
+- **说明**：缩放范围（像素 / 世界单位）。上限缺省放到足够大，避免经纬度等小量纲数据的 `fitSpacing.minDistance` 被旧上限悄悄截断；显式配置仍按给定值执行
 
 #### `fitPadding`
 
@@ -1106,15 +1296,16 @@ createGisView(container, {
 
 - **类型**：`GisViewPlugin[]`
 - **默认值**：`[]`
-- **说明**：插件：`(view, context) => hook`，返回的 `destroy` 在实例销毁时倒序回调，见「插件」
+- **说明**：插件：`(view, context) => hook`；`context` 提供 `signal` / `onCleanup` / `on` / `registerCommand`，返回的 `destroy` 仍兼容并在实例销毁时倒序回调，见「插件」
 - **参考**：见「插件」一节，子字段在那里的表里逐个展开
 - **示例**：
 
 ```js
 const view = createGisView(container, {
-	plugins: [(view, context) => ({
-		destroy() { /* context.apiVersion 当前为 1 */ }
-	})]
+	plugins: [(view, context) => {
+		context.onCleanup(() => { /* 随插件卸载自动执行 */ })
+		return { destroy() { /* 旧写法仍兼容；context.apiVersion 当前为 1 */ } }
+	}]
 })
 ```
 

package/docs/manual/07-/346/214/207/351/222/210/344/270/216/350/246/201/347/264/240/347/274/226/350/276/221.md

@@ -4,7 +4,7 @@
 
 ## 点击与样式
 
-单击命中要素时会套用选中样式，命中空白处会清空选中；双击在单击之后额外派发 `onDblClick`。**这两件事都缺省关**：`clickable` 没写时点击只发回调（`action.type` 是 `click`）、不改选中集，悬停（`onHover` 与悬停样式）也不重算；写 `clickable: true` / `features: { hover: true, select: true }` 或 `features: 'view'` 才开。样式优先级是 **状态样式 > 要素自身字段 > 全局样式（`pointStyle` / `lineStyle`）> 内置默认值**：
+单击命中要素时会套用选中样式，命中空白处会清空选中；双击在单击之后额外派发 `onDblClick`。**这两件事都缺省关**：`clickable` 没写时点击只发回调（`action.type` 是 `click`）、不改选中集，悬停（`onHover` 与悬停样式）也不重算；写 `clickable: true` / `features: { hover: true, select: true }` 或 `features: 'view'` 才开。样式优先级是 **状态样式 > 热力图 > `override` 规则 > 要素自身字段 > 普通规则 > 全局样式（`pointStyle` / `lineStyle`）> 内置默认值**：
 
 ```js
 createGisView(container, {
@@ -60,7 +60,7 @@ view.updateOptions({ cascadeHighlight: false }) // 关掉并收掉当前高亮
 - 框选触发时，框内每个命中项都参与邻接计算，取并集后一次派发；`origin` 取框内按数据顺序的第一个命中项作代表。框内直接命中的项走 `boxSelectStyle` / `lineSelectStyle`，框外的邻接节点 / 线路才套级联样式。
 - 点空白处是否收掉由 `clearOnEmptyClick` 控制，缺省 `true`。收掉、首次点亮、换节点 / 线路 / 通道或改范围都会发 `onCascadeHighlight` 与总线事件 `cascadeHighlight`；读数与回调收到的是同一份对象，收掉时是 `null`。
 - `origin.target` 为 `point` / `line` / `channel`：通道回线在底层仍是线路，但 `origin` 会另带 `channelId` / `channelIndex` / `groupId` / `groupIndex` / `channel`，方便直接回显“点的是哪条通道的哪一组”。
-- 数据整份更新后会按新的邻接关系刷新；来源被删除、被隐藏到不可拾取，或 `cascadeHighlight` 关掉时，高亮自动收掉。它不写 `selectionKeys`，`getSelectionData()` / `getSelections()` 不会因为级联高亮多出条目。
+- 数据整份更新后会按新的邻接关系刷新；来源被删除、被隐藏到不可拾取、选中被取消（`toggleSelect` / Ctrl 取反 / `deselect` / `selectFeatures` 的 remove 或清空），或 `cascadeHighlight` 关掉时，高亮自动收掉。取消那一击只清旧级联，不会先点亮再发一条 `null`。它不写 `selectionKeys`，`getSelectionData()` / `getSelections()` 不会因为级联高亮多出条目。
 - 综合 Demo（`?demo=full`）的「视图 · 交互 → 交互开关与快捷键」面板已接入这项能力：可现场开关、在「节点 + 直连线路 / 只亮节点」之间切换，并直接读 `getCascadeHighlight()` 的来源、范围与节点 / 线路条数。
 
 ## 指针事件

package/docs/manual/08-/351/200/211/344/270/255/344/270/216/346/213/220/347/202/271.md

@@ -13,6 +13,7 @@
 | 换一份选中集 | `view.selectFeatures(refs)`（缺省 `mode: 'replace'`） |
 | 追加 / 取反 / 移除 | `view.selectFeatures(refs, { mode: 'add' \| 'toggle' \| 'remove' })` |
 | 多选 | 打开 `multiSelect` 后单击，或按住 Ctrl / ⌘ 单击；框选先开 `boxSelect`，再按住 Shift 拖动 |
+| 再次选中取消 | 打开 `toggleSelect` 后再次普通单击已选要素；Ctrl / ⌘ 先选中后再普通单击也取消 |
 | 取消指定项 | `view.deselect(refs)`，等价于 `view.selectFeatures(refs, { mode: 'remove' })` |
 | 取消全部 | 单击空白处、无其它编辑态时按 Esc、`view.deselect()`、`view.selectFeatures(null)` 或 `view.selectFeatures([])` |
 | 读回结果 | `view.isSelected(ref)` / `view.getSelections()` / `view.getSelectionData()` |
@@ -61,15 +62,47 @@ createGisView(container, {
 
 拖动期间选框实时跟随，但事件只在松手时派发一次，不会拖动一帧报一次。**框选默认只收节点**，保持旧口径；写 `selectionKinds` 后可以把通道外的线路与通道回线一起纳入（三类任意组合），也可以改用端点口径，只收两端节点都框住的线路 / 通道，见下节。选中结果用 `getSelections()` / `getSelectionData().ids` 读回。用代码框选等价于调用 `selectInBox({ x, y, width, height })`，矩形同样是画布 CSS 像素；第二段还能临时覆盖类型过滤。框选命中的节点套用框选样式（`options.pointBoxSelectStyle`，节点自己的 `boxSelectStyle` 优先），缺省与选中样式完全一致；框选出来的线路走普通的 `lineSelectStyle`（线路没有单独的框选样式）。
 
+### 保留框与整组拖动（selectionBoxPersistent）
+
+`selectionBoxPersistent: true` 会让非空框选结束后继续显示矩形。此时在框内按下并拖动，会把框中选中的节点当成一组平移：节点和保留框都按同一个世界坐标增量移动，绑定线路、通道骨架与回线一起跟随；相机恰好在拖动中变化也不会错位。拖动整框不参与节点合并；在框内按下但没有拖动也不会被当成点空白，不会清掉选中集。框选出来的若只有线路 / 通道、没有可拖动节点，保留框仍能显示，但没有可整组平移的节点。
+
+```js
+const view = createGisView(container, {
+  boxSelect: true,             // 框选入口
+  draggable: true,             // 保留框拖动依赖节点可拖
+  selectionBoxPersistent: true,
+  selectionBoxStyle: {
+    render: 'div',
+    className: 'selection-box-dashed',
+    stroke: '#f59e0b',
+    strokeWidth: 2,
+    borderStyle: 'dashed',
+    radius: 6
+  }
+})
+
+view.selectInBox({ x: 60, y: 50, width: 300, height: 180 })
+const box = view.getSelectionBox() // 按当前相机投影后的画布 CSS 像素；没有保留框时是 null
+view.clearSelectionBox()            // 只收起矩形，不改选中集
+```
+
+保留框会在以下情况自动收起：重新框选或选中集发生变化（点击别的要素、`selectFeatures` / `deselect` 实际改动集合）、点空白 / Esc 清空、`updateOptions({ selectionBoxPersistent: false })`、实例销毁；空框选也不会留下矩形。需要只关框、保留选中时调用 `clearSelectionBox()`。
+
+样式可以只改颜色，也可以挂成 DOM 再交给类名接管：`selectionBoxStyle.render: 'div'` 会创建 `.gis-view__selection-box`，`className` 追加自定义类；`borderStyle` / `radius` 只在 DOM 模式生效。canvas 模式的边框恒为实线直角。保留框锚在世界坐标里，地图平移 / 缩放时两种渲染都会重新投影，DOM 框的平移只更新合成层 `transform`，缩放时才改宽高；颜色、线型和类名只在 `selectionBoxStyle` 变化后重写。它只负责显示，不接管指针，框内拖动仍由画布统一处理。
+
 不想拖动时也可以用 Ctrl（macOS 为 Cmd）逐个点击节点累加选中，命中已选中的节点会把它取消掉；两种方式得到的选中集合一样，之后按住组内任意一个节点拖动就是整组移动。不想按修饰键就把多选开关打开（`options.multiSelect: true`，运行时用 `updateOptions({ multiSelect })` 切）：普通单击即取反累加，线路也认（受 `channelSelectMode` 的整组 / 整条摊开约束）；单击触发模式下双击的第二次点击不再取反，`onDblClick` 照常派发。多选命中的节点走多选样式（`options.pointMultiSelectStyle`，节点自己的 `multiSelectStyle` 优先），框选命中的走框选样式（`options.pointBoxSelectStyle`，节点自己的 `boxSelectStyle` 优先），两者缺省都与选中样式完全一致。注意框选样式只给节点；选中线路 / 通道回线时仍按 `lineSelectStyle` / `lineMultiSelectStyle` 上色。
 
+只想让「再次点同一个就取消」、又不想把普通单击都变成多选时，打开 `toggleSelect`。它只接管本来会改选中集、且命中项已经在选中集里的普通点击：单击模式下第一下取反、双击的第二下保持；`selectTrigger: 'dblClick'` 下由双击第二下取反，再次双击取消。Ctrl / ⌘ 先选中的要素，后续普通单击同样取消。取反生效时点击与选中变更的动作名都是 `toggleSelect`；这条取消路径不受 `selectionKinds` 限制，同一来源的级联高亮也会一起收掉。缺省关，运行时可用 `updateOptions({ toggleSelect })` 切换。
+
+点中通道回线时，取消范围跟随 `channelSelectMode`：`line` 取消命中的单条回线，`group` 取消该回线所在的整组，`channel` 取消整条通道；其他已选要素保留。若该回线所属分组 / 通道已经完整选中（例如先通过右键菜单或 `selectFeatures` 选中了整组 / 通道），即使当前是 `line` 模式，再次点击也会整组 / 整条取消，不会只删命中那一条、留下仍然选中的假象。部分选中时按当前模式取消展开范围，点到组内 / 通道内的另一条回线同样生效。独立线路始终只取消它自己。
+
 ### 点击选中与 dblClick
 
 `selectTrigger` 缺省是 `'click'`：命中的节点 / 线路在第一次单击时就进选中集，点空白也在第一次单击时清空。写 `selectTrigger: 'dblClick'` 后，第一次点击只派发 `onClick`（`action.type` 是 `'click'`），同一位置 320ms 内、6px 范围内的第二下才应用选择结果：
 
-- 点要素：选中它；`multiSelect` 或按住 Ctrl / ⌘ 时取反累加。第二下同时派发 `onClick`（`action.double: true`，取反时 `action.type` 为 `'toggleSelect'`，普通选中为 `'select'`）与 `onDblClick`（`action.type: 'dblClick'`）。
+- 点要素：选中它；`multiSelect` 或按住 Ctrl / ⌘ 时取反累加。`toggleSelect` 打开时，已选中的要素在第二下取消，未选中的仍选中。第二下同时派发 `onClick`（`action.double: true`，取反时 `action.type` 为 `'toggleSelect'`，普通选中为 `'select'`）与 `onDblClick`（`action.type: 'dblClick'`）。
 - 点空白：第二下才清空选中集并派发 `onDblClick`。
-- `click` 模式下普通双击的 `onDblClick` 也照常派发，只是第一次单击已经完成了选中；Ctrl / `multiSelect` 的取反快捷路保持原口径（不额外发 `onClick` / `onDblClick`）。两种模式都不影响拐点双击删除与通道草稿等既有双击交互。
+- `click` 模式下普通双击的 `onDblClick` 也照常派发，只是第一次单击已经完成了选中；Ctrl / `multiSelect` 的取反快捷路保持原口径（不额外发 `onClick` / `onDblClick`）。`toggleSelect` 放在任一模式都只取反一次：双击模式看第二下，单击模式看第一下。两种模式都不影响拐点双击删除与通道草稿等既有双击交互。
 
 ```js
 createGisView(container, {
@@ -108,7 +141,7 @@ view.selectInBox({ x: 40, y: 40, width: 320, height: 200 }, { selectionKinds: ['
 view.selectInBox({ x: 40, y: 40, width: 320, height: 200 }, { selectionKinds: ['channelEndpoints'] })
 ```
 
-**不写 `selectionKinds` 时保留旧行为**：框选只收节点，Ctrl / 多选点击仍收节点与线路（通道回线按 `channelSelectMode` 摊开）。显式写了之后，框选与 Ctrl / 多选点击统一按这一份过滤；普通单选、`selectFeatures` 这些接口入口不受它限制。运行中用 `updateOptions({ selectionKinds })` 切换即可，不需要重排场景。
+**不写 `selectionKinds` 时保留旧行为**：框选只收节点，Ctrl / 多选点击仍收节点与线路（通道回线按 `channelSelectMode` 摊开）。显式写了之后，框选与 Ctrl / 多选点击统一按这一份过滤；普通单选、`toggleSelect` 的再次点击取消、`selectFeatures` 这些接口入口不受它限制。运行中用 `updateOptions({ selectionKinds })` 切换即可，不需要重排场景。
 
 ## 接口选中（selectFeatures）与读回选中
 
@@ -204,7 +237,7 @@ view.focusOn(selection.items, { select: true, zoom: true }) // 反过来也行
 
 ### 取消选中（deselect / selectFeatures(null)）
 
-取消某一个 / 某一类 / 全部都是**一句话**（`deselect()` 与 `selectFeatures(null)` 都表示全部取消）：与选中落在同一份 state 上，清完 `getSelections()` / `getSelectionData()` 立刻读得到；选中集实际变化时按 `onSelect → onSelectChange` 派发，`onSelect` 的载荷为 `null`、`cause` 为 `'api'`。
+取消某一个 / 某一类 / 全部都是**一句话**（`deselect()` 与 `selectFeatures(null)` 都表示全部取消）：与选中落在同一份 state 上，清完 `getSelections()` / `getSelectionData()` 立刻读得到；选中集实际变化时按 `onSelect → onSelectChange` 派发，`onSelect` 的载荷为 `null`、`cause` 为 `'api'`。这次真的移除了选中项时，点击级联也同步收掉并补一条 `onCascadeHighlight(null)`，不留下残留高亮。
 
 ```js
 view.deselect('station-1024')                               // 取消一个节点（id，或 { type: 'point', index: 3 }）

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

@@ -26,6 +26,63 @@ view.showFeatures('channel', 'c1')
 
 逐条回线也可以写 `lines[].visible: false`：那只收起这一条回线，通道声明、分组、骨架与其它回线都不变；整条通道一起收用 `channel` 上的 `visible` 或 `hideFeatures('channel', ...)`。
 
+### 节点、线路、通道与分组的批量显隐
+
+四类要素共用同一套显隐入口：`setFeatureVisible(kind, refs, visible)`，另有 `hideFeatures(kind, refs)` / `showFeatures(kind, refs)` 两个快捷写法。它们只改数据里的 `visible`，不删除节点、线路、通道或分组；整次调用收在一个 `batch` 里，只记一条历史、只发一条 `batch` 数据变更。
+
+| `kind` | 单条 | 批量 | 恢复 | 说明 |
+| --- | --- | --- | --- | --- |
+| `'point'` | `view.hideFeatures('point', 'a')` | `view.hideFeatures('point', ['a', 'b'])` | `view.showFeatures('point', ['a', 'b'])` | 绑定线路与以它为端点的通道由引擎级联处理；改回来按原几何恢复 |
+| `'line'` | `view.hideFeatures('line', 'l1')` | `view.hideFeatures('line', ['l1', 'l2'])` | `view.showFeatures('line', ...)` | 只收起线路本身；通道声明、分组、骨架与其它回线不动 |
+| `'channel'` | `view.hideFeatures('channel', 'c1')` | `view.hideFeatures('channel', ['c1', 'c2'])` | `view.showFeatures('channel', ...)` | 整条通道与成员回线退场，声明 / 分组 / 拐点 / 编辑状态保留 |
+| `'group'` | `view.hideFeatures('group', { channelId: 'c1', groupId: 'c1::2' })` | `view.hideFeatures('group', refs)` | `view.showFeatures('group', refs)` | 只收起这一组；成员、骨架、拐点、`getLineChannel()` 归属都保留 |
+
+分组引用支持这几种定位方式；分组 id 在整个视图里唯一时也可以直接写 id 或 id 数组：
+
+```js
+view.hideFeatures('group', [
+  { channelId: 'c1', groupId: 'c1::2' }, // 通道 id + 分组 id
+  { channelIndex: 0, groupIndex: 1 },     // 通道下标 + 分组序号（从 0 起）
+  { id: 'c2::3' },                       // 分组 id 简写
+  'c3::2'                                // 全局唯一的分组 id
+])
+
+view.showFeatures('group', { channelId: 'c1', groupId: 'c1::2' })
+view.hideFeatures('line', 'selection')    // 当前选中集里的线路
+view.hideFeatures('channel', 'selection') // 选中回线所属的整条通道
+view.hideFeatures('group', 'selection')   // 选中回线所属的分组
+view.hideFeatures('point', 'selection')   // 当前选中集里的节点
+```
+
+`refs: 'selection'` 对 `point` / `line` 取选中集里同类型的要素；对 `channel` 由选中回线的归属推出整条通道；对 `group` 由选中回线推出所属分组。分组隐藏后仍会出现在 `getChannelGroups()` 与 `getLineChannel()` 的读数里（`visible: false`），但成员不绘制、不参与拾取，也不注册通道锚点；改回 `true` 时使用原来的成员、分组顺序与骨架。要整份重写分组时也可以在 `updateChannel(id, { groups })` 的组项上直接写 `visible: false`。
+
+返回统一为 `{ ok, reason, kind, visible, indexes, ids, items, groups, skipped }`，认不出的引用逐条进 `skipped`、不阻塞其余条目。`point` / `line` / `channel` 的 `indexes` 是数据下标，`ids` 是要素 id（没有 id 时退回下标），`items` 是对应数据项，`groups` 为空数组。`group` 的三列口径不同：`indexes` 是每个分组所在**通道**的下标（同一通道的两组会重复），`ids` 是分组 id，`items` 是这些分组所属的通道数据，`groups` 是受影响分组的当前快照（带 `visible` / `lineIds` / `path` 等）。批量操作的结果要按 `groups` 读分组，不要拿 `items` 当下标去对应分组。
+
+### 隐藏回线后的车道（channelHiddenLineLayout）
+
+隐藏一条回线或一整个分组之后，剩余回线有两种排法，由 `channelHiddenLineLayout` 决定：
+
+| 值 | 行为 | 适用 |
+| --- | --- | --- |
+| `'preserve'`（缺省） | 保留整条通道原来的车道槽位，其余回线不因为邻居隐藏而挪位 | 想把回线固定在原来的走廊位置，隐藏 / 恢复时画面稳定 |
+| `'center'` | 只取当前真正可见的回线，按原声明顺序压成连续槽位，再按通道宽度重新居中 | 双回线隐藏一条后期望另一条回到中线；希望剩余回线占满通道 |
+
+```js
+const view = createGisView(container, {
+  channels: [{ id: 'c1', lineIds: ['l1', 'l2'] }],
+  channelHiddenLineLayout: 'center'
+})
+
+view.hideFeatures('line', 'l1')  // center：l2 回到中线；preserve：l2 留在原来的车道
+view.updateOptions({ channelHiddenLineLayout: 'preserve' })
+view.showFeatures('line', 'l1')
+
+// 分组同样按整组参与：隐藏 c1 的第二组后，center 只重排剩下的可见组
+view.hideFeatures('group', { channelId: 'c1', groupId: 'c1::2' })
+```
+
+判断可见性时会同时看通道 / 分组 / 回线自己的 `visible`、端点是否可用以及筛选结果；隐藏分组不占车道，`channelSimplify` 折叠出的代表线也不参与连续车道分配。`updateOptions({ channelHiddenLineLayout })` 会重新计算通道车道，但不会改线路的 `path` 数据或分组声明。
+
 ### 通道选中模式（channelSelectMode）
 
 点中通道里的一条回线时选中什么由 `channelSelectMode` 决定（缺省 `'line'`）：
@@ -237,7 +294,7 @@ console.log(view.getChannels()) // 骨架、每条回线的偏移与推导出来
 
 两端锚定的通道还会把切点往节点里收一段：缺省按成员回线里最粗那条的线宽收（切点从节点边缘再往节点里挪一个线宽），所以线不会从节点边缘探出去；`options.channelTangentInset` 或单个通道的 `tangentInset` 可以改成固定的 CSS 像素（`0` 表示切点正好落在节点边上），和线宽一样会随相机缩放折算回世界单位。内收两侧合计最多吃掉节点宽度的 40%，小节点配粗线时不会把回线挤成一条；写成负数就是**外收**：切点从节点边缘往外让一段，整组回线比节点还宽，单侧最多让出节点宽度的 50%。
 
-筛选只改变节点自身是否绘制，不改变仍显示的通道宽度：被筛掉的端点仍按 `points` 里的数据和同一条样式链取外框（点自身 > 规则 > `pointStyle`，含热力倍率），所以只筛掉一端时不会改按另一端尺寸算，两端都被筛掉时也不会退回 `width` / `channelWidth`。只有节点真被删除或写了 `visible: false` 时才按「没有节点」处理。
+筛选只改变节点自身是否绘制，不改变仍显示的通道宽度：被筛掉的端点仍按 `points` 里的数据和同一条样式链取外框（`override` 规则 > 点自身 > 普通规则 > `pointStyle`，含热力倍率），所以只筛掉一端时不会改按另一端尺寸算，两端都被筛掉时也不会退回 `width` / `channelWidth`。只有节点真被删除或写了 `visible: false` 时才按「没有节点」处理。
 
 通道的配置项没有重复的，成对出现的都是「**全局默认 + 逐通道覆盖**」：`channelWidth` / `width`、`channelNodeWidth` / `nodeWidth`、`channelInset` / `inset`、`channelTangentInset` / `tangentInset`，单个通道不写就取 `options` 上的同名值；`groups` / `path` / `from` / `to` 分别管分组、骨架与两端锚定，各管一件事（`path` 是可选骨架，不写时由锚点或第一条回线补出）。要留意的是各自的**生效条件**（不是冗余，而是只在特定组合下才有意义）：`offsetMode: 'tangent'`（默认）时 `inset` / `channelInset` 不参与计算；`nodeWidth` 不为 0 且两端都锚在节点上时 `width` 只作兜底（宽度按节点尺寸算，改它看不到变化）；`tangentInset` 只对两端锚定的通道有效（没锚定时切点就是骨架端点，无所谓往哪收）；只有一条回线的通道不排偏移（回线就是骨架），`nodeWidth` 与 `tangentInset` 对它的回线位置没有影响。