gis-view-webgl2 0.1.11 → 0.1.13

package/dist/index.d.ts

@@ -334,13 +334,24 @@ export interface GisViewCursorStyle {
 	}
 }
 
-/** 框选矩形样式：填充与边框分别配置 */
+/** 框选矩形样式：填充与边框分别配置；div 模式还支持线型、圆角与自定义类名 */
 export interface GisViewSelectionBoxStyle {
 	fill?: string
 	fillOpacity?: number
 	stroke?: string
-	/** 边框线宽（CSS 像素） */
+	/** 边框线宽（CSS 像素）；canvas 渲染时 0 表示不画边框 */
 	strokeWidth?: number
+	/**
+	 * 框选矩形的渲染方式：'canvas'（缺省，画在 WebGL）或 'div'（在画布上方挂一个 DOM 元素）。
+	 * div 模式额外支持 borderStyle / radius / className；canvas 模式的边框恒为实线直角。
+	 */
+	render?: 'canvas' | 'div'
+	/** div 模式追加的类名；与 .gis-view__selection-box 一起挂到边框元素上，便于整体换样式 */
+	className?: string
+	/** div 模式的边框线型，缺省 solid */
+	borderStyle?: 'solid' | 'dashed' | 'dotted'
+	/** div 模式的圆角（CSS 像素），缺省 0 */
+	radius?: number
 }
 
 /** 鹰眼图里的节点：颜色 + 半径（CSS 像素） */
