gis-view-webgl2 0.1.2 → 0.1.3

package/dist/index.d.ts

@@ -1157,6 +1157,12 @@ export interface GisViewLine {
 	 * 对象在全局那一份上逐字段覆盖，false / null 关掉这一条；不写就跟随全局（全局没配 = 不画）。
 	 */
 	effect?: GisViewLineEffectInput | null
+	/**
+	 * 这条线的正向是否从 from / path[0] 走向 to / path[last]，默认 true。
+	 * 写 false 时装饰位置与朝向、方向箭头、线路动画都按反方向解释；effect.reverse 与
+	 * direction.reverse 仍各自生效，两者与 forward 是异或关系（反两次等于正一次）。
+	 */
+	forward?: boolean
 	/**
 	 * 这条线的方向箭头（静态，不跑动）：true 用全局那一份（options.lineDirection），
 	 * 对象在全局那一份上逐字段覆盖，false / null 关掉这一条；不写就跟随全局（全局没配 = 不画）。
@@ -1165,6 +1171,70 @@ export interface GisViewLine {
 	direction?: GisViewLineDirectionInput | null
 }
 
+/** 级联高亮的范围：points 只亮节点，both 同时亮直接连接的线路 */
+export type GisViewCascadeHighlightScope = 'points' | 'both'
+
+/**
+ * 点击级联高亮：点击节点时高亮它和直接相连的节点 / 线路，点击线路或通道时高亮这条线的两端。
+ * 它与选中集完全分开 —— 不写 selectionKeys、不改 selected，样式也不走悬停 / 选中那一套。
+ * true 等价于 { enabled: true, scope: 'both' }；不配或 false 都是关闭。
+ */
+export interface GisViewCascadeHighlightOptions {
+	/** 开关，缺省 true（写了对象就表示打开） */
+	enabled?: boolean
+	/** 高亮范围，缺省 'both'：points 只亮节点，both 连直接连接的线路一起亮 */
+	scope?: GisViewCascadeHighlightScope
+	/** 普通单击是否触发 / 更新级联高亮，缺省 true；关闭后这次单击只走选中，并清掉旧级联 */
+	triggerOnClick?: boolean
+	/**
+	 * Ctrl / ⌘ 多选或 options.multiSelect 的累加点击是否触发级联高亮，缺省 true。
+	 * 关闭后多选只改变选中集，不改级联状态（并把旧级联收掉）
+	 */
+	triggerOnMultiSelect?: boolean
+	/**
+	 * 框选是否触发级联高亮，缺省 false（保持框选只改选中集的既有行为）。
+	 * 打开后框内每个命中项都参与邻接计算，直接命中的节点 / 线路仍走框选样式，只有邻接项套级联样式
+	 */
+	triggerOnBoxSelect?: boolean
+	/** 级联节点样式；缺省是琥珀色描边的白心节点。整份替换，不与悬停 / 选中样式叠加 */
+	pointStyle?: GisViewPointStyle
+	/** 级联线路样式；缺省是琥珀色、稍粗的实线。整份替换，不与悬停 / 选中样式叠加 */
+	lineStyle?: GisViewLineStyle
+	/** 点空白处是否收掉级联高亮，缺省 true */
+	clearOnEmptyClick?: boolean
+}
+export type GisViewCascadeHighlightInput = boolean | GisViewCascadeHighlightOptions
+
+/** 级联高亮里的一个节点 / 线路条目 */
+export interface GisViewCascadeHighlightEntry<T = GisViewPoint | GisViewLine> {
+	index: number
+	item: T
+}
+
+/** 级联高亮的来源：这一次点击命中的节点 / 线路 / 通道回线 */
+export interface GisViewCascadeHighlightOrigin {
+	/** 命中的种类：通道回线在这里是 channel，底层数据类型仍是 line */
+	target: 'point' | 'line' | 'channel'
+	type: 'point' | 'line'
+	index: number
+	item: GisViewPoint | GisViewLine
+	channelId?: string | number
+	channelIndex?: number
+	groupId?: string | number
+	groupIndex?: number
+	channel?: GisViewChannel
+}
+
+/** getCascadeHighlight() / onCascadeHighlight 的读数：来源、范围与当前亮着的节点 / 线路 */
+export interface GisViewCascadeHighlightInfo {
+	origin: GisViewCascadeHighlightOrigin | null
+	scope: GisViewCascadeHighlightScope
+	points: Array<GisViewCascadeHighlightEntry<GisViewPoint>>
+	lines: Array<GisViewCascadeHighlightEntry<GisViewLine>>
+	pointIndexes: number[]
+	lineIndexes: number[]
+}
+
 /**
  * updateLine 的补丁：线路自己的字段之外，还可以带一组「分组指令」。
  * groupId / groupIndex 会先把这条回线挪到目标分组（通道内的回线只能进一组），
@@ -1462,24 +1532,6 @@ export interface GisViewChannelContext {
 	actions: GisViewChannelAction[]
 }
 
-/** 右键点中通道回线时的载荷：上下文 + 命中的回线与屏幕 / 世界坐标，点空白处回调收到 null */
-export interface GisViewChannelContextPayload extends GisViewChannelContext {
-	/** 这一次操作的判读：type 为 'contextMenu'、target 为 'channel'（与 onContextMenu 是同一件操作） */
-	action?: GisViewPointerAction
-	/** 命中的回线在 lines 数组里的下标 */
-	lineIndex: number
-	lineId: string | number
-	coordinate: [number, number]
-	/** 鼠标按键：右键固定是 2（与指针载荷同一份口径，组件层按它补出 action.button） */
-	button?: number
-	/** 画布 CSS 像素坐标 */
-	x: number
-	y: number
-	clientX: number
-	clientY: number
-	originalEvent: Event
-}
-
 /** 新增通道时一个节点的读数：下标、id / 数据对象与坐标 */
 export interface GisViewChannelNodeDraft {
 	index: number
@@ -1678,6 +1730,11 @@ export interface GisViewChannelBetween {
 export interface GisViewChannelDraftOptions {
 	/** 两个节点一选完就自动提交，不用再调 commitAddChannel */
 	autoCommit?: boolean
+	/**
+	 * 预指定起点：节点 id / 下标 / `{ id }` / `{ index }`。给了就从「已选好起点」进入草稿，
+	 * 下一次点节点只选终点；不写则仍由第一次点击选起点。找不到节点时草稿不开始并报 warning
+	 */
+	from?: GisViewPointRef
 	/**
 	 * 连续新增：一段线路落地之后自动开下一段草稿，不用再点一次「新增通道」。
 	 * true 每段都从空白开始；'chain' 以上一段的终点当下一段起点（首尾相接）
@@ -2048,9 +2105,7 @@ export interface GisViewAddPointResult extends GisViewAddItemsResult<GisViewPoin
  * coordinate 与通道字段），另加 target（'point' / 'line' / 'channel'）与 lngLat（配了 GeoJSON 底图才有）；
  * 没命中返回 null。只读 —— 不改选中、不动光标。
  */
-export interface GisViewPickAtResult extends GisViewPickResult {
-	target: 'point' | 'line' | 'channel'
-}
+export type GisViewPickAtResult = GisViewHitResult & { target: 'point' | 'line' | 'channel' | 'cluster' }
 
 /**
  * getFeaturesInRect 的结果：points 是框内的节点（与框选同一口径，含 screen / coordinate / 通道上下文），
@@ -2506,6 +2561,14 @@ export interface GisViewWaypointKey {
 	pathIndex: number
 }
 
+/** 拐点定位的对象写法：lineIndex / lineId / id 任给一个，pathIndex 必有 */
+export interface GisViewWaypointRef {
+	lineIndex?: number
+	lineId?: string | number
+	id?: string | number
+	pathIndex: number
+}
+
 /** 拐点信息：坐标与是否处于选中态 */
 export interface GisViewWaypointInfo extends GisViewWaypointKey {
 	coordinate: [number, number]
@@ -2552,6 +2615,72 @@ export interface GisViewPickResult extends GisViewFeatureKey {
 	group?: GisViewChannelGroupInfo & { groupIndex: number; lineCount: number; waypointCount: number }
 }
 
+/** 点聚合配置：true 等价于开着一份缺省档；对象写法可逐项覆盖。 */
+export interface GisViewPointClusterOptions {
+	/** 缺省 true；写成 false 与不配一样，都是关 */
+	enabled?: boolean
+	/** 聚合半径（CSS 像素），缺省 60，夹在 8 ~ 500 */
+	radius?: number
+	/** 至少多少个点才合成一个聚合圆，缺省 2（最小也是 2） */
+	minPoints?: number
+	/** 相机比例 / 基准比例超过它之后展开原始点；0（缺省）表示不设上限 */
+	maxZoom?: number
+}
+
+/** getPointCluster() 的读数：归一化之后的配置 + 当前缩放档是否仍在聚合。 */
+export interface GisViewPointClusterReadout extends Required<GisViewPointClusterOptions> {
+	active: boolean
+}
+
+/** 一个展示组：count 为 1 是单成员，大于 1 是聚合圆；坐标与包围盒都是世界坐标。 */
+export interface GisViewCluster {
+	id: string
+	count: number
+	pointIndexes: number[]
+	pointIds: Array<string | number>
+	coordinate: [number, number]
+	/** 当前相机下的画布 CSS 像素位置 */
+	screen: [number, number]
+	radius: number
+	bounds: GisViewBounds
+}
+
+/** 多成员聚合圆的拾取结果：item 永远为 null，index 为 -1，不进入普通要素选中集。 */
+export interface GisViewClusterPickResult extends GisViewCluster {
+	type: 'cluster'
+	index: -1
+	item: null
+	distance: number
+	selected: boolean
+	wasSelected: boolean
+	lngLat?: [number, number]
+}
+
+/** pick / pickAt / hover 可能拿到普通要素或聚合圆。 */
+export type GisViewHitResult = GisViewPickResult | GisViewClusterPickResult
+
+/** action.data 里的聚合读数：不带 action 自身，避免载荷循环引用。 */
+export interface GisViewClusterPointerData extends GisViewCluster {
+	type: 'cluster'
+}
+
+/** 聚合数量文字：覆盖层每帧只需要位置、半径与数量。 */
+export interface GisViewClusterLabel {
+	id: string
+	count: number
+	screen: [number, number]
+	radius: number
+}
+
+/** onClusterClick / clusterClick 的载荷：与点击载荷同一套指针字段，但不带普通要素的 item。 */
+export type GisViewClusterClickPayload = GisViewClusterPickResult & {
+	button?: number
+	buttons?: number
+	originalEvent: Event
+	selection: GisViewSelectionInfo
+	action: GisViewPointerAction
+}
+
 /** 选中事件载荷：点击选中为 0 / 1 个要素，Shift 框选为框内全部节点（随 shortcuts.boxSelect 改变） */
 export interface GisViewSelectPayload {
 	items: GisViewPickResult[]
@@ -2589,11 +2718,11 @@ export interface GisViewSelectionInfo {
  *    `{ channelId, lineIds: [...] }` / `{ channelIndex, lineIndexes: [...] }` 只取通道里的某几条回线。
  */
 export interface GisViewSelectionRefObject {
-	/** 要素类型；写 'channel'（或写了 channelId / channelIndex / channel）就是通道写法 */
-	type?: GisViewFeatureType | 'channel'
-	/** 搜索命中的类型（与 type 一个意思，point / line / channel 都认）：搜索命中可以直接丢给 select */
-	kind?: GisViewFeatureType | 'channel'
-	/** 要素 id；type / kind 是通道时它就是这个通道的 id */
+	/** 要素类型；写 'channel'（或写了 channelId / channelIndex / channel）就是通道写法，写 'group' 是分组写法 */
+	type?: GisViewFeatureType | 'channel' | 'group'
+	/** 搜索命中的类型（与 type 一个意思，point / line / channel / group 都认）；type 是 group 时 id 就是分组 id */
+	kind?: GisViewFeatureType | 'channel' | 'group'
+	/** 要素 id；type / kind 是通道时它就是这个通道的 id，是分组时是分组 id */
 	id?: string | number
 	/** 要素在 points / lines 里的下标；通道写法里是通道下标 */
 	index?: number
@@ -2602,8 +2731,12 @@ export interface GisViewSelectionRefObject {
 	channelId?: string | number
 	channelIndex?: number
 	channel?: string | number | GisViewChannel
+	/** 分组上下文（getLineChannel 的 group 可以直接放进来） */
+	group?: string | number | { id?: string | number }
 	/** 只要通道里的某一组 */
 	groupId?: string | number | null
+	/** groupId 的 snake_case 别名 */
+	group_id?: string | number
 	/** 只要通道里的某几组 */
 	groupIds?: Array<string | number>
 	/** 只要通道里的某一条 / 某几条回线（按 id 或 lines 下标） */
@@ -2764,7 +2897,7 @@ export interface GisViewClickPayload extends GisViewPickResult {
  * 'waypoint'（线路拐点）/ 'label'（标签）/ 'selection'（一整批选中集，只有 selectChange 用）/ 'empty'（空白）。
  * 与载荷里的 type 差一层：通道回线的 type 也是 'line'，但按通道处理的多，target 单独给一个 'channel'。
  */
-export type GisViewPointerTarget = 'point' | 'line' | 'channel' | 'waypoint' | 'label' | 'selection' | 'empty'
+export type GisViewPointerTarget = 'point' | 'line' | 'channel' | 'cluster' | 'waypoint' | 'label' | 'selection' | 'empty'
 
 /**
  * 一次指针操作的动作名。同一个名字在「按下 / 松开 / 点击」三条事件里含义略有不同：
@@ -2786,6 +2919,7 @@ export type GisViewPointerActionType =
 	| 'selectWaypoint'
 	| 'dragWaypoint'
 	| 'dragPoint'
+	| 'clusterClick'
 	| 'dragLabel'
 	| 'selectLabel'
 	| 'contextMenu'
@@ -2830,7 +2964,7 @@ export interface GisViewPointerAction {
 	 * 通道回线是通道定义、选中集事件是这一批 items、拐点是「哪条线、第几个顶点、坐标、改完的线」，
 	 * 空白处是 null（拐点那一份见 GisViewWaypointPayload.action.data、标签那一份见 GisViewLabelActionData）。
 	 */
-	data?: GisViewPoint | GisViewLine | GisViewChannel | GisViewPickResult[] | GisViewWaypointActionData | GisViewLabelActionData | null
+	data?: GisViewPoint | GisViewLine | GisViewChannel | GisViewClusterPointerData | GisViewPickResult[] | GisViewWaypointActionData | GisViewLabelActionData | null
 	/** 只在 click 载荷里出现：true 说明这一下是双击里的第二下（单双击要分开做事的界面按它推迟一下） */
 	double?: boolean
 	/**
@@ -2869,8 +3003,8 @@ export interface GisViewPointerPayload {
 	 * target 说明点的是点 / 线 / 通道 / 空白，data 直接给到那一份数据（左键 / 右键都认这一份）
 	 */
 	action: GisViewPointerAction
-	/** 命中的要素类型，空白处为 null */
-	type: GisViewFeatureType | null
+	/** 命中的要素类型，空白处为 null；多成员聚合是 'cluster' */
+	type: GisViewFeatureType | 'cluster' | null
 	/** 命中的要素在数据里的下标，空白处为 -1 */
 	index: number
 	/** 有没有命中要素 */
@@ -2881,6 +3015,9 @@ export interface GisViewPointerPayload {
 	screen?: [number, number]
 	/** 命中的要素自身的世界坐标 */
 	coordinate?: [number, number]
+	/** 命中的是线路（含通道回线）时，线路在 lines 数组里的下标与 id；右键菜单按它找线路 */
+	lineIndex?: number
+	lineId?: string | number
 	/** 命中的是通道内的回线时，回线所属通道与分组 */
 	channelIndex?: number
 	channel?: GisViewChannel
@@ -2888,6 +3025,15 @@ export interface GisViewPointerPayload {
 	groupIndex?: number
 	/** 命中的是通道内的回线时，这一组的读数 */
 	group?: GisViewChannelGroupInfo & { groupIndex: number; lineCount: number; waypointCount: number }
+	/** 命中通道回线时的分组上下文：action.target 为 channel，按它直接渲染通道菜单 */
+	channelContext?: GisViewChannelContext
+	/** 命中多成员聚合时：聚合 id、成员数、成员下标 / id、包围盒与屏幕半径 */
+	id?: string
+	count?: number
+	pointIndexes?: number[]
+	pointIds?: Array<string | number>
+	bounds?: GisViewBounds
+	radius?: number
 	/**
 	 * 这一刻命中的要素在不在当前选中集里（没有命中就是 false）。
 	 * 左键按下 / 抬起与右键都是当下这一份状态：selected 与 wasSelected 相同
@@ -2918,7 +3064,7 @@ export interface GisViewPointerPayload {
  * 另外带一份 action（type 恒为 'hover'、target 说明停在什么上面、button 恒为 'none'）。
  * 光标正好停在最近一次指针事件的位置上时，originalEvent / clientX / clientY 就是那一次事件（修饰键读得到）。
  */
-export interface GisViewHoverPayload extends GisViewPickResult {
+export type GisViewHoverPayload = GisViewHitResult & {
 	/** 悬停读数一样有：有没有停在某个要素上（空白处是 null，不走这一份） */
 	hit: boolean
 	action: GisViewPointerAction
@@ -3655,6 +3801,12 @@ export interface GisViewEngineStats {
 	lineEffectCount: number
 	/** 这一帧铺进去的节点涟漪圈数（一个节点 count 圈算 count；关掉或视野内没有涟漪时为 0） */
 	pointEffectCount: number
+	/** 当前点聚合的多成员圆个数；聚合关闭或超过 maxZoom 时为 0 */
+	clusterCount: number
+	/** 被收进多成员聚合圆的原始点数：展示点数 = pointCount - clusterPointCount + clusterCount */
+	clusterPointCount: number
+	/** 最近一次聚合重算耗时（毫秒）；聚合关闭时为 0 */
+	clusterMs: number
 	/** 动画是否还在排下一帧：静止画面是按需渲染的，这时候是 false */
 	animating: boolean
 	quality: GisViewQualityState
@@ -5041,6 +5193,18 @@ export interface GisViewInitialView {
 	padding?: number
 }
 
+/**
+ * 适应视图的节点间距兜底：普通「铺满数据范围」让最近节点在屏幕上挤在一起时，
+ * 按 minDistance 反推一个更高的相机比例。放大时以最近节点对的中点为中心，
+ * 远处孤立点可以把包围盒撑大，但不再把主体节点压成一团，也允许落到视口外。
+ */
+export interface GisViewFitSpacingOptions {
+	/** 可见节点中心之间的最小屏幕距离（CSS 像素），默认 24；写 0 或负数关闭 */
+	minDistance?: number
+	/** 相对普通适应比例的最大放大倍数，默认 0（不限，只受 maxScale 约束）；正数表示上限 */
+	maxZoom?: number
+}
+
 /**
  * 插件：视图建好之后调用一次，拿到实例本身与带 apiVersion 的上下文；返回 { destroy } 时会挂进实例的 destroy。
  * 写一次插件，之后换项目直接复用，不必把「URL 同步 / 自建图例 / 业务操作」再抄一遍。
@@ -5501,8 +5665,6 @@ export type GisViewFeatureName =
 	| 'remove'
 	/** 新增通道：进入草稿、点两个节点、落地 */
 	| 'channelDraft'
-	/** 通道右键交互框（onChannelContextMenu） */
-	| 'channelMenu'
 	/** 右键回调 onContextMenu（关掉之后组件不再拦右键，浏览器菜单照常） */
 	| 'contextMenu'
 	/** 悬停提示（tooltip）：关掉只影响提示，悬停样式与 onHover 还在 */
@@ -5678,7 +5840,7 @@ export interface GisViewBatchOptions {
 /**
  * 全部可订阅事件（与 EVENT_NAMES 一致）：事件名与 options 里的回调一一对应（`dataChange` 就是 `onDataChange`），
  * 载荷也是同一份 —— 区别只在写法：`on` 可以挂多条、可以运行时订阅、返回的函数就是取消订阅。
- * 需要原样带回 DOM 事件的那四个（pointerDown / pointerUp / contextMenu / channelContextMenu）载荷是
+ * 需要原样带回 DOM 事件的那三个（pointerDown / pointerUp / contextMenu）载荷是
  * `{ payload, event }`，与回调的两个参数一一对应。
  */
 export interface GisViewEventMap {
@@ -5698,6 +5860,8 @@ export interface GisViewEventMap {
 	pointerUp: { payload: GisViewPointerPayload; event: PointerEvent }
 	contextMenu: { payload: GisViewPointerPayload; event: MouseEvent }
 	click: GisViewClickPayload
+	/** 点中多成员聚合圆：不选中内部节点，普通 click 不会同时触发 */
+	clusterClick: GisViewClusterClickPayload
 	dblClick: GisViewClickPayload
 	/** 点了一下标签（label.editable / lineLabel.editable 打开时）：用它选中要编辑的那一条 */
 	labelClick: GisViewLabelClickPayload
@@ -5711,13 +5875,14 @@ export interface GisViewEventMap {
 	labelDblClick: GisViewLabelPointerPayload
 	select: GisViewSelectPayload | null
 	selectChange: GisViewSelectChangePayload
+	/** 点击级联高亮变了：载荷与 getCascadeHighlight() 同一份，收掉时是 null */
+	cascadeHighlight: GisViewCascadeHighlightInfo | null
 	pointDrag: GisViewPointDragPayload
 	pointCopy: GisViewPointCopyPayload | GisViewBatchCopyPayload
 	pointMerge: GisViewPointMergePayload | GisViewMergeResult | GisViewMergeFailure | GisViewMergeSelectedPayload
 	/** 删除：pending（要删什么 / 连带什么 / 能按哪些范围删）→ remove（已删，result 是结果）/ cancel */
 	remove: GisViewRemovePayload
 	waypointChange: GisViewWaypointPayload
-	channelContextMenu: { payload: GisViewChannelContextPayload | null; event: MouseEvent }
 	channelDraft: GisViewChannelDraftPayload
 	channelDraftClick: GisViewChannelDraftPayload
 	/** 动态装饰器草稿：start / hover / leave / ready / update / commit / cancel */
@@ -5984,10 +6149,12 @@ export interface GisViewOptions {
 	 * 纯文本标签的渲染方式，缺省 `auto`：
 	 * - `auto`：强制显示档下，视口里的纯文本标签达到 1024 条时自动改画到单张 Canvas；
 	 *   需要 DOM 的标签（`html: true`、函数返回元素、可拖拽 / 可编辑）仍逐条建节点。
+	 * - `canvas`：纯文本标签始终改画到单张 Canvas，不受 1024 条阈值限制，`labelOptimize: true` 时
+	 *   也按画布尺寸参与避让 / 换落点；需要 DOM 的标签仍逐条建节点。
 	 * - `dom`：始终逐条建 `.gis-view__label`，保持旧行为。
 	 * 画布档不改变标签内容、锚点与显隐，只减少高密度场景的 DOM 数量。
 	 */
-	labelRender?: 'auto' | 'dom'
+	labelRender?: 'auto' | 'canvas' | 'dom'
 	/**
 	 * 标签的运行时状态（`getLabelStates()` 的那一份：拖过的偏移、改过的内容与样式、运行时加的标签、隐藏覆盖）：
 	 * 创建 / `updateOptions` 时喂回来就回显，与 `setLabelStates(states)` 同一条路。
@@ -6004,6 +6171,12 @@ export interface GisViewOptions {
 	tooltip?: GisViewTooltipOptions
 	/** 初始筛选条件，等价于创建之后调用 setFilter；可以写完整格式，也可以只给节点条件 */
 	filter?: GisViewFilterInput | null
+	/**
+	 * 线路是否跟随节点，默认 true。开启时隐藏 / 删除 / 筛选节点会连带绑定线路与通道；
+	 * 关闭后这些操作只影响节点，线路与通道继续停在节点最后一次坐标，筛选未显式写 cascade 时默认不级联。
+	 * 筛选里显式写了 cascade 时始终以筛选自己的写法为准。
+	 */
+	lineFollowsNode?: boolean
 	/** 内置鹰眼图：不配就不显示，配了默认开 */
 	minimap?: GisViewMinimapOptions | null
 	/** 筛选是否用 Worker 计算：默认在数据量超过阈值时自动启用，false 表示始终同步计算 */
@@ -6028,6 +6201,12 @@ export interface GisViewOptions {
 	lineSelectStyle?: GisViewLineStyle
 	/** Ctrl 点击累加多选时的线样式：缺省沿用 lineSelectStyle，单条线可用 multiSelectStyle 覆盖 */
 	lineMultiSelectStyle?: GisViewLineStyle
+	/**
+	 * 点击级联高亮（默认关）：点击节点时亮起它和直接相连的节点；scope 为 both 时连线路一起亮，
+	 * 点击线路 / 通道回线时亮起两端节点。它不进选中集，样式与悬停 / 选中分开配置，
+	 * 当前亮起的清单用 getCascadeHighlight() 读。
+	 */
+	cascadeHighlight?: GisViewCascadeHighlightInput
 	/** 没有配置状态样式时，是否仍用尺寸 / 宽度增幅画出内置强调；默认 false（不配样式就不改变外观） */
 	defaultHighlight?: boolean
 	/** 节点整体放大系数（常数倍数，与地图缩放无关，屏幕上的大小因此恒定）：与点自身 size、缩放联动一起相乘，默认 1 */
@@ -6048,17 +6227,18 @@ export interface GisViewOptions {
 	lineZoomScale?: number
 	/** 缩放联动的基准比例：等于它时放大系数为 1，缺省用首次适应视图时的 camera.scale */
 	zoomBaseScale?: number
-	/**
-	 * 自适应比例开关（默认 false）：打开后没写联动指数的 pointZoomScale / lineZoomScale 按 1 算 ——
-	 * 要素与地图同倍率，包围盒变大（相机比例变小）时节点 / 线宽跟着一起小，
-	 * 节点大小与通道间距的比例不再被带跑；显式写过指数（哪怕写 0）以显式值为准。
-	 */
-	zoomScaleAuto?: boolean
 	/**
 	 * 大数据初始化是否从视图中心向外发散渲染（默认开）。
 	 * 开启后首屏只排中心附近的那一批，剩下的分帧往外补；关了就一次性排完。
 	 */
 	progressiveInit?: boolean
+	/**
+	 * 点聚合：true 用缺省档（半径 60px、至少 2 点、不限缩放），对象写法见 GisViewPointClusterOptions。
+	 * 只影响展示、拾取、快照与导出；原始 points、选中集与 getData() 不变，
+	 * listPoints({ visibleOnly: true }) 会跳过被聚合圆收起的成员，传 false 仍可列全。
+	 * 聚合期间发散初始化暂停；缩放超过 maxZoom 后恢复逐点显示。
+	 */
+	pointCluster?: boolean | GisViewPointClusterOptions
 	/** 是否绘制网格：与其它功能开关同一条口径，**缺省关**，写 showGrid: true 才画 */
 	showGrid?: boolean
 	gridColor?: string
@@ -6169,6 +6349,11 @@ export interface GisViewOptions {
 	 * zoom 是相对「适应视图」的倍数（2 = 比适应近一倍），scale 是绝对的 像素 / 世界单位。
 	 */
 	initialView?: GisViewInitialView | null
+	/**
+	 * 适应视图时按可见节点间距兜底（默认关）：true 用 minDistance 24 / maxZoom 不限，
+	 * 对象可改两个参数。只在首次默认适应与 fitView() 生效，显式 initialView.scale / zoom 优先。
+	 */
+	fitSpacing?: boolean | GisViewFitSpacingOptions
 	/**
 	 * onStats 的最小间隔（毫秒），默认 250，0 表示每帧都发。
 	 * 读数不需要 60Hz，节流能省下每帧一次的回调与对象分配（拖拽时尤其明显）。
@@ -6212,6 +6397,8 @@ export interface GisViewOptions {
 	onSelect?: (payload: GisViewSelectPayload | null) => void
 	/** 单击要素或空白处 */
 	onClick?: (payload: GisViewClickPayload | null) => void
+	/** 点中多成员聚合圆：载荷带 count / pointIds / bounds；不会同时触发 onClick，也不改选中集 */
+	onClusterClick?: (payload: GisViewClusterClickPayload, event: Event) => void
 	/** 双击要素或空白处 */
 	onDblClick?: (payload: GisViewClickPayload | null) => void
 	/** 点了一下标签（label.editable / lineLabel.editable 打开时）：载荷里是这一条标签的类型、下标与当前覆盖 */
@@ -6231,8 +6418,13 @@ export interface GisViewOptions {
 	onPointerDown?: (payload: GisViewPointerPayload, event: PointerEvent) => void
 	/** 左键 / 中键 / 右键抬起：与 onPointerDown 成对 */
 	onPointerUp?: (payload: GisViewPointerPayload, event: PointerEvent) => void
-	/** 右键：点、线、空白都会发（要素信息在载荷里，要自己弹菜单就在这里 preventDefault） */
+	/**
+	 * 右键：点、线、通道、空白都会发这一条。命中通道回线时 action.target 为 'channel'，
+	 * 载荷另带 channelContext；要自己弹菜单就在这里 preventDefault()。
+	 */
 	onContextMenu?: (payload: GisViewPointerPayload, event: MouseEvent) => void
+	/** 点击级联高亮变了：载荷与 getCascadeHighlight() 同一份，收掉时是 null */
+	onCascadeHighlight?: (payload: GisViewCascadeHighlightInfo | null) => void
 	onHover?: (payload: GisViewHoverPayload) => void
 	onCursor?: (payload: GisViewCursorPayload) => void
 	/** 光标移动 / 移出画布：屏幕坐标、世界坐标与经纬度（配了 GeoJSON 底图才有 lngLat） */
@@ -6258,8 +6450,6 @@ export interface GisViewOptions {
 	onRemove?: (payload: GisViewRemovePayload) => void
 	/** 拐点新增、选中、删除与拖动 */
 	onWaypointChange?: (payload: GisViewWaypointPayload) => void
-	/** 右键点中通道回线：给出分组上下文（几组 / 当前哪组 / 有哪些交互），点空白处给 null */
-	onChannelContextMenu?: (payload: GisViewChannelContextPayload | null, event: MouseEvent) => void
 	/** 新增通道草稿：start / from / to / ready / cancel / commit / blocked，两个节点的信息与方案都在载荷里 */
 	onChannelDraft?: (payload: GisViewChannelDraftPayload) => void
 	/** 草稿里每点一次发一条：step 1 拿到起点、step 2 拿到终点（线路结束），载荷与 onChannelDraft 相同 */
@@ -6374,7 +6564,10 @@ export interface GisViewSearchResult {
 /**
  * focusOn 的目标（一个）：搜索命中、要素写法、世界坐标（两个数 / `[x, y]` / `{ x, y }`）、
  * 一段世界坐标范围、通道写法（取通道范围）、`{ center: [x, y] }` 或 `{ lngLat: [经度, 纬度] }`
- * （配了 GeoJSON 底图才有意义）。
+ * （配了 GeoJSON 底图才有意义）。要素 / 通道 / 分组可以用 `type` 明确消歧：
+ * `{ type: 'point' | 'line' | 'channel', id | index }`、`{ type: 'group', channelId, groupId }`
+ * （group 的 channelId 可省略，只要 groupId 全局唯一）。字符串 / 数字仍按「先节点 id、再线路 id」兼容；
+ * 同 id 时显式写 `type` 即可；裸字符串不表示通道，通道请写 `{ channelId }` 或显式 `type: 'channel'`。
  */
 export type GisViewFocusTarget = GisViewSearchHit | GisViewFeatureKey | GisViewSelectionRefObject | string | number | GisViewCoordinate | GisViewBounds | { x: number, y: number } | { center: GisViewCoordinate } | { lngLat: GisViewCoordinate } | { longitude: number, latitude: number }
 
@@ -6411,6 +6604,13 @@ export interface GisViewExportImageOptions {
 	quality?: number
 	/** 导出倍率：位图相对画布 CSS 尺寸，缺省按设备像素比导（与屏幕一致）；SVG 只影响宽高属性，缺省 1 */
 	scale?: number
+	/**
+	 * 导出范围：'viewport'（缺省）只导当前可视区域；'all' 临时适应全部数据范围，导完恢复原相机。
+	 * 筛选 / visible: false 隐藏的要素仍不会出现；'all' 指当前场景里全部可见内容
+	 */
+	scope?: 'viewport' | 'all'
+	/** scope: 'all' 时四周留白（CSS 像素，缺省 24）；scope: 'viewport' 时忽略 */
+	padding?: number
 	/**
 	 * 背景：缺省 = 带背景（背景色 / 底图 / GeoJSON 区域填充与网格，与屏幕上一致）；
 	 * false / 'none' / 'transparent' = 不带背景（透明底，上面那些都不画）；
@@ -6961,6 +7161,20 @@ export interface GisViewSceneGraphic {
 	preserveAspectRatio: string
 }
 
+/** 矢量快照里的多成员聚合圆（数量文字也在这里；单成员不画圆） */
+export interface GisViewSceneCluster {
+	id: string
+	count: number
+	x: number
+	y: number
+	radius: number
+	fill: string
+	stroke: string
+	strokeWidth: number
+	textColor: string
+	fontSize: number
+}
+
 export interface GisViewSceneSnapshot {
 	width: number
 	height: number
@@ -6974,6 +7188,7 @@ export interface GisViewSceneSnapshot {
 	/** 数据线路与节点装饰连接线（连接线也画在节点 / 装饰之前） */
 	lines: GisViewSceneLine[]
 	points: GisViewSceneNode[]
+	clusters: GisViewSceneCluster[]
 	backgroundPoints: GisViewSceneNode[]
 	decorations: GisViewSceneNode[]
 	waypoints: GisViewSceneNode[]
@@ -7194,7 +7409,7 @@ export interface GisViewInstance {
 	setCamera(camera: Partial<GisViewCamera>): GisViewInstance
 	getCamera(): GisViewCamera
 	getBounds(): GisViewBounds
-	/** 缩放联动的基准比例（pointZoomScale / lineZoomScale / zoomScaleAuto 共用那一份）：缺省是首次适应视图时的 camera.scale */
+	/** 缩放联动的基准比例（pointZoomScale / lineZoomScale 共用那一份）：缺省是首次适应视图时的 camera.scale */
 	getZoomBaseScale(): number
 	/** 重定缩放联动的基准比例：不传就取当下相机的比例（把现在这一屏当成「原样大小」），之后放大缩小都从它算倍数，返回 this */
 	setZoomBaseScale(scale?: number): GisViewInstance
@@ -7279,7 +7494,7 @@ export interface GisViewInstance {
 	createGeoMapper(options?: GisViewGeoMapperOptions): GisViewGeoMapper | null
 	/** 直接把一份点 / 线 / 通道数据映射到 GeoJSON 坐标上（复制，不改原数据）；没有 GeoJSON 底图时是 null */
 	mapDataToGeoJson<T extends { points?: GisViewPoint[]; lines?: GisViewLine[]; channels?: GisViewChannel[] }>(data: T, options?: GisViewGeoMapperOptions): T | null
-	pick(x: number, y: number): GisViewPickResult | null
+	pick(x: number, y: number): GisViewHitResult | null
 	/**
 	 * 按浏览器客户端坐标拾取（鼠标事件里的 clientX / clientY）：与指针事件载荷同一份读数，另加 target
 	 * （'point' / 'line' / 'channel'）与 lngLat（配了 GeoJSON 底图才有）；没命中返回 null。
@@ -7315,11 +7530,19 @@ export interface GisViewInstance {
 	 * getSelectionData 立刻就能读回来。认这些写法（见 GisViewSelectionRef）：
 	 * ① 节点：id、`{ type: 'point', index: 3 }`、一批 id 与对象混着写；
 	 * ② 通道：`{ type: 'channel', channelId: 'channel-a' }` 选整条通道的回线，
-	 *    `{ channelId, groupId }` 选某一组，`{ channelId, lineIds: [...] }` 选通道里的某几条回线；
+	 *    `{ channelId, groupId }` / `{ type: 'group', channelId, groupId }` 选某一组
+	 *    （只给全局唯一的 groupId 也可以），`{ channelId, lineIds: [...] }` 选通道里的某几条回线；
 	 * ③ 线路：id 或 `{ type: 'line', index: 3 }`。
 	 * options.mode 给 'add' / 'toggle' / 'remove' 就在当前选中集上做加 / 取反 / 减
 	 */
 	selectFeatures(refs: GisViewSelectionRefs, options?: GisViewSelectOptions): GisViewInstance
+	/**
+	 * 选中一个拐点：`selectWaypoint('line-1', 2)` / `selectWaypoint({ lineIndex: 3, pathIndex: 1 })` /
+	 * `selectWaypoint({ lineId: 'line-1', pathIndex: 2 })`。同时把拐点所在线路选上（缺省
+	 * `waypointVisibility: 'selected'` 下拐点才可见）；`selectWaypoint(null)` 只取消拐点选中，
+	 * 不改要素选中集。`pathIndex` 只认 `getWaypoints()` 给出的可编辑拐点，无效时不会猜位置。
+	 */
+	selectWaypoint(waypoint: GisViewWaypointKey | GisViewWaypointRef | string | number | null, pathIndex?: number, options?: GisViewSelectOptions): GisViewInstance
 	/**
 	 * 取消选中：写法与 selectFeatures 完全一样（节点 / 通道 / 线路，一批可以混着写），
 	 * 把这些从当前选中集里去掉，其余选中原样留着 —— `deselect('p-1')` 取消一个节点、
@@ -7345,6 +7568,11 @@ export interface GisViewInstance {
 	 * bounds 走一次 getElementBounds（十万级选中下约 5 ms），只想问「选了哪几个」用 getSelections() 更省
 	 */
 	getSelectionData(): GisViewSelectionData
+	/**
+	 * 当前点击级联高亮的读数：来源、scope 与亮着的节点 / 线路；没有级联高亮（或功能关着）时是 null。
+	 * 它只读，不改变选中集；点空白处、换数据或关掉 cascadeHighlight 会收掉。
+	 */
+	getCascadeHighlight(): GisViewCascadeHighlightInfo | null
 	/** 按画布 CSS 像素矩形框选；options.selectionKinds 可临时覆盖全局类型过滤 */
 	selectInBox(box: GisViewRect, options?: GisViewSelectInBoxOptions): GisViewInstance
 	/**
@@ -7530,7 +7758,8 @@ export interface GisViewInstance {
 	/** 执行右键交互框里的动作，返回执行之后的上下文 */
 	runChannelAction(actionId: GisViewChannelActionId, options?: { channelId?: string | number; groupId?: string | number; coordinate?: GisViewCoordinate; pathIndex?: number; size?: number }): GisViewChannelContext | null
 	/**
-	 * 进入「新增通道」：点第一个节点当起点，一条线跟随光标，点第二个节点发结束事件
+	 * 进入「新增通道」：缺省点第一个节点当起点，一条线跟随光标，点第二个节点发结束事件；
+	 * options.from 可以预指定起点，此后只需要再选终点
 	 * （phase: 'ready'，载荷里带两个节点、hasChannel / hasGroup / groups / channel 与可选方案）。
 	 * 它只负责这条可视化示例路径 —— 真正的落地必须用 addChannel（或 addChannelGroupLines /
 	 * joinChannelGroupLines / addLine），不在事件里落地就用 endAddChannel / cancelAddChannel 收掉假通道。
@@ -7798,6 +8027,10 @@ export interface GisViewInstance {
 	getChannel(ref: GisViewFeatureRef): GisViewChannelSnapshot | null
 	/** 按条件列节点快照（indexes / inView / limit / withScreen / visibleOnly）：可见点读数的通用入口 */
 	listPoints(options?: GisViewListOptions): GisViewListedPoint[]
+	/** 当前点聚合的展示组（含 count: 1 的单成员）：只读，原始 points / getData() 不变 */
+	getClusters(): GisViewCluster[]
+	/** 当前点聚合配置与运行时开关（缩放超过 maxZoom 后 active 为 false） */
+	getPointCluster(): GisViewPointClusterReadout | null
 	/** 按条件列线路快照（与 listPoints 同一套选项）：通道回线带通道读数，另有 color / width */
 	listLines(options?: GisViewListOptions): GisViewListedLine[]
 	/** 一批要素的世界包围盒；一个都没对上（数据已经换过）返回 null */
@@ -7958,6 +8191,8 @@ export interface GisViewEngineOptions {
 	lineSelectStyle?: GisViewLineStyle | null
 	/** Ctrl 点击累加多选时的线样式：缺省沿用 lineSelectStyle */
 	lineMultiSelectStyle?: GisViewLineStyle | null
+	/** 点击级联高亮：true / 对象打开，false / null 关闭；详细写法见 GisViewOptions.cascadeHighlight */
+	cascadeHighlight?: GisViewCascadeHighlightInput | null
 	/** 没有配置状态样式时是否仍画内置强调（尺寸 / 宽度增幅与强调环）；默认 false */
 	defaultHighlight?: boolean
 	/** 节点整体放大系数，默认 1 */
@@ -7970,12 +8205,14 @@ export interface GisViewEngineOptions {
 	lineZoomScale?: number
 	/** 缩放联动的基准比例，缺省用首次适应视图时的 camera.scale */
 	zoomBaseScale?: number
-	/** 自适应比例开关：没写联动指数的那几项按 1（与地图同倍率）算，默认 false */
-	zoomScaleAuto?: boolean
 	/** 大数据初始化是否从视图中心向外发散渲染，默认开 */
 	progressiveInit?: boolean
+	/** 点聚合：true 用缺省档，对象写法见 GisViewPointClusterOptions（只改展示 / 拾取 / 快照） */
+	pointCluster?: boolean | GisViewPointClusterOptions
 	/** 初始视图：首次拿到数据时相机落在哪里（缺省适应数据范围），结构见 GisViewInitialView */
 	initialView?: GisViewInitialView | null
+	/** 适应视图的节点间距兜底：true 用缺省档，对象可改 minDistance / maxZoom，默认关 */
+	fitSpacing?: boolean | GisViewFitSpacingOptions
 	/** onStats 的最小间隔（毫秒），默认 250，0 表示每帧都发 */
 	statsInterval?: number
 	/** 画质：档位名或 `{ mode, budgetMs, minScale }`（见 GisViewQualityOptions），只影响画哪些批次与分辨率 */
@@ -8000,7 +8237,7 @@ export interface GisViewEngineOptions {
 	contextMenu?: boolean
 	/**
 	 * 右键默认把浏览器的系统菜单收掉（组件接住右键时 preventDefault contextmenu）。
-	 * 写 false 保留系统菜单：onContextMenu / onChannelContextMenu 照常发，只是不再挡浏览器自己弹菜单。
+	 * 写 false 保留系统菜单：onContextMenu 照常发，只是不再挡浏览器自己弹菜单。
 	 */
 	preventContextMenu?: boolean
 	/** 悬停拾取的移动阈值（CSS 像素）：指针移动不超过它时不重算拾取，0 表示每次指针事件都重算；默认 2 */
@@ -8028,6 +8265,8 @@ export interface GisViewEngineOptions {
 	channelSelectMode?: GisViewChannelSelectMode
 	/** 分组拐点拖动模式：'parallel'（缺省）/ 'vertex'，见 GisViewOptions.channelWaypointDragMode */
 	channelWaypointDragMode?: GisViewChannelWaypointDragMode
+	/** 线路是否跟随节点，缺省 true；关闭后节点退场时线路 / 通道停在最后一份坐标与解析尺寸 */
+	lineFollowsNode?: boolean
 
 	/** 快捷键：动作 -> 写法（框选、多选、加点、复制、粘贴、取消、删除、适应视图），没写的沿用默认值 */
 	shortcuts?: GisViewShortcuts
@@ -8058,12 +8297,19 @@ export interface GisViewEngineOptions {
 	 */
 	onSelect?: (payload: GisViewSelectPayload | null, detail?: { mode?: 'single' | 'multi' | 'box'; originalEvent?: Event | null }) => void
 	onClick?: (payload: GisViewClickPayload | null) => void
+	/** 点中多成员聚合圆（引擎不选中成员，普通点击回调不会同时触发） */
+	onClusterClick?: (payload: GisViewClusterClickPayload, event: Event) => void
 	onDblClick?: (payload: GisViewClickPayload | null) => void
 	/** 左键 / 中键 / 右键按下与抬起：命中的要素、按钮与光标位置都在载荷里 */
 	onPointerDown?: (payload: GisViewPointerPayload, event: PointerEvent) => void
 	onPointerUp?: (payload: GisViewPointerPayload, event: PointerEvent) => void
-	/** 右键：点、线、空白都会发 */
+	/**
+	 * 右键：点、线、通道、空白都会发这一条。命中通道回线时 action.target 为 'channel'，
+	 * 载荷另带 channelContext（几组 / 当前哪组 / 能做什么），不再有单独的通道路由。
+	 */
 	onContextMenu?: (payload: GisViewPointerPayload, event: MouseEvent) => void
+	/** 点击级联高亮变了：载荷与 getCascadeHighlight() 同一份，收掉时是 null */
+	onCascadeHighlight?: (payload: GisViewCascadeHighlightInfo | null) => void
 	onPointDrag?: (payload: GisViewPointDragPayload) => void
 	/** 复制节点：start / move / commit / end / cancel（剪贴板另有 clipboard） */
 	onPointCopy?: (payload: GisViewPointCopyPayload | GisViewBatchCopyPayload) => void
@@ -8071,8 +8317,6 @@ export interface GisViewEngineOptions {
 	onPointMerge?: (payload: GisViewPointMergePayload | GisViewMergeResult | GisViewMergeFailure | GisViewMergeSelectedPayload) => void
 
 	onWaypointChange?: (payload: GisViewWaypointPayload) => void
-	/** 右键点中通道回线：给出分组上下文（几组 / 当前哪组 / 有哪些交互），点空白处给 null */
-	onChannelContextMenu?: (payload: GisViewChannelContextPayload | null, event: MouseEvent) => void
 	/** 新增通道草稿：start / from / ready / cancel / commit / blocked / restart / pick */
 	onChannelDraft?: (payload: GisViewChannelDraftPayload) => void
 	/** 草稿里每点一次发一条：step 1 拿到起点、step 2 拿到终点（线路结束） */
@@ -8249,7 +8493,7 @@ export interface GisViewEngine {
 	applyInitialView(): void
 	resetView(): void
 	getBounds(): GisViewBounds
-	/** 缩放联动的基准比例（pointZoomScale / lineZoomScale / zoomScaleAuto 共用那一份）：缺省是首次适应视图时的 camera.scale */
+	/** 缩放联动的基准比例（pointZoomScale / lineZoomScale 共用那一份）：缺省是首次适应视图时的 camera.scale */
 	getZoomBaseScale(): number
 	/** 重定缩放联动的基准比例：不传就取当下相机的比例（把现在这一屏当成「原样大小」），返回落定的基准 */
 	setZoomBaseScale(scale?: number): number
@@ -8261,6 +8505,12 @@ export interface GisViewEngine {
 	getViewRect(): GisViewBounds
 	/** 按条件列节点（只读快照，见 GisViewListOptions）：面板读数 / 导出 / 校验用，十万级下别逐帧调 */
 	listPoints(options?: GisViewListOptions): GisViewListedPoint[]
+	/** 当前展示组（含 count: 1 的单成员）：原始 points 不受影响 */
+	getClusters(): GisViewCluster[]
+	/** 覆盖层每帧同步数量文字用的轻量读数：只含多成员聚合圆 */
+	getClusterLabels(): GisViewClusterLabel[]
+	/** 当前点聚合配置与运行时开关 */
+	getPointCluster(): GisViewPointClusterReadout
 	/** 按条件列线路（只读快照）：通道内的回线给的是骨架推导出来的折线，另带 color / width 与通道读数 */
 	listLines(options?: GisViewListOptions): GisViewListedLine[]
 	/** 一批要素的世界包围盒；一个都没对上返回 null */
@@ -8303,9 +8553,9 @@ export interface GisViewEngine {
 	clientToWorld(clientX: number, clientY: number): [number, number]
 	/** 世界坐标 → 客户端坐标（摆 DOM 浮层 / 菜单用） */
 	worldToClient(x: number, y: number): [number, number]
-	pick(x: number, y: number): GisViewPickResult | null
+	pick(x: number, y: number): GisViewHitResult | null
 	/** 与组件实例的 pickAt 同一份：按浏览器客户端坐标拾取（引擎不等 DOM 事件，直接给 clientX / clientY） */
-	pickAtClient(clientX: number, clientY: number): GisViewPickResult | null
+	pickAtClient(clientX: number, clientY: number): GisViewHitResult | null
 	/** 程序化悬停（客户端坐标）：让指针「停」在这儿，悬停高亮 / 光标 / onHover 一起更新，返回这一次的读数 */
 	hoverAtClient(clientX: number, clientY: number): GisViewHoverPayload | null
 	/** 取消程序化悬停：清掉高亮与读数并补发 onHover(null) */