gis-view-webgl2 0.1.0 → 0.1.2

package/docs/internals/16-03-/344/274/230/345/214/226/344/270/216/345/217/226/350/210/215-/344/270/213.md

@@ -131,4 +131,15 @@
 
 ---
 
+### 16.74 头 / body 为什么先校验、类实例为什么跳过、导出格式为什么是模块级同步注册（本轮已做 / 留档）
+
+- **为什么头 / body 校验放在幂等缓存之前**：幂等表按 `opId` 命中，但「同一个 `opId`」只有在请求确实是同一次业务重试时才有意义。先校验 `Idempotency-Key === body.opId`、`If-Match === "v" + baseVersion` 与有限版本，错误请求连幂等缓存都不该碰；否则一个坏请求可能被当成历史请求回放，或者把缓存里的旧响应冒充新动作的成功结果。请求指纹把 method / url / 规范化 body 一起算，字段顺序变化不算换请求，真正换了内容才返回 `409 IDEMPOTENCY_CONFLICT`。
+- **为什么无效日期写 `null`、类实例跳过**：文档的承诺是「JSON 安全」，不是「尽量猜」。无效日期没有可逆的 ISO 写法，继续调用 `toISOString()` 只会让一份业务数据里的一个坏字段毁掉整次导出；写 `null` 并告警，调用方至少拿得到其余数据。类实例的问题相反：它看起来是对象，但 JSON 只保留自有可枚举字段，直接展开会把原型上的业务语义悄悄丢掉，得到一个 `{}`。按「JSON 存不下」跳过并点名，比给一份假成功更诚实；要导出类实例就由调用方先转成普通对象。
+- **为什么正常路径不再拼路径字符串**：`toJsonValue` 的路径只服务于告警，正常导出里 99% 的字段都不告警。递归时维护 `['points[2]', 'props', 'name']` 这样的段数组，只在告警时拼成文字，既保留可读的定位，又把每值一次 `String` 分配去掉；这份优化不改任何导出结果，`full` 文档仍逐字节一致。
+- **为什么自定义导出器是模块级、同步、拿标准文档**：格式是「应用级词汇表」，不是某一个视图实例的状态，所以注册表挂在模块上，`listExportFormats` 对所有实例一致。同步是导出接口的既有契约 —— `exportData` 是同步取值，不能一半调用方拿到对象、一半拿到 Promise；异步 DTO（比如要再查后端）由调用方先 `await` 自己的数据，再注册一个同步映射。适配器拿到标准文档而不是内部数组，扩展点就只依赖公开的文档口径，不碰组件内部结构；`options` / `parts` / `warnings` 让筛选与告警继续走同一条路。
+- **为什么 `exportViewportData` 的结果要展开补元数据**：自定义适配器只负责业务结构，不知道视口范围；`viewRect` / `margin` 是这次查询的上下文，必须由 `exportViewportData` 统一补上，且不能覆盖适配器同名字段之外的内容。对象结果才展开、非对象原样返回，避免适配器返回 `null` 时凭空造一个对象。
+- **为什么严格契约放在 demos 自测里**：这两个接口是「演示即文档」的一部分，后端同学拿到的第一个可执行样例就是假后端。把 400 / 409 断言放在 `selftest-demos.html`，每次演示页回归都会重新验证契约，不需要另起一套测试设施。
+
+---
+
 [← 16-02 优化与取舍（中）](16-02-%E4%BC%98%E5%8C%96%E4%B8%8E%E5%8F%96%E8%88%8D-%E4%B8%AD.md) · [实现原理目录](../GisView实现原理.md) · [17 调试与扩展建议 →](17-%E8%B0%83%E8%AF%95%E4%B8%8E%E6%89%A9%E5%B1%95%E5%BB%BA%E8%AE%AE.md)

package/docs/internals/17-/350/260/203/350/257/225/344/270/216/346/211/251/345/261/225/345/273/272/350/256/256.md

@@ -6,7 +6,7 @@
 - **排查 GL 错误**：`view.gl.getError()`（0 是干净）。创建之后、每类交互之后各读一次，能很快定位是哪个批次出的问题。
 - **想看解析结果**：`listPoints()`（含屏幕半径与图层号，`getVisiblePoints()` 并进了这一条）、`getChannels()`（骨架 + 偏移 + 每条回线的折线）、`getChannelGroups()`、`getParallelGroups()`、`getData()`。
 - **想接自己的覆盖层**：`listPoints()` + `getChannelMembers()` + `project` / `unproject` + `onCameraChange` 就够了（鹰眼图本身就是这么写的；引擎侧那份缓存快照 `engine.getVisiblePoints()` 只有标签层在用）。
-- **想把视图级逻辑打包复用**：写成 `view => hook` 的插件 —— 创建时挂走 `options.plugins`，之后才决定要挂的走 `view.use(plugin)`（立即执行，返回幂等的卸载函数；清理写在插件自己的 `destroy` 里，见「插件」一节）。插件拿到的就是实例，只用公开 API 的插件不随内部重构失效。
+- **想把视图级逻辑打包复用**：写成 `(view, context) => hook` 的插件 —— 创建时挂走 `options.plugins`，之后才决定要挂的走 `view.use(plugin)`（立即执行，返回幂等的卸载函数；清理写在插件自己的 `destroy` 里，见「插件」一节）。插件拿到的就是实例，只用公开 API 的插件不随内部重构失效。
 - **想加一种符号**：只是一支画笔（三角 / 星形 / 带角标的图标…）直接 `registerSymbolPainter(name, painter)` 注册，或在那一条数据上写 `{ type: 'custom', draw }`，不用改库 —— 走贴图那条路（尺寸档 / 缓存 / 预热全复用，见 16.61）；要的是新图元类型本身（新的形状着色器、新的贴图来源），才在 `symbols.js` 的 `normalizeSymbol` 里加分支（返回 `{ kind, texture | shape, width, height }`），形状类的在点着色器里加一段距离场。
 - **想加一种交互**：`handlePointerDown` / `handlePointerMove` / `handlePointerUp` 三个入口里加状态机分支，光标分类在 `CURSOR_KEYS` 里加一个键。
 - **想加一种数据字段**：以「要素自身字段 > 规则 > 全局样式」的顺序接通解析（`point.js` / `line.js` 各一处），再补 `types.d.ts` 与文档。

package/docs/manual/02-/345/235/220/346/240/207/344/270/216/346/225/260/346/215/256.md

@@ -86,6 +86,14 @@ createGisView(container, { points, lines, channels })
 - **分组**：`channels[].groups[]`（`{ id?, lineIds, path? }`）。缺省一个通道一组；拆开之后每组自带成员与拐点，见「通道分组」。
 - **拐点**：就是折线的中间顶点 —— 线路的 `path` 中间项、通道的 `path`（中间项）、分组的 `groups[].path`。运行时用 `getWaypoints(lineIndex)` / `getChannelGroups(channelId)` 读，改动由 `onWaypointChange` 载荷里的 `line` / `groups[].path` 写回，见「线路拐点」「分组拐点」。
 
+### ID 解析口径
+
+节点 / 线路 / 通道都按 `id` 关联。为了让「按 id 定位」「筛选联动」「复制快照」「Worker 搜索」走同一份结果，组件采用以下固定口径：
+
+- 只忽略 `undefined` / `null`；空字符串 `''` 仍是一个合法 id，需要表示「没有 id」时请留空或写 `null`。
+- 同一份数据里出现重复 id 时，**按数组顺序只认第一条**；后面的同名项照常绘制，但按 id 定位、`from` / `to` 端点绑定、筛选投影与复制引用都会落到第一条。
+- 这个口径对节点与线路同样成立；通道按 id 找成员回线时也取第一条。需要操作某一条重名数据时，请改用下标入口（如 `focusOn({ type: 'line', index: 3 })`）或先修正数据里的 id。
+
 ### 节点（GisViewPoint）
 
 | 字段 | 类型 | 说明 |
@@ -109,6 +117,7 @@ createGisView(container, { points, lines, channels })
 | `labelPosition` | `GisViewLabelPosition` | 标签贴在节点的哪一侧 |
 | `labelOffset` | `[number, number]` | 标签的额外像素偏移 |
 | `labels` | `GisViewItemLabel \| GisViewItemLabel[]` | 这个点上的标签清单（逐条写：`id` / `content` / `position` / `offset` / `style` / `hidden`…），与 `options.label` 里同 id 的那一条合并；导出数据的 `labels` 列就是它，见「标签（labels，导入即回显）」 |
+| `decorations` | `GisViewPointDecoration[]` | 节点上挂的图片 / SVG：可写屏幕像素偏移（`offset` 或 `distance` + `direction`）、固定世界坐标（`anchor: 'fixed'` / `at`），并可用 `connector` 从节点中心画连接线，见「节点上的装饰」 |
 | `tooltip` | `GisViewTooltipContent \| false` | 这个点的提示内容，`false` 表示不显示 |
 | `hoverStyle` / `selectStyle` / `multiSelectStyle` / `boxSelectStyle` | `GisViewPointStyle` | 这个点自己的状态样式（按字段覆盖自身样式） |
 
