gis-view-webgl2 0.1.2 → 0.1.4

package/docs/manual/17-/345/217/202/346/225/260/351/200/237/346/237/245.md

@@ -1,6 +1,6 @@
 # 17 参数速查（逐个方法）
 
-> 241 个成员逐个列全：参数、默认值与返回。
+> 256 个成员逐个列全：参数、默认值与返回。
 
 ### 参数速查（逐个方法）
 
@@ -8,6 +8,17 @@
 不写默认值的就是必填；返回值只写类型（`this` = 实例本身，可以接着链式调），对象型返回值的字段名见 `src/gis-view/types.d.ts` 里同名的接口。
 消息里的每个名字都能在下面查到 —— `node docs/steps/check-doc-coverage.mjs` 会逐个对账（实例成员 + 数据字段全覆盖才算通过）。
 
+#### 调用与响应口径（先读这一段）
+
+参数表只列出「最少要知道的东西」，实际调用时这几种响应在所有成员上口径一致：
+
+- **同步方法返回 `this` 时可链式调用**：所有 `update*` / `set*` / `add*` / `remove*`、选中与视角方法都先完成本地状态更新再返回实例；需要结果时用相邻的 `get*` / `list*` 读回。少数返回数组、对象或 `null` 的方法在「返回」列单独标出。
+- **数据写入只发一次通知**：`updatePoint`、`updateLine`、`patch*`、`add*`、`remove*` 等每次成功改数据都会发一条对应的 `dataChange`（底层统一为 `updatePoints` / `updateLines` / `updateChannels` 等类型）并落一步历史；在 `batch()` 里连续调用会合并成一条。`emit: false` 只写数据、不发通知，适合宿主自己在保存成功后统一刷新。
+- **选中方法会同步选中集**：`selectFeatures` / `selectWaypoint` / `selectInBox` 先更新引擎选中态，再同步 `getSelections()`、`getSelectionData()` 与 `isSelected()`；一次有效变更会发 `onSelect`（`cause` 标明是 `api`、`box` 或指针来源）和 `onSelectChange`。没有命中任何目标时不会凭空选中，`selectWaypoint(null)` 只清拐点、不动要素选中集。
+- **视角方法会更新相机**：`focusOn` / `zoomTo` / `setCamera` / `fitView` 成功落到目标范围后更新 `getCamera()`，并触发 `onCameraChange`；目标认不出来、视口尚未量出或参数非法时保持当前相机。`focusOn` 缺省只居中、不改比例；`zoom` / `scale` / `center` / `padding` / `maxZoom` 只影响这一次调用，不会改写持久配置。
+- **只读方法返回快照或副本**：`getSelectionData()`、`getFilter()`、`getStats()`、`snapshotScene()`、`listPoints()` / `listLines()` 返回的是调用当时的读数，不会随后续数据变更自动更新；需要最新值就再调一次。对象型字段的含义以 `types.d.ts` 同名接口为准。
+- **失败是可控的**：找不到 id / 下标越界 / 不支持的写法会跳过这一条，能返回 `null` 或 `{ ok: false, reason }` 的就按对应签名返回；需要排查时订阅 `onWarning`。异步筛选 / 搜索通过完成事件、`getFilterResult()` / 搜索结果或返回的 Promise 取结果，不要在调用下一行假定 Worker 已经跑完。
+
 #### 配置与数据
 
 | 方法 | 参数（名字: 类型 = 默认值） | 返回 |
@@ -47,12 +58,12 @@
 | `zoomBy(factor, origin?)` | `factor: number` 缩放倍数（`> 1` 放大、`< 1` 缩小）；`origin?: [number, number]` 缩放中心（画布 CSS 像素，缺省画布中心） | `this` |
 | `zoomTo(scale, origin?)` | `scale: number` 目标缩放值（世界单位 → CSS 像素的比例）；`origin?: [x, y]` 缩放中心 | `this` |
 | `zoomToBounds(bounds, padding?)` | `bounds: GisViewBounds` 要装进画面的世界矩形 `[minX, minY, maxX, maxY]`（也认 `{ minX, minY, maxX, maxY }`）；`padding?: number` 四周留白 | `this` |
-| `focusOn(target, options?)` | `target: GisViewFocusTargets` 要对准的东西：id / `{ type, index }` / `[x, y]` 坐标 / 一个矩形 / 通道写法 / `{ lngLat }` / `{ center }`，或者**一批**（数组取整体包围盒 —— 搜到三个节点就是这三个点的中心当屏幕中心）；`options?: GisViewFocusOptions`：`scale` / `center`（只居中、比例不动）/ `padding` / `maxZoom` / `select`（顺带选中，`mode` 决定怎么并进当前选中集） | `this` |
-| `search(input)` | `input: string \| GisViewSearchOptions` 关键字，或 `{ keyword, scope, fields, limit }` 这类选项（`scope` 可选 `'points'` / `'lines'` / `'channels'`，也认它们的数组）—— **只返回结果、不动视角**，要定位就自己调 `focusOn(result.hits, …)` | `GisViewSearchResult` |
-| `searchAsync(input)` | 同上 | `Promise<GisViewSearchResult>`：多一个 `worker`（是不是在 Worker 里算的）与 `stale`（回来时数据已经改过、或又搜过一次，这一份不作数了） |
+| `focusOn(target, options?)` | `target: GisViewFocusTargets` 要对准的东西：id / `{ type: 'point' \| 'line' \| 'channel' \| 'group', id \| index }` / `{ channelId }`（整条通道）/ `{ type: 'group', channelId?, groupId }` / `[x, y]` 坐标 / 矩形 / `{ lngLat }` / `{ center }`，或者**一批**（数组取整体包围盒）。字符串按「先节点、再线路」，裸字符串不能表示通道；同 id 用显式 `type` 消歧，分组必须用 `type: 'group'`（`groupId` 全局唯一时可省略 `channelId`）。**缺省只居中、比例一点不动**；`options.zoom: true` 才按解析出的真实范围适配，四类目标共用这一条、没有额外放大倍率；`scale` 优先级高于 `zoom`，`maxZoom` 只给单点 / 单线这类零面积目标补最小范围。`options?: GisViewFocusOptions`：`zoom: true` 显式适配、`scale` 直接给比例、`center: true` 显式只居中（与缺省一致）、`padding` 要四周留白（CSS 像素，缺省 40）、`maxZoom` 限制这次适配的最大比例、`select` 顺带选中（`true` 选这次目标，也可另给一批写法）、`mode` 决定怎么并进当前选中集。目标认不出来或参数非法时什么都不做 | `this`（相机更新后发 `onCameraChange`；`select` 生效时另发 `onSelect` / `onSelectChange`） |
+| `search(input)` | `input: string \| GisViewSearchOptions` 关键字，或 `{ keyword, scope, fields, limit }` 这类选项。`scope` 可选 `'points'` / `'lines'` / `'channels'` / `'groups'`，也认与 `focusOn` 一致的单数别名 `'point'` / `'line'` / `'channel'` / `'group'` 及数组；省略或写错时四类全搜。`limit` 对每一类分别计数。返回的 `groups` / `hits` 带分组命中（`channelIndex` / `groupId` / `groupIndex`，`item` 是轻量快照）—— **只返回结果、不动视角**，要定位就自己调 `focusOn(result.hits, …)` | `GisViewSearchResult`：`keyword` / `scope` / `points` / `lines` / `channels` / `groups` / `hits` / `total` / `truncated` / `durationMs` |
+| `searchAsync(input)` | 同上；分组范围的当前轻量快照会随请求交给 Worker | `Promise<GisViewSearchResult>`：多一个 `worker`（是不是在 Worker 里算的）与 `stale`（回来时数据已经改过、或又搜过一次，这一份不作数了） |
 | `setCamera(camera)` | `camera: Partial<GisViewCamera>` 要改的相机字段 `{ x, y, scale }`（只写一个也行） | `this` |
 | `getCamera()` | 无 | `GisViewCamera` |
-| `getZoomBaseScale()` | 无 | `number` 缩放联动的基准比例（`pointZoomScale` / `lineZoomScale` / `zoomScaleAuto` 共用那一份；缺省是首次适应视图时的 `camera.scale`） |
+| `getZoomBaseScale()` | 无 | `number` 缩放联动的基准比例（`pointZoomScale` / `lineZoomScale` 共用那一份；缺省是首次适应视图时的 `camera.scale`） |
 | `setZoomBaseScale(scale?)` | `scale?: number` 新的基准比例；不传取当下相机的比例（把现在这一屏当成「原样大小」） | `this` |
 | `getBounds()` | 无 | `GisViewBounds` |
 | `getViewport()` | 无 | `{ cssWidth, cssHeight, pixelRatio, displayScale }`：画布 CSS 尺寸、设备像素比与渲染分辨率比例 |
@@ -106,6 +117,8 @@
 | `getLine(ref)` | `ref` 线路定位（同上） | `GisViewLineInfo \| null` |
 | `getChannel(ref)` | `ref` 通道定位：通道 id 或下标 | `GisViewChannelSnapshot \| null` |
 | `listPoints(options?)` | `options?: GisViewListOptions`：`indexes`（只看这几个下标）、`inView: boolean`（只要当前视口里的）、`withScreen: boolean`（连屏幕坐标一起给）、`visibleOnly: boolean`（跳过隐藏的）、`limit: number`（最多几条） | `GisViewListedPoint[]` |
+| `getClusters()` | 无 | `GisViewCluster[]`。当前展示组（含 `count: 1` 的单成员），`screen` 按当前相机现算；聚合关掉时是空表 |
+| `getPointCluster()` | 无 | `GisViewPointClusterReadout \| null`。归一化配置 `{ enabled, radius, minPoints, maxZoom, active }`，超过 `maxZoom` 后 `active` 为 `false` |
 | `listLines(options?)` | 同 `listPoints`（`inView` / `withScreen` / `limit`…） | `GisViewListedLine[]` |
 | `forEachPointInView(rect, visit)` | `rect: GisViewBounds` 世界坐标矩形（一般直接给 `getViewRect()` 的返回值）；`visit: (index, item, x, y, radius) => void \| false` 逐个回调，返回 `false` 提前结束 | `void`。只遍历矩形里的可见节点（数据顺序、不建中间数组）：与 `listPoints({ inView: true })` 同一份可见判定，但不生成清单 —— 放大看一小片时不会去碰整份数据 |
 | `getVisibleData()` | 无 | `GisViewData` |