@@ -408,6 +419,8 @@ export interface GisViewMinimapLineRuleStyle {
 export interface GisViewMinimapPointRule {
 	when?: GisViewConditionInput<GisViewPoint>
 	style: GisViewMinimapPointRuleStyle
+	/** 优先级：缺省 false（规则只补点自身没写的字段）；true 时这条规则写了的字段压过点自身字段 */
+	override?: boolean
 	name?: string
 }
 
@@ -415,6 +428,8 @@ export interface GisViewMinimapPointRule {
 export interface GisViewMinimapLineRule {
 	when?: GisViewConditionInput<GisViewLine>
 	style: GisViewMinimapLineRuleStyle
+	/** 优先级：缺省 false（规则只补线自身没写的字段）；true 时这条规则写了的字段压过线自身字段 */
+	override?: boolean
 	name?: string
 }
 
@@ -579,7 +594,7 @@ export interface GisViewMinimapOptions {
 	/**
 	 * 节点规则：按属性给小图上的节点定颜色 / 半径 / 形状 / 层级（条件语言与主图一样）。
 	 * 不配时沿用主图样式链：颜色 / 描边色 / 层级取规则，尺寸与符号取引擎最终解析结果
-	 * （点自身 > 主图 pointRules > 主图 pointStyle），圆、方、图片与 SVG 图标都会画出来
+	 * （override 规则 > 点自身 > 普通规则 > 主图 pointStyle），圆、方、图片与 SVG 图标都会画出来
 	 */
 	pointRules?: GisViewMinimapPointRule[]
 	/** 线路规则：按属性给小图上的线路定颜色 / 线宽 / 透明度 / 层级，不配时沿用主图 lineRules（颜色 / 透明度）与样式链线宽 */
@@ -807,6 +822,225 @@ export interface GisViewEngineHeatDensity {
 	/** 一次烘焙的耗时（毫秒） */
 	ms: number
 }
+
+/** 图例形态：ruler / continuous 是连续色带 + 刻度，piecewise 是分段色块 */
+export type GisViewVisualMapType = 'ruler' | 'continuous' | 'piecewise'
+export type GisViewVisualMapOrientation = 'vertical' | 'horizontal'
+export type GisViewVisualMapPositionName = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
+/** 落选值怎么处理：只退热力 / 连对应网架一起隐藏 / 不做内置效果 */
+export type GisViewVisualMapOutOfRange = 'heatmap' | 'network' | 'none'
+/** 图例四边定位：数字按 CSS 像素，字符串原样作为 CSS 长度（例如 '50%'）；缺省左下角 */
+export interface GisViewVisualMapPosition {
+	top?: number | string
+	right?: number | string
+	bottom?: number | string
+	left?: number | string
+}
+/** 图例外层的内联样式：普通 CSS 属性或 --gis-view-visual-map-* 变量 */
+export type GisViewVisualMapStyle = Record<string, string | number | null | undefined>
+
+/** 分段图例的一段：范围写法与 ECharts 的 pieces 一致，支持 gte / gt / lte / lt / min / max */
+export interface GisViewVisualMapPiece {
+	gte?: number
+	gt?: number
+	lte?: number
+	lt?: number
+	min?: number
+	max?: number
+	/** 自定义这一段显示的文字；不写按范围自动格式化 */
+	label?: string
+	/** 自定义这一段色块的颜色；不写按色带在区间中点的颜色取 */
+	color?: string
+}
+
+/** 图例 formatter 的读数：连续刻度与分段色块都会走同一份 */
+export interface GisViewVisualMapFormatterInfo {
+	value: number
+	min: number
+	max: number
+	ratio: number
+	type: 'ruler' | 'piecewise'
+	target: GisViewHeatmapTarget
+	field: string
+	index?: number
+	piece?: GisViewVisualMapPiece
+}
+
+/** 自定义图例回调可用的读数与受控交互入口 */
+export interface GisViewVisualMapRenderContext {
+	type: 'ruler' | 'piecewise'
+	target: GisViewHeatmapTarget
+	field: string
+	domain: [number, number]
+	colors: string[]
+	stops: number[] | null
+	opacity: number | [number, number]
+	orient: GisViewVisualMapOrientation
+	title: string
+	unit: string
+	ticks: GisViewVisualMapTick[]
+	pieces: GisViewVisualMapValuePiece[]
+	selectedMode: 'single' | 'multiple' | false
+	calculable: boolean
+	outOfRange: GisViewVisualMapOutOfRange
+	/** 当前选中的分段下标；连续尺恒为空数组 */
+	selected: number[]
+	/** 当前区间（数值，低值在前）；未开启 calculable 时为 null */
+	range: [number, number] | null
+	/** 当前区间在色带上的比例（0 ~ 1，低比例在前） */
+	rangeRatios: [number, number] | null
+	root: HTMLElement
+	body: HTMLElement
+	titleElement: HTMLElement
+	/** 把 0 ~ 1 的色带比例换成数值 */
+	valueAt(ratio: number): number
+	/** 按图例的 precision / formatter / unit 格式化数值 */
+	formatValue(value: number): string
+	/** 设置分段选择；返回是否发生变化 */
+	setSelection(selected: number[] | Record<string, boolean>): boolean
+	/** 设置数值区间；返回是否发生变化 */
+	setRange(range: [number, number]): boolean
+	/** 分段图例清空选择，连续尺恢复完整区间 */
+	clearSelection(): boolean
+	/** 用当前状态主动触发 onChange */
+	emitChange(reason?: 'piece' | 'range' | 'api'): void
+}
+
+/** 图例交互回调：只有用户操作 / 自定义渲染主动调用时触发，受控配置更新不回声 */
+export interface GisViewVisualMapChangePayload {
+	type: 'ruler' | 'piecewise'
+	target: GisViewHeatmapTarget
+	field: string
+	domain: [number, number]
+	interactive: boolean
+	selectedMode: 'single' | 'multiple' | false
+	calculable: boolean
+	outOfRange: GisViewVisualMapOutOfRange
+	selected: number[]
+	range: [number, number] | null
+	rangeRatios: [number, number] | null
+	element: HTMLElement
+	source: 'user' | 'api'
+	reason: 'piece' | 'range' | 'api'
+	originalEvent: Event | null
+}
+
+/**
+ * 图例（visualMap）：参考 ECharts 的 visualMap，把热力图的色带画成带刻度的尺或分段色块。
+ * 配置对象本身即开关；不写时一个 DOM 节点都不产生。字段 / 值域 / 颜色默认跟随 heatmap，
+ * 也能在自己的配置里覆盖成一条独立图例。不写 target 时，展示值域取 heatmap 启用目标中
+ * 第一个能扫到数值的那一类，当前分段 / 区间却门控 heatmap 的全部启用目标（同一 field）；
+ * 显式 target 才只作用这一类。默认继承主图热力的鹰眼图同步门控，显式 minimap.heatmap 仍独立。
+ * outOfRange 决定落选值是只回普通样式、连对应网架一起隐藏，还是不做内置效果；数据、筛选与分组不变。
+ */
+export interface GisViewVisualMap {
+	/** 关掉这一份配置（等价于不配 visualMap） */
+	enabled?: boolean
+	/** 'ruler'（缺省，continuous 同义）连续尺 / 'piecewise' 分段色块 */
+	type?: GisViewVisualMapType
+	/**
+	 * 展示值域使用哪一类要素：显式写只门控这一类；不写时跟随 heatmap 的全部启用目标，
+	 * 展示值域按 point → line → channel 选第一个真正有数值的目标（都缺值时回落第一个启用目标）。
+	 */
+	target?: GisViewHeatmapTarget
+	/** 取值字段：不写跟随 heatmap.field，没有 heatmap 时按 'value' 自动扫数据 */
+	field?: string
+	/** 显式值域 [起, 止]；反向写就是颜色反向。不写 / 'auto' 按当前数据自动算 */
+	domain?: [number, number] | 'auto'
+	/** ECharts 写法的单端覆盖：只给一端时另一端仍按自动值域取 */
+	min?: number
+	max?: number
+	/** 渐变色（至少两段），不写跟随 heatmap.colors，最后回落到内置色带 */
+	colors?: string[]
+	/** 色标位置（0 ~ 1，与 colors 一一对应） */
+	stops?: number[]
+	/** 色带透明度，写法与 heatmap.opacity 一致 */
+	opacity?: number | [number, number]
+	title?: string
+	/** 每个数值后面追加的单位（自定义 formatter 时不自动追加） */
+	unit?: string
+	orient?: GisViewVisualMapOrientation
+	/** 四角名或四边定位对象，缺省 'bottom-left' */
+	position?: GisViewVisualMapPositionName | GisViewVisualMapPosition
+	/** 连续尺色带的宽度 / 高度（CSS 像素）；横向时缺省 200 × 14，纵向时 14 × 160 */
+	width?: number
+	height?: number
+	/** 连续尺的刻度数，同时也是不写 pieces 时的自动分段数（2 ~ 12，缺省 5） */
+	tickCount?: number
+	/** 打开图例交互：分段可点选，连续尺默认出现可拖动的区间；当前选区会实时门控图例作用目标上同 field 的热力上色 / 光晕 / 密度；缺省 false */
+	interactive?: boolean
+	/** 落选值处理：'heatmap'（缺省，只退热力、网架回普通样式）/ 'network'（对应点 / 独立线路 / 通道从画布与拾取中隐藏，未写 target 时三类同时生效）/ 'none'（只保留 onChange） */
+	outOfRange?: GisViewVisualMapOutOfRange
+	/** 分段选择方式：single 单选 / multiple（或 true）多选；不写时 interactive 默认 multiple */
+	selectedMode?: 'single' | 'multiple' | boolean | null
+	/** 初始选中分段：下标数组，或按下标 / 标签映射的布尔对象；未选中的分段不参与图例作用目标上同 field 的热力；不写默认全选 */
+	selected?: number[] | Record<string, boolean> | null
+	/** 连续尺初始区间 [低, 高]；区间外的值不参与图例作用目标上同 field 的热力；不写且 calculable 时是完整值域 */
+	range?: [number, number] | null
+	/** 连续尺是否显示可拖动的区间手柄；interactive 时缺省 true，显式 false 可关掉 */
+	calculable?: boolean
+	/** 数字固定小数位；不写按值域跨度自动选 */
+	precision?: number
+	/**
+	 * 文字格式：函数收到数值与读数；字符串支持 {value} / {min} / {max} / {unit} / {title} / {field}
+	 * 占位符。函数返回空串时这一项仍占位，只是不显示文字。
+	 */
+	formatter?: string | ((value: number, info: GisViewVisualMapFormatterInfo) => string)
+	/** piecewise 的分段；不写按值域与 tickCount 等分 */
+	pieces?: GisViewVisualMapPiece[]
+	/**
+	 * 完全自定义图例：返回 DOM 节点 / DocumentFragment / HTML 字符串，或直接往 context.body 里追加节点。
+	 * 内置标题会隐藏；容器定位与 pointer-events 仍沿用图例根节点。
+	 */
+	render?: (context: GisViewVisualMapRenderContext) => Node | string | null | void
+	/** 分段点选 / 区间拖动后的回调；图例自身已同步门控热力，这里用于额外业务联动；受控配置更新不会反过来触发它 */
+	onChange?: (payload: GisViewVisualMapChangePayload) => void
+	/** 挂载容器（元素或选择器），不写挂到组件根节点；选择器找不到时也回落到组件根节点 */
+	container?: string | HTMLElement
+	/** 追加在根节点上的 class（位置 / 颜色也可以用 CSS 变量整体覆盖） */
+	className?: string
+	/** 直接写在这层 DOM 上的内联样式 */
+	style?: GisViewVisualMapStyle
+}
+
+/** 图例上一根刻度的读数 */
+export interface GisViewVisualMapTick {
+	value: number
+	ratio: number
+	label: string
+}
+
+/** 图例上一个分段的读数 */
+export interface GisViewVisualMapValuePiece {
+	low: number | null
+	high: number | null
+	label: string
+	color: string
+	ratio: number
+}
+
+/** getVisualMap() 的读数：值域、色带与当前显示的刻度 / 分段 */
+export interface GisViewVisualMapReadout {
+	type: 'ruler' | 'piecewise'
+	/** 实际用于展示值域的目标；未写 target 且前一类缺值时可能是 line / channel */
+	target: GisViewHeatmapTarget
+	field: string
+	domain: [number, number]
+	colors: string[]
+	orient: GisViewVisualMapOrientation
+	title: string
+	unit: string
+	interactive: boolean
+	selectedMode: 'single' | 'multiple' | false
+	calculable: boolean
+	outOfRange: GisViewVisualMapOutOfRange
+	selected: number[]
+	range: [number, number] | null
+	rangeRatios: [number, number] | null
+	ticks: GisViewVisualMapTick[]
+	pieces: GisViewVisualMapValuePiece[]
+}
+
 /**
  * 线路动画（沿线跑动的图标，ECharts 的 `lines.effect` 那一类）：配在 options.effects.line 上作为全局缺省，
  * 逐条线路用 lines[].effect 覆盖它 —— `false` / `null` 关掉这一条，`true` 用全局那一份（全局没配就用缺省值），
@@ -1244,6 +1478,7 @@ export type GisViewCascadeHighlightScope = 'points' | 'both'
 /**
  * 点击级联高亮：点击节点时高亮它和直接相连的节点 / 线路，点击线路或通道时高亮这条线的两端。
  * 它与选中集完全分开 —— 不写 selectionKeys、不改 selected，样式也不走悬停 / 选中那一套。
+ * 通过 toggleSelect / Ctrl 取反 / deselect / selectFeatures 的 remove 或清空取消选中时，级联会一起收掉。
  * true 等价于 { enabled: true, scope: 'both' }；不配或 false 都是关闭。
  */
 export interface GisViewCascadeHighlightOptions {
@@ -1341,6 +1576,8 @@ export type GisViewChannelOffsetMode = 'tangent' | 'inset'
 export interface GisViewChannelGroup {
 	/** 分组 id：缺省时第一组用通道 id，第 n 组用 `${通道 id}::${n}`（n 从 2 起） */
 	id?: string | number
+	/** 这一组是否显示，缺省 true；隐藏后成员、骨架与拐点都保留，改回 true 原样恢复 */
+	visible?: boolean
 	/** 这一组的线路 id，至少一条；同一条线只能出现在一组里，没列出来的并回第一组 */
 	lineIds: Array<string | number>
 	/** 这一组自己的骨架拐点（两端锚定时只写中间拐点）：新拆分出来的分组不带拐点，就是一条直线 */
@@ -1437,6 +1674,8 @@ export interface GisViewChannelInfo {
 	channelId: string | number
 	/** 通道在 channels 数组里的下标 */
 	channelIndex: number
+	/** 这一组当前是否显示；隐藏组的成员不出现在图上，但几何与拐点仍保留 */
+	visible: boolean
 	/** 通道内线路在 lines 数组里的下标，顺序与回线顺序一致 */
 	lineIndexes: number[]
 	/** 骨架折线（中心线） */
@@ -1462,6 +1701,8 @@ export interface GisViewChannelMembers {
 	channelId: string | number
 	/** 通道在 channels 数组里的下标（热力图这类按通道取值时用它） */
 	channelIndex: number
+	/** 这一组当前是否显示 */
+	visible: boolean
 	/** 成员回线在 lines 数组里的下标 */
 	lineIndexes: number[]
 	/** 每条成员回线的横向偏移（世界单位，与 lineIndexes 一一对应） */
@@ -1492,6 +1733,8 @@ export interface GisViewChannelGroupInfo {
 	channelIndex: number
 	/** 分组 id */
 	id: string | number
+	/** 这一组当前是否显示 */
+	visible: boolean
 	/** 这一组的线路在 lines 数组里的下标 */
 	lineIndexes: number[]
 	/** 这一组的线路 id */
@@ -1553,6 +1796,8 @@ export interface GisViewChannelContextGroup {
 	channelId: string | number
 	/** 分组在通道里的序号（从 0 起，顺序即声明顺序） */
 	index: number
+	/** 这一组当前是否显示 */
+	visible: boolean
 	/** 这一组的回线 id */
 	lineIds: Array<string | number>
 	/** 这一组的回线在 lines 数组里的下标 */
@@ -2050,10 +2295,26 @@ export interface GisViewMovedPoint {
 }
 
 /** 可整批隐藏 / 显示的要素类型 */
-export type GisViewVisibilityKind = 'point' | 'line' | 'channel'
+export type GisViewVisibilityKind = 'point' | 'line' | 'channel' | 'group'
+
+/**
+ * 分组引用的定位写法：通道认 channelId / channelIndex，分组认 groupId / groupIndex；
+ * 也可以只写 id（分组 id 在整个视图里唯一时）。直接给字符串 / 数字时按分组 id 找。
+ */
+export interface GisViewChannelGroupVisibilityRef {
+	channelId?: string | number
+	channelIndex?: number
+	groupId?: string | number
+	groupIndex?: number
+	/** 分组 id 的简写；与 groupId 同时写时以 groupId 为准 */
+	id?: string | number
+}
+
+/** 分组之外，其余类型沿用要素引用 */
+export type GisViewVisibilityRef = GisViewFeatureRef | GisViewChannelGroupVisibilityRef
 
 /** 隐藏 / 显示的引用：单个 id / 下标 / `{ id }` / `{ index }`，一批，或当前选中集 `'selection'` */
-export type GisViewVisibilityRefs = GisViewFeatureRef | 'selection' | Array<GisViewFeatureRef | 'selection'>
+export type GisViewVisibilityRefs = GisViewVisibilityRef | 'selection' | Array<GisViewVisibilityRef | 'selection'>
 
 /** 隐藏 / 显示时没认出来的引用 */
 export interface GisViewVisibilitySkip {
@@ -2072,12 +2333,16 @@ export interface GisViewSetVisibilityOutcome {
 	/** 对应的 id；要素没 id 时退回下标 */
 	ids: Array<string | number>
 	items: Array<GisViewPoint | GisViewLine | GisViewChannel>
+	/** kind 为 'group' 时受影响的分组读数；其余类型为空数组 */
+	groups: GisViewChannelGroupInfo[]
 	skipped: GisViewVisibilitySkip[]
 }
 
 /** 通道变化里的一组：成员与骨架都是当次读数的可比较快照 */
 export interface GisViewChangedChannelGroup {
 	id: string | number | null
+	/** 这一组当前是否显示 */
+	visible: boolean
 	lineIds: string[]
 	path: GisViewCoordinate[] | null
 }
@@ -2573,6 +2838,17 @@ export interface GisViewGeoJsonStyle {
 	strokeWidth?: number
 	/** y 轴比例，与 ECharts 的 geo.aspectScale 一致：默认 0.75；坐标不是经纬度时传 1 */
 	aspectScale?: number
+	/**
+	 * 画出来的目标世界范围：填了就按这份矩形把整份 GeoJSON 独立缩放 / 平移到指定位置，
+	 * 因此可以不改原始 GeoJSON 就调整宽高比与大小；不写时沿用数据范围与 aspectScale 的结果。
+	 * rawBounds 仍保留原始坐标范围，经纬度投影与 data 映射口径不变。
+	 */
+	bounds?: GisViewBounds
+	/**
+	 * 绕 bounds 中心顺时针旋转的角度（度，缺省 0）：只旋转画出来的 GeoJSON，不改原数据；
+	 * rawBounds 仍是原始坐标范围，bounds 与 getResolvedBackground().geoJson.bounds 是旋转后的轴对齐外框。
+	 */
+	rotation?: number
 	/** 区域名从 properties 的哪个字段取，默认 'name' */
 	nameProperty?: string
 	/** 区域文字：配了就显示 */
@@ -2602,6 +2878,88 @@ export interface GisViewBackground {
 	opacity?: number
 }
 
+/** 内置背景编辑器的描边 / 手柄样式（都是 CSS 像素，改完立刻作用在覆盖层上） */
+export interface GisViewBackgroundEditorStyle {
+	/** 轮廓、旋转连线与手柄颜色 */
+	color?: string
+	/** 背景面的填充色；不想要填充可写 'transparent' */
+	fill?: string
+	/** 轮廓与旋转连线宽度 */
+	lineWidth?: number
+	/** 轮廓 / 连线是否虚线 */
+	dashed?: boolean
+	/** 缩放手柄边长 */
+	handleSize?: number
+	/** 缩放手柄形状 */
+	handleShape?: 'circle' | 'square'
+}
+
+/** beginBackgroundEdit 的配置：背景类型从当前 background 自动识别（同时有图片时优先图片） */
+export interface GisViewBackgroundEditorOptions {
+	/** 是否锁宽高比；true 只出四角，false 出四角 + 四边中点 */
+	aspectLocked?: boolean
+	/** 是否显示旋转点（true 时手柄数再 +1） */
+	rotation?: boolean
+	/** 按住 Shift 时的旋转吸附角（度）；0 关闭 */
+	snapAngle?: number
+	/** 拖缩放时的最小屏幕尺寸（CSS 像素） */
+	minSize?: number
+	/** 旋转点离上边的附加距离（CSS 像素） */
+	rotationDistance?: number
+	/** 进入时是否把背景放回视野 */
+	fitView?: boolean
+	/** fitView / updateBackgroundEdit({ fitView: true }) 的留白 */
+	fitPadding?: number
+	/** 是否显示底部操作提示 */
+	showHint?: boolean
+	style?: GisViewBackgroundEditorStyle
+	/** 编辑器驱动的每次变化（移动 / 缩放 / 旋转 / 配置）回调 */
+	onChange?: (state: GisViewBackgroundEditorState) => void
+	/** 一次拖动手势结束时回调 */
+	onEnd?: (state: GisViewBackgroundEditorState) => void
+}
+
+/** 内置背景编辑器的实时读数：rotation 是角度（度，顺时针），rotationEnabled 才控制旋转点显隐 */
+export interface GisViewBackgroundEditorState {
+	active: true
+	backgroundType: 'image' | 'geojson'
+	aspectLocked: boolean
+	rotationEnabled: boolean
+	/** 当前角度（度，顺时针，-180 ~ 180） */
+	rotation: number
+	center: [number, number]
+	width: number
+	height: number
+	handleCount: number
+	backgroundEditing: boolean
+	snapAngle: number
+	minSize: number
+	rotationDistance: number
+	showHint: boolean
+	fitView: boolean
+	fitPadding: number
+	style: Required<GisViewBackgroundEditorStyle>
+}
+
+/** updateBackgroundEdit 的增量：rotation 写布尔值切旋转点，写数字等价于 angle */
+export interface GisViewBackgroundEditorPatch {
+	aspectLocked?: boolean
+	rotation?: boolean | number
+	angle?: number
+	snapAngle?: number
+	minSize?: number
+	rotationDistance?: number
+	fitView?: boolean
+	fitPadding?: number
+	showHint?: boolean
+	style?: GisViewBackgroundEditorStyle
+	center?: [number, number]
+	width?: number
+	height?: number
+	onChange?: (state: GisViewBackgroundEditorState) => void
+	onEnd?: (state: GisViewBackgroundEditorState) => void
+}
+
 /** 解析后的背景图片：quad 是四个顶点的 [x, y, u, v]（左上 / 右上 / 左下 / 右下），直接喂给渲染管线 */
 export interface GisViewResolvedBackgroundImage {
 	/** 解码后的图片元素（Canvas2D 侧画缩略图用），WebGL 侧只用 texture */
@@ -2651,6 +3009,8 @@ export interface GisViewResolvedGeoJsonRegion {
 export interface GisViewResolvedGeoJson {
 	regions: GisViewResolvedGeoJsonRegion[]
 	labels: GisViewResolvedBackgroundLabel[]
+	/** 实际落到画面上的旋转角（度，顺时针，已归一到 [-180, 180)） */
+	rotation: number
 	/** 缩放前的真实坐标范围（aspectScale 生效前）：相机、fitView 与经纬度换算用它 */
 	rawBounds: GisViewBounds | null
 	/** 这份底图实际使用的 aspectScale（默认 0.75） */
@@ -3134,7 +3494,7 @@ export type GisViewPointerTarget = 'point' | 'line' | 'channel' | 'cluster' | 'w
 
 /**
  * 一次指针操作的动作名。同一个名字在「按下 / 松开 / 点击」三条事件里含义略有不同：
- * - onPointerDown 是「这一次按下打算做什么」（意图）：'pan' / 'dragPoint' / 'dragWaypoint' / 'boxSelect' /
+ * - onPointerDown 是「这一次按下打算做什么」（意图）：'pan' / 'dragPoint' / 'dragSelectionBox' / 'dragWaypoint' / 'boxSelect' /
  *   'copy' / 'channelDraft'（点两次加通道）/ 'decorationDraft'（动态装饰器草稿）/ 'contextMenu'（右键）/ 'click'（左键按下，但下面没有可拖的东西）；
  * - onPointerUp 是「刚做完的那一件事」：拖过就是拖动的名字，没拖就是 'click'（配合 action.moved 判读）；
  * - onClick / onDblClick 是真正发生的那一件：'select'（点中要素）/ 'click'（没开选中）/ 'dblClick'（双击）；
@@ -3152,6 +3512,8 @@ export type GisViewPointerActionType =
 	| 'selectWaypoint'
 	| 'dragWaypoint'
 	| 'dragPoint'
+	/** 拖动保持中的框选矩形：连同框内选中的节点一起平移 */
+	| 'dragSelectionBox'
 	| 'clusterClick'
 	| 'dragLabel'
 	| 'selectLabel'
@@ -4181,20 +4543,32 @@ export type GisViewConditionInput<T = never> =
 /** 条件判定函数：不传字段即不按条件过滤，数组表示「并且」 */
 export declare const createConditionMatcher: <T = never>(input: GisViewConditionInput<T>) => (item: T, index?: number) => boolean
 
-/** 点的批量样式规则：条件命中就套用 style，只补点自身没写的字段 */
+/**
+ * 点的批量样式规则：条件命中就套用 style。
+ * 缺省只补点自身没写的字段；写 `override: true` 时这条规则的字段压过点自身字段，
+ * 但仍低于悬停 / 选中 / 框选状态样式与热力图。
+ */
 export interface GisViewPointRule {
 	/** 命中条件，缺省命中全部点 */
 	when?: GisViewConditionInput<GisViewPoint>
 	/** 命中的点按字段套用的样式：颜色、大小、符号、描边、透明度、阴影、绘制层级（zIndex） */
 	style: GisViewPointStyle
+	/** 优先级：缺省 false（规则只补点自身没写的字段）；true 时这条规则的样式压过点自身字段 */
+	override?: boolean
 	/** 规则名，仅作标识 */
 	name?: string
 }
 
-/** 线的批量样式规则：条件命中就套用 style，只补线自身没写的字段 */
+/**
+ * 线的批量样式规则：条件命中就套用 style。
+ * 缺省只补线自身没写的字段；写 `override: true` 时这条规则的字段压过线自身字段，
+ * 但仍低于悬停 / 选中 / 框选状态样式与热力图。
+ */
 export interface GisViewLineRule {
 	when?: GisViewConditionInput<GisViewLine>
 	style: GisViewLineStyle
+	/** 优先级：缺省 false（规则只补线自身没写的字段）；true 时这条规则的样式压过线自身字段 */
+	override?: boolean
 	name?: string
 }
 
@@ -5305,14 +5679,14 @@ export interface GisViewChannelSnapshot {
 }
 
 
-/** getPointSpacing() 的端点：可见节点在原始 points 里的 id、下标与数据对象 */
+/** getPointSpacing() / getPointsSpacing() 的端点：节点在原始 points 里的 id、下标与数据对象 */
 export interface GisViewPointSpacingNode {
 	id: string | number
 	index: number
 	item: GisViewPoint
 }
 
-/** getPointSpacing() 的一对节点：distance 是当前相机比例下的 CSS 像素 */
+/** getPointSpacing() / getPointsSpacing() 的一对节点：distance 是当前相机比例下的 CSS 像素 */
 export interface GisViewPointSpacingPair {
 	from: GisViewPointSpacingNode
 	to: GisViewPointSpacingNode
@@ -5320,11 +5694,12 @@ export interface GisViewPointSpacingPair {
 }
 
 /**
- * getPointSpacing() 的读数：当前可见节点的最近正距离与最远距离，单位都是 CSS 像素，
- * 与 fitSpacing 同一套屏幕口径，并随当前相机比例换算。筛选 / 隐藏后的节点不参与。
+ * getPointSpacing() / getPointsSpacing() 的读数：一组节点的最近正距离与最远距离，单位都是 CSS 像素，
+ * 与 fitSpacing 同一套屏幕口径，并随当前相机比例换算。前者统计当前可见节点；
+ * 后者只统计显式传入的节点，筛选 / 隐藏不影响。
  */
 export interface GisViewPointSpacing {
-	/** 当前参与统计的可见节点数 */
+	/** 当前参与统计的节点数 */
 	count: number
 	/** 最近两个不同位置节点之间的 CSS 像素距离；不足两个节点或全部重合时为 null */
 	minDistance: number | null
@@ -5447,7 +5822,7 @@ export interface GisViewDropPreviewInput {
 	screen?: [number, number]
 	/** 落点钉住的世界坐标；只给 screen 时按当前相机换算 */
 	world?: [number, number]
-	/** 准备落地的要素字段：走与真实要素完全相同的样式链（规则 -> 全局样式 -> 这一份的字段） */
+	/** 准备落地的要素字段：走与真实要素完全相同的样式链（override 规则 > 这一份的字段 > 普通规则 > 全局样式） */
 	item?: Partial<GisViewPoint> & Partial<GisViewLine>
 	/** line / channel 预览的起点（世界坐标）：缺省就是落点，那样画不出线段 */
 	from?: [number, number]
@@ -5502,16 +5877,17 @@ export interface GisViewInitialView {
 
 /**
  * 适应视图的节点间距兜底：普通「铺满数据范围」让最近节点在屏幕上挤在一起时，
- * 按 minDistance 反推一个更高的相机比例；节点分布太散、最远节点铺得过开时，
- * 按 maxDistance 把比例压回来。minDistance / maxDistance 二选一，
+ * minDistance 按 `minDistance / 最近正世界距离` 精确反推相机比例，放大或缩小都会覆盖普通适应；
+ * 节点分布太散、最远节点铺得过开时，maxDistance 只会把普通适应比例压回来。
+ * minDistance / maxDistance 二选一，
  * 同时给时只启用 maxDistance；相机中心始终沿用普通适应的包围盒中心。
  */
 export interface GisViewFitSpacingOptions {
-	/** 距离模式一：可见节点中心之间的最小屏幕距离（CSS 像素），默认 24；与 maxDistance 二选一 */
+	/** 距离模式一：可见节点中心之间的精确屏幕距离（CSS 像素），默认 24；与 maxDistance 二选一 */
 	minDistance?: number
 	/** 距离模式二：可见节点里最远一对的中心距不超过这个屏幕距离（CSS 像素）；与 minDistance 二选一，同时给时只启用它 */
 	maxDistance?: number
-	/** 相对普通适应比例的最大放大倍数，默认 0（不限，只受 maxScale 约束）；正数表示上限 */
+	/** @deprecated 兼容旧配置保留；不再限制 minDistance / maxDistance，实际比例只由 minScale / maxScale 最终夹取 */
 	maxZoom?: number
 }
 
@@ -5524,8 +5900,24 @@ export interface GisViewPluginContext {
 	readonly apiVersion: 1
 	/** 与插件第一个参数相同，方便统一改写成只收一个上下文对象 */
 	readonly view: GisViewInstance
+	/** 这个插件作用域自己的中止信号：view.use() 返回的卸载函数或实例 destroy() 调用时 abort */
+	readonly signal: AbortSignal
+	/**
+	 * 登记一个自动清理函数：插件卸载 / 实例销毁时按登记顺序的倒序执行。
+	 * 返回的函数用于提前执行并摘掉这一项（幂等，重复调用只执行一次）。
+	 */
+	onCleanup(cleanup: () => void): () => void
+	/** 订阅视图事件并自动退订；返回的函数可提前退订（幂等） */
+	on<K extends GisViewEventName>(name: K, handler: GisViewEventListener<K>): () => void
+	on(name: GisViewEventWildcard, handler: GisViewAnyEventListener): () => void
+	/** 注册实例命令并自动注销；同名覆盖时旧注销函数不会误删新命令 */
+	registerCommand<Payload = unknown, Value = unknown>(name: string, handler: GisViewCommandHandler<Payload, Value>): () => void
 }
 
+/**
+ * 插件返回值只需要 destroy；第二个参数是插件作用域上下文（signal / 自动清理）。
+ * 旧写法 `view => ({ destroy })` 不受影响。
+ */
 export type GisViewPlugin = (view: GisViewInstance, context: GisViewPluginContext) => void | { destroy?: () => void }
 
 /** 实例命令的上下文：注册表属于这个视图，handler 里拿它就能继续调实例方法 */
@@ -5625,7 +6017,7 @@ export interface GisViewCopyOptions {
 /** 合并前的一个节点样式快照：getPointStyle() 的返回，合并取尺寸 / 图标用的就是它 */
 export interface GisViewPointStyleSnapshot {
 	index: number
-	/** 样式链（节点自身 > 规则 > pointStyle）定下来的尺寸，含 sizeScale，不含状态样式与热力倍率 */
+	/** 样式链（override 规则 > 节点自身 > 普通规则 > pointStyle）定下来的尺寸，含 sizeScale，不含状态样式与热力倍率 */
 	size: number
 	/** 样式链定下来的图标（没配就是 undefined） */
 	symbol: GisViewSymbolInput | undefined
@@ -5635,7 +6027,7 @@ export interface GisViewPointStyleSnapshot {
 /** 一条线路解析之后的样式快照：getLineStyle() 的返回 */
 export interface GisViewLineStyleSnapshot {
 	index: number
-	/** 样式链（线路自身 > 规则 > lineStyle）定下来的原始线宽，不含 lineWidthScale 与缩放联动 */
+	/** 样式链（override 规则 > 线路自身 > 普通规则 > lineStyle）定下来的原始线宽，不含 lineWidthScale 与缩放联动 */
 	width: number
 	/** 解析后的 RGBA 颜色，四个分量都在 0 ~ 1 */
 	color: [number, number, number, number]
@@ -5759,6 +6151,9 @@ export type GisViewChannelWaypointDragMode =
 	/** 只把同组同一 pathIndex 的拐点按相同世界增量平移，其他拐点（含相邻顶点）保持不动 */
 	| 'vertex'
 
+/** 隐藏部分回线后的车道排布：保留原槽位，或让剩余可见回线在通道宽度内重新居中 */
+export type GisViewChannelHiddenLineLayout = 'preserve' | 'center'
+
 /**
  * 框选允许收哪几类要素：节点、独立线路、通道回线，以及线路 / 通道的端点口径。
  * 通道回线只归 channel 这一档管；通道之外的普通线路归 line，两者可以任意组合。
@@ -6154,6 +6549,7 @@ export interface GisViewOptionChangePayload {
 		channels: boolean
 		filter: boolean
 		minimap: boolean
+		visualMap: boolean
 		features: boolean
 		quality: boolean
 		history: boolean
@@ -6523,9 +6919,9 @@ export interface GisViewOptions {
 	background?: GisViewBackground
 	pointStyle?: GisViewPointStyle
 	lineStyle?: GisViewLineStyle
-	/** 点的批量样式规则：按顺序命中覆盖，只补点自身没写的字段 */
+	/** 点的批量样式规则：按顺序命中覆盖；缺省只补空位，单条可写 override: true 压过点自身字段 */
 	pointRules?: GisViewPointRule[]
-	/** 线的批量样式规则：按顺序命中覆盖，只补线自身没写的字段 */
+	/** 线的批量样式规则：按顺序命中覆盖；缺省只补空位，单条可写 override: true 压过线自身字段 */
 	lineRules?: GisViewLineRule[]
 	/**
 	 * 热力图：按字段的数值给节点 / 线路 / 通道回线取色带颜色，并可按同一个值缩放尺寸（节点看 size、线路看 width）。
@@ -6533,6 +6929,14 @@ export interface GisViewOptions {
 	 * 鹰眼图默认沿用这一份，也能用 minimap.heatmap 单独换一份或关掉
 	 */
 	heatmap?: GisViewHeatmap | null
+	/**
+	 * 图例：参考 ECharts visualMap，把热力图的色带画成带刻度的连续尺（ruler / continuous）或分段色块（piecewise）。
+	 * 不写 / null 时零 DOM；默认跟随 heatmap 的字段、自动值域与颜色，也能独立给 domain / colors。
+	 * 不写 target 时展示值域取第一类有数值的目标，交互选区门控 heatmap 全部启用目标上同 field 的
+	 * 热力上色、光晕与密度；显式 target 只门控这一类。不删除数据、不改筛选；
+	 * 只改图例配置仍只重画这一层，不触发引擎场景重排或标签重排
+	 */
+	visualMap?: GisViewVisualMap | null
 	/**
 	 * 节点标签：配了就按这个配置渲染，内容、位置、数量与显隐都可配。
 	 * 写数组就是「一个节点上显示多条标签」：数组里每一条各自有内容 / 位置 / 样式 / 显隐，
@@ -6611,7 +7015,7 @@ export interface GisViewOptions {
 	/**
 	 * 点击级联高亮（默认关）：点击节点时亮起它和直接相连的节点；scope 为 both 时连线路一起亮，
 	 * 点击线路 / 通道回线时亮起两端节点。它不进选中集，样式与悬停 / 选中分开配置，
-	 * 当前亮起的清单用 getCascadeHighlight() 读。
+	 * 当前亮起的清单用 getCascadeHighlight() 读；取消选中时同步收掉，不会留下级联残影。
 	 */
 	cascadeHighlight?: GisViewCascadeHighlightInput
 	/** 没有配置状态样式时，是否仍用尺寸 / 宽度增幅画出内置强调；默认 false（不配样式就不改变外观） */
@@ -6648,6 +7052,23 @@ export interface GisViewOptions {
 	pointCluster?: boolean | GisViewPointClusterOptions
 	/** 是否绘制网格：与其它功能开关同一条口径，**缺省关**，写 showGrid: true 才画 */
 	showGrid?: boolean
+	/**
+	 * 网架整体显隐：false 时节点、线路、通道、装饰、动画与标签全部不画，只保留背景、网格与自定义 WebGL 层。
+	 * 适合先铺数据、再加 / 调背景；缺省 true。运行时用 updateOptions({ networkVisible }) 一键切换。
+	 */
+	networkVisible?: boolean
+	/**
+	 * 网架整体不透明度（0 ~ 1，缺省 1）：在每类要素自身 opacity 之后再乘一层，背景不受影响。
+	 * 与 networkVisible 分开：要完全看不见用 networkVisible: false，只想压淡网架调这一项。
+	 */
+	networkOpacity?: number
+	/**
+	 * 背景编辑模式：true 时节点、线路、通道的悬停、点击、选中、拖拽、框选、右键与数据快捷键全部停用，
+	 * 但滚轮缩放照常可用，方便让网架和背景一起放大缩小后只调整背景。缺省 false。
+	 * 背景本身的移动 / 旋转 / 缩放可用内置 beginBackgroundEdit() / updateBackgroundEdit() / endBackgroundEdit()，
+	 * 也可由使用方编辑界面自行调用 updateBackground() 完成。
+	 */
+	backgroundEditing?: boolean
 	gridColor?: string
 	/** 网格线的屏幕目标间距（像素），实际步长吸附到 1 / 2 / 5 × 10^n */
 	gridSize?: number
@@ -6695,6 +7116,17 @@ export interface GisViewOptions {
 	 * 关着时多选仍走框选（boxSelect）与按住多选快捷键（默认 Ctrl / ⌘）。
 	 */
 	multiSelect?: boolean
+	/**
+	 * 再次选中即取消（**缺省关**）：打开后，普通点击已在选中集里的要素会把它取消；
+	 * Ctrl / ⌘ 先选中、再普通点击同一要素也同样取消。单击 / 双击两种 selectTrigger 都适用，
+	 * 双击会按一次操作处理（第一下取反、第二下保持），不会因为双击的两下连点而反复切换。
+	 * 命中通道回线时按 channelSelectMode 决定取消单条回线 / 当前分组 / 整条通道，其他选中项保留；
+	 * 该组 / 通道只选中一部分、或点到组内另一条回线时，也按同一展开范围整体取消；
+	 * 该组 / 通道已经完整选中时，即使 channelSelectMode 为 line 也整组 / 整条取消。
+	 * 这条取消路径不受 selectionKinds 限制；取消生效时同一来源的点击级联也会一起收掉。
+	 * 与 multiSelect 同时打开时沿用 multiSelect 的累加取反口径；运行时走 updateOptions({ toggleSelect })。
+	 */
+	toggleSelect?: boolean
 	/**
 	 * 选中触发方式：缺省 'click'（单击选中）；写 'dblClick' 后第一次点击只派发 onClick，
 	 * 第二次（双击判定命中）才更新选中集，并同时派发 onClick 与 onDblClick。
@@ -6706,13 +7138,19 @@ export interface GisViewOptions {
 	 * 另有 'lineEndpoints' / 'channelEndpoints' 只在框选时要求线路 / 通道两端节点都在框内；
 	 * 可写数组任意组合，'all' / true 全开，false / null 全关。
 	 * **不写时保留旧行为**：框选只收节点，Ctrl / 多选点击仍可收节点与线路；
-	 * 写了之后框选与 Ctrl / 多选点击统一按这一份过滤（普通单选与接口 select 不受限制）。
+	 * 写了之后框选与 Ctrl / 多选点击统一按这一份过滤（普通单选、toggleSelect 的取消与接口 select 不受限制）。
 	 * 两个端点口径只影响框选，不会因为写进同一份数组就让 Ctrl 点击去猜端点。
 	 * 运行时走 updateOptions({ selectionKinds })。
 	 */
 	selectionKinds?: GisViewSelectionKindsInput
-	/** 框选矩形样式 */
+	/** 框选矩形样式；render: 'div' 时可用 className / borderStyle / radius 整体换外观 */
 	selectionBoxStyle?: GisViewSelectionBoxStyle
+	/**
+	 * 框选结束后是否保留矩形（缺省 false）。保留时在框内按下并拖动会把框内选中的节点整组平移，
+	 * 线路与通道随节点更新；选中集变化、清空或调用 clearSelectionBox() 时自动收起。
+	 * 运行时走 updateOptions({ selectionBoxPersistent })。
+	 */
+	selectionBoxPersistent?: boolean
 	/**
 	 * 选中的要素是否画在所有要素之上（默认 true）：抬层的包括点击 / 拖动 / 待确认合并的节点，
 	 * 以及选中线路所在的整条通道 —— 选中了就一定看得见，与 zIndex 无关；
@@ -6731,6 +7169,12 @@ export interface GisViewOptions {
 	 * 普通线路不受影响；切换走 updateOptions({ channelWaypointDragMode })，下一次拖动生效
 	 */
 	channelWaypointDragMode?: GisViewChannelWaypointDragMode
+	/**
+	 * 隐藏回线时车道怎么排：'preserve'（缺省）保留原来的车道槽位，'center' 让剩余可见回线
+	 * 在整条通道宽度内重新居中。隐藏的通道分组按整组处理。
+	 * 运行时走 updateOptions({ channelHiddenLineLayout })。
+	 */
+	channelHiddenLineLayout?: GisViewChannelHiddenLineLayout
 
 	/**
 	 * 快捷键：框选、多选、加点、复制、粘贴、取消、删除、适应视图都可以在这里改
@@ -6752,7 +7196,9 @@ export interface GisViewOptions {
 	waypointStyle?: GisViewPointStyle
 	/** 拐点被选中时的样式：没有配置（且 defaultHighlight 为 false）时选中不改变外观 */
 	waypointSelectStyle?: GisViewPointStyle
+	/** 相机比例下限（像素 / 世界单位），默认 0.002 */
 	minScale?: number
+	/** 相机比例上限（像素 / 世界单位），默认 1000000000；显式值仍会限制 fitSpacing 能达到的间距 */
 	maxScale?: number
 	/** 适应视图时四周留白（CSS 像素） */
 	fitPadding?: number
@@ -6769,8 +7215,8 @@ export interface GisViewOptions {
 	 */
 	initialView?: GisViewInitialView | null
 	/**
-	 * 适应视图时按可见节点间距兜底（默认关）：true 用 minDistance 24 / maxZoom 不限，
-	 * 对象在 minDistance / maxDistance 中二选一，另可改 maxZoom。只在首次默认适应与 fitView() 生效，
+	 * 适应视图时按可见节点间距兜底（默认关）：true 用精确的 minDistance 24，
+	 * 对象在 minDistance / maxDistance 中二选一。只在首次默认适应与 fitView() 生效，
 	 * 显式 initialView.scale / zoom 优先。
 	 */
 	fitSpacing?: boolean | GisViewFitSpacingOptions
@@ -7848,6 +8294,18 @@ export interface GisViewInstance {
 	/** 现在有哪些扩展图形（按 zIndex、再按加入顺序） */
 	getGraphics(): GisViewGraphic[]
 	updateBackground(background?: GisViewBackground): GisViewInstance
+	/**
+	 * 进入内置背景编辑：在根节点里挂一层编辑覆盖层，移动、四角 / 八向缩放与可选旋转都由组件接管。
+	 * 图片写回 image.corners，GeoJSON 写回 geoJsonStyle.bounds + rotation；其它背景字段原样保留。
+	 * 进入期间 backgroundEditing 自动打开，退出时恢复进入前的值。没有背景时不做任何事并走 onWarning。
+	 */
+	beginBackgroundEdit(options?: GisViewBackgroundEditorOptions): GisViewInstance
+	/** 运行中改编辑器配置或背景几何（center / width / height / angle）；返回实例 */
+	updateBackgroundEdit(patch: GisViewBackgroundEditorPatch): GisViewInstance
+	/** 退出内置背景编辑并移除覆盖层；编辑后的背景保留，backgroundEditing 恢复进入前的值 */
+	endBackgroundEdit(): GisViewInstance
+	/** 当前编辑读数；没有开启编辑器时返回 null */
+	getBackgroundEdit(): GisViewBackgroundEditorState | null
 	/**
 	 * 把当前画面导出成图片（data URL）：画布内容 + DOM 标签合成到一张 2D 画布上。
 	 * 默认按设备像素导出（跟屏幕上一样清晰），也可以给 scale 指定倍率。
@@ -7933,6 +8391,12 @@ export interface GisViewInstance {
 	 * 少于两个可见节点时为 null，全部重合时 nearest 为 null、maxDistance 为 0。
 	 */
 	getPointSpacing(): GisViewPointSpacing
+	/**
+	 * 指定一组节点的整体最近正距离 / 最远距离（CSS 像素，和 fitSpacing 同一套屏幕口径）。
+	 * refs 支持单个或数组、id / 下标 / `{ id }` / `{ index }`；重复引用去重，非法引用忽略。
+	 * 与 getPointSpacing() 不同，被筛选 / 隐藏的显式节点照样参与统计。
+	 */
+	getPointsSpacing(refs: GisViewFeatureRef | GisViewFeatureRef[]): GisViewPointSpacing
 	/** 缩放联动的基准比例（pointZoomScale / lineZoomScale 共用那一份）：缺省是首次适应视图时的 camera.scale */
 	getZoomBaseScale(): number
 	/** 重定缩放联动的基准比例：不传就取当下相机的比例（把现在这一屏当成「原样大小」），之后放大缩小都从它算倍数，返回 this */
@@ -7941,6 +8405,10 @@ export interface GisViewInstance {
 	getIdleTime(): number
 	/** 鹰眼图根节点（没配 minimap 时为 null）：拖动整张图 / 绑定自定义手势时拿它 */
 	getMinimapElement(): HTMLElement | null
+	/** 图例根节点（没配 visualMap 或 enabled: false 时为 null） */
+	getVisualMapElement(): HTMLElement | null
+	/** 当前图例读数：值域、色带与刻度 / 分段；没配时为 null */
+	getVisualMap(): GisViewVisualMapReadout | null
 	/** 鹰眼图自身的倍数：1 是「刚好铺满小图」 */
 	getMinimapZoom(): number
 	/** 设置鹰眼图的倍数（夹在 minimap.minZoom ~ maxZoom 之间），内容重新跟着数据范围居中 */
@@ -8086,7 +8554,7 @@ export interface GisViewInstance {
 	 * `deselect({ type: 'channel', channelId: 'channel-a' })` 取消整条通道的回线。
 	 * 一个目标都不给（不传 / 传 null）等于取消全部（与 selectFeatures(null) 同一件事），
 	 * 传空数组是「没有目标」，什么都不做；认不出来的条目跳过。改变选中集时发
-	 * onSelect 与 onSelectChange（cause: api）。
+	 * onSelect 与 onSelectChange（cause: api）；这一次真的移除了选中项时，点击级联也一起收掉。
 	 */
 	deselect(refs?: GisViewSelectionRefs): GisViewInstance
 	/**
@@ -8118,11 +8586,15 @@ export interface GisViewInstance {
 	getSelectionData(): GisViewSelectionData
 	/**
 	 * 当前点击级联高亮的读数：来源、scope 与亮着的节点 / 线路；没有级联高亮（或功能关着）时是 null。
-	 * 它只读，不改变选中集；点空白处、换数据或关掉 cascadeHighlight 会收掉。
+	 * 它只读，不改变选中集；取消选中、点空白处、换数据或关掉 cascadeHighlight 会收掉。
 	 */
 	getCascadeHighlight(): GisViewCascadeHighlightInfo | null
 	/** 按画布 CSS 像素矩形框选；options.selectionKinds 可临时覆盖全局类型过滤 */
 	selectInBox(box: GisViewRect, options?: GisViewSelectInBoxOptions): GisViewInstance
+	/** 收起当前保留的框选矩形；只动矩形，不改变选中集 */
+	clearSelectionBox(): GisViewInstance
+	/** 当前保留的框选矩形（画布 CSS 像素，已归整为左上角 + 宽高）；没有时返回 null */
+	getSelectionBox(): GisViewRect | null
 	/**
 	 * 开始复制一个节点：给 id / index 就直接出预览（`commit: true` 出预览即落地，`follow: true` 跟随鼠标），
 	 * 不给来源就是「先点按钮再选节点」模式 —— 下一次点中的节点作为来源、复制到它旁边。
@@ -8607,13 +9079,15 @@ export interface GisViewInstance {
 	getPoint(ref: GisViewFeatureRef): GisViewPointInfo | null
 	/**
 	 * 节点解析之后的样式快照（size / symbol / zIndex）：size 与 symbol 取样式链
-	 * （节点自身 > 规则 > pointStyle）定下来的那一份，含 sizeScale、不含悬停 / 选中样式与热力倍率 ——
+	 * （override 规则 > 节点自身 > 普通规则 > pointStyle）定下来的那一份，
+	 * 含 sizeScale、不含悬停 / 选中样式与热力倍率 ——
 	 * 拖拽落点预览拿它核对「预览与落地同一个尺寸」，合并取双方较大值走的也是这一份；下标不存在返回 null
 	 */
 	getPointStyle(index: number): GisViewPointStyleSnapshot | null
 	/**
 	 * 线路解析之后的样式快照（width / color / opacity / zIndex）：width 取样式链
-	 * （线路自身 > 规则 > lineStyle）定下来的原始线宽，不含 lineWidthScale / 缩放联动与热力倍率；
+	 * （override 规则 > 线路自身 > 普通规则 > lineStyle）定下来的原始线宽，
+	 * 不含 lineWidthScale / 缩放联动与热力倍率；
 	 * 下标不存在时返回 null。鹰眼图沿用主图线路宽度时用的就是它。
 	 */
 	getLineStyle(index: number): GisViewLineStyleSnapshot | null
@@ -8819,7 +9293,7 @@ export interface GisViewEngineOptions {
 	pointCluster?: boolean | GisViewPointClusterOptions
 	/** 初始视图：首次拿到数据时相机落在哪里（缺省适应数据范围），结构见 GisViewInitialView */
 	initialView?: GisViewInitialView | null
-	/** 适应视图的节点间距兜底：true 用缺省档，对象可改 minDistance / maxZoom，默认关 */
+	/** 适应视图的节点间距兜底：true 用 minDistance 24，对象在 minDistance / maxDistance 中二选一，默认关 */
 	fitSpacing?: boolean | GisViewFitSpacingOptions
 	/** onStats 的最小间隔（毫秒），默认 250，0 表示每帧都发 */
 	statsInterval?: number
@@ -8829,6 +9303,12 @@ export interface GisViewEngineOptions {
 	gridSize?: number
 	/** 是否绘制网格，**缺省关**（见 GisViewOptions.showGrid） */
 	showGrid?: boolean
+	/** 网架整体显隐，**缺省开**（见 GisViewOptions.networkVisible）：false 时只留背景、网格与自定义 WebGL 层 */
+	networkVisible?: boolean
+	/** 网架整体不透明度（0 ~ 1，缺省 1），在逐要素 opacity 之后相乘；背景不受影响 */
+	networkOpacity?: number
+	/** 背景编辑模式（见 GisViewOptions.backgroundEditing）：true 时屏蔽网架指针与数据快捷键，仅保留滚轮缩放 */
+	backgroundEditing?: boolean
 	/** 写 true 打开拖拽平移 / 滚轮缩放 / 右键回调（= pan / zoom / contextMenu），**缺省关** */
 	interactive?: boolean
 	/** 写 true 打开悬停拾取与点击选中（= hover / select），**缺省关** */
@@ -8862,9 +9342,13 @@ export interface GisViewEngineOptions {
 	boxSelect?: boolean
 	/** 多选开关（**缺省关**）：打开后不用按修饰键，直接单击要素就取反累加（与按住 shortcuts.multiSelect 点击同一套行为） */
 	multiSelect?: boolean
+	/** 再次选中即取消（**缺省关**），语义见 GisViewOptions.toggleSelect */
+	toggleSelect?: boolean
 	/** 框选 / Ctrl 多选允许的要素类型，写法与缺省口径见 GisViewOptions.selectionKinds */
 	selectionKinds?: GisViewSelectionKindsInput
 	selectionBoxStyle?: GisViewSelectionBoxStyle | null
+	/** 框选后保留矩形，并允许拖动矩形平移框内选中节点；缺省 false */
+	selectionBoxPersistent?: boolean
 	/** 选中 / 拖动 / 待确认合并的节点与选中通道是否画在所有要素之上，默认 true */
 	selectionOnTop?: boolean
 	/**
@@ -8875,6 +9359,8 @@ export interface GisViewEngineOptions {
 	channelSelectMode?: GisViewChannelSelectMode
 	/** 分组拐点拖动模式：'parallel'（缺省）/ 'vertex'，见 GisViewOptions.channelWaypointDragMode */
 	channelWaypointDragMode?: GisViewChannelWaypointDragMode
+	/** 隐藏回线后的车道排布，见 GisViewOptions.channelHiddenLineLayout；缺省 preserve */
+	channelHiddenLineLayout?: GisViewChannelHiddenLineLayout
 	/** 线路是否跟随节点，缺省 true；关闭后节点退场时线路 / 通道停在最后一份坐标与解析尺寸 */
 	lineFollowsNode?: boolean
 
@@ -8962,6 +9448,10 @@ export interface GisViewEngine {
 	describeSelection(selection: GisViewFeatureKey[], preferredGroupId?: string | number): GisViewDescribedSelection
 	/** 按画布 CSS 像素矩形框选，返回框内要素 */
 	selectInBox(box: GisViewRect, options?: GisViewSelectInBoxOptions): GisViewPickResult[]
+	/** 收起框选矩形；只动矩形，不改变选中集 */
+	clearSelectionBox(): void
+	/** 当前框选矩形的副本；没有时返回 null */
+	getSelectionBox(): GisViewRect | null
 	/** 拐点增删改，insertIndex 缺省时按直线上离目标最近的线段插入 */
 	insertWaypoint(lineIndex: number, coordinate: GisViewCoordinate, insertIndex?: number): GisViewWaypointPayload | null
 	/** 删除指定线路上的拐点 */
@@ -9091,7 +9581,8 @@ export interface GisViewEngine {
 	getPointRadius(index: number): number
 	/**
 	 * 节点解析之后的样式快照（size / symbol / zIndex）：size 与 symbol 取样式链
-	 * （节点自身 > 规则 > pointStyle）定下来的那一份，不含悬停 / 选中样式与热力倍率 ——
+	 * （override 规则 > 节点自身 > 普通规则 > pointStyle）定下来的那一份，
+	 * 不含悬停 / 选中样式与热力倍率 ——
 	 * 合并节点取双方最大尺寸、图标优先目标用的就是它；下标不存在时返回 null
 	 */
 	getPointStyle(index: number): GisViewPointStyleSnapshot | null