@@ -141,7 +150,7 @@ createGisView(container, { points, lines, channels })
 
 ### 标签（labels，导入即回显）
 
-`options.label` / `options.lineLabel` 是**全局默认**，数据里还能逐条带标签：每个点 / 每条线的 `labels`（单个对象或数组）写明「这条要素上有几条标签、每条写在哪、长什么样」—— 只喂数据、一条标签配置都不写，标签照样画得出来。`exportData` / `exportPointData` / `exportLineData` / `exportChannelData` / `exportSelectionData` 的 `labels` 列就是这一份，导出再导入即回显。
+`options.label` / `options.lineLabel` 是**全局默认**，数据里还能逐条带标签：每个点 / 每条线的 `labels`（单个对象或数组）写明「这条要素上有几条标签、每条写在哪、长什么样」—— 只喂数据、一条标签配置都不写，标签照样画得出来。`exportData()`（含 `scope: 'selection'` 与各 `parts` 分项）的 `labels` 列就是这一份，导出再导入即回显。
 
 ```js
 const points = [
@@ -174,6 +183,10 @@ createGisView(container, { points, lines }) // 不配 label / lineLabel 也画
 | `visibility` | `'auto' \| 'always' \| 'hidden'` | 这一条的显隐策略 |
 | `hidden` | `boolean` | 这一条不画（等于 `visibility: 'hidden'`；`removeLabel` 对声明里那一条落的覆盖就是它） |
 | `parallel` | `boolean` | 线路标签：这一条是否跟着线路方向转 |
+| `overlapMode` | `'shift' \| 'hide'` | 碰撞后的处理方式：换落点或直接不画；逐条覆盖全局的 `overlapMode` |
+| `avoidOverlap` | `boolean` | 这一条是否参与避让；写 `false` 时即使全局开着避让也会画出来（`LabelDemo` 用它让两条标签同时出现） |
+| `draggable` | `boolean` | 这一条能不能拖动；逐条覆盖 `options.label` / `options.lineLabel` 的 `draggable` |
+| `editable` | `boolean` | 这一条能不能点选编辑；逐条覆盖 `options.label` / `options.lineLabel` 的 `editable`，写 `false` 时点击不触发 `labelClick` |
 | `className` | `string` | 这一条的附加类名 |
 | `added` | `boolean` | 这条是运行时加的（`addLabel`），持久化 / 整份回显时按它重建 |
 
@@ -213,7 +226,7 @@ const next = createGisView(el, {
 前三份各看一类字段（标签 / 拐点 / 分组），`sample-full.json` 再把它们摆在同一份里：
 10 点 / 22 线 / 3 通道、5 条线路各带 3 ~ 4 个拐点、同一节点最多 4 条标签、同一线路最多 3 条标签、
 6 回通道拆 3 组且每组各带 2 个骨架拐点、23 个标记、6 条标签状态（拖过 / 改过 / 运行时加 / 隐藏）。
-另有 `sample-document.json`：同一份 `sample-full.json` 的**标准文档**写法（顶层带 `format: 'gis-view'` 与 `view` 相机那一列，见「导出数据」）。演示页「完整样本」（`?demo=samples`）把五份切着看：四份普通样本用 `exportData({ format: 'input' })` 与文件逐字节对账，标准文档那一份用 `exportData({ format: 'full' })` 对账。
+另有 `sample-document.json`：同一份 `sample-full.json` 的**标准文档**写法（顶层带 `format: 'gis-view'` 与 `view` 相机那一列，见「导出数据」）。五份文件都能直接作为创建入参或整份文档回灌：四份普通样本可用 `exportData({ format: 'input' })` 与文件逐字节对账，标准文档用 `exportData({ format: 'full' })` 对账。
 
 ### 通道与分组（GisViewChannel）
 
@@ -222,8 +235,9 @@ const next = createGisView(el, {
 | 字段 | 类型 | 说明 |
 | --- | --- | --- |
 | `id` | `string \| number` | 通道 id：同 id 的通道在数据刷新之间保留已编辑过的骨架 |
+| `visible` | `boolean` | `false` 时整条通道与成员回线一起不画；数据、分组、拐点与编辑状态保留，改回 `true` 立即恢复 |
 | `lineIds` | `Array<string \| number>` | 通道内的线路 id，**顺序就是回线顺序**（沿骨架左法线方向） |
-| `groups` | `GisViewChannelGroup[]` | 分组声明：`{ id?, lineIds, path? }`。缺省是「一个通道一组」 |
+| `groups` | `GisViewChannelGroup[]` | 分组声明：`{ id?, lineIds, path?, waypointOffsets? }`。缺省是「一个通道一组」；`waypointOffsets` 是 `vertex` 拖动按骨架序号记的刚性偏移 |
 | `path` | `GisViewCoordinate[]` | 骨架的中间拐点（两端用 `from` / `to` 绑节点时只需写中间） |
 | `from` / `to` | `string \| number` | 两端节点：声明了任意一端，两端就都必须落在节点上，节点不存在时整条通道与回线都不显示 |
 | `width` | `number` | 通道宽度（覆盖 `channelWidth`），只在 `nodeWidth` 为 0 或两端没锚定时真正生效 |
@@ -234,7 +248,7 @@ const next = createGisView(el, {
 | `tooltip` | `GisViewTooltipContent \| false` | 通道回线悬停时的提示内容（`{name}` 是通道名，`{circuits}` 是回数） |
 | `cursor` / `ctrlCursor` | `GisViewCursorValue` | 悬停到这条通道回线上时的光标（回线自身也配了 `cursor` 时以回线为准） |
 
-分组的语义：**一个通道默认一组**，拆分之后每组有自己的成员与拐点；加点 / 拖点只作用于同一分组，没列进任何分组的线路并回第一组。运行时读数用 `getChannelGroups()`，写回用 `groups[].path`（它已经是「可以直接写回数据的中间拐点」）。
+分组的语义：**一个通道默认一组**，拆分之后每组有自己的成员与拐点；加点 / 拖点只作用于同一分组，没列进任何分组的线路并回第一组。运行时读数用 `getChannelGroups()`，写回用 `groups[].path`（它已经是「可以直接写回数据的中间拐点」）与 `waypointOffsets`（`vertex` 拖动的刚性偏移，键按含首尾端点的骨架序号算）。
 
 ### createChannels
 

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

@@ -15,6 +15,7 @@
 | `features` | `GisViewFeaturesInput` | 无（**缺省全关**） | 功能开关：预设名（`'edit'` 全开 / `'view'` 打开查看类 / `'static'` 与缺省一致（全关））、开关表或布尔值。**什么都不写时只剩画布与数据**：没写的开关跟随各自的详细配置（`interactive` / `clickable` / `draggable` / `boxSelect` / `copy.enabled`…），详细配置也没写就是关（提示 / 标签 / 鹰眼图配了才有），写了 `true` / `false` 就是强制打开 / 关闭；想一次打开一批就用 `'view'`（能平移缩放、能悬停选中看提示但改不动数据）或 `'edit'`（等价 `features: true`）。运行时用 `setFeatures()` 换、`getFeatures()` 读，见「功能开关」 |
 | `history` | `GisViewHistoryOptions` | 关 | 历史（撤销 / 重做）：`true` 用缺省上限 50 条，`{ limit }` 自定义（`0` 表示不限），不配就是关。打开之后 Ctrl+Z 撤销、Ctrl+Shift+Z / Ctrl+Y 重做，接口是 `undo()` / `redo()` / `canUndo()` / `canRedo()`，见「历史」 |
 | `quality` | `GisViewQualityOptions \| GisViewQualityMode \| boolean` | `'high'` | 画质档位（自动档按渲染耗时与整帧间隔两路信号升降）：`'high'` 全开 / `'balanced'` 关光晕 / `'lean'` 连装饰一起关 / `'fast'` 再降到 0.75 倍渲染分辨率，`'auto'`（也可以直接写 `true`）按这两路信号自己升降，对象写法 `{ mode, budgetMs, minScale }` 能换预算与分辨率下限。只改「画哪些批次 + 多大分辨率」，不重排场景、不动数据，见「画质」 |
+| `denseMode` | `GisViewDenseModeInput` | `'auto'` | 大数据展示模式：`'auto'` 按可见节点数、屏幕密度与数据总量自动进入密集档，`'on'` / `'off'`（或 `true` / `false`）强制开关；对象写法可换 `visibleThreshold` / `densityThreshold` / `pointThreshold` 三档阈值。进入后标签自动走避让 / 截断，线路动点与节点涟漪暂停；读数看 `getStats().dense`，见「大数据展示模式（denseMode）」 |
 | `points` | `GisViewPoint[]` | `[]` | 点数据，`x` / `y` 为世界坐标（经纬度、投影米或任意平面坐标） |
 | `lines` | `GisViewLine[]` | `[]` | 线数据，`start` / `end` 支持 `{ x, y }` 或 `[x, y]`，折线用 `path`，端点可用 `from` / `to` 绑定点 id |
 | `channels` | `GisViewChannel[]` | `[]` | 通道：把若干条线路组织成并行敷设的多回线走廊，回线几何由骨架折线按偏移推导；两端可用 `from` / `to` 绑在节点上 |
@@ -24,21 +25,24 @@
 | `channelTangentInset` | `number \| null` | `null` | 两端切点往节点里收多少 CSS 像素：缺省（`null`）按成员回线里最粗那条的线宽收，线因此不会从节点边缘探出去；`0` 表示切点正好落在节点边上，**负数外收**（切点往节点外让、回线整段比节点宽）；单个通道可用 `tangentInset` 覆盖；内收两侧合计最多收掉节点宽度的 40%，外收单侧最多让出 50% |
 | `channelMaxGroups` | `number` | `0` | 一条通道最多几个分组（`0` 表示不限）：新增通道时用来判断还能不能变成新分组，见「新增通道」 |
 | `channelGroupMaxLines` | `number` | `0` | 一个分组最多几条回线（`0` 表示不限）：新增通道时用来判断还能不能并进某一组，见「新增通道」 |
-| `channelDraftStyle` | `GisViewChannelDraftStyle` | 蓝色 2px + 两端圆点 | 新增通道草稿线（选好起点之后跟随光标的那条预览线）的样式：`color` / `width` / `dot` |
+| `channelDraftStyle` | `GisViewChannelDraftStyle` | 蓝色 2px + 两端圆点，箭头关闭 | 新增通道草稿预览的全局样式：`color` / `width` / `dot` / `dotColor` / `arrow` / `arrowSize` / `arrowPositions` / `arrowReverse` / `arrowColor` / `circuitSpacing` / `opacity` / `customDraw`；`beginAddChannel({ channelDraftStyle })` 可按这一次草稿覆盖，`updateAddChannelStyle(patch)` 可在草稿期间增量修改 |
+| `webglLayers` | `GisViewWebGLLayer[]` | `[]` | WebGL 自定义绘制层：每层提供 `draw({ gl, canvas, viewport, camera, frame, project, unproject, requestRender })`，在内置内容之后按 `order` 绘制；运行时也可用 `addWebGLLayer` / `updateWebGLLayer` / `removeWebGLLayer` 维护 |
 | `background` | `GisViewBackground` | 浅色底 | 背景层，支持底色、图片与 GeoJSON |
 | `pointStyle` | `GisViewPointStyle` | 见下 | 点的默认样式，可被单个点覆盖；运行时按字段合并用 `updatePointStyle(patch)`（`updateOptions({ pointStyle })` 是整份换） |
 | `lineStyle` | `GisViewLineStyle` | 见下 | 线的默认样式，可被单条线覆盖；运行时按字段合并用 `updateLineStyle(patch)` |
 | `pointRules` / `lineRules` | `GisViewPointRule[]` / `GisViewLineRule[]` | `[]` | 批量样式规则：按属性给点 / 线批量配色、改大小、换符号，见「批量样式规则」 |
 | `heatmap` | `GisViewHeatmap \| null` | 无 | 热力图：按业务字段的数值到渐变色带上取颜色，并可按同一个值缩放节点大小 / 线宽，作用对象可选节点 / 线路 / 通道；不配（或 `null`）就是关的，见「热力图」 |
-| `effects` | `GisViewEffectsInput` | 关 | 动画效果（全局缺省）：线路上的跑动图标（`line`，ECharts `lines.effect` 那一类）与节点上的扩散涟漪（`point`，`effectScatter` 那一类），逐要素用 `points[].effect` / `lines[].effect` 覆盖；没配就是关的，但「只在数据里逐条配了 `effect`」的场景照样会动。`false` 或 `{ enabled: false }` 是**一处关掉**（谁都别动）；运行时有 `setEffects()` / `getEffects()` / `getLineEffects()`，见「动画效果（effects）」 |
+| `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）」 |
 | `label` | `GisViewLabelOptions \| GisViewLabelOptions[]` | 无 | 节点标签：内容 / 位置 / 显隐 / 避让 / 拖动与编辑都可配，**写数组就是同一个节点上多条标签**，与 `lineLabel` 共用一套避让网格，见「节点标签」 |
 | `labelOptimize` | `boolean` | `false` | 标签显示优化开关：**缺省关 = 强制显示**（不避让、不按 `maxCount` 截断、不设 `scanLimit` / 扫描预算，节点 / 线路的每个可见要素该出现的标签一条不少）；写 `true` 与从前一致 —— 避让 / 换落点 / 数量上限 / 候选上限全部生效。标签订得密、数据量大（十万级）时建议打开，见「标签显示优化开关」 |