@@ -126,16 +139,18 @@
 
 | 方法 | 参数（名字: 类型 = 默认值） | 返回 |
 | --- | --- | --- |
-| `selectFeatures(refs, options = {})` | `refs: GisViewSelectionRefs` 要选中的东西：id / id 数组（多选）/ `{ type, index }` / 通道写法 / 拾取载荷 / 搜索命中，传 `null` / 空数组等于清空；`options?: GisViewSelectOptions` 只有 `mode`（`'replace'` 缺省 / `'add'` / `'toggle'` / `'remove'`） | `this` |
+| `selectFeatures(refs, options = {})` | `refs: GisViewSelectionRefs` 要选中的东西：节点 / 线路 id、id 数组、`{ type, index }`、通道写法（`{ type: 'channel', channelId \| channelIndex }`，可再给 `groupIds` / `lineIds` / `lineIndexes` 取子集）、分组写法（`{ type: 'group', channelId?, groupId }`，`groupId` 全局唯一时可省略通道）、拾取载荷 / 搜索命中，传 `null` / 空数组等于清空一份新的选中集。认不出来的条目逐条跳过；`options?: GisViewSelectOptions` 只有 `mode`：`'replace'` 缺省换一份、`'add'` 追加、`'toggle'` 在就取消 / 不在就选上、`'remove'` 去掉 | `this`（选中真的变了才发 `onSelect` 与 `onSelectChange`，`cause` 为 `api`） |
+| `selectWaypoint(lineRef, pathIndex?, options = {})` | `lineRef` 线路 id、`lines` 下标或 `{ lineIndex, pathIndex }` / `{ lineId, pathIndex }` 对象；`pathIndex?: number` 必须是 `getWaypoints()` 给出的可编辑中间拐点下标（首尾端点不算，通常直接从读数里取）；`options?: GisViewSelectOptions` 的 `mode` 决定所在线路怎么并进当前选中集（缺省 `replace`）。有效拐点会同时选中线路；线路不存在 / 下标非法 / 拐点不可见时只清拐点选中，不猜位置；传 `null` 也只清拐点，不改要素选中集 | `this` |
 | `deselect(refs = null)` | `refs?: GisViewSelectionRefs` 要取消的东西（写法与 `selectFeatures` 一致：节点 / 通道 / 线路 / 混合一批）；不传 / `null` 等于取消全部（= `selectFeatures(null)`），空数组是「没有目标」什么都不做 | `this` |
 | `getSelections()` | 无 | `GisViewPickResult[]` |
 | `isSelected(ref)` | `ref: GisViewFeatureRef \| GisViewFeatureKey \| GisViewSelectionRefObject` 要素定位（id / 下标 / `{ id }` / `{ index }` / `{ type, index }` / `{ item }`） | `boolean` |
 | `getSelectionData()` | 无 | `GisViewSelectionData`：`{ ids, count, pointCount, lineCount, channelCount, points, lines, channels, items, pointIndexes, lineIndexes, bounds }`（`bounds` 是世界包围盒，空选中时 `null`） |
-| `selectInBox(box, options = {})` | `box: GisViewRect` **画布 CSS 像素**矩形 `{ x, y, width, height }`（与手动框选同一套坐标）；`options?: GisViewSelectInBoxOptions`：`selectionKinds` 临时覆盖这一次的类型过滤（`'point'` / `'line'` / `'channel'`、数组、`'all'` / `true` / `false` / `null`），`originalEvent` 原样带进 `onSelect`；第二段也兼容旧的 Event 写法 | `this` |
-| `beginCopyPoint(options = {})` | `options: GisViewCopyStartOptions`：`id` / `index`（复制哪个节点）、`label`（历史里这一步的名字）、`style`（草稿样式） | `GisViewPointCopyPayload \| null` |
-| `commitPointCopy()` | 无 | `GisViewPointCopyPayload \| null` |
-| `cancelPointCopy()` | 无 | `GisViewPointCopyPayload \| null` |
-| `updateCopyPoint(patch)` | `patch: Partial<GisViewPoint>` 草稿节点要改的字段（主要是 `x` / `y` 跟着指针走） | `GisViewPoint \| null` |
+| `getCascadeHighlight()` | 无 | `GisViewCascadeHighlightInfo \| null`：当前点击级联高亮的来源、范围与节点 / 线路读数 `{ origin, scope, points, lines, pointIndexes, lineIndexes }`，不改变选中集 |
+| `selectInBox(box, options = {})` | `box: GisViewRect` **画布 CSS 像素**矩形 `{ x, y, width, height }`（与手动框选同一套坐标）；`options?: GisViewSelectInBoxOptions`：`selectionKinds` 临时覆盖这一次保留哪几类（`'point'` / `'line'` / `'channel'`、数组、`'all'` / `true` / `false` / `null`，不写沿用全局 `selectionKinds`），`originalEvent` 原样带进 `onSelect`；第二段也兼容旧的 Event 写法。空框不会选中任何要素 | `this`（发 `onSelect` / `onSelectChange`，`cause` 为框选） |
+| `beginCopyPoint(options = {})` | `options: GisViewCopyStartOptions`：`id` / `index` / `item` 三选一给来源，都不给就进入「下一次点选节点」模式；`coordinate` / `screen` 是落点（缺省按 `copy.offset`）；`follow` 让预览跟指针；`autoCommit` 覆盖 `copy.autoCommit`；`commit: true` 出预览即落地；`via` / `originalEvent` 原样带回。必须配置 `copy`（`enabled` 不为 `false`），否则返回 `null`。预览节点插在 `points` 末尾且不带 id，不会把绑定源 id 的线路 / 通道带过去 | `GisViewPointCopyPayload \| null`：`phase: 'start'` 的预览载荷；来源认不出来时返回 `null` |
+| `commitPointCopy()` | 无：把当前复制预览落地，先发 `commit`、落地后发 `end`；`commit` 阶段载荷里的 `cancel()` 可以拦住这次复制 | `GisViewPointCopyPayload \| null`：成功的 `end` 载荷；没有预览或已被取消时为 `null` |
+| `cancelPointCopy()` | 无：撤掉预览并补一条 `cancel`，数据与历史不动 | `GisViewPointCopyPayload \| null`：取消载荷；没有预览时为 `null` |
+| `updateCopyPoint(patch)` | `patch: Partial<GisViewPoint>` 预览节点的字段级合并（名称 / 样式等；`x` / `y` 仍以当前落点为准），只重解析这一个预览节点 | `GisViewPoint \| null`：改完的预览节点；没有预览或 `patch` 不是对象时 `null` |
 | `getPointCopy()` | 无 | `GisViewPointCopyState \| null` |
 | `copyPoint(source?)` | `source?: string \| number \| GisViewCopyStartOptions` 复制哪个节点（不给就用选中的 / 光标下的，都没有就进「点一个节点」模式） | `GisViewCopyItem \| null` |
 | `copyPoints(sources?, options = {})` | `sources?: GisViewPointRef \| GisViewPointRef[]` 要复制的节点（不给就取当前选中集；`copySelectedPoints` 不回落到光标）；显式给 `sources` 时只复制这批节点，不再顺带选中的线路 / 通道。`options: GisViewCopyPointsOptions`：`coordinate` / `screen`（落点，缺省按 `copy.offset`）、`offset`（屏幕像素偏移）、`lineIndexes` / `channelIndexes`（显式点名选中的线路 / 通道）、`withLines` / `withChannels`（缺省 `false`：只复制选中要素；写 `true` 恢复「来源内部全带」的旧口径，写 `false` 连选中线路 / 通道也不带）、`select`（复制后选中新节点）、`label` / `via` / `originalEvent` | `GisViewBatchCopyPayload` |
@@ -150,14 +165,14 @@
 | `splitPoint(source, parts, options = {})` | `source: GisViewPointRef` 要拆的节点；`parts: GisViewSplitPointPart[]` 至少两份，每份可直接写节点字段或放进 `item`，并用 `lines` / `channels` / `channelFrom` / `channelTo` 分配线路与通道端点；`options?: GisViewSplitPointOptions`：`keepSourceId`（缺省 `true`，第一份沿用来源 id）/ `label` | `GisViewSplitPointOutcome`：`{ ok, reason, source, items, indexes, pointIds, linesChanged, removedLines, removedLineIds, removedLineIndexes, channelsChanged, removedChannels, removedChannelIds, skipped, changes }`；`changes` 可直接作为后端事务输入 |
 | `getPointMerge()` | 无（载荷带 `impact`：`lineCount` / `linesChanged` / `removedLines` / `lineIds` / `removedLineIds` 与通道读数，确认前就能估算影响） | `GisViewPointMergePayload \| null` |
 | `resolvePointMerge(confirmed, options = {})` | `confirmed?: boolean`（缺省 `true` = 确认，`false` = 取消）；`options?: GisViewPointMergeConfirmOptions`：`keep` 选 `'target'`（缺省，保留碰撞目标）/ `'source'`（保留拖动的来源），`item` 是最终节点字段补丁（名称 / 分区 / 颜色 / 尺寸 / 图标 / 描边等；位置与 id 始终取保留端） | `GisViewPointMergePayload \| null` |
-| `commitPointMerge()` | 无 | `boolean` |
-| `revertPointMerge(options = {})` | `options?: { originalEvent?: Event \| null; silent?: boolean }`：`silent: true` 时不再补发一条 `cancel` 载荷 | `GisViewPointMergePayload \| null` |
+| `commitPointMerge()` | 无：收掉「已确认、数据已由使用方并好」的合并状态；`mergePoints` / `resolvePointMerge` 的正常路径由组件自己调用，只有完全自建合并落地流程时才手动调 | `boolean`：真的收掉了一个待确认合并为 `true`，没有可收的状态为 `false` |
+| `revertPointMerge(options = {})` | `options?: { originalEvent?: Event \| null; silent?: boolean }`：把拖动的来源节点还原回原位并收掉合并状态；`silent: true` 时不补发 `cancel` 载荷 | `GisViewPointMergePayload \| null`：回退载荷；没有待回退的合并时为 `null` |
 | `removePoints(refs, options = {})` | `refs: \| GisViewFeatureRef \| 数组 \| 'all' \| 'selection' \| 'visible'` 要删哪些节点；`options?: { reason?: string }` 记进事件载荷的删除原因 | `GisViewRemovePointsOutcome` |
