gis-view-webgl2 0.1.3 → 0.1.5

package/dist/index.d.ts

@@ -489,9 +489,21 @@ export interface GisViewMinimapOptions {
 	/** 尺寸（CSS 像素），默认 168 × 120 */
 	width?: number
 	height?: number
+	/** 贴近主视图（或 container 指定的外部宿主）的哪个角，默认 bottom-right */
 	position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
 	/** 距离容器边缘的间距（CSS 像素），默认 12 */
 	margin?: number
+	/**
+	 * 相对 position 那个角的位移（CSS 像素，[x, y]）：x 正数向右、y 正数向下。
+	 * 四角配置都按同一直觉换算，updateOptions 改它就能动态移动整张鹰眼图。
+	 */
+	offset?: [number, number]
+	/**
+	 * 外部宿主：HTMLElement 或 CSS 选择器。给了就把小图根节点挂到它里面，position / margin / offset
+	 * 都相对这个元素；外部宿主需要 position: relative（或 absolute / fixed）才能让绝对定位按它算。
+	 * 不写 / 选择器找不到时回落到主视图根节点；运行时换容器会移动同一个根节点，不重建画布。
+	 */
+	container?: HTMLElement | string | null
 	/**
 	 * 小图背景：'inherit'（默认）画主视图那一份（底色 / 图片 / GeoJSON，含区域配色与文字）；
 	 * false / 'none' 不画；字符串是容器底色（旧写法）；对象是与 background 同结构的独立配置
@@ -504,6 +516,12 @@ export interface GisViewMinimapOptions {
 	 * 两者离得很远就是这样），只画正在看的那一份 —— 合并只会让两份都看不清
 	 */
 	extent?: GisViewMinimapExtent
+	/**
+	 * `extent: 'auto'` 时是否允许范围跟着相机收窄：默认 false，始终按「数据 ∪ 底图」铺。
+	 * 打开后，相机落在其中一份范围、而那份在合并结果里不足 6 像素时只画正在看的那一份；
+	 * 数据 / 底图内容消失、相机进出这份范围时鹰眼图会重新计算包围盒。
+	 */
+	extentFollowCamera?: boolean
 	/** 给小图容器再加一个类名（与内置的 gis-view__minimap 并列），方便用样式表改外观 */
 	className?: string
 	/** 直接落到小图容器上的内联样式（中划线 / CSS 变量键与驼峰键都认）；换配置时上一轮写过、这一轮没写的键会被清掉 */
@@ -515,7 +533,10 @@ export interface GisViewMinimapOptions {
 	draw?: (info: GisViewMinimapDrawInfo) => void
 	/** 可拆分的自定义绘制层：按 placement 分段、段内按 order，最后才轮到旧的 draw */
 	layers?: GisViewMinimapLayer[]
-	/** 小图容器的底色（CSS），默认 rgba(255, 255, 255, 0.92) */
+	/**
+	 * 小图容器的底色（CSS），默认 rgba(255, 255, 255, 0.92)。显式设置时它接管画布底色：
+	 * 继承的底图仍画图片 / GeoJSON，但不再用主图的不透明底色盖住它。
+	 */
 	backgroundStyle?: string
 	/** 小图画布备份像素比上限（默认 4）：高分屏或宿主缩放很大时可降到 1 ~ 2 降低填充开销 */
 	maxPixelRatio?: number
@@ -529,12 +550,18 @@ export interface GisViewMinimapOptions {
 	lineStyle?: GisViewMinimapLineStyle
 	/**
 	 * 节点规则：按属性给小图上的节点定颜色 / 半径 / 形状 / 层级（条件语言与主图一样）。
-	 * 不配时沿用主图的 pointRules，但只取颜色与层级：主图的尺寸是主画布上的像素，搬到小图上会糊成一片
+	 * 不配时沿用主图样式链：颜色 / 描边色 / 层级取规则，尺寸与符号取引擎最终解析结果
+	 * （点自身 > 主图 pointRules > 主图 pointStyle），圆、方、图片与 SVG 图标都会画出来
 	 */
 	pointRules?: GisViewMinimapPointRule[]
-	/** 线路规则：按属性给小图上的线路定颜色 / 线宽 / 透明度 / 层级，不配时沿用主图 lineRules（只取颜色与透明度） */
+	/** 线路规则：按属性给小图上的线路定颜色 / 线宽 / 透明度 / 层级，不配时沿用主图 lineRules（颜色 / 透明度）与样式链线宽 */
 	lineRules?: GisViewMinimapLineRule[]
-	/** 没有自己的规则时是否沿用主图的 pointRules / lineRules，默认 true；显式 false 表示小图只用 pointStyle / lineStyle */
+	/**
+	 * 没有自己的规则时是否沿用主图样式，默认 true：节点连尺寸与图标一起沿用，线路沿用颜色 / 透明度 / 线宽；
+	 * 沿用尺寸时按小图与主图 CSS 视口宽高的较小比例缩放，独立于主图相机倍数与小图自身倍数；
+	 * 小图自身多次放大时再按 pointZoomScale / lineZoomScale 联动；
+	 * 显式 false 表示小图只用 pointStyle / lineStyle
+	 */
 	inheritRules?: boolean
 	/**
 	 * 小图自己的热力图：不写就沿用主图的 options.heatmap（两边的色带与取的值完全一致，自动值域也按同一份数据算），
@@ -551,24 +578,24 @@ export interface GisViewMinimapOptions {
 	 * 主视图筛选出来的隐藏结果本来就带联动，这里管的是小图自己挡掉的那部分
 	 */
 	cascade?: GisViewFilterCascade
-	/** 节点半径的整体倍数（与主视图的 pointSizeScale 同名同义，常数倍数），默认 1 */
+	/** 节点半径的整体倍数（与主视图的 pointSizeScale 同名同义，常数倍数）：自有规则与沿用主图的节点都乘这一份，默认 1 */
 	pointSizeScale?: number
-	/** 线路宽度的整体倍数（与主视图的 lineWidthScale 同名同义），默认 1 */
+	/** 线路宽度的整体倍数（与主视图的 lineWidthScale 同名同义）：自有规则与沿用主图的线路都乘这一份，默认 1 */
 	lineWidthScale?: number
 	/**
 	 * 小图自身的倍数对节点半径的放大指数（0 表示不跟随，1 表示同倍率放大），默认 0。
 	 * 只在小图真的放大过才看得出来：zoomable 关着、或者倍数还在 1（刚好铺满）时是恒等系数；
-	 * 想让小图跟着**主视图**的缩放一起变，配的是 pointMapZoomScale
+	 * 沿用主图规则的节点也按这一份联动；主图相机倍数不会改变它们的大小
 	 */
 	pointZoomScale?: number
-	/** 小图自身的倍数对线路宽度的放大指数（0 表示不跟随），默认 0；同样只在小图倍数 ≠ 1 时起作用，跟随主视图要用 lineMapZoomScale */
+	/** 小图自身的倍数对线路宽度的放大指数（0 表示不跟随），默认 0；同样只在小图倍数 ≠ 1 时起作用，沿用主图线宽也按它联动 */
 	lineZoomScale?: number
 	/**
-	 * 主视图的地图倍数对节点半径的放大指数：0（默认）不跟随，1 与主视图同倍率放大，
-	 * 0.5 是主视图放大 4 倍、小图节点放大 2 倍。与主视图的 pointZoomScale 是同一套说法
+	 * 主视图的地图倍数对**小图自有规则 / 样式**节点半径的放大指数：0（默认）不跟随，1 与主视图同倍率放大，
+	 * 0.5 是主视图放大 4 倍、小图节点放大 2 倍。沿用主图规则的节点不吃这一份（尺寸只跟视口比例与小图自身倍数）
 	 */
 	pointMapZoomScale?: number
-	/** 主视图的地图倍数对线路宽度的放大指数（0 表示不跟随、1 同倍率），与主视图的 lineZoomScale 同一套说法 */
+	/** 主视图的地图倍数对**小图自有规则 / 样式**线路宽度的放大指数（0 不跟随、1 同倍率）；沿用主图线宽不吃这一份 */
 	lineMapZoomScale?: number
 	/** 地图倍数联动的基准比例，缺省取主视图首次适应视图时的比例（与主视图 zoomBaseScale 同源） */
 	mapZoomBaseScale?: number
@@ -582,9 +609,9 @@ export interface GisViewMinimapOptions {
 	onInteraction?: (info: GisViewMinimapInteractionInfo) => void
 	/** 长按多久算「要移动视角」（毫秒），默认 180 */
 	longPressDelay?: number
-	/** 在小图上滚轮是否缩放主图（以光标处的世界坐标为锚点），默认 true；zoomable 打开时改由 Ctrl / ⌘ + 滚轮触发 */
+	/** 在小图上滚轮是否缩放主图（以光标处的世界坐标为锚点），默认 true；zoomable: true 时改由 Ctrl / ⌘ + 滚轮触发 */
 	wheelZoom?: boolean
-	/** 鹰眼图自身的倍数：1（默认）是「刚好铺满小图」，滚轮与 setMinimapZoom 改的都是它 */
+	/** 鹰眼图自身的倍数：1（默认）是「刚好铺满小图」；手动缩放时由滚轮 / setMinimapZoom 改，跟随主图时它是基准倍数 */
 	zoom?: number
 	/** 倍数下限与上限，默认 0.5 / 8 */
 	minZoom?: number
@@ -595,16 +622,26 @@ export interface GisViewMinimapOptions {
 	zoomInStep?: number
 	/** 只覆盖「缩小」一侧的步进倍率，缺省用 zoomStep */
 	zoomOutStep?: number
-	/** 是否允许缩放鹰眼图自身（滚轮，锚点落在光标处），默认 false；打开后滚轮不再缩放主图（改为 Ctrl / ⌘ + 滚轮） */
-	zoomable?: boolean
 	/**
-	 * 开了 zoomable 之后，小图空白处（视口框之外）拖动的动作：
+	 * 缩放模式，默认 false（关闭）：
+	 * - true：手动缩放鹰眼图自身，滚轮以光标为锚点，滚轮不再缩放主图（改为 Ctrl / ⌘ + 滚轮）；
+	 * - 'follow'：整体显示范围跟随主图倍数变化，滚轮仍然缩放主图；与 true 互斥。
+	 */
+	zoomable?: boolean | 'follow'
+	/**
+	 * `zoomable: 'follow'` 时主图相对基准倍数的指数：1（默认）同倍率，0.5 表示主图放大 4 倍、鹰眼图放大 2 倍，
+	 * 0 表示鹰眼图倍数不随主图变化。最终倍数仍夹在 minZoom ~ maxZoom 之间。
+	 */
+	followZoomScale?: number
+	/**
+	 * 小图空白处（视口框之外）拖动的动作：
 	 * pan（默认）平移小图内容，box 直接拉出框选矩形（松手后主图显示框住的区域）。
-	 * 按住 Ctrl / ⌘ 拖动始终是另一个动作，两个动作不用切换配置就能用。
+	 * box 不依赖 zoomable；只有手动缩放（zoomable: true）时，按住 Ctrl / ⌘ 才会切换成另一个动作。
 	 */
 	dragAction?: 'pan' | 'box'
 	/**
-	 * 通道是否画出全部回线，默认 true；关掉（false）时一个通道只画偏移最靠中间的那一根。
+	 * 通道是否画出全部回线，默认 true；关掉（false）时一个通道分组只画一根代表线：
+	 * 按当前可见成员逐顶点取平均，双回线落在两根正中间（而不是固定挑上面 / 左边那一根）。
 	 * 通道多、底图挤的时候关掉更清爽，通道位置与走向仍然看得出来。
 	 */
 	channelCircuits?: boolean
@@ -2216,6 +2253,50 @@ export interface GisViewChannelAddSpec {
 	group?: GisViewChannelAddGroup | GisViewChannelAddGroup[]
 }
 
+/**
+ * commitAddChannel 的对象入参：可以写一份新通道 / 新线路，也可以放在 channel / line / lines 里逐段给。
+ * - 直接通道对象必须带 lineIds：每个 id 生成一条新回线，groups 是分组声明；通道 id 不参与回线 id。
+ * - 直接线路对象的业务字段透传到 lineProps；path 是中间拐点，首尾仍取 from / to。
+ * - 容器里的 line 缺省是独立线路，lines / lineData / lineItems 才是成员回线表，且 lines 优先；
+ *   空数组不覆盖草稿。channel.lineIds 只在没有成员回线表时当 id 种子。
+ * - 对象里的端点、id、名称、路径、样式与分组优先于草稿；没写的字段仍沿用当前草稿。
+ * - 容器顶层的 channel.lineProps 目前不参与合并；公共字段写顶层 lineProps，单条写 lines[i]。
+ */
+export interface GisViewChannelAddCommitInput extends Partial<GisViewChannelAddInput> {
+	/** 本次新增的通道对象（lineIds 会作为新回线 id 种子；groups 作为分组声明） */
+	channel?: GisViewChannel
+	/** 本次新增的一条线路对象（写了它就按独立线路提交） */
+	line?: GisViewLine
+	/** 本次新增的回线对象 / 数据（一条或一批，与 lineData / lineItems 同义） */
+	lines?: GisViewChannelLineData
+	/** lines 的别名（与 addChannel 的第二段同一个写法） */
+	lineData?: GisViewChannelLineData
+	/** 新通道的分组声明（与 channel.groups 同义） */
+	channelGroups?: GisViewChannelAddGroup | GisViewChannelAddGroup[]
+	/** channelGroups 的别名（与 addChannel 的第三段同一个写法） */
+	group?: GisViewChannelAddGroup | GisViewChannelAddGroup[]
+}
+
+/** 新增通道草稿端点示例点单端的样式：只写哪几项就覆盖哪几项 */
+export interface GisViewChannelDraftDotStyle {
+	/** 这一端是否画示例点，默认 true */
+	show?: boolean
+	/** 示例点半径（CSS 像素），缺省用 dot */
+	size?: number
+	/** 示例点颜色，缺省用 dots.color / dotColor / color */
+	color?: string
+	/** 形状，缺省 circle */
+	shape?: 'circle' | 'square'
+}
+
+/** 草稿两端示例点的共同样式；from / to 可以分别覆盖 */
+export interface GisViewChannelDraftDots extends GisViewChannelDraftDotStyle {
+	/** 起点的单独设置（优先于这一层的共同设置） */
+	from?: GisViewChannelDraftDotStyle
+	/** 终点的单独设置（优先于这一层的共同设置） */
+	to?: GisViewChannelDraftDotStyle
+}
+
 /** 新增通道草稿线的样式：跟随光标的那条预览线 */
 export interface GisViewChannelDraftStyle {
 	color?: string
@@ -2225,6 +2306,16 @@ export interface GisViewChannelDraftStyle {
 	dot?: number
 	/** 端点圆点颜色，缺省沿用 color */
 	dotColor?: string
+	/**
+	 * 两端示例点：false 两个都不画，true / 不写按 dot 与 dotColor 画；对象可统一设置 size / color / shape / show，
+	 * 并用 from / to 分别覆盖。示例点始终画在真正点中的节点中心（不受多回线偏移影响）。
+	 */
+	dots?: boolean | GisViewChannelDraftDots
+	/**
+	 * 示例线路的绘制层级：'above'（默认，画在真实节点之后）或 'below-points'（线 / 箭头 / customDraw 先画，
+	 * 再盖真实节点）；端点示例点始终在节点之后画，确保看得见。
+	 */
+	layer?: 'above' | 'below-points'
 	/** 预览线末端是否画方向箭头，缺省 false */
 	arrow?: boolean
 	/** 箭头大小（CSS 像素），缺省 12 */
@@ -2886,7 +2977,7 @@ export interface GisViewClickPayload extends GisViewPickResult {
 	selection: GisViewSelectionInfo
 	/**
 	 * 这一次点击的判读：type 为 'select'（点中要素、选中已生效）或 'click'（没开选中时的普通点击），
-	 * double 为 true 说明这一下是双击里的第二下。点空白处的载荷是 null，
+	 * 多选取反生效时是 'toggleSelect'；double 为 true 说明这一下是双击里的第二下。点空白处的载荷是 null，
 	 * 「点了空白」这件事看 onPointerDown / onPointerUp 的 action.target（'empty'）与 selectChange。
 	 */
 	action: GisViewPointerAction
@@ -3681,6 +3772,8 @@ export type GisViewDataChangeType =
 	| 'addLines'
 	| 'removePoints'
 	| 'removeLines'
+	/** 删除型筛选（filter.mode: 'remove'）把不命中的要素从数据里删掉 */
+	| 'filterRemove'
 	| 'removeSelected'
 	| 'removeLine'
 	| 'removeChannel'
@@ -3704,6 +3797,8 @@ export interface GisViewDataChangePayload {
 	/** 动到 / 删掉的节点下标（单点更新是那一个，删除是删除前的下标升序，新增是它们在数组里的位置） */
 	index?: number
 	indexes?: number[]
+	/** 这一次删掉的节点下标（删除前它们在 points 里的位置，升序；removeSelected / filterRemove 会带上） */
+	pointIndexes?: number[]
 	/** 这一次调用成没成（addPoints / addLines / removePoints 这类批量接口会带上） */
 	ok?: boolean
 	/** 新增这类动作：这批要素是从哪个下标开始接上去的（就是追加前原数组的长度） */
@@ -3753,8 +3848,14 @@ export interface GisViewDataChangePayload {
 	lineIndex?: number
 	channelId?: string | number | null
 	channelIndex?: number
+	/** filterRemove：这次从数据里删掉的节点数据，顺序与 pointIndexes 对应 */
+	removedPoints?: GisViewPoint[]
+	/** filterRemove：这次从数据里删掉的线路数据，顺序与 removedLineIndexes 对应 */
+	removedLineItems?: GisViewLine[]
 	removedLineIds?: Array<string | number>
 	removedLineIndexes?: number[]
+	/** filterRemove：固定为 'remove'，便于按载荷分流 */
+	mode?: GisViewFilterMode
 	/** 通道分组：这条通道最新的分组声明 */
 	groups?: GisViewChannelGroup[]
 	replaced?: boolean
@@ -4886,19 +4987,29 @@ export interface GisViewTooltipOptions {
  */
 export type GisViewFilterCascade = false | 'binding' | 'coordinate' | 'both'
 
-/** 筛选条件：点、线各一个条件，缺省表示该维度不过滤 */
+/** 筛选模式：hide 只隐藏（缺省）；remove 把不命中的要素从数据里删掉（不可恢复，除非撤销） */
+export type GisViewFilterMode = 'hide' | 'remove'
+
+/**
+ * 筛选条件：点、线各一个条件，缺省表示该维度不过滤。
+ * 缺省 mode: 'hide' 只算「隐藏集合」，不改数据；已经选中的要素被隐藏后仍留在选中集里，
+ * 条件放宽 / 清空后会原样恢复高亮。mode: 'remove' 把筛选结果（hiddenPoints / hiddenLines）
+ * 真正从数据里删掉（走 dataChange('filterRemove')，可用撤销恢复；不会额外按节点联级删线路）。
+ */
 export interface GisViewFilter {
 	points?: GisViewConditionInput<GisViewPoint>
 	lines?: GisViewConditionInput<GisViewLine>
 	/** 联动隐藏，默认 binding */
 	cascade?: GisViewFilterCascade
+	/** 不命中的要素怎么处理：'hide' 只隐藏（默认），'remove' 从数据里删除 */
+	mode?: GisViewFilterMode
 	/** 是否用 Worker 计算，缺省跟随 options.filterWorker */
 	worker?: boolean
 }
 
 /**
  * 筛选条件的简写：只筛节点时可以直接给节点条件，等价于 `{ points: 条件 }`：
- * `view.setFilter({ vn_kv: { gte: 525 } })`。顶层出现 points / lines / cascade / worker
+ * `view.setFilter({ vn_kv: { gte: 525 } })`。顶层出现 points / lines / cascade / mode / worker
  * 任一键时按完整格式解释，因此简写里可以放心使用业务字段名。
  */
 export type GisViewFilterShorthand = GisViewConditionInput<GisViewPoint>
@@ -4906,7 +5017,7 @@ export type GisViewFilterShorthand = GisViewConditionInput<GisViewPoint>
 /** setFilter / options.filter 接受的条件：完整格式，或只筛节点的简写 */
 export type GisViewFilterInput = GisViewFilter | GisViewFilterShorthand
 
-/** 筛选结果：hiddenPoints / hiddenLines 是当前被隐藏的要素下标 */
+/** 筛选结果：hiddenPoints / hiddenLines 是当前被隐藏的要素下标；remove 模式删除完会回到空数组 */
 export interface GisViewFilterResult {
 	filter: GisViewFilter | null
 	hiddenPoints: number[]
@@ -5218,6 +5329,24 @@ export interface GisViewPluginContext {
 
 export type GisViewPlugin = (view: GisViewInstance, context: GisViewPluginContext) => void | { destroy?: () => void }
 
+/** 实例命令的上下文：注册表属于这个视图，handler 里拿它就能继续调实例方法 */
+export interface GisViewCommandContext {
+	readonly view: GisViewInstance
+	/** 这次执行注册时用的命令名（已去掉首尾空白） */
+	readonly name: string
+}
+
+/** 实例命令：同步执行；返回值原样放进 GisViewCommandResult.value */
+export type GisViewCommandHandler<Payload = unknown, Value = unknown> = (payload: Payload, context: GisViewCommandContext) => Value
+
+/** executeCommand 的读数：拿到命令并执行成功时 ok: true；没注册 / 名字非法 / handler 抛错时 ok: false 并给原因 */
+export interface GisViewCommandResult<Value = unknown> {
+	readonly ok: boolean
+	readonly name: string
+	readonly value?: Value
+	readonly reason?: string
+}
+
 /**
  * 快捷键写法（大小写不敏感，多个用 + 连接）：
  * - 纯修饰键：`ctrl` / `meta` / `shift` / `alt` / `mod`（`ctrl` 同时认 macOS 的 ⌘），按住 + 操作；
@@ -6025,6 +6154,12 @@ export interface GisViewWebGLLayer {
 	draw(context: GisViewWebGLLayerDrawContext): void
 }
 
+/**
+ * 选中触发方式：'click'（缺省）在第一次单击时改选中集；'dblClick' 等到双击的第二下才改，
+ * 第一下仍照常派发 onClick。两种方式下 onDblClick 都会在双击第二下派发。
+ */
+export type GisViewSelectTrigger = 'click' | 'dblClick'
+
 export interface GisViewOptions {
 	/**
 	 * 功能开关：预设名（'edit' / 'view' / 'static'）、开关表或布尔值 ——
@@ -6288,6 +6423,12 @@ export interface GisViewOptions {
 	 * 关着时多选仍走框选（boxSelect）与按住多选快捷键（默认 Ctrl / ⌘）。
 	 */
 	multiSelect?: boolean
+	/**
+	 * 选中触发方式：缺省 'click'（单击选中）；写 'dblClick' 后第一次点击只派发 onClick，
+	 * 第二次（双击判定命中）才更新选中集，并同时派发 onClick 与 onDblClick。
+	 * Ctrl / ⌘ 多选与 multiSelect 在双击模式下同样等到第二下才取反。运行时走 updateOptions({ selectTrigger })。
+	 */
+	selectTrigger?: GisViewSelectTrigger
 	/**
 	 * 框选 / Ctrl 多选允许收哪几类要素：'point' 节点、'line' 独立线路、'channel' 通道回线，
 	 * 可写数组任意组合，'all' / true 全开，false / null 全关。
@@ -6510,37 +6651,63 @@ export interface GisViewOptions {
 	onError?: (message: string) => void
 }
 
-/** 搜索范围：节点 / 线路 / 通道（通道会连成员回线一起搜） */
-export type GisViewSearchScope = 'points' | 'lines' | 'channels'
+/** 搜索范围（规范化后的键）：节点 / 线路 / 通道 / 通道分组（通道会连成员回线一起搜） */
+export type GisViewSearchScope = 'points' | 'lines' | 'channels' | 'groups'
+
+/** scope 的入参写法：复数的规范化键，或与 focusOn 目标一致的 point / line / channel / group 单数别名 */
+export type GisViewSearchScopeInput = GisViewSearchScope | 'point' | 'line' | 'channel' | 'group'
 
 export interface GisViewSearchOptions {
 	/** 关键字：空格分隔多个词时要在同一个字段里全部出现才命中，不区分大小写 */
 	keyword?: string
-	/** 搜索范围，缺省三类都搜 */
-	scope?: GisViewSearchScope | GisViewSearchScope[]
+	/**
+	 * 搜索范围，缺省四类都搜。复数的 points / lines / channels / groups 与单数别名
+	 * point / line / channel / group 都收；写错或空数组会回落到四类全搜。
+	 */
+	scope?: GisViewSearchScopeInput | GisViewSearchScopeInput[]
 	/** 限定参与匹配的字段路径（如 ['name', 'props.vn_kv']），缺省用要素的全部字段 */
 	fields?: string[]
 	/** 每类要素的命中上限，缺省 200，0 表示不限 */
 	limit?: number
 }
 
+/**
+ * 分组搜索命中里的 item：与 getChannelGroups() 的读数同源，但只保留搜索与定位需要的轻量字段
+ * （不带骨架 / 回线几何）。groupIndex 是这一组在所属通道里的序号（从 0 起）。
+ */
+export interface GisViewSearchGroupItem {
+	channelId: string | number
+	channelIndex: number
+	id: string | number
+	groupIndex: number
+	lineIndexes: number[]
+	lineIds: Array<string | number>
+	lineCount: number
+	anchored: boolean
+	edited: boolean
+}
+
 /** 一条搜索命中：field / value 是命中的那一项，bounds 用来居中或适应视图 */
 export interface GisViewSearchHit {
-	kind: 'point' | 'line' | 'channel'
-	/** 点 / 线在数据里的下标；通道是通道下标 */
+	kind: 'point' | 'line' | 'channel' | 'group'
+	/** 点 / 线在数据里的下标；通道是通道下标；分组是 groups 结果里的下标 */
 	index: number
 	id?: string | number
-	item: GisViewPoint | GisViewLine | GisViewChannel
+	item: GisViewPoint | GisViewLine | GisViewChannel | GisViewSearchGroupItem
 	field: string
 	value: string
 	bounds: GisViewBounds
-	/** 要素属于某条通道时给出通道下标（线路命中，或通道命中自身字段） */
+	/** 要素属于某条通道时给出通道下标（线路 / 分组命中，或通道命中自身字段） */
 	channelIndex?: number
 	/** 通道内第几条回线（0 开始） */
 	memberIndex?: number
 	/** 通道命中来自回线时，该回线在 lines 里的下标与 id */
 	memberLineIndex?: number
 	memberLineId?: string | number
+	/** 分组命中：分组 id（与 focusOn / selectFeatures 的 groupId 同一口径） */
+	groupId?: string | number
+	/** 分组命中：这一组在所属通道里的序号（从 0 起） */
+	groupIndex?: number
 }
 
 export interface GisViewSearchResult {
@@ -6549,7 +6716,8 @@ export interface GisViewSearchResult {
 	points: GisViewSearchHit[]
 	lines: GisViewSearchHit[]
 	channels: GisViewSearchHit[]
-	/** 三类命中的合集，顺序是节点、线路、通道 */
+	groups: GisViewSearchHit[]
+	/** 四类命中的合集，顺序是节点、线路、通道、分组 */
 	hits: GisViewSearchHit[]
 	total: number
 	/** 命中数达到上限被截断 */
@@ -6575,13 +6743,15 @@ export type GisViewFocusTarget = GisViewSearchHit | GisViewFeatureKey | GisViewS
 export type GisViewFocusTargets = GisViewFocusTarget | GisViewFocusTarget[]
 
 export interface GisViewFocusOptions {
-	/** 直接设成这个比例（像素 / 世界单位）；不给就按目标范围适应视图 */
+	/** 直接设成这个比例（像素 / 世界单位）；优先级高于 zoom */
 	scale?: number
-	/** 只把中心挪到目标上、比例一点不动（聚焦一个点又不想改缩放时用） */
+	/** 显式要求按目标范围适应视图；**缺省不缩放**，只把中心移到目标上 */
+	zoom?: boolean
+	/** 显式只居中、比例一点不动（与缺省行为一致，保留旧写法） */
 	center?: boolean
-	/** 按范围适应视图时四周的留白（CSS 像素），缺省 40 */
+	/** 按范围适应视图（zoom: true）时四周的留白（CSS 像素），缺省 40 */
 	padding?: number
-	/** 适应视图时最多放大到多少比例：单个节点 / 一条直线没有面积，靠它决定要不要放大 */
+	/** 适应视图（zoom: true）时最多放大到多少比例：单个节点 / 一条直线没有面积，靠它决定要不要放大 */
 	maxZoom?: number
 	/**
 	 * 顺手把这些被聚焦的要素变成选中状态：`true` 选中这次聚焦的这批（通常配合搜索命中），
@@ -7413,6 +7583,8 @@ export interface GisViewInstance {
 	getZoomBaseScale(): number
 	/** 重定缩放联动的基准比例：不传就取当下相机的比例（把现在这一屏当成「原样大小」），之后放大缩小都从它算倍数，返回 this */
 	setZoomBaseScale(scale?: number): GisViewInstance
+	/** 鹰眼图根节点（没配 minimap 时为 null）：拖动整张图 / 绑定自定义手势时拿它 */
+	getMinimapElement(): HTMLElement | null
 	/** 鹰眼图自身的倍数：1 是「刚好铺满小图」 */
 	getMinimapZoom(): number
 	/** 设置鹰眼图的倍数（夹在 minimap.minZoom ~ maxZoom 之间），内容重新跟着数据范围居中 */
@@ -7777,8 +7949,35 @@ export interface GisViewInstance {
 	cancelAddChannel(): GisViewInstance
 	/** 结束新增草稿并收掉视图上的示例假通道 / 线路（静默，不补 cancel）：提前结束不新建就用它 */
 	endAddChannel(): GisViewInstance
-	/** 提交草稿：resolution 缺省用草稿里的推荐方案（autoCommit 时由内部自动提交） */
-	commitAddChannel(resolution?: GisViewChannelAddInput['resolution'], options?: { auto?: boolean }): GisViewChannelAddResult
+	/**
+	 * 提交已 ready 的新增草稿（autoCommit 时由组件内部调用）。input 有五类写法：
+	 * 1. 不传 / null：用草稿的 preferred；
+	 * 2. 旧 resolution：字符串，或只含 type / groupId / groupIndex / channelId 的对象；
+	 * 3. 直接线路对象：无 lineIds，且有 from / to / path / kind: 'line' / start / end 之一；
+	 * 4. 直接通道对象：lineIds 为数组，缺省按 newChannel 落地；
+	 * 5. 容器：{ channel, line, lines, lineData, lineItems, channelGroups, group, channelProps, lineProps, resolution, ... }。
+	 *
+	 * 字段优先级：from / to = 顶层 → channel → line → lineItems 中第一个对象项 → 草稿；
+	 * path = 顶层 → line → channel → 草稿；分组 = channelGroups → group → channel.groups；
+	 * 容器 lineProps = 草稿 → 顶层 → line.lineProps → lines[i]（不读 channel.lineProps）；
+	 * channelProps = 草稿 → channel 上的业务字段 → 顶层 channelProps。直接通道对象自己的 lineProps 会生效。
+	 *
+	 * 直接通道默认新建；要并进已有通道 / 分组，用容器并显式写 resolution。
+	 * ready 里的方案对象带 enabled / count / lineIds 等读数，不能整条回传，只取
+	 * `{ type, groupId, groupIndex, channelId }` 子集。调用前草稿必须 ready，否则返回 ok: false 且不写数据。
+	 *
+	 * ```ts
+	 * view.commitAddChannel({
+	 *   resolution: { type: 'joinGroup', groupId: 'corridor-1::2' },
+	 *   lines: [{ id: 'join-1', color: '#dd4b2e' }, { id: 'join-2' }],
+	 *   lineProps: { width: 2.4 }
+	 * })
+	 * ```
+	 */
+	commitAddChannel(
+		input?: GisViewChannelAddInput['resolution'] | GisViewChannel | GisViewLine | GisViewChannelAddCommitInput,
+		options?: { auto?: boolean; continuous?: boolean; originalEvent?: Event | null }
+	): GisViewChannelAddResult
 	/** 两个节点之间的新增方案：新通道 / 新分组 / 并进某一组 / 无法添加（kind 为 'line' 时方案表是空的） */
 	getChannelAddOptions(from: string | number, to: string | number, count?: number, kind?: 'channel' | 'line'): GisViewChannelAddPlan | null
 	/**
@@ -8083,6 +8282,16 @@ export interface GisViewInstance {
 	 * 调它就把这个插件返回的 `destroy` 清掉（重复调用只清一次；实例销毁之后再调也安全）
 	 */
 	use(plugin: GisViewPlugin): () => void
+	/**
+	 * 注册一个实例命令：`handler(payload, context)` 同步执行，`context.view` 就是这个视图。
+	 * 同名覆盖（后注册的生效）；返回幂等的注销函数，同名被后注册覆盖后旧卸载函数不会误删新命令。
+	 * 名字空 / handler 不是函数只报一条 onWarning；实例销毁后注册不生效。
+	 */
+	registerCommand<Payload = unknown, Value = unknown>(name: string, handler: GisViewCommandHandler<Payload, Value>): () => void
+	/** 执行一个实例命令：成功给 `{ ok: true, name, value }`；没注册 / 名字非法 / handler 抛错给 `{ ok: false, name, reason }` */
+	executeCommand<Value = unknown>(name: string, payload?: unknown): GisViewCommandResult<Value>
+	/** 当前注册着哪些实例命令（按注册顺序；同名覆盖不改变原来的位置） */
+	listCommands(): string[]
 	/**
 	 * 注册一个自定义图元：名字写进数据的 `symbol` 字段（`symbol: '三角'`），画法交给一支画笔
 	 * （`painter(context, info)`，读数见 `GisViewSymbolPainterInfo`）。注册完（或换一支画笔之后）
@@ -8234,6 +8443,8 @@ export interface GisViewEngineOptions {
 	zoom?: boolean
 	hover?: boolean
 	select?: boolean
+	/** 选中触发方式：'click'（缺省）或 'dblClick'，见 GisViewSelectTrigger */
+	selectTrigger?: GisViewSelectTrigger
 	contextMenu?: boolean
 	/**
 	 * 右键默认把浏览器的系统菜单收掉（组件接住右键时 preventDefault contextmenu）。
@@ -8379,6 +8590,10 @@ export interface GisViewEngine {
 	getChannels(): GisViewChannelInfo[]
 	/** 单条通道运行时状态：只复制这一组；channelId 找不到时可按 channels 下标兜底 */
 	getChannel(channelId?: string | number | null, channelIndex?: number): GisViewChannelInfo | null
+	/** 单条通道的范围：按当前骨架与每条回线的折线计算，不复制几何；channelId 找不到时可按 channels 下标兜底 */
+	getChannelBounds(channelId?: string | number | null, channelIndex?: number): GisViewBounds | null
+	/** 一个分组的范围：按这一组当前骨架与回线折线计算，不复制几何；没有 channelId 时按通道下标兜底 */
+	getChannelGroupBounds(channelId: string | number | null | undefined, groupId: string | number, channelIndex?: number): GisViewBounds | null
 	/** 通道成员表：成员回线下标与各自的横向偏移，不复制几何（自建覆盖层按通道分流绘制用它） */
 	getChannelMembers(): GisViewChannelMembers[]
 	/** 通道分组现状：不传 channelId 返回所有分组 */