+| `labelRender` | `'auto' \| 'dom'` | `'auto'` | 纯文本标签的容器渲染方式：`auto` 在强制显示档（`labelOptimize` 未开且未进密集档）下，同一层纯文本标签达到 1024 条时改画到一张 Canvas，不再逐条建 `div`；HTML / 元素内容 / 可拖拽 / 可编辑 / 超出 Canvas 样式能力的标签仍走 DOM。`dom` 始终逐条建 `.gis-view__label`。只影响容器，不改内容、锚点、显隐与 `html` 解析，见「标签容器渲染（labelRender）」 |
 | `lineLabel` | `GisViewLineLabelOptions \| GisViewLineLabelOptions[]` | 无 | 线路标签：位置沿线走（比例 / 百分比 / 绝对距离），内容、避让、显隐都可配，与节点标签共用一套避让网格；**写数组就是同一条线上多条标签**，见「线路标签」 |
 | `labelStates` | `GisViewLabelState[]` | 无 | 标签的运行时状态（`getLabelStates()` 的那一份：拖出来的偏移、改过的内容与样式、运行时加的标签、隐藏覆盖）：创建时喂回来就回显，等价于创建之后调 `setLabelStates(states)`；`updateOptions({ labelStates })` 同样认。`exportData({ format: 'input' })` 的结果里就叫 `labelStates`，存档 → 回灌直接接上 |
+| `graphics` | `GisViewGraphic[]` | 无 | 与节点无关的扩展图形：按世界坐标放 SVG 路径 / 图片 / Canvas，支持锚点、偏移、旋转、透明度、`zIndex` 与 `scaleWithView`；位于画布之上、标签之下，运行时用 `addGraphic` / `addGraphics` / `updateGraphic` / `removeGraphic` / `clearGraphics` 增删改，见「扩展图形（graphic）」 |
 | `tooltip` | `GisViewTooltipOptions` | 无 | 悬停提示：点 / 线 / 通道分别配置内容，见「悬浮提示」 |