-| `removeSelected(options = {})` | `options?: { reason?: string }` 同上 | `GisViewRemoveSelectedOutcome` |
-| `requestRemove(options = {})` | `options?: { originalEvent?: Event \| null }` 原样带进载荷（键盘触发时是那一次 `keydown`） | `GisViewRemoveOutcome` |
-| `getRemoveRequest()` | 无 | `GisViewRemovePayload \| null` |
-| `resolveRemove(scope)` | `scope?: GisViewRemoveScope` 删除范围（缺省用载荷里的 `scope`） | `GisViewRemoveResult \| null` |
-| `cancelRemove()` | 无 | `GisViewRemovePayload \| null` |
+| `removeSelected(options = {})` | `options?: { reason?: string }` 记进删除载荷：直接删当前选中集（节点连带线路 / 空掉的通道，拐点先删），删完清空选中；整次调用只落一条历史、只发一条 `removeSelected` 数据变更 | `GisViewRemoveSelectedOutcome`：`{ ok, reason?, pointIndexes, lineIndexes, pointIds, lineIds, points, lines, removedChannels }`；没有选中可删时为 `ok: false` |
+| `requestRemove(options = {})` | `options?: { originalEvent?: Event \| null }` 原样带进载荷（键盘触发时是那一次 `keydown`）：只生成待确认载荷，**数据不动**；`remove.confirm` 为 `false` 时当场删，为函数时按返回值 / Promise 裁决，不写就停在 `pending` | `GisViewRemoveOutcome`：`phase: 'pending' \| 'remove' \| 'cancel'` 的载荷，或没有可删要素时的 `phase: 'empty'` 失败读数 |
+| `getRemoveRequest()` | 无：读当前待确认的删除请求，供自建确认框渲染 | `GisViewRemovePayload \| null`：没有待确认请求时为 `null` |
+| `resolveRemove(scope)` | `scope?: GisViewRemoveScope` 删除范围（缺省用载荷里的 `scope`；可选 `'lines'` / `'groups'` / `'channels'`） | `GisViewRemoveResult \| null`：删除结果；没有待确认请求或请求已裁决时为 `null` |
+| `cancelRemove()` | 无：取消待确认删除，数据不动并补 `cancel` 载荷 | `GisViewRemovePayload \| null`：取消载荷；没有待确认请求时为 `null` |
 
 #### 拐点与通道
 
@@ -186,7 +201,7 @@
 | `addChannelGroupWaypoint(channelId, groupId, coordinate)` | `channelId` 通道 id；`groupId` 分组 id；`coordinate` 新拐点世界坐标 | `this` |
 | `removeChannelGroupWaypoint(channelId, groupId, pathIndex)` | `channelId` / `groupId` / `pathIndex` 要删的骨架顶点下标 | `this` |
 | `runChannelAction(actionId, options?)` | `actionId: GisViewChannelActionId` 动作名（`'select-group'` / `'deselect-group'` / `'add-waypoint'` / `'remove-waypoint'` / `'split'` / `'merge'`，见 `getChannelContext().actions`）；`options?: GisViewChannelActionOptions` 动作自己的参数（`groupId` / `lineId` / `coordinate`…） | `GisViewChannelContext \| null` |
-| `beginAddChannel(options = {})` | `options?: GisViewChannelDraftOptions` 草稿配置：`kind` / `circuits` / `autoCommit` / `continuous` / `chain` / `name` / `lineId` / `lineProps` / `linePropsByMember` / `lineItems`（第二段）/ `routing` / `path`（中间拐点）/ `channelProps` / `channelDraftStyle`（本次草稿的预览样式）/ `handoff`（交接模式）/ `select`（点中的节点顺手选中，走 `onSelect` 那一套） | `this`（只负责那条示例假通道，真正新增走 `addChannel`） |
+| `beginAddChannel(options = {})` | `options?: GisViewChannelDraftOptions` 草稿配置：`from`（预指定起点，下一步只选终点）/ `kind` / `circuits` / `autoCommit` / `continuous` / `chain` / `name` / `lineId` / `id` / `lineProps` / `linePropsByMember` / `lineItems`（第二段）/ `routing` / `path`（中间拐点）/ `channelProps` / `channelDraftStyle`（本次草稿的预览样式）/ `handoff`（交接模式）/ `select`（点中的节点顺手选中，走 `onSelect` 那一套）/ `originalEvent` | `this`（只负责那条示例假通道，真正新增走 `addChannel`） |
 | `getAddChannelDraft()` | 无 | `GisViewChannelDraftPayload \| null` |
 | `updateAddChannelStyle(patch = {})` | `patch?: GisViewChannelDraftStyle \| null` 字段级合并的预览样式（箭头位置 / 多回线间距 / 自绘等）；传 `null` 回到全局 `channelDraftStyle` | `this` |
 | `continueAddChannel(options = {})` | `options?: GisViewChannelDraftOptions` 开下一段草稿（写法与 `beginAddChannel` 一致，不传就沿用这一段原来的） | `this` |
@@ -284,14 +299,14 @@
 | 方法 | 参数（名字: 类型 = 默认值） | 返回 |
 | --- | --- | --- |
 | `exportData(options = {})` | `options: GisViewExportDataOptions`：`scope`（`'all'` 缺省 / `'viewport'` / `'selection'`，也认 `visible` / `view` / `selected`）、`format`（`'view'` 缺省 / `'input'` / `'new'` / `'test'` / `'full'`）、`parts`（只导 `points` / `lines` / `channels` / `parallelGroups` 里的哪几份）、`points` / `lines` / `channels`（只导指定要素）、`withLines: false`（selection 不要两端都在集合里的线路）、`labels`、`extra`。`format: 'full'` / `'input'` 返回可直接回灌的数据，不夹带 `scope` / `counts` 读数 | `GisViewExportDataResult \| GisViewDocument`（`format: 'full'`） |
-| `exportImage(options = {})` | `options?: GisViewExportImageOptions`：`type`（`'image/png'` / `'image/jpeg'`）、`quality`（JPEG 0 ~ 1）、`scale`（导出倍数）、`background`（底色）、`transparent` | `Promise<string>` |
+| `exportImage(options = {})` | `options?: GisViewExportImageOptions`：`type`（`'image/png'` / `'image/jpeg'` / `'image/webp'` / `'svg'`）、`quality`（JPEG / WebP 0 ~ 1）、`scale`（导出倍数；SVG 只影响宽高）、`scope`（`'viewport'` 缺省 / `'all'` 全部内容）、`padding`（`scope: 'all'` 的留白，缺省 24）、`background`（缺省带背景 / `false` 或 `'none'` 透明 / 颜色字符串换底色）、`includeLabels`（缺省 `true`）、`download`（`true` 或文件名） | `Promise<string>`（data URL） |
 | `exportSelection(options = {})` | `options?: GisViewExportSelectionOptions`：`format` / `type` / `quality` / `scale` / `padding`（只导选中要素那一块） | `Promise<GisViewExportSelectionResult>` |
 
 #### 筛选
 
 | 方法 | 参数（名字: 类型 = 默认值） | 返回 |
 | --- | --- | --- |
-| `setFilter(filter)` | `filter: GisViewFilterInput \| null` 筛选条件：完整格式 `{ points, lines, cascade, worker }`；只筛节点时可以简写成节点条件本身；传 `null` 等于清空 | `this` |
+| `setFilter(filter)` | `filter: GisViewFilterInput \| null` 筛选条件：完整格式 `{ points, lines, cascade, mode, worker }`；只筛节点时可以简写成节点条件本身；传 `null` 等于清空。`mode: 'hide'`（缺省）只隐藏、不删数据、不清空选中集；`mode: 'remove'` 删除筛选结果，只发一条 `filterRemove` 与最终一条 `onFilter` | `this` |
 | `getFilter()` | 无 | `GisViewFilter \| null` |
 | `getFilterResult()` | 无 | `GisViewFilterResult \| null` |
 
@@ -300,13 +315,16 @@
 | 方法 | 参数（名字: 类型 = 默认值） | 返回 |
 | --- | --- | --- |
 | `on(name, handler)` | `name: GisViewEventName \| '*'` 事件名（`'dataChange'` / `'labelClick'`… 或 `'*'` 订阅全部）；`handler: (payload, name?) => void` 回调，载荷字段见「事件」一节的表 | `() => void` 取消订阅 |
-| `once(name, handler)` | 同上，只触发一次（回调跑完自动摘掉） | `() => void` 取消订阅 |
-| `off(name, handler?)` | `name` 事件名；`handler?` 只摘掉这一个回调（不传 = 摘掉这个事件的全部） | `number` 摘掉几条 |
+| `once(name, handler)` | 与 `on` 同一套事件名与载荷；只触发一次，回调跑完自动摘掉。返回的取消函数可提前撤销；即使提前取消，重复调用也安全 | `() => void` 取消订阅 |
+| `off(name, handler?)` | `name` 事件名（也认 `'*'`）；`handler?` 只摘掉这一个回调，不传 = 摘掉这个事件的全部订阅 | `number` 摘掉几条（没摘到返回 `0`） |
 | `use(plugin)` | `plugin: GisViewPlugin`（`(view, context) => hook`，与 `options.plugins` 的写法一致）：立即执行一次，返回卸载函数 —— 调它跑插件自己的 `destroy`（重复调用只清一次，实例销毁之后也安全） | `() => void` 卸载 |
+| `registerCommand(name, handler)` | `name: string` 命令名（会 `trim`，同名覆盖）；`handler: GisViewCommandHandler<Payload, Value>` 同步处理函数 `(payload, context) => Value`，`context` 是冻结的 `{ view, name }`。名字为空 / handler 不是函数只报 warning、不注册；视图销毁后注册不生效 | `() => void` 幂等注销；同名已被后来者覆盖时不会误删新命令 |
+| `executeCommand(name, payload?)` | `name: string` 命令名；`payload?: unknown` 原样交给 handler | `GisViewCommandResult<Value>`：`{ ok: true, name, value }` / `{ ok: false, name, reason }`（未注册 / 名字非法 / handler 抛错） |
+| `listCommands()` | 无 | `string[]` 当前注册的命令名（按注册顺序；同名覆盖不改变位置） |
 | `getFeatures()` | 无 | `GisViewFeatureState` |
 | `setFeatures(next)` | `next: GisViewFeaturesInput` 预设名（`'edit'` / `'view'` / `'static'`）、开关表或布尔值 | `this` |
-| `undo()` / `redo()` | 无 | `GisViewHistoryStepResult \| null` |
-| `canUndo()` / `canRedo()` | 无 | `boolean` |
+| `undo()` / `redo()` | 无：从撤销 / 重做栈回放一步；会同步数据、发 `history` 与对应的 `dataChange`，并更新相机以外的运行时读数 | `GisViewHistoryStepResult \| null`：`{ type, label, canUndo, canRedo }`；历史没开或栈空时为 `null` |
+| `canUndo()` / `canRedo()` | 无：只读当前两份栈，不触发历史变化；界面据此灰掉按钮 | `boolean` |
 | `getHistoryState()` | 无 | `GisViewHistoryState` |
 | `getHistory()` | 无 | `GisViewHistoryEntry[]` |
 | `clearHistory()` | 无 | `number` |
@@ -337,4 +355,6 @@
 
 ---
 
+**相关章节**：[08 选中与拐点](08-选中与拐点.md) · [16 实例方法总表](16-实例方法总表.md) · [18 逐方法示例（复制就能跑）](18-逐方法示例.md)
+
 [← 16 实例方法总表](16-实例方法总表.md) · [手册目录](../GisView.md) · [18 逐方法示例（复制就能跑） →](18-逐方法示例.md)

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

@@ -26,6 +26,7 @@ view.updateOptions({ points: nextPoints, lines: nextLines }, true)
 // denseMode：大数据展示模式（'auto' 缺省 / 'on' / 'off'，或对象写法换三档阈值）
 view.updateOptions({ denseMode: 'on' })     // 临时强制进入密集档（标签避让 / 截断，动效暂停）
 view.updateOptions({ denseMode: { mode: 'auto', visibleThreshold: 3000, densityThreshold: 2500, pointThreshold: 60000 } })
+view.updateOptions({ selectTrigger: 'dblClick' })  // 改成双击选中（缺省 'click'）；第二下同时派发 onClick 与 onDblClick
 const dense = view.getStats().dense        // { mode, active, reason, visiblePoints, visibleThreshold, densityThreshold, pointThreshold }
 
 // updatePointStyle(patch)：按字段合并全局点样式；写 null 清掉整份
@@ -168,16 +169,24 @@ view.zoomTo(12)
 view.zoomToBounds([0, 0, 400, 200], 40)
 view.zoomToBounds({ minX: 116, minY: 39, maxX: 117, maxY: 40 })
 
-// focusOn(target, options?)：对准一个或多个目标（id / 下标 / 坐标 / 矩形 / 通道写法 / 搜索命中 / 一批）
-view.focusOn('a')
-view.focusOn(['a', 'b'], { padding: 60, maxZoom: 8, select: true })
-view.focusOn([120, 80], { center: true })              // 只居中，比例不动
+// focusOn(target, options?)：对准一个或多个目标（id / 显式类型 / 坐标 / 矩形 / 搜索命中 / 一批）
+view.focusOn('a')                                      // 缺省只居中，比例不动
+view.focusOn('a', { zoom: true, maxZoom: 8 })          // 显式按范围适配
+view.focusOn(['a', 'b'], { zoom: true, padding: 60, select: true })
+view.focusOn({ type: 'point', id: 'a' })               // 节点与线路同 id 时显式消歧
+view.focusOn({ type: 'line', id: 'a' })
+view.focusOn({ type: 'channel', channelId: 'c1' })     // 通道也可以直接写 { channelId: 'c1' }
+view.focusOn({ type: 'group', channelId: 'c1', groupId: 'c1::2' })
+view.focusOn({ type: 'group', groupId: 'global-group' }) // groupId 全局唯一时可省略通道
+view.focusOn([120, 80], { center: true })              // 显式只居中（与缺省一致）
 view.focusOn({ lngLat: [116.4, 39.9] })
 
 // search(input) / searchAsync(input)：搜索（只返回结果、不动视角）
 const hits = view.search('甲站')
-const scoped = view.search({ keyword: '甲', scope: ['points', 'channels'], limit: 10 })
-view.focusOn(hits.hits, { maxZoom: 8 })                // 命中集直接丢给 focusOn
+const scoped = view.search({ keyword: '甲', scope: ['points', 'channels', 'groups'], limit: 10 })
+const groupHits = view.search({ keyword: 'c1::2', scope: 'group' }) // 单数别名与 focusOn 一致
+view.focusOn(groupHits.groups[0], { zoom: true, select: true }) // 按整组范围适配并选中成员回线
+view.focusOn(hits.hits, { zoom: true, maxZoom: 8 })    // 命中集直接丢给 focusOn
 const asyncHits = await view.searchAsync('甲站')       // 大表走 Worker；stale 说明这一份不作数了
 
 // setCamera(camera) / getCamera()：读写相机（只写一个字段也行）
@@ -185,8 +194,7 @@ view.setCamera({ scale: 10 })
 view.setCamera({ x: 200, y: 120 })
 const camera = view.getCamera()
 
-// zoomScaleAuto / getZoomBaseScale() / setZoomBaseScale(scale?)：自适应比例（节点大小与通道间距按同一比例变）
-view.updateOptions({ zoomScaleAuto: true })   // 没写联动指数的那几项按 1 跟随地图（显式写过的仍以显式值为准）
+// getZoomBaseScale() / setZoomBaseScale(scale?)：缩放联动的基准比例（配合 pointZoomScale / lineZoomScale）
 const zoomBase = view.getZoomBaseScale()     // 基准（缺省首次适应视图时的 camera.scale）
 view.setZoomBaseScale()                      // 以当下这一屏为「原样大小」，之后放大缩小都从它算倍数
 view.setZoomBaseScale(2.5)                   // 也可以直接给一个比例
@@ -301,6 +309,13 @@ const pointStyle = view.getPointStyle(0)
 const listedPoints = view.listPoints({ limit: 5, withScreen: true })
 const listedLines = view.listLines({ inView: true, limit: 200 })
 