-| `minimap` | `GisViewMinimapOptions \| null` | 无 | 内置鹰眼图：位置、尺寸、节点 / 线路 / 视口框三份样式与交互都可配，`extent` 决定小图按数据范围还是「数据 ∪ 底图」铺（默认 `auto`，GeoJSON 底图不会缩成一个点），`zoomable` 打开后小图自身可整体放大缩小（空白处拖动可以平移小图或直接框选让主图显示过去，每格倍率 `zoomStep`），通道还能只画一根；小图同样支持规则（`pointRules` / `lineRules`，缺省沿用主图规则的颜色与层级），可以只画某几层（`levels`）、关掉分层叠画（`layered`）、按三组系数给节点与线路定尺寸（整体倍数 `pointSizeScale` / `lineWidthScale`、跟随小图倍数 `pointZoomScale` / `lineZoomScale`（只在小图自身倍数 ≠ 1 时起作用）、跟随主视图地图倍数 `pointMapZoomScale` / `lineMapZoomScale`），视口框与框选矩形的颜色 / 背景 / 边框 / 圆角也能配（`boxStyle` / `selectStyle`），`extent` 还能直接写死一份世界范围、容器可加 `className` / `style`、`draw` 钩子每帧自己往上画一层，不配则不产生任何 DOM，见「鹰眼图」 |
+| `minimap` | `GisViewMinimapOptions \| null` | 无 | 内置鹰眼图：位置、尺寸、节点 / 线路 / 视口框三份样式与交互都可配，`extent` 决定小图按数据范围还是「数据 ∪ 底图」铺（默认 `auto`，GeoJSON 底图不会缩成一个点），`zoomable` 打开后小图自身可整体放大缩小（空白处拖动可以平移小图或直接框选让主图显示过去，每格倍率 `zoomStep`），通道还能只画一根；小图同样支持规则（`pointRules` / `lineRules`，缺省沿用主图规则的颜色与层级），可以只画某几层（`levels`）、关掉分层叠画（`layered`）、按三组系数给节点与线路定尺寸（整体倍数 `pointSizeScale` / `lineWidthScale`、跟随小图倍数 `pointZoomScale` / `lineZoomScale`（只在小图自身倍数 ≠ 1 时起作用）、跟随主视图地图倍数 `pointMapZoomScale` / `lineMapZoomScale`），视口框与框选矩形的颜色 / 背景 / 边框 / 圆角也能配（`boxStyle` / `selectStyle`），`extent` 还能直接写死一份世界范围、容器可加 `className` / `style`、`layers` 按 `placement` 分数据前 / 数据后、段内按 `order` 拆出多层自绘内容（旧 `draw` 钩子仍兼容并排在最后）、`onInteraction` 在手势结束时给出类型 / 世界坐标 / 相机、`maxPixelRatio` 限制备份倍率上限，不配则不产生任何 DOM，见「鹰眼图」 |
 | `filter` | `GisViewFilterInput \| null` | 无 | 初始筛选条件，等价于创建之后调用 `setFilter`，见「筛选」 |
 | `filterWorker` | `boolean \| GisViewFilterWorkerOptions` | `{ threshold: 20000 }` | 筛选是否用 Web Worker 计算：默认点 + 线总数超过阈值才用，`false` 表示始终同步算 |
 | `searchWorker` | `boolean \| GisViewSearchWorkerOptions` | `{ threshold: 20000 }` | [异步搜索](14-视图与筛选.md#搜索与定位)是否用 Web Worker 计算：默认点 + 线总数超过阈值才用，`false` 表示 `searchAsync` 也同步算；同步的 `search` 一直在主线程算，不受这一项影响 |
@@ -54,8 +58,9 @@
 | `selectionKinds` | `GisViewSelectionKindsInput` | 无（框选只收节点；Ctrl 多选收节点 / 线路 / 通道） | 框选与 Ctrl / 多选点击的类型过滤：`'point'` 节点、`'line'` 通道外的独立线路、`'channel'` 通道回线；可写数组任意组合，`'all'` / `true` 全开，`false` / `null` 全关。通道回线只归 `channel` 管，通道外的线路只归 `line` 管；通道回线仍按 `channelSelectMode` 摊开。不写时保留旧口径；普通单选与 `select` / `selectFeatures` 不受它限制。运行时走 `updateOptions({ selectionKinds })`，见「框选」与「选择类型过滤」 |
 | `selectionBoxStyle` | `GisViewSelectionBoxStyle` | 蓝底 0.16 透明 + 1px 蓝框 | 框选矩形的填充与边框：`fill`、`fillOpacity`、`stroke`、`strokeWidth` |
 | `selectionOnTop` | `boolean` | `true` | 选中的节点 / 拖动中的整组 / 待确认合并的目标节点，以及选中线路所在的整条通道，是否画在所有要素之上（与 `zIndex` 无关），见「选中 / 拖动的层级」 |
-| `channelSelectMode` | `'line' \| 'group' \| 'channel'` | `'line'` | 通道选中模式：点中通道里的一条回线时选中什么 —— `'line'` 只选这一条、`'group'` 连它所在的分组一起、`'channel'` 整条通道（所有分组的回线）；通道以外的线路永远只选自己。Ctrl / ⌘ + 点击在 `group` / `channel` 下按整批取反；切换走 `updateOptions({ channelSelectMode })`，只重画一帧、不重排场景，见「通道选中模式」 |
-| `waypointEditable` | `boolean` | `false` | 是否允许编辑线路拐点（按住加点快捷键 `shortcuts.addWaypoint`（默认 Ctrl / ⌘）+ 点击添加、拖动移动、双击或删除快捷键删除），单条线可用 `waypointEditable` 覆盖；**缺省关**，写 `waypointEditable: true` 或 `features: { waypoint: true }` 才开 |
+| `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 })`，下一次拖动生效，见「分组拐点拖动模式」 |
+| `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` 没配时选中拐点用内置强调环，见「线路拐点」的「拐点样式」小节 |
 | `cursorStyle` | `GisViewCursorStyle` | 见「光标」 | 鼠标光标按分类配置：`idle` / `pan` / `box` / `drag` / `draft` / `point` / `line` / `channel` / `waypoint` 九类，每类可以给系统关键字、CSS 变量或图片（`{ url, hotspot, fallback }`），`ctrl` 里再配按住 Ctrl / ⌘ 时的替代值；节点 / 线路 / 通道还能用 `cursor` / `ctrlCursor` 逐要素覆盖，详见「光标」 |
@@ -70,7 +75,7 @@
 | `shortcuts` | `GisViewShortcuts` | 见「快捷键」 | 所有快捷键都可自定义：框选 / 多选 / 加点 / 复制 / 粘贴 / 取消 / 删除 / 适应视图，没写的动作沿用默认值，写 `false` 等于关掉这个动作的快捷键 |
 | `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` 开关、`distance` 碰撞容差（CSS 像素）、`confirm`（不写停在 `pending` 等使用方裁决 / `false` 直接合并 / 函数自行裁决）、`channelGroups`（`'keep'` 各自保留分组 / `'merge'` 合成一个分组）、`createItem` 定制合并结果，见「节点合并」 |
+| `merge` | `GisViewMergeOptions` | 缺省关 | 合并节点（**写了这份配置才算开**，`enabled: false` 显式关掉）：`enabled` 开关、`trigger` 触发时机（`'collision'` 两个节点半径相碰 / `'center'` 拖动节点中心进入目标节点区域）、`distance` 额外像素容差、`confirm`（不写停在 `pending` 等使用方裁决 / `false` 直接合并 / 函数自行裁决）、`channelGroups`（`'keep'` 各自保留分组 / `'merge'` 合成一个分组）、`createItem` 定制合并结果，见「节点合并」 |
 | `minScale` / `maxScale` | `number` | `0.002` / `20000` | 缩放范围（像素 / 世界单位） |
 | `fitPadding` | `number` | `48` | 适应视图时四周留白（CSS 像素）；留白比画布还大时按「内容至少留 48px」反过来压留白，不会把内容挤成一个点 |
 | `fitOnInit` | `boolean` | `true` | 首次拿到数据时自动适应视图；配了 `initialView` 时以它为准（`false` 只关掉「适应」，`initialView` 仍然生效，见「初始视图」） |
@@ -78,7 +83,7 @@
 | `progressiveInit` | `boolean` | `true` | 大数据（2 万点以上）初始化是否从视图中心向外发散渲染：首帧只排中心附近的一批，剩下的分帧往外补，见「大数据量」 |
 | `statsInterval` | `number` | `250` | `onStats` 的最小间隔（毫秒），`0` 表示每帧都发 |
 | `renderEmitInterval` | `number` | `400` | `onRender` 的节流间隔（毫秒），`0` 与 `onStats` 同拍（再配上 `statsInterval: 0` 就是每帧一条） |
-| `plugins` | `GisViewPlugin[]` | `[]` | 插件：`view => hook`，返回的 `destroy` 在实例销毁时倒序回调，见「插件」 |
+| `plugins` | `GisViewPlugin[]` | `[]` | 插件：`(view, context) => hook`，返回的 `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 |
@@ -99,13 +104,13 @@
 | --- | --- |
 | 总开关与历史 | `features` · `history` |
 | 数据与背景 | `points` · `lines` · `channels` · `background` |
-| 通道几何 | `channelWidth` · `channelInset` · `channelNodeWidth` · `channelTangentInset` · `channelMaxGroups` · `channelGroupMaxLines` · `channelDraftStyle` · `channelSelectMode` |
-| 样式与规则 | `pointStyle` · `lineStyle` · `pointRules` / `lineRules` · `heatmap` · `effects` · `lineDirection` · `prebake` · `label` · `labelOptimize` · `lineLabel` · `labelStates` · `tooltip` · `pointSizeScale` / `lineWidthScale`、`pointZoomScale` / `lineZoomScale`、`zoomBaseScale` · `cursorStyle` · `gridColor` · `gridSize` · `showGrid` |
+| 通道几何 | `channelWidth` · `channelInset` · `channelNodeWidth` · `channelTangentInset` · `channelMaxGroups` · `channelGroupMaxLines` · `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` · `waypointEditable` · `waypointVisibility` · `interactive` · `preventContextMenu` · `clickable` · `draggable` · `liveDrag` · `shortcuts` · `copy` · `remove` · `merge` |
 | 视图与相机 | `minScale` / `maxScale` · `fitPadding` · `fitOnInit` · `initialView` · `zoomStep` |
-| 画质与渲染 | `quality` · `width` / `height` · `pixelRatio` · `maxCanvasPixels` · `antialias` · `interactionThinLines` · `interactionNoMsaa` · `renderer` |
-| 大数据（筛选 / 搜索 / 读数） | `filter` · `filterWorker` · `searchWorker` · `progressiveInit` · `statsInterval` · `renderEmitInterval` |
+| 画质与渲染 | `quality` · `width` / `height` · `pixelRatio` · `maxCanvasPixels` · `antialias` · `interactionThinLines` · `interactionNoMsaa` · `renderer` · `webglLayers` |
+| 大数据（筛选 / 搜索 / 读数） | `denseMode` · `filter` · `filterWorker` · `searchWorker` · `progressiveInit` · `statsInterval` · `renderEmitInterval` |
 | 外部界面与集成 | `minimap` · `plugins` · `ariaLabel` |
 
 ### 总开关与历史
@@ -175,7 +180,7 @@ const lines = [
 
 - **类型**：`GisViewChannel[]`
 - **默认值**：`[]`
-- **说明**：通道：把若干条线路组织成并行敷设的多回线走廊，回线几何由骨架折线按偏移推导；两端可用 `from` / `to` 绑在节点上
+- **说明**：通道：把若干条线路组织成并行敷设的多回线走廊，回线几何由骨架折线按偏移推导；两端可用 `from` / `to` 绑在节点上，每条通道可写 `visible: false` 整条收起（成员回线、分组与拐点保留，改回 `true` 恢复）
 - **示例**：
 
 ```js
@@ -252,17 +257,24 @@ view.updateOptions({ channelWidth: 0.08 })   // 没绑节点的那几条跟着
 #### `channelDraftStyle`
 
 - **类型**：`GisViewChannelDraftStyle`
-- **默认值**：蓝色 2px + 两端圆点
-- **说明**：新增通道草稿线（选好起点之后跟随光标的那条预览线）的样式：`color` / `width` / `dot`
+- **默认值**：蓝色 2px + 两端圆点，箭头关闭
+- **说明**：新增通道草稿预览的全局样式：`color` / `width` / `dot` / `dotColor` / `arrow` / `arrowSize` / `arrowPositions` / `arrowReverse` / `arrowColor` / `circuitSpacing` / `opacity` / `customDraw`。`kind: 'channel'` 且 `circuits > 1` 时按 `circuitSpacing` 画出平行回线；`arrowPositions` 是沿线归一化位置（单个数或数组），`customDraw` 可拿最终 GL 上下文与每条回线路径自绘；`routing: 'orthogonal'` 时折线预览同样分段绘制。真实线路箭头仍看 `direction`，预览箭头只影响草稿
 - **参考**：见「新增通道」一节，子字段在那里的表里逐个展开
 
 #### `channelSelectMode`
 
 - **类型**：`'line' | 'group' | 'channel'`
 - **默认值**：`'line'`
-- **说明**：通道选中模式：点中通道里的一条回线时选中什么 —— `'line'` 只选这一条、`'group'` 连它所在的分组一起、`'channel'` 整条通道（所有分组的回线）；通道以外的线路永远只选自己。Ctrl / ⌘ + 点击在 `group` / `channel` 下按整批取反；切换走 `updateOptions({ channelSelectMode })`，只重画一帧、不重排场景，见「通道选中模式」
+- **说明**：通道选中模式：点中通道里的一条回线时选中什么 —— `'line'` 只选这一条、`'group'` 连它所在的分组一起、`'channel'` 整条通道（所有分组的回线）；通道以外的线路永远只选自己。普通点选与 Ctrl / ⌘ + 点击加点共用这一档高亮范围；Ctrl / ⌘ + 点击在 `group` / `channel` 下按整批取反；切换走 `updateOptions({ channelSelectMode })`，只重画一帧、不重排场景，见「通道选中模式」
 - **参考**：见「通道选中模式（channelSelectMode）」一节，子字段在那里的表里逐个展开
 
+#### `channelWaypointDragMode`
+
+- **类型**：`'parallel' | 'vertex'`
+- **默认值**：`'parallel'`
+- **说明**：分组拐点拖动模式。`'parallel'` 沿用共用骨架 + 平行偏移，拖动时拐角处的相邻顶点可能随 miter 一起微调；`'vertex'` 只把当前分组同一 `pathIndex` 的拐点按相同世界增量平移，组内每条回线都跟着这个序号走，其他拐点与其它分组保持不动。普通线路不受这一项影响；`'vertex'` 的结果写进 `groups[].waypointOffsets`（键按含首尾端点的骨架序号算，只认中间拐点），切换走 `updateOptions({ channelWaypointDragMode })`，下一次拖动生效。切换模式不会清掉已有偏移；要恢复纯平行骨架，重写分组声明并带上当前 `path`、省略 `waypointOffsets`
+- **参考**：见「分组拐点拖动模式（channelWaypointDragMode）」与「分组拐点：把某一组拉走」
+
 ### 样式与规则
 
 #### `pointStyle`
@@ -322,7 +334,7 @@ view.updateOptions({ heatmap: { enabled: false } })   // 关掉回正常配色
 
 - **类型**：`GisViewEffectsInput`
 - **默认值**：关
-- **说明**：动画效果（全局缺省）：线路上的跑动图标（`line`，ECharts `lines.effect` 那一类）与节点上的扩散涟漪（`point`，`effectScatter` 那一类），逐要素用 `points[].effect` / `lines[].effect` 覆盖；没配就是关的，但「只在数据里逐条配了 `effect`」的场景照样会动。`false` 或 `{ enabled: false }` 是**一处关掉**（谁都别动）；运行时有 `setEffects()` / `getEffects()` / `getLineEffects()`，见「动画效果（effects）」
+- **说明**：动画效果（全局缺省）：线路上的跑动图标（`line`，ECharts `lines.effect` 那一类）与节点上的扩散涟漪（`point`，`effectScatter` 那一类），逐要素用 `points[].effect` / `lines[].effect` 覆盖；没配就是关的，但「只在数据里逐条配了 `effect`」的场景照样会动。`false` 或 `{ enabled: false }` 是**一处关掉**（谁都别动）；运行时有 `updateOptions({ effects })` / `getEffects()` / `getLineEffects()`，见「动画效果（effects）」
 - **参考**：见「动画效果（effects）」一节，子字段在那里的表里逐个展开
 - **示例**：
 
@@ -374,6 +386,13 @@ view.updateOptions({ prebake: { combos: view.getSymbolCombos().combos } })
 - **说明**：标签显示优化开关：**缺省关 = 强制显示**（不避让、不按 `maxCount` 截断、不设 `scanLimit` / 扫描预算，节点 / 线路的每个可见要素该出现的标签一条不少）；写 `true` 与从前一致 —— 避让 / 换落点 / 数量上限 / 候选上限全部生效。标签订得密、数据量大（十万级）时建议打开，见「标签显示优化开关」
 - **参考**：见「标签显示优化开关（labelOptimize）」一节，子字段在那里的表里逐个展开
 
+#### `labelRender`
+
+- **类型**：`'auto' | 'dom'`
+- **默认值**：`'auto'`
+- **说明**：纯文本标签的画法。`auto` 只在**强制显示档**（缺省 `labelOptimize: false` 且 `denseMode` 未激活）启用：节点层或线路层里可画布的纯文本标签达到 **1024** 条时，该层改用一张 Canvas，不再逐条建 `.gis-view__label`；`html: true`、函数返回 `HTMLElement`、可拖拽 / 可编辑，以及带 Canvas 不支持样式的标签仍保留 DOM。`dom` 始终走逐条 DOM，保持旧行为。它和 `html` 是两件事：`html` 只控制字符串按文本还是 HTML 解析，`html: false` 仍然会建 `div`；见「标签容器渲染（labelRender）」
+- **参考**：见「标签容器渲染（labelRender）」一节
+
 #### `lineLabel`
 
 - **类型**：`GisViewLineLabelOptions | GisViewLineLabelOptions[]`
@@ -388,6 +407,26 @@ view.updateOptions({ prebake: { combos: view.getSymbolCombos().combos } })
 - **说明**：标签的运行时状态（`getLabelStates()` 的那一份：拖出来的偏移、改过的内容与样式、运行时加的标签、隐藏覆盖）：创建时喂回来就回显，等价于创建之后调 `setLabelStates(states)`；`updateOptions({ labelStates })` 同样认。`exportData({ format: 'input' })` 的结果里就叫 `labelStates`，存档 → 回灌直接接上
 - **参考**：见「标签的拖动与编辑」一节，子字段在那里的表里逐个展开
 
+#### `graphics`
+
+- **类型**：`GisViewGraphic[]`
+- **默认值**：无
+- **说明**：与节点 / 线路数据无关的扩展图形层（参考 ECharts 的 `graphic`）：每一条按世界坐标 `x` / `y` 锚在视图上，支持 `type: 'path' | 'image' | 'canvas'`、`anchor`、`offset`、`rotation`、`scale`、`opacity`、`visible`、`zIndex` 与 `scaleWithView`。图形排在 WebGL 画布之上、标签层之下，不参与指针拾取；相机移动 / 缩放与容器 resize 时自动重投影，PNG / SVG 导出都会带上。运行时用 `addGraphic` / `addGraphics` / `updateGraphic` / `removeGraphic` / `clearGraphics` 增删改，读回用 `getGraphic` / `getGraphics`
+- **参考**：见「12 标签与装饰」的「扩展图形（graphic）」一节，逐字段写法、锚点与导出说明都在那里
+- **示例**：
+
+```js
+createGisView(container, {
+  graphics: [
+    { id: 'logo', type: 'image', src: '/logo.png', x: 120, y: 80, width: 48, height: 48, anchor: 'bottom-left' },
+    { id: 'frame', type: 'path', d: 'M0 0H100V60H0Z', viewBox: [0, 0, 100, 60], x: 0, y: 0, width: 120, height: 72, fill: 'none', stroke: '#2f6fd0' }
+  ]
+})
+
+view.addGraphic({ id: 'pin', type: 'path', d: 'M0 0L8 20L16 0Z', viewBox: [0, 0, 16, 20], x: 60, y: 40, width: 16, height: 20, fill: '#e35b5b', scaleWithView: true })
+view.clearGraphics()
+```
+
 #### `tooltip`
 
 - **类型**：`GisViewTooltipOptions`
@@ -564,7 +603,7 @@ view.selectInBox(rect, { selectionKinds: 'channel' }) // 仅这一次只框通
 
 - **类型**：`boolean`
 - **默认值**：`false`
-- **说明**：是否允许编辑线路拐点（按住加点快捷键 `shortcuts.addWaypoint`（默认 Ctrl / ⌘）+ 点击添加、拖动移动、双击或删除快捷键删除），单条线可用 `waypointEditable` 覆盖；**缺省关**，写 `waypointEditable: true` 或 `features: { waypoint: true }` 才开
+- **说明**：是否允许编辑线路拐点（按住加点快捷键 `shortcuts.addWaypoint`（默认 Ctrl / ⌘）+ 点击添加、拖动移动、双击或删除快捷键删除），单条线可用 `waypointEditable` 覆盖；**缺省关**，写 `waypointEditable: true` 或 `features: { waypoint: true }` 才开。`false`（以及 `features: { waypoint: false }`）会同时关闭新增、移动与删除，没有只关其中一项的细分开关；`shortcuts.addWaypoint` 仍只决定加点的组合键
 - **参考**：见「线路拐点」一节，子字段在那里的表里逐个展开
 
 #### `waypointVisibility`
@@ -662,7 +701,8 @@ view.resolveRemove('all')         // 或 'points' / false
 | 字段 | 类型 | 默认值 | 说明 |
 | --- | --- | --- | --- |
 | `enabled` | `boolean` | 写了 `merge` 即 `true` | 是否启用合并；显式 `false` 关掉。`features.merge` 也能强制打开 / 关掉 |
-| `distance` | `number` | `0` | 额外碰撞容差（CSS 像素）：两个节点画在屏幕上的半径之和再加它才算撞上，负数按 0 处理 |
+| `trigger` | `'collision' \| 'center'` | `'collision'` | 触发时机：`collision` 按两个节点画在屏幕上的半径之和判断，响应更早；`center` 只要求拖动的节点中心进入目标节点的屏幕区域，更晚、更稳。两种都再叠加 `distance` 容差 |
+| `distance` | `number` | `0` | 额外触发容差（CSS 像素）：`collision` 加在两个节点半径之和上，`center` 加在目标节点半径上，负数按 0 处理 |
 | `confirm` | `false \| (payload) => boolean \| void \| Promise<boolean \| void>` | 不写（停在 `pending`） | 确认方式：不写时组件不弹任何界面，等使用方调 `payload.confirm()` / `resolvePointMerge()`；`false` 松手直接合并；函数自行裁决，返回 / resolve `false` 取消，返回 `undefined` 表示继续等使用方接管 |
 | `channelGroups` | `'keep' \| 'merge'` | `'keep'` | 两个节点合并后、两端撞成同一条通道时回线怎么分组：`keep` 各自保留原分组，`merge` 合成一个分组（回线取并集） |
 | `createItem` | `(source, target, context) => GisViewPoint` | 内置合并规则 | 整份接管合并后的节点数据。`context` 含双方数据 / 坐标 / 样式快照 / `lines` / `channels` / `view`；不写时按「目标优先、来源独有字段带过来、尺寸取双方最大、图标优先目标」合并，坐标与 id 始终取保留端 |
@@ -672,7 +712,7 @@ view.resolveRemove('all')         // 或 'points' / false
 - **示例**：
 
 ```js
-createGisView(container, { merge: { enabled: true, distance: 12, confirm: true } })
+createGisView(container, { merge: { enabled: true, trigger: 'center', distance: 6, confirm: false } })
 view.mergePoints('a', 'b')        // 接口合并
 view.getPointMerge()              // 待确认时读预览
 view.getLine('l1')                 // impact.lineIds 里的 id 按它查线路详情
@@ -784,8 +824,48 @@ const view = createGisView(container, { renderer: 'webgl2' })   // 连 WebGPU
 view.getRendererInfo()   // { backend: 'webgl2', webgpu: { available, reason } }
 ```
 
+#### `webglLayers`
+
+- **类型**：`GisViewWebGLLayer[]`
+- **默认值**：`[]`
+- **说明**：WebGL 自定义绘制层。每层写 `{ id, order, enabled, draw }`，`draw({ gl, canvas, viewport, camera, frame, project, unproject, requestRender })` 在内置内容与后备缓冲贴回之后执行；`order` 从小到大排序，`enabled: false` 跳过该层。每层开画前会重置帧缓冲、viewport、混合与 scissor 等状态，前一层改过的 GL 状态不会漏给下一层。层只叠加画面，不参与拾取、场景解析或数据导出；`view.gl` 也可直接取到同一个 WebGL2 上下文
+- **参考**：见「WebGL 自定义层」一节，运行动画可在 `draw` 里调用 `requestRender()`
+- **示例**：
+
+```js
+const removeLayer = view.addWebGLLayer({
+  id: 'overlay',
+  order: 10,
+  draw({ gl, canvas, project, requestRender }) {
+    const [x, y] = project(120, 30) // 世界坐标 → 画布 CSS 像素
+    // 在这里用自己的 shader / 缓冲区绘制；数据变化时调用 requestRender()
+    requestRender()
+  }
+})
+
+view.updateWebGLLayer('overlay', { enabled: false }) // 暂不画，但保留层
+view.removeWebGLLayer('overlay')                     // 删除这一层
+removeLayer()                                        // 卸载函数也幂等
+```
+
 ### 大数据（筛选 / 搜索 / 读数）
 
+#### `denseMode`
+
+- **类型**：`GisViewDenseModeInput`
+- **默认值**：`'auto'`
+- **说明**：大数据展示模式：`'auto'`（缺省）按三路信号自动判定 —— 视口内可见节点达到 `visibleThreshold`（4000）、可见密度达到 `densityThreshold`（每百万 CSS 像素 3000 个），或数据总量达到 `pointThreshold`（50000）；任意一项越线就进入密集档，`'on'` / `'off'`（布尔值 `true` / `false` 等价）强制开关。对象写法 `{ mode, visibleThreshold, densityThreshold, pointThreshold }` 可改阈值，阈值只认正数。判定延迟 160 ms；退出时留 22% 缓冲（回落到进入阈值的 78% 才恢复），避免在边界附近来回缩放时标签层反复重排。密集档内标签自动走避让 / 截断（与 `labelOptimize: true` 同一条路），线路动点与节点涟漪暂停，用户原来的 `effects` 配置仍保留在 `getOptions()` 里；退出后自动恢复。运行时用 `updateOptions({ denseMode })` 切换，当前档位、判定依据与可见节点数看 `getStats().dense`
+- **参考**：见「大数据展示模式（denseMode）」一节，三档阈值与回滞、读数形状都在那里展开
+
+```js
+const view = createGisView(container, {
+  points, lines,
+  denseMode: { mode: 'auto', visibleThreshold: 2500, densityThreshold: 2000 }
+})
+view.updateOptions({ denseMode: 'off' })   // 临时强制关闭
+const { dense } = view.getStats()         // { mode, active, reason, visiblePoints, thresholds… }
+```
+
 #### `filter`
 
 - **类型**：`GisViewFilterInput | null`
@@ -838,7 +918,7 @@ view.setFilter(null)     // 清掉筛选
 
 - **类型**：`GisViewMinimapOptions | null`
 - **默认值**：无
-- **说明**：内置鹰眼图：位置、尺寸、节点 / 线路 / 视口框三份样式与交互都可配，`extent` 决定小图按数据范围还是「数据 ∪ 底图」铺（默认 `auto`，GeoJSON 底图不会缩成一个点），`zoomable` 打开后小图自身可整体放大缩小（空白处拖动可以平移小图或直接框选让主图显示过去，每格倍率 `zoomStep`），通道还能只画一根；小图同样支持规则（`pointRules` / `lineRules`，缺省沿用主图规则的颜色与层级），可以只画某几层（`levels`）、关掉分层叠画（`layered`）、按三组系数给节点与线路定尺寸（整体倍数 `pointSizeScale` / `lineWidthScale`、跟随小图倍数 `pointZoomScale` / `lineZoomScale`（只在小图自身倍数 ≠ 1 时起作用）、跟随主视图地图倍数 `pointMapZoomScale` / `lineMapZoomScale`），视口框与框选矩形的颜色 / 背景 / 边框 / 圆角也能配（`boxStyle` / `selectStyle`），`extent` 还能直接写死一份世界范围、容器可加 `className` / `style`、`draw` 钩子每帧自己往上画一层，不配则不产生任何 DOM，见「鹰眼图」
+- **说明**：内置鹰眼图：位置、尺寸、节点 / 线路 / 视口框三份样式与交互都可配，`extent` 决定小图按数据范围还是「数据 ∪ 底图」铺（默认 `auto`，GeoJSON 底图不会缩成一个点），`zoomable` 打开后小图自身可整体放大缩小（空白处拖动可以平移小图或直接框选让主图显示过去，每格倍率 `zoomStep`），通道还能只画一根；小图同样支持规则（`pointRules` / `lineRules`，缺省沿用主图规则的颜色与层级），可以只画某几层（`levels`）、关掉分层叠画（`layered`）、按三组系数给节点与线路定尺寸（整体倍数 `pointSizeScale` / `lineWidthScale`、跟随小图倍数 `pointZoomScale` / `lineZoomScale`（只在小图自身倍数 ≠ 1 时起作用）、跟随主视图地图倍数 `pointMapZoomScale` / `lineMapZoomScale`），视口框与框选矩形的颜色 / 背景 / 边框 / 圆角也能配（`boxStyle` / `selectStyle`），`extent` 还能直接写死一份世界范围、容器可加 `className` / `style`、`layers` 按 `placement` 分数据前 / 数据后、段内按 `order` 拆出多层自绘内容（旧 `draw` 钩子仍兼容并排在最后）、`onInteraction` 在手势结束时给出类型 / 世界坐标 / 相机、`maxPixelRatio` 限制备份倍率上限，不配则不产生任何 DOM，见「鹰眼图」
 - **参考**：见「鹰眼图」一节，子字段在那里的表里逐个展开
 
 ```js
@@ -847,9 +927,14 @@ createGisView(container, {
 		enabled: true,
 		width: 220,
 		height: 130,
-		position: 'right-bottom',
+		position: 'bottom-right',
 		levels: [1, 5, 20],
-		pointStyle: { color: '#2f6fed' }
+		pointStyle: { color: '#2f6fed' },
+		layers: [
+			{ id: 'grid', placement: 'below-data', draw: ({ context, width, height }) => { /* 网格 */ } },
+			{ id: 'north', placement: 'above-data', draw: ({ context, width }) => { /* 指北针 */ } }
+		],
+		onInteraction: info => console.log(info.type, info.world)
 	}
 })
 ```
@@ -858,14 +943,14 @@ createGisView(container, {
 
 - **类型**：`GisViewPlugin[]`
 - **默认值**：`[]`
-- **说明**：插件：`view => hook`，返回的 `destroy` 在实例销毁时倒序回调，见「插件」
+- **说明**：插件：`(view, context) => hook`，返回的 `destroy` 在实例销毁时倒序回调，见「插件」
 - **参考**：见「插件」一节，子字段在那里的表里逐个展开
 - **示例**：
 
 ```js
 const view = createGisView(container, {
-	plugins: [view => ({
-		destroy() { /* 插件自己的清理 */ }
+	plugins: [(view, context) => ({
+		destroy() { /* context.apiVersion 当前为 1 */ }
 	})]
 })
 ```

package/docs/manual/04-/344/272/213/344/273/266/344/270/216/345/233/236/350/260/203.md

@@ -19,12 +19,13 @@
 | `onPointer` | `GisViewPointerState` | 光标每次移动（含移出画布）都发：`{ inside, screen, world, lngLat }`，屏幕坐标是画布 CSS 像素、`lngLat` 要有 GeoJSON 背景才有；`getPointer()` 随时能读同一份，移出时 `inside: false` |
 | `onPointDrag` | `GisViewPointDragPayload` | 拖拽点：`phase` 为 `start` / `drag` / `end`，载荷带最新坐标、本次移动的全部节点 `points` 与跟随移动的线路 `lines` |
 | `onPointCopy` | `GisViewPointCopyPayload \| GisViewBatchCopyPayload` | 复制节点：`phase` 为 `start` / `move` / `commit` / `end` / `cancel`（复制到剪贴板另有 `clipboard`，批量复制 / 整组粘贴是 `batch`），`commit` 阶段可以 `payload.cancel()` 取消、`payload.update()` / `setItem()` 改数据；`clipboard` 载荷带整组 `sources` / `items` / `lines` / `channels` / `count` / `anchor`，`batch` 载荷另带 `indexes` / `lineSources` / `channelSources` / `revert()`，见「节点复制」 |
-| `onPointMerge` | `GisViewPointMergePayload \| GisViewMergeResult \| GisViewMergeFailure \| GisViewMergeSelectedPayload` | 合并节点：拖到另一个节点上时先发 `pending`（组件不弹任何界面，在回调里调 `payload.confirm()` / `cancel()` 裁决，或存下来自己接界面），之后发 `confirm`（载荷里的 `item` 是合并结果，可改 / 可取消）、`cancel`，数据并完 / 并失败再发一条 `merge`（`ok: true` / `ok: false`）；框选 / 多选之后调 `mergeSelectedPoints()` 时**逐对发 `merge`**，收尾再发一条 `phase: 'mergeSelected'` 的汇总（`merged` 逐对列出、`skipped` 说明谁没并进去），见「节点合并」 |
+| `onPointMerge` | `GisViewPointMergePayload \| GisViewMergeResult \| GisViewMergeFailure \| GisViewMergeSelectedPayload` | 合并节点：拖到另一个节点上时先发 `pending`（组件不弹任何界面，在回调里调 `payload.confirm()` / `cancel()` 裁决，或存下来自己接界面），之后发 `confirm`（载荷里的 `item` 是合并结果，可改 / 可取消）、`cancel`，数据并完 / 并失败再发一条 `merge`（`ok: true` / `ok: false`）；拖拽入口的载荷带 `trigger`（`'collision'` / `'center'`），说明这一次按哪种时机命中；框选 / 多选之后调 `mergeSelectedPoints()` 时**逐对发 `merge`**，收尾再发一条 `phase: 'mergeSelected'` 的汇总（`merged` 逐对列出、`skipped` 说明谁没并进去），见「节点合并」 |
 | `onRemove` | `GisViewRemovePayload` | 删除请求（Delete 键 / `requestRemove()`）：`pending` 时给一份载荷说明要删什么、连带什么、能按哪些范围删（`points` / `lines` / `waypoints` / `groups` / `channels` / `actions` / `counts`），确认之后发 `phase: 'remove'`（`result` 是结果）、取消发 `phase: 'cancel'`；组件不弹任何界面，弹不弹、怎么弹都由使用方决定（在回调里调 `payload.confirm(scope)` / `payload.cancel()`，或存下来自己接界面），见「删除（remove）」 |
 | `onWaypointChange` | `GisViewWaypointPayload` | 拐点新增 / 选中 / 删除与拖动，`phase` 为 `add` / `select` / `remove` 或拖动时的 `start` / `move` / `end`，载荷带最新线路数据与所属集合的 `group_id`；通道内的回线共用骨架，载荷是**被操作的那条回线**的推导结果。同步后端只接改变数据的 `add` / `remove` / `end`，并用 `getChannelGroupWaypoints().path` 提交整份骨架，见「通道与多回线」 |
 | `onChannelContextMenu` | `GisViewChannelContextPayload \| null` | 右键点中通道回线：给出这条通道的上下文（有几组、当前是哪一组、分组列表与可用交互），点空白处给 `null`（用它收框）；**落在节点上时也给 `null`**（点的层级高于线，见「通道右键交互框」） |
-| `onChannelDraft` | `GisViewChannelDraftPayload` | 新增通道草稿：`start` / `from` / `ready` / `pick` / `restart` / `cancel` / `commit` / `blocked`，两个节点的信息与可选方案都在载荷里，见「新增通道」 |
+| `onChannelDraft` | `GisViewChannelDraftPayload` | 新增通道草稿：`start` / `from` / `ready` / `pick` / `restart` / `cancel` / `commit` / `blocked`，两个节点的信息、`routing` / `path` 与可选方案都在载荷里（`path` 是中间拐点），见「新增通道」 |
 | `onChannelDraftClick` | `GisViewChannelDraftPayload` | 草稿里**每点一次**都发一条：`step` 为 `1` 时拿到起点、`2` 时拿到终点（线路到此结束）；加上 `phase: 'pick'` 时是点在空白或点回起点；载荷与 `onChannelDraft` 相同 |
+| `onDecorationDraft` | `GisViewDecorationDraftPayload` | 动态装饰器草稿：`start` 开启 → `hover` 跟随命中线路或节点 / `leave` 移出收掉 → 左键在目标上松开发 `ready`（空白处不发）→ `commit` / `cancel`；`target` 为 `line` / `point` / `both`，`scope` 为 `line` / `group` / `channel`，节点侧 `placement` 为 `offset` / `fixed` / `pointer`，白名单、上限与重复策略见「动态装饰器草稿」 |
 | `onChannelGroupChange` | `GisViewChannelGroupChangePayload` | 分组变化：拆分 / 合并 / 挪线 / 新建组（`action.type` 为 `splitGroups` / `mergeGroups` / `moveLine` / `addGroup`）与整份声明跟着补丁换（`setGroups`，`updateChannel` 写 `groups` / `lineIds`）；`action` 带这一笔的 `groupId` / `groupIds` / `lineIds`（`updateLine` 顺带挪组时 `action.via` 为 `'updateLine'`），`item` / `groups` 是与 `dataChange('channelGroups')` 同一份的最新读数。同步后端时用 `getChannelGroups(channelId)` 提交整份声明，不按 action 猜 delta，见「通道分组」 |
 | `onLabelDrag` | `GisViewLabelDragPayload` | 标签被拖走（`draggable`）：`phase` 为 `start` / `move` / `end`，载荷带 `kind`（`point` / `line`）、`index` / `id` / `item`、当前偏移 `offset`、起手时的 `startOffset` 与本次位移 `delta`（CSS 像素），见「标签的拖动与编辑」 |
 | `onLabelClick` | `GisViewLabelClickPayload` | 点了一下标签（`editable`，位移小于 3 px 才算点选）：载荷带 `kind` / `index` / `id` / `item`、当前 `offset` 与这一条的状态读数 `state`，使用方按它选中这一条 |
@@ -77,14 +78,14 @@ const view = createGisView('#map', {
 
 | 载荷字段 | 说明 |
 | --- | --- |
-| `type` | 动作名：`updateData` / `updatePoints` / `updateLines` / `updateChannels` / `updateOptions` / `updateBackground` / `updatePoint` / `updateLine` / `updateChannel` / `pointDrag` / `copyPoint` / `copyPoints` / `mergePoints` / `waypoint` / `addChannel` / `addChannels` / `addChannelGroups` / `addLine` / `addPoints` / `addLines` / `removePoints` / `removeSelected` / `removeLines` / `removeLine` / `removeChannel` / `channelGroups` / `batch` |
+| `type` | 动作名：`updateData` / `updatePoints` / `updateLines` / `updateOptions` / `updateBackground` / `updatePoint` / `updateLine` / `updateChannel` / `pointDrag` / `copyPoint` / `copyPoints` / `mergePoints` / `waypoint` / `addChannel` / `addChannels` / `addChannelGroups` / `addLine` / `addPoints` / `addLines` / `removePoints` / `removeSelected` / `removeLines` / `removeLine` / `removeChannel` / `channelGroups` / `batch` |
 | `points` / `lines` / `channels` | 变更之后的最新数据（组件内部那一份的引用，只读，不要就地改） |
 | `counts` | `{ points, lines, channels }` 三个条数 |
 | `ok` / `reason` | 这一次调用成没成（`addPoints` / `addLines` / `removePoints` 这类批量接口会带上），`reason` 说明没成的原因 |
 | 动作专属字段 | 拖拽带 `movedPoints` / `movedLines`，复制带 `item` / `source` / `revert()`（`copyPoints` / 整组粘贴另有 `sources` / `items` / `indexes` / `lines` / `channels` / `count`），合并带 `source` / `target` / `removedLines` / `mergedChannels`，拐点带 `lineIndex` / `pathIndex` / `phase`，新增带 `lineIds` / `lineIndex` / `channelId` / `groupId`（`addPoints` / `addLines` 另有 `indexes` / `items` / `position`：新要素在数组里的位置与加进去的那几条，`addChannelGroups` 另有 `results` / `groupIds` / `items`），删除带 `indexes` / `item` / `removedLineIds`，分组带 `index` / `groups` / `action`（细分动作，与 `onChannelGroupChange` 同一份）；批量补丁（`patchPoints` / `patchLines`）的 `updatePoints` / `updateLines` 带 `indexes` / `items` / `count` / `skipped`，`removeSelected` 带 `pointIds` / `lineIds` / `pointIndexes` / `lineIndexes` / `removedChannels` |
 
 `onSelectChange` 与 `onSelect` 的区别只有一个：**只在选中集真的变了时发** —— 框选过程中的重复同步、
-数据变化引起的补发都不发；并且**接口选中**（`select()` / `select(null)` / `selectInBox()`）也会发
+数据变化引起的补发都不发；并且**接口选中**（`selectFeatures()` / `selectFeatures(null)` / `selectInBox()`）也会发
 （引擎那条 `setSelection` 自己不派发 onSelect，组件层在这里补上）。载荷里的 `cause` 说明这次是怎么选上的：
 `click`（指针点击）/ `boxSelect`（框选）/ `keyboard`（Esc 清空）/ `api`（接口调用）。
 
@@ -158,7 +159,7 @@ view.off('*')  // 不传 handler = 摘掉这个事件的全部订阅，返回摘
 | 高频事件不白算 | 组件内部按「有没有人订阅」短路（`count(name) \|\| count('*')`）：没人听的时候不构造载荷，`pointer` / `hover` / `render` 这些每帧级别的事件也可以直接订阅 |
 | 订阅时机 | 创建时的 `ready` 与首次 `dataChange` 发生在 `createGisView` 返回之前，这两条要在 options 里写回调（`onReady` 等） |
 
-全部事件名（与 `EVENT_NAMES` 一致）：`ready`、`error`、`warning`、`viewport`、`cameraChange`、`cursor`、`hover`、`pointer`、`pointerDown`、`pointerUp`、`contextMenu`、`click`、`dblClick`、`labelClick`、`labelDrag`、`labelChange`、`labelContextMenu`、`labelDblClick`、`select`、`selectChange`、`pointDrag`、`pointCopy`、`pointMerge`、`remove`、`waypointChange`、`channelContextMenu`、`channelDraft`、`channelDraftClick`、`channelGroupChange`、`dataChange`、`dataRendered`、`filter`、`history`、`featureChange`、`qualityChange`、`optionChange`、`shortcut`、`stats`、`render`、`destroy`，加上 `'*'`。
+全部事件名（与 `EVENT_NAMES` 一致）：`ready`、`error`、`warning`、`viewport`、`cameraChange`、`cursor`、`hover`、`pointer`、`pointerDown`、`pointerUp`、`contextMenu`、`click`、`dblClick`、`labelClick`、`labelDrag`、`labelChange`、`labelContextMenu`、`labelDblClick`、`select`、`selectChange`、`pointDrag`、`pointCopy`、`pointMerge`、`remove`、`waypointChange`、`channelContextMenu`、`channelDraft`、`channelDraftClick`、`decorationDraft`、`channelGroupChange`、`dataChange`、`dataRendered`、`filter`、`history`、`featureChange`、`qualityChange`、`optionChange`、`shortcut`、`stats`、`render`、`destroy`，加上 `'*'`。
 
 ## 功能开关
 
@@ -172,23 +173,27 @@ createGisView('#map', {
   points, lines,
   features: { drag: true, label: false }                       // 打开「拖动节点」、关掉「节点标签」
 })
+createGisView('#map', {
+  points, lines,
+  features: { waypoint: false }                                 // 新增 / 移动 / 删除拐点一起关掉
+})
 ```
 
 | 预设 | 效果 |
 | --- | --- |
 | `'edit'` | 全开（编辑类也一起打开），等价于 `features: true` |
 | `'view'` | 只读浏览：一次打开查看类（平移缩放、悬停、选中、右键回调、键盘），`boxSelect` / `drag` / `waypoint` / `copy` / `merge` / `remove` / `channelDraft` / `channelMenu` 仍关着 —— 「能看能选、改不动数据」 |
-| `'static'` | 静态图：与缺省一致（全关），只剩画布与数据；留着这个名字方便「从全开切回静态」 |
+| `'static'` | 静态图：显式全关（含标签 / 提示 / 鹰眼图），只剩画布与数据；留着这个名字方便「从全开切回静态」 |
 
 | 开关 | 关掉之后 | 没写时跟随 |
 | --- | --- | --- |
 | `pan` | 拖拽平移 | `interactive === true`（缺省关） |
 | `zoom` | 滚轮缩放 | `interactive === true`（缺省关） |
 | `hover` | 悬停拾取（`onHover` 与悬停样式） | `clickable === true`（缺省关） |
-| `select` | 点击选中（`select()` / `selectInBox()` 这些接口不受限） | `clickable === true`（缺省关） |
+| `select` | 点击选中（`selectFeatures()` / `selectInBox()` 这些接口不受限） | `clickable === true`（缺省关） |
 | `boxSelect` | Shift + 拖动框选（可用 `shortcuts.boxSelect` 改） | `boxSelect === true`（缺省关） |
 | `drag` | 拖动节点（含整组拖动） | `draggable === true`（缺省关） |
-| `waypoint` | 线路拐点的添加 / 拖动 / 删除 | `waypointEditable === true`（缺省关） |
+| `waypoint` | 线路拐点的新增 / 移动 / 删除（一道总闸，不做细分） | `waypointEditable === true`（缺省关） |
 | `copy` | Alt 点击复制与复制接口 | 写了 `copy` 且 `copy.enabled !== false`（缺省关） |
 | `merge` | 拖到另一个节点上合并 | 写了 `merge` 且 `merge.enabled !== false`（缺省关） |
 | `remove` | Delete 删除选中的拐点 / 线路 / 节点（先出删除载荷，确认之后才动数据） | 写了 `remove` 且 `remove.enabled !== false`（缺省关） |