+// getClusters() / getPointCluster()：读当前点聚合展示组与配置
+view.updateOptions({ pointCluster: { radius: 64, minPoints: 3, maxZoom: 2.5 } })
+const clusterGroups = view.getClusters()
+const clusteredOnly = clusterGroups.filter(group => group.count > 1)
+const clusterState = view.getPointCluster()   // { enabled, radius, minPoints, maxZoom, active }
+view.updateOptions({ pointCluster: false })   // 关掉聚合，原始点全部恢复
+
 // forEachPointInView(rect, visit)：只遍历视口里的节点，不建中间数组；回调返回 false 提前结束
 view.forEachPointInView(view.getViewRect(), (index, item, x, y, radius) => {
   readout.push(`${item.name}：半径 ${radius.toFixed(1)}px`)
@@ -327,8 +342,17 @@ view.selectFeatures('a')                               // 选中一个
 view.selectFeatures(['a', 'b'])                        // 一批
 view.selectFeatures('a', { mode: 'add' })              // mode：replace（缺省）/ add / toggle / remove
 view.selectFeatures([{ type: 'line', index: 0 }], { mode: 'toggle' })
+view.selectFeatures({ type: 'channel', channelId: 'c1' }) // 整条通道的全部回线
+view.selectFeatures({ type: 'group', channelId: 'c1', groupId: 'c1::2' })
+view.selectFeatures({ type: 'group', groupId: 'global-group' }) // groupId 全局唯一时可省略通道
 view.selectFeatures(null)                              // 清空（空数组同义）
 
+// selectWaypoint(lineRef, pathIndex? / { lineIndex | lineId, pathIndex }, options?)：选中拐点并带选线路
+view.selectWaypoint('l1', 2)                           // pathIndex 从 getWaypoints() 取
+view.selectWaypoint({ lineIndex: 0, pathIndex: 1 }, { mode: 'add' })
+view.selectWaypoint({ lineId: 'l1', pathIndex: 2 })
+view.selectWaypoint(null)                              // 只取消拐点选中，不改要素选中集
+
 // deselect(refs?)：取消选中（写法与 selectFeatures 一致；不传 / null 全清，空数组什么都不做）
 view.deselect('a')
 view.deselect(['a', 'b'])
@@ -339,6 +363,19 @@ const picks = view.getSelections()
 const selection = view.getSelectionData()              // { ids, count, points, lines, channels, bounds, … }
 const selected = view.isSelected('a')
 
+// getCascadeHighlight()：读点击级联高亮（与选中集分开；没有高亮时为 null）
+const cascade = view.getCascadeHighlight()             // { origin, scope, points, lines, pointIndexes, lineIndexes }
+view.updateOptions({
+  cascadeHighlight: {
+    scope: 'points',
+    triggerOnClick: true,
+    triggerOnMultiSelect: false,
+    triggerOnBoxSelect: true,
+    clearOnEmptyClick: true
+  }
+})
+view.on('cascadeHighlight', payload => console.log(payload?.pointIndexes, payload?.lineIndexes))
+
 // selectInBox(box, options?)：用矩形框选（画布 CSS 像素，与手动框选同一套判定）
 view.selectInBox({ x: 40, y: 40, width: 320, height: 200 })
 view.selectInBox({ x: 40, y: 40, width: 320, height: 200 }, { selectionKinds: ['line', 'channel'] })
@@ -349,11 +386,13 @@ view.updateOptions({ selectionKinds: 'channel' })           // 只收通道回
 view.updateOptions({ selectionKinds: ['point', 'line', 'channel'] })
 
 // beginCopyPoint(options) / getPointCopy() / updateCopyPoint(patch) / commitPointCopy() / cancelPointCopy()
-view.beginCopyPoint({ id: 'a' })                       // 出复制预览（跟着鼠标走）
-view.beginCopyPoint()                                  // 先点按钮再选节点（点中下一个节点当来源）
-view.updateCopyPoint({ name: '新节点' })                // 改预览节点的数据
-view.commitPointCopy()                                 // 落地
-view.cancelPointCopy()                                 // 取消
+view.updateOptions({ copy: { enabled: true, autoCommit: false } })  // API 复制入口要先开 copy 配置
+view.beginCopyPoint({ id: 'a', coordinate: [40, 30] })             // 出预览并钉在世界坐标 [40, 30]
+view.beginCopyPoint({ id: 'a', follow: true })                     // 预览跟着指针走（autoCommit 缺省停住）
+view.beginCopyPoint()                                              // 先点按钮再选节点（点中下一个节点当来源）
+view.updateCopyPoint({ name: '新节点' })                            // 字段级改预览节点（落点仍由 coordinate / 指针决定）
+const copyEnd = view.commitPointCopy()                              // 落地：返回 end 载荷；没有预览时为 null
+view.cancelPointCopy()                                              // 取消：预览撤掉，数据与历史不动
 const copyState = view.getPointCopy()                  // 当前预览 / 选点态（没有就是 null）
 
 // copyPoint(source?) / copyPoints(sources?, options?) / copySelectedPoints(options?) / copyPointToClipboard(sources?, options?) / copyPointsToClipboard(sources?, options?) / pastePoint(options?) / pastePoints(options?) / getPointClipboard()
@@ -407,15 +446,15 @@ view.removePoints('all')                               // 全删
 view.removePoints('a', { reason: '误建' })              // 原因会带进数据变更载荷
 
 // removeSelected(options?)：删「当前选中的东西」（节点 / 线路 / 拐点按各自口径）
-view.removeSelected()
-view.removeSelected({ reason: '按 Delete 确认' })
+const removed = view.removeSelected()                   // 返回 pointIds / lineIds / removedChannels 等；删完清空选中
+view.removeSelected({ reason: '按 Delete 确认' })        // 整次只记一条历史、只发一条 removeSelected 数据变更
 
 // requestRemove(options?) / getRemoveRequest() / resolveRemove(scope?) / cancelRemove()：先出载荷、再裁决
-const removePayload = view.requestRemove()             // 发一条 phase: 'pending' 的 onRemove 载荷
+const removePayload = view.requestRemove()             // 只生成 phase: 'pending' 的载荷，数据不动
 const pendingRemove = view.getRemoveRequest()          // 从外面拿这一份（没有就是 null）
-view.resolveRemove('channels')                         // 按范围确认：'lines' / 'groups' / 'channels'
+view.resolveRemove('channels')                         // 按范围确认：'lines' / 'groups' / 'channels'；无请求时返回 null
 view.resolveRemove()                                   // 按载荷里的 scope 确认
-view.cancelRemove()                                    // 取消（数据一个字节都不动）
+view.cancelRemove()                                    // 取消（数据一个字节都不动；无请求时返回 null）
 ```
 
 #### 拐点与通道
@@ -508,6 +547,7 @@ view.beginAddChannel({
     circuitSpacing: 12, opacity: 0.9
   }
 }) // 点两个节点：第一个起点、第二个终点；通道 3 回时预览也画 3 条平行回线
+view.beginAddChannel({ from: 'station-a' })            // 预指定起点：接下来只点终点
 const draft = view.getAddChannelDraft()                // 草稿读数（跟随光标的预览、两个节点、方案表与实际 style）
 view.updateAddChannelStyle({ arrowPositions: [0.25, 0.75], arrowReverse: true }) // 字段级合并，只改箭头
 view.updateAddChannelStyle(null)                       // 回到全局 channelDraftStyle
@@ -785,6 +825,7 @@ const parallelData = view.exportData({ format: 'test', parts: ['waypoint'], all:
 // exportImage(options?)：导出图片（Promise<dataURL>；type: 'svg' 走矢量导出）
 const imageUrl = await view.exportImage({ scale: 2, background: '#ffffff' })
 await view.exportImage({ type: 'image/jpeg', quality: 0.9, download: '场景.jpg' })   // 也可以直接下载
+await view.exportImage({ scope: 'all', padding: 24, includeLabels: false })          // 全部内容（导完恢复相机）
 
 // exportSelection(options?) / exportData({ scope: 'selection' })：导出选中的那几个
 const exportedSelection = await view.exportSelection({ withLines: true, scale: 2 })
@@ -795,15 +836,29 @@ const selectionData = view.exportData({ scope: 'selection', parts: ['station', '
 #### 筛选
 
 ```js
-// setFilter(filter)：设筛选条件（只筛节点可以写简写）；传 null 等于清空
+// setFilter(filter)：设筛选条件（只筛节点可以写简写）；传 null 等于清空；默认只隐藏
 view.setFilter({ vn_kv: { gte: 525 } })
 view.setFilter({ points: { station_type: 'coal' }, lines: { vn_kv: { gte: 525 } }, cascade: 'binding' })
 view.setFilter(null)
 
+// 默认 hide：只隐藏显示，不删数据、也不清空选中集；被筛掉的选中项在条件放宽后原样恢复
+view.selectFeatures(['a', 'a-b'])
+view.setFilter({ points: { station_type: 'coal' }, cascade: false })
+view.getSelections().map(item => item.item.id) // 仍然包含被隐藏的 'a' / 'a-b'
+view.setFilter(null)
+
+// remove：不命中的点 / 线直接从数据里删掉；先删线路再删节点，只发一条 filterRemove
+view.on('dataChange', payload => {
+  if (payload.type === 'filterRemove') console.log(payload.pointIndexes, payload.removedPoints, payload.removedLineItems)
+})
+view.setFilter({ points: { station_type: 'coal' }, mode: 'remove' })
+view.getFilterResult()   // 删除完成后 hiddenPoints / hiddenLines 为空
+view.undo()              // 开了 history 时恢复数据；回放本身不会再触发一次删除
+
 // getFilter() / getFilterResult()：当前条件（副本）/ 最近一次结果
 view.setFilter(null)
 const filter = view.getFilter()
-const filterResult = view.getFilterResult()   // { hiddenPoints, hiddenLines, visiblePoints, visibleLines, worker, durationMs }
+const filterResult = view.getFilterResult()   // hide 模式是隐藏下标；remove 完成后 hidden 为空
 ```
 
 #### 事件、开关与历史
@@ -820,6 +875,20 @@ view.off('dataChange', sync)          // 只摘掉这一个（返回摘掉几条
 const dispose = view.use((view, context) => ({ destroy() { /* 插件自己的清理；context.apiVersion 当前为 1 */ } }))
 dispose()
 
+// registerCommand(name, handler) / executeCommand(name, payload?) / listCommands()：实例级业务命令
+const disposeCommand = view.registerCommand('focusHighestLoad', (payload = {}, context) => {
+  const threshold = Number(payload.threshold ?? 0.8)
+  const target = view.getData().points
+    .filter(point => Number(point.max_loading_rate ?? 0) >= threshold)
+    .sort((left, right) => Number(right.max_loading_rate ?? 0) - Number(left.max_loading_rate ?? 0))[0]
+  if (!target) return { focused: false, threshold }
+  context.view.focusOn(target.id, { select: true, zoom: true, maxZoom: 12 })
+  return { focused: true, id: target.id, command: context.name }
+})
+const commandResult = view.executeCommand('focusHighestLoad', { threshold: 0.85 })
+const commandNames = view.listCommands()   // ['focusHighestLoad']
+disposeCommand()                           // 幂等卸载；同名覆盖时不会误删新命令
+
 // getFeatures() / setFeatures(next)：功能开关的读 / 写（预设名 / 开关表 / 布尔值）
 const features = view.getFeatures()
 view.setFeatures('view')              // 'edit' / 'view' / 'static'
@@ -889,4 +958,6 @@ const gl = view.gl
 
 ---
 
+**相关章节**：[08 选中与拐点](08-选中与拐点.md) · [16 实例方法总表](16-实例方法总表.md) · [17 参数速查（逐个方法）](17-参数速查.md)
+
 [← 17 参数速查（逐个方法）](17-参数速查.md) · [手册目录](../GisView.md) · [19 读数与拖拽预览 →](19-读数与拖拽预览.md)

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

@@ -20,8 +20,8 @@ view.listLines({ inView: true, limit: 200 })        // 视口里看得见的线
 view.getElementBounds(view.getSelections())         // { minX, minY, maxX, maxY }
 
 // 把视角挪过去 / 一次取全读数
-view.focusOn(view.getSelections(), { maxZoom: 8 })         // 选中集整体居中；单个节点也会放大到 8 倍
-view.focusOn([{ type: 'point', index: 3 }, { type: 'line', index: 2 }], { padding: 60 })
+view.focusOn(view.getSelections(), { zoom: true, maxZoom: 8 }) // 选中集按整体范围适配；单个节点最多放大到 8 倍
+view.focusOn([{ type: 'point', index: 3 }, { type: 'line', index: 2 }], { zoom: true, padding: 60 })
 const state = view.getViewState()                          // camera / viewport / layoutReady / stats …
 
 // 自定义右键菜单：一个屏幕点上的东西都在这里
@@ -34,7 +34,7 @@ canvas.addEventListener('contextmenu', (event) => {
 
 `GisViewListOptions` 的几个筛选条件是「与」的关系：`indexes`（只看这几个下标）、`inView`（`true` 按当前视口，或者直接给一份世界矩形 `{ minX, minY, maxX, maxY }`）、`limit`（最多几条）、`visibleOnly`（缺省 `true`：被筛选 / `visible: false` 隐藏掉的不算）、`withScreen`（补一份画布 CSS 像素坐标）。都不给就是「全部可见的」；十万级数据下这套方法适合面板读数、导出与校验，别逐帧调。
 
-`listPoints()` 用的就是引擎画点那一份可见判定（旧版单独暴露的 `getVisiblePoints()` 并进了这一条）：`radius` / 图层号 / 屏幕坐标这些几何读数都在它给的条目里。`focusOn()` 只移动相机、不改数据：`{ center: true }` 只居中、比例不动，`{ select: true }` 顺带把这批选上，传一批目标（数组）就是整体居中。
+`listPoints()` 用的就是引擎画点那一份可见判定（旧版单独暴露的 `getVisiblePoints()` 并进了这一条）：`radius` / 图层号 / 屏幕坐标这些几何读数都在它给的条目里。`focusOn()` 只移动相机、不改数据：缺省（以及显式 `{ center: true }`）只居中、比例不动，`{ zoom: true }` 才按目标范围适配，`{ select: true }` 顺带把这批选上，传一批目标（数组）就是整体居中。
 
 只要「屏幕里这一片」的节点时用 `forEachPointInView()`：它按数据顺序逐个回调 `(index, item, x, y, radius)`，不建中间数组，回调返回 `false` 可以提前结束 —— 放大看一小片时不会去碰整份数据（十万级数据下，面板读数、导出与排序用上面那两条，按视口画自己的东西用这一条）：
 

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

@@ -30,17 +30,41 @@ view.updateOptions({ denseMode: 'off' })   // 手动退出
 
 `reason` 的取值：`manual-on` / `manual-off`（强制档）、`total`（总量越线）、`visible`（可见节点数越线）、`density`（屏幕密度越线）、`below-threshold`（auto 档已退出）、`checking`（引擎还没建好或正在等首轮布局）。`visiblePoints` 只数到触发阈值就停，因此可能正好等于阈值；按总量触发时是 `null`。PerfDemo 的面板可以直接切 auto / on / off，并在读数里看到这一份状态。
 
+## 点聚合（pointCluster）
+
+`pointCluster` 面向「点很密、单个符号已经没有辨认价值」的场景：按屏幕半径把邻近点合成一个圆，圆里显示数量；点击圆只发 `clusterClick`，不会误选内部节点。它只改变展示与命中，不改业务数据、选中集与 `getData()`：
+
+```js
+const view = createGisView(container, {
+  points,
+  pointCluster: { radius: 64, minPoints: 3, maxZoom: 2.5 }
+})
+
+const groups = view.getClusters()          // 含 count: 1 的单成员
+const state = view.getPointCluster()       // { enabled, radius, minPoints, maxZoom, active }
+const stats = view.getStats()              // clusterCount / clusterPointCount / clusterMs
+```
+
+- **配置**：写 `true` 用缺省档（半径 60px、至少 2 点、不限缩放）；`radius` 夹在 8 ~ 500 CSS 像素，`minPoints` 最小 2，`maxZoom: 0` 表示不限。`maxZoom` 以 `zoomBaseScale`（或首次适应视图比例）为基准，相机比例超过它之后 `active` 变 `false`，原始点逐点展开。
+- **算法开销**：`cluster.js` 用固定网格把邻近点串成组，每个点只查相邻 9 格，单次建组按总量 O(n)；成员用 `Int32Array` 链表保存，稀疏场景不为每个单成员常驻组对象。平移不重算聚合，缩放、数据、配置、选中集、拖动、合并与复制预览变化才标脏。
+- **绘制与拾取**：聚合圆单独一批绘制，原始点批次过滤掉被收起的成员；标签、涟漪、节点装饰、框选、最近点查询与 `listPoints({ visibleOnly: true })` 都按同一份隐藏集合跳过内部点。`getClusters()` 为需要全量展示组的场景补上单成员，绘制与数量文字只遍历多成员圆。
+- **隔离规则**：选中点、拖动成员、待确认合并的源 / 目标以及复制预览强制保持单成员，避免用户点不到正在操作的点；聚合开启时发散初始化与追加式补点暂停，保证成员关系按整份数据一次算清。
+- **和 denseMode 的关系**：两者可以同时开。`denseMode` 管标签避让 / 截断与动画降级，`pointCluster` 管点本身的展示密度；只希望更快但仍要看每个符号时可关掉聚合，只保留密集档。十万点档在 `?demo=cluster` 可现场切 2 千 / 1.2 万 / 6 万 / 10 万，并观察聚合耗时与展示项数。
+
 ## 大数据量
 
 10 万点 + 10 万线（含通道）在 `docs/demos/GisViewDemo.vue` 里可以直接切到，交互路径上没有按总量线性增长的循环：
 
-- **高密度纯文本标签自动画布化**：强制显示档（`labelOptimize` 未开、`denseMode` 未激活）下，节点层或线路层里能画布的纯文本标签达到 **1024** 条时，默认 `labelRender: 'auto'` 会让该层改用一张 `.gis-view__label-canvas`，不再为每条标签建 `div`。HTML、函数返回元素、可拖拽 / 可编辑及超出 Canvas 样式能力的标签仍留在同层 DOM，因此画布与少量 DOM 可以混排；`labelRender: 'dom'` 可强制回退逐条 DOM。优化档 / 密集档仍走 DOM（避让、截断与命中判定要真实量尺寸），这一步不是它们的替代品。`selftest-labels.html` 用 1100 条纯文本验证了点标签层只剩一张画布、混入一条 `html: true` 时只保留那一条 DOM，并覆盖切回 `dom`、再切回 `auto` 的节点回收与 SVG 导出。
+- **高密度纯文本标签画布化**：强制显示档（`labelOptimize` 未开、`denseMode` 未激活）下，节点层或线路层里能画布的纯文本标签达到 **1024** 条时，默认 `labelRender: 'auto'` 会让该层改用一张 `.gis-view__label-canvas`，不再为每条标签建 `div`。要求优化档也走画布时显式写 `labelRender: 'canvas'`：不设数量阈值，`maxCount` / `when` / `scanLimit` 仍照常截断，避让、换锚点与沿线滑动直接使用画布尺寸，不创建也不测量 DOM。HTML、函数返回元素、可拖拽 / 可编辑及超出 Canvas 样式能力的标签始终留在同层 DOM，因此画布与少量 DOM 可以混排；`labelRender: 'dom'` 可强制回退逐条 DOM。画布路径另有文字测量缓存（同字体 / 样式 / 文案只量一次）、交互期 `requestAnimationFrame` 合并重绘与屏外标签裁剪，连续平移 / 缩放时不会因多次指针事件重复清画布。`selftest-labels.html` 用 1100 条纯文本验证字宽只测一次、连续 5 次缩放只重绘 1 次、显式画布在优化档遵守 `maxCount: 200`，以及线路标签 6 条全部进画布；另覆盖混入 `html: true` 时只保留那一条 DOM、切回 `dom`、再切回 `auto` 的节点回收与 SVG 导出。
 - 拾取与框选共用网格索引：点走按数据范围重建的均匀网格，线走随线段重建的 `createSegmentGrid`，每次交互只遍历光标附近的候选，耗时与总量基本脱钩，`getStats().pickMs` 是随手可读的实测值（10 万规模下热态约 0.2 ~ 0.3 ms / 次）。线段按格线步进登记进它真正穿过的格子（早期按包围盒填格，一条斜跨全图的线会占掉上万格、只好整条丢进「超长线」单，而十万条线里绝大多数都是这种，于是每次拾取都要重算十万条的距离）；剩下的长线只记一条包围盒，查询时按盒子先筛一遍。10 万点 / 10 万线的合成数据里（随机配对、长线极密），500 次 `pick` 从 3530 ms 降到 164 ms（0.3 ms / 次）。
 - 拖动时「哪些线跟着这个点走」按需建索引：`collectDragLinks` 从前每次都把全部线路的端点与组内成员逐个比一遍，10 万点 / 12 万线下这一步占总 CPU 的 27%，是拖动路径上唯一还按总量线性付费的循环。现在线路超过 `LINE_BIND_TOLERANCE_SCAN_LIMIT`（2048）条时改用一张线路归属表（按 `from` / `to` 的 id 与端点坐标建，整份换数据 / 增删线 / 改绑定才重建，只改坐标就地把那一条换掉），只对命中的候选逐字段判定 —— 十万级拖动降到 CPU 的 1% 以下，单条 `updatePoint`（改名这类不动几何的改动）55 → 3.3 ms（稳态 0.02 ms）。线路不多时保留原来的浮点容差扫描（行为与从前逐字不差）；索引那条路只认 id 绑定与坐标精确相等 —— 这个量级坐标都是同一份来源算出来的，容差是给手写数据留的余量。
 - 视口里的线路改走线段网格：线路标签排版这类「只看屏幕里这一片」的路径（`forEachLineInView`）原先要把每条线的包围盒过一遍，10 万级 + 标签的 CPU profile 里它占 47 ~ 58%。现在线路超过 `LINE_VIEW_GRID_MIN_LINES`（2048）条、且估计出来的候选线段只占总数的 1/32 以内（`LINE_VIEW_GRID_COST_SHARE`）时改查拾取用的那张线段网格，再逐条按包围盒确认；候选排回要素下标顺序，脏线与没有线段的退化线单独补一遍，访问顺序与判定口径与整份扫描逐行相同。网格脏着（正在拖线 / 改线）或线路不多时照旧整份扫描。
 - 视口里的节点遍历也先查点网格：`forEachPointInView` 在节点超过 `POINT_VIEW_GRID_MIN_POINTS`（2048）、点网格不脏且估计候选不足总数的 1/32（`POINT_VIEW_GRID_COST_SHARE`）时，只查视口覆盖的格子、把候选排回数据顺序再逐个精确判定；网格脏着（刚改过数据 / 拖拽中）或视口几乎铺满时仍走整份扫描，避免为了省一趟遍历先付出建网格和排序的成本。`createPointGrid.estimate(..., stopAfter)` 与查询共用同一套格子口径，传 `stopAfter` 时一旦超过阈值立即返回，只判断候选是否过密时不必扫完视口里的全部格子；框选线路则复用已有的 `forEachLineInView`，不再为每条候选线复制路径 / 包围盒 / 颜色快照。
 - 悬停、选中、拖拽只做增量更新：选中集合用点 / 线两张下标 `Set` 维护，样式变化按要素下标重新解析，顶点与实例数据就地改写后按「实例槽位」上传，不重建整批缓冲。
 - 状态样式就地更新：悬停 / 选中样式只改颜色、大小、描边时按实例槽位覆盖，不重建整批；符号换成 / 换出贴图、阴影条数变化这类批次结构变化才回退整批重排。哪些要素当前真的按状态样式画过另有一份记账（`stateStyledSignatures`），整体重建后立刻重算，取消选中时按它精确还原本体样式，不会留下残留。
+- 动效只维护真正的动画线路：`lineEffectRuns` 让每帧的动点循环只遍历配了 `effect` 的线路，路径就地变化时只重算这一条的总长与包围盒；普通线路再多，也不会进入动画的逐帧扫描。
+- 热力图的要素采样与密度烘焙分开缓存：坐标 / 权重 / 显隐变化才重新采集，核参数 / 色带变化复用采样重烤，`density.opacity` 与 `layer` 只改绘制；拖动期间延迟到停手统一补烤。
+- 鹰眼图的线路层单独使用离屏 canvas：缓存键覆盖尺寸、范围、投影、倍率与样式，线路包围盒完全落在小图视野外时直接跳过；布局尺寸没变时不再重设画布尺寸，补画不会清空线路缓存。
 - 拐点只处理当前显示的那些：`waypointVisibility: 'selected'` 下没有选中线路时，上万条线的拐点解析与上传都省掉了。
 - 通道回线的偏移在骨架变化时统一推导一次，拖动过程中只重算这一条通道的成员线。
 - 配置变更走一次合并：`updateOptions({ points, lines, channels, background, ... })` 只在需要时重建场景；demo 里的通道宽度、内收距离用 `v-model.lazy` 提交，避免拖动滑块时每帧重排。

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

@@ -22,10 +22,10 @@
 ## 常见问题
 
 **拖也拖不动、点了没反应，是不是坏了？**
-不是 —— 功能开关**缺省全关**（见「功能开关」），什么都不写时组件只剩画布与数据。查看类要手动打开：详细配置写 `interactive: true`（平移 / 缩放 / 右键回调）与 `clickable: true`（悬停 / 选中），或一步写 `features: 'view'`；改数据的交互各有自己的开关 —— `boxSelect: true` / `draggable: true` / `waypointEditable: true` / `copy: {…}` / `merge: {…}` / `remove: {…}` / `features: { channelDraft: true, channelMenu: true }`，`features: 'edit'` 一次全开。标签 / 提示 / 鹰眼图不在开关表里：配了 `label` / `lineLabel` / `tooltip` / `minimap` 就等于打开。
+不是 —— 功能开关**缺省全关**（见「功能开关」），什么都不写时组件只剩画布与数据。查看类要手动打开：详细配置写 `interactive: true`（平移 / 缩放 / 右键回调）与 `clickable: true`（悬停 / 选中），或一步写 `features: 'view'`；改数据的交互各有自己的开关 —— `boxSelect: true` / `draggable: true` / `waypointEditable: true` / `copy: {…}` / `merge: {…}` / `remove: {…}` / `features: { channelDraft: true }`，`features: 'edit'` 一次全开。标签 / 提示 / 鹰眼图不在开关表里：配了 `label` / `lineLabel` / `tooltip` / `minimap` 就等于打开。
 
 **怎么一次关闭 / 打开组件的所有功能？**
-`features: false` 或 `features: 'static'` 会把全部 18 个功能开关关掉（`'static'` 连已配置的标签 / 提示 / 鹰眼图也一起关；`false` 与缺省全关同一口径）；`features: true` 或 `features: 'edit'` 全部打开。运行时用 `view.setFeatures(...)` 换、`view.getFeatures()` 读 18 项有效值，完整清单见「功能开关」一节的表。
+`features: false` 或 `features: 'static'` 会把全部 17 个功能开关关掉（`'static'` 连已配置的标签 / 提示 / 鹰眼图也一起关；`false` 与缺省全关同一口径）；`features: true` 或 `features: 'edit'` 全部打开。运行时用 `view.setFeatures(...)` 换、`view.getFeatures()` 读 17 项有效值，完整清单见「功能开关」一节的表。
 
 **怎么完全关闭拐点的新增、移动和删除？**
 写 `features: { waypoint: false }` 或 `waypointEditable: false`。`waypoint` 就是拐点编辑的唯一总闸：新增（Ctrl + 点击、`addWaypoint` / `addWaypoints` / `addChannelGroupWaypoint`、通道右键框「加拐点」）、移动已有拐点、双击 / Delete 删除会同时停掉，没有只关其中一项的细分开关。已有拐点仍可显示和选中，数据与历史都不动。
@@ -39,6 +39,9 @@
 **数据更新之后画面没变？**
 `updateData`（只换一列时用 `updateData({ points })` / `updateData({ lines })`）会换数据副本；直接改数组里的对象不会触发重画，改单个要素请用 `updatePoint` / `updateLine` / `updateChannel`，或者重新 `updateData` 一次。
 
+**筛选之后，选中的要素会从选中集里消失吗？**
+默认不会。`setFilter` 的 `mode` 缺省是 `'hide'`：原始数据、选中集与 `getSelections()` 都保持原样，被隐藏的选中项在条件放宽 / 清空后恢复高亮，也不会额外发一次 `onSelectChange`。显式写 `mode: 'remove'` 时，不命中的要素会从数据里删掉（被删的选中项也会从选中集移除），只发一条 `filterRemove`，可用历史撤销。搜索同理：`search({ scope: 'group' })` 只返回分组命中，不隐藏其它要素；命中可交给 `focusOn` / `selectFeatures`。
+
 **接口数据还没回来，先 createGisView 还是等回来再建？**
 先建。空实例照样先铺底图 / 网格，第一次 `updateData` 拿到数据时会按 `initialView` 自动落一次位（容器当时是 0×0 也会记成待办、显示出来补上）；相机、筛选、选中、标签与历史都挂在实例上，等接口回来再 `destroy()` 重建会全丢。收 loading 用 `whenDataRendered()`，完整写法与几条注意点在「动态换数据与加载完成」的「从接口拿数据」与「接口列名不一样」两段。
 
@@ -166,7 +169,7 @@
 | 分类 | 类型 |
 | --- | --- |
 | 入口 | `GisViewOptions`、`GisViewInstance`、`GisViewEngineOptions`、`GisViewEngine`、`createGisView`、`createGisViewEngine` |
-| 插件与初始视图 | `GisViewPlugin`、`GisViewInitialView` |
+| 插件与初始视图 | `GisViewPlugin`、`GisViewInitialView`、`GisViewFitSpacingOptions` |
 | 数据 | `GisViewPoint`、`GisViewLine`、`GisViewChannel`、`GisViewChannelGroup`、`GisViewData`、`GisViewCoordinate`、`GisViewBounds`、`GisViewRect` |
 | 样式 | `GisViewPointStyle`、`GisViewLineStyle`、`GisViewShadow`、`GisViewSelectionBoxStyle`、`GisViewCursorStyle`、`GisViewCursorValue`、`GisViewCursorTarget` |
 | 线型 | `GisViewLineType`、`GisViewLineDash`、`GisViewLineDashValues`、`GisViewLineDashObject` |
@@ -174,17 +177,17 @@
 | 规则与条件 | `GisViewPointRule`、`GisViewLineRule`、`GisViewConditionInput`、`GisViewCondition`、`GisViewConditionOperator`、`createConditionMatcher` |
 | 热力图 | `GisViewHeatmap`、`GisViewHeatmapGlow`、`GisViewHeatmapDensity`、`GisViewHeatmapDensityCore`、`GisViewHeatmapTarget`、`GisViewHeatmapMissing`、`GisViewHeatmapOverride` |
 | 覆盖层 | `GisViewLabelOptions`、`GisViewLineLabelOptions`、`GisViewItemLabel`、`GisViewLabelState`、`GisViewLabelPatch`、`GisViewSetLabelContentOptions`、`GisViewLabelListItem`、`GisViewItemLabelsInfo`、`GisViewRemoveLabelResult`、`GisViewSetLabelStatesResult`、`GisViewLabelChangePayload`、`GisViewLabelDragPayload`、`GisViewLabelClickPayload`、`GisViewLabelPointerPayload`、`GisViewLabelRef`、`GisViewLabelTarget`、`GisViewLabelBatchEntry`、`GisViewLabelRemoveEntry`、`GisViewLabelBatchSkip`、`GisViewAddLabelsResult`、`GisViewUpdateLabelsResult`、`GisViewRemoveLabelsResult`、`GisViewLineDecoration`、`GisViewTooltipOptions`、`GisViewLabelPayload`、`GisViewLineLabelPayload` |
-| 筛选 | `GisViewFilter`、`GisViewFilterResult`、`GisViewFilterCascade`、`GisViewFilterWorkerOptions` |
+| 筛选 | `GisViewFilter`、`GisViewFilterInput`、`GisViewFilterShorthand`、`GisViewFilterResult`、`GisViewFilterCascade`、`GisViewFilterMode`、`GisViewFilterWorkerOptions` |
 | 大数据展示模式 | `GisViewDenseMode`、`GisViewDenseModeOptions`、`GisViewDenseModeInput`、`GisViewDenseState` |
-| 通道 | `GisViewChannelInput`、`GisViewChannelBuildOptions`、`GisViewChannelBuild`、`GisViewChannelInfo`、`GisViewChannelGroupInfo`、`GisViewChannelGroupWaypoints`、`GisViewChannelGroupLineWaypoints`、`GisViewChannelMember`、`GisViewChannelContext`、`GisViewChannelContextPayload`、`GisViewChannelAddPlan`、`GisViewChannelBetween`、`GisViewChannelAddOption`、`GisViewChannelAddInput`、`GisViewChannelAddResult`、`GisViewChannelDraftOptions`、`GisViewChannelDraftPayload`、`GisViewChannelLineMoveTarget`、`GisViewChannelLineMoveResult`、`GisViewRemoveLineResult`、`GisViewRemoveChannelResult`、`GisViewRemoveLinesResult`、`GisViewChannelInView`、`GisViewChannelAction`、`GisViewChannelActionId`、`GisViewChannelDraftStyle`、`GisViewChannelWaypointDragMode`、`createChannels`、`CHANNEL_DEFAULT_COLORS` |
-| 事件载荷 | `GisViewPickResult`、`GisViewPickAtResult`、`GisViewRectQueryResult`、`GisViewSelectionInfo`、`GisViewSelectedItems`、`GisViewSelectPayload`、`GisViewClickPayload`、`GisViewPointerPayload`、`GisViewPointerAction`、`GisViewPointerActionType`、`GisViewPointerTarget`、`GisViewPointerModifiers`、`GisViewWaypointActionData`、`GisViewLabelActionData`、`GisViewHoverPayload`、`GisViewCursorPayload`、`GisViewPointDragPayload`、`GisViewDragPointChange`、`GisViewDragLineChange`、`GisViewPointCopyPayload`、`GisViewPointCopyState`、`GisViewPointMergePayload`、`GisViewMergeImpact`、`GisViewMergeResult`、`GisViewMergeFailure`、`GisViewWaypointPayload`、`GisViewWaypointInfo`、`GisViewWaypointKey`、`GisViewParallelGroup`、`GisViewReadyPayload`、`GisViewEngineStats`、`GisViewEngineHeatDensity`、`GisViewDataChangeType`、`GisViewDataChangePayload`、`GisViewSelectChangePayload`、`GisViewShortcutPayload`、`GisViewRenderPayload`、`GisViewAddItemsResult`、`GisViewAddPointResult` |
+| 通道 | `GisViewChannelInput`、`GisViewChannelBuildOptions`、`GisViewChannelBuild`、`GisViewChannelInfo`、`GisViewChannelGroupInfo`、`GisViewChannelGroupWaypoints`、`GisViewChannelGroupLineWaypoints`、`GisViewChannelMember`、`GisViewChannelContext`、`GisViewChannelAddPlan`、`GisViewChannelBetween`、`GisViewChannelAddOption`、`GisViewChannelAddInput`、`GisViewChannelAddResult`、`GisViewChannelDraftOptions`、`GisViewChannelDraftPayload`、`GisViewChannelLineMoveTarget`、`GisViewChannelLineMoveResult`、`GisViewRemoveLineResult`、`GisViewRemoveChannelResult`、`GisViewRemoveLinesResult`、`GisViewChannelInView`、`GisViewChannelAction`、`GisViewChannelActionId`、`GisViewChannelDraftStyle`、`GisViewChannelWaypointDragMode`、`createChannels`、`CHANNEL_DEFAULT_COLORS` |
+| 事件载荷 | `GisViewPickResult`、`GisViewPickAtResult`、`GisViewRectQueryResult`、`GisViewSelectionInfo`、`GisViewSelectedItems`、`GisViewSelectPayload`、`GisViewClickPayload`、`GisViewPointerPayload、GisViewCascadeHighlightScope、GisViewCascadeHighlightOptions、GisViewCascadeHighlightInput、GisViewCascadeHighlightEntry、GisViewCascadeHighlightOrigin、GisViewCascadeHighlightInfo`、`GisViewPointerAction`、`GisViewPointerActionType`、`GisViewPointerTarget`、`GisViewPointerModifiers`、`GisViewWaypointActionData`、`GisViewLabelActionData`、`GisViewHoverPayload`、`GisViewCursorPayload`、`GisViewPointDragPayload`、`GisViewDragPointChange`、`GisViewDragLineChange`、`GisViewPointCopyPayload`、`GisViewPointCopyState`、`GisViewPointMergePayload`、`GisViewMergeImpact`、`GisViewMergeResult`、`GisViewMergeFailure`、`GisViewWaypointPayload`、`GisViewWaypointInfo`、`GisViewWaypointKey`、`GisViewParallelGroup`、`GisViewReadyPayload`、`GisViewEngineStats`、`GisViewEngineHeatDensity`、`GisViewDataChangeType`、`GisViewDataChangePayload`、`GisViewSelectChangePayload`、`GisViewShortcutPayload`、`GisViewRenderPayload`、`GisViewAddItemsResult`、`GisViewAddPointResult` |
 | 快捷键与复制 / 合并 / 删除 | `GisViewShortcuts`、`GisViewShortcut`、`GisViewShortcutAction`、`GisViewCopyOptions`、`GisViewCopyContext`、`GisViewCopyStartOptions`、`GisViewPasteOptions`、`GisViewCopyItem`、`GisViewClipboardItem`、`GisViewMergeOptions`、`GisViewMergeContext`、`GisViewPointStyleSnapshot`、`GisViewPointRef`、`GisViewMergeResult`、`GisViewMergeFailure`、`GisViewMergeOutcome`、`GisViewRemovePointsOutcome`、`GisViewRemoveSelectedOutcome`、`GisViewRemoveOptions`、`GisViewRemoveScope`、`GisViewRemovePayload`、`GisViewRemoveResult`、`GisViewRemoveOutcome`、`GisViewRemoveFailure`、`GisViewRemoveAction`、`GisViewRemovePoint`、`GisViewRemoveLine`、`GisViewRemoveWaypoint`、`GisViewRemoveGroup`、`GisViewRemoveChannel`、`GisViewRemoveCounts`、`GisViewChannelSelectMode`、`GisViewUpdateItemsOutcome`、`GisViewUpdateItemEntry` |
 | 相机与视图 | `GisViewCamera`、`GisViewViewport`、`GisViewFocusOptions`、`GisViewFocusTarget`、`GisViewExportImageOptions`、`GisViewExportSelectionOptions`、`GisViewExportSelectionResult` |
 | 导出数据 | `GisViewExportScope`、`GisViewExportPart`、`GisViewExportDataOptions`、`GisViewExportDataResult`、`GisViewFeatureRef`、`GisViewExportFilterOptions`、`GisViewExportMeta`、`GisViewExportedLabel`、`GisViewStationRecord`、`GisViewPointRecord`、`GisViewLineRecord`、`GisViewChannelRecord`、`GisViewExportFormat`、`GisViewBuiltinExportFormat`、`GisViewExportFormatContext`、`GisViewExportFormatAdapter` |
-| 开关 / 历史 / 事件 | `GisViewFeatureName`、`GisViewFeatures`、`GisViewFeatureState`、`GisViewFeaturePreset`、`GisViewFeaturesInput`、`FEATURE_NAMES`、`FEATURE_PRESETS`、`FEATURE_PRESET_NAMES`、`FEATURE_EDIT_NAMES`、`featureDefault`、`normalizeFeatures`、`featureOn`、`hasForcedFeatures`、`GisViewHistoryOptions`、`GisViewHistoryState`、`GisViewHistoryEntry`、`GisViewHistoryRecord`、`GisViewHistoryOp`、`GisViewHistoryOpEntry`、`GisViewHistoryRecorder`、`GisViewHistoryHost`、`GisViewHistoryPayload`、`GisViewHistoryStepResult`、`GisViewHistoryAction`、`GisViewHistoryCollection`、`createGisHistory`、`normalizeHistoryOptions`、`applyHistoryOps`、`DEFAULT_HISTORY_LIMIT`、`HISTORY_COLLECTIONS`、`GisViewEventMap`、`GisViewEventName`、`GisViewEventNameInput`、`GisViewEventWildcard`、`GisViewEventListener`、`GisViewAnyEventListener`、`GisViewEventBus`、`GisViewEventBusHost`、`createGisEventBus`、`EVENT_NAMES` |
+| 开关 / 历史 / 事件 | `GisViewFeatureName`、`GisViewFeatures`、`GisViewFeatureState`、`GisViewFeaturePreset`、`GisViewFeaturesInput`、`GisViewSelectTrigger`、`FEATURE_NAMES`、`FEATURE_PRESETS`、`FEATURE_PRESET_NAMES`、`FEATURE_EDIT_NAMES`、`featureDefault`、`normalizeFeatures`、`featureOn`、`hasForcedFeatures`、`GisViewHistoryOptions`、`GisViewHistoryState`、`GisViewHistoryEntry`、`GisViewHistoryRecord`、`GisViewHistoryOp`、`GisViewHistoryOpEntry`、`GisViewHistoryRecorder`、`GisViewHistoryHost`、`GisViewHistoryPayload`、`GisViewHistoryStepResult`、`GisViewHistoryAction`、`GisViewHistoryCollection`、`createGisHistory`、`normalizeHistoryOptions`、`applyHistoryOps`、`DEFAULT_HISTORY_LIMIT`、`HISTORY_COLLECTIONS`、`GisViewEventMap`、`GisViewEventName`、`GisViewEventNameInput`、`GisViewEventWildcard`、`GisViewEventListener`、`GisViewAnyEventListener`、`GisViewEventBus`、`GisViewEventBusHost`、`createGisEventBus`、`EVENT_NAMES` |
 | 动画效果与预热 | `GisViewLineEffect`、`GisViewLineEffectInput`、`GisViewPointEffect`、`GisViewPointEffectInput`、`GisViewEffectsOptions`、`GisViewEffectsInput`、`GisViewEffectsReadout`、`GisViewLineEffectReadout`、`GisViewPointEffectReadout`、`GisViewPrebakeOptions`、`GisViewPrebakeCombo`、`GisViewPrebakeReadout`、`GisViewSymbolCombos`、`PREBAKE_COMBO_KEYS`、`LINE_EFFECT_DEFAULTS`、`LINE_EFFECT_KEYS`、`POINT_EFFECT_DEFAULTS`、`POINT_EFFECT_KEYS`、`EFFECT_OPTION_KEYS`、`PREBAKE_OPTION_KEYS`、`normalizeLineEffect`、`normalizePointEffect`、`normalizeEffectsOptions`、`normalizePrebakeCombo`、`normalizePrebakeOptions`、`isEffectConfig`、`isEffectsExplicitlyOff`、`wrapPhase`、`phaseSeed`、`polylineLength`、`samplePolyline`、`lineEffectDistance`、`pointEffectPhase`、`sameLineEffect`、`samePointEffect` |
 | 坐标与映射 | `GisViewGeoProjection`、`GisViewGeoMapper`、`GisViewGeoMapperOptions`、`GisViewPointerState`、`GisViewResolvedGeoJson`、`createGeoProjection`、`createGeoMapper` |
-| 搜索 | `GisViewSearchOptions`、`GisViewSearchScope`、`GisViewSearchHit`、`GisViewSearchResult`、`GisViewVisiblePoint` |
+| 搜索 | `GisViewSearchOptions`、`GisViewSearchScope`、`GisViewSearchScopeInput`、`GisViewSearchHit`、`GisViewSearchGroupItem`、`GisViewSearchResult`、`GisViewVisiblePoint` |
 | 背景 | `GisViewBackground`、`GisViewBackgroundImage`、`GisViewGeoJsonStyle`、`GeoJsonInput`、`GeoJsonFeatureCollection`、`GeoJsonFeature`、`GeoJsonGeometry`、`GeoJsonPosition` |
 | 鹰眼图 | `GisViewMinimapOptions`、`GisViewMinimapExtent`、`GisViewMinimapPointStyle`、`GisViewMinimapLineStyle`、`GisViewMinimapBoxStyle`、`GisViewMinimapPointRule`、`GisViewMinimapLineRule`、`GisViewMinimapDrawData`、`GisViewMinimapDrawInfo`、`GisViewMinimapLayer`、`GisViewMinimapLayerPlacement`、`GisViewMinimapLayerStage`、`GisViewMinimapInteractionType`、`GisViewMinimapInteractionInfo` |