gis-view-webgl2 0.1.12 → 0.1.13

package/dist/index.d.ts

@@ -822,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` 用全局那一份（全局没配就用缺省值），
@@ -1259,6 +1478,7 @@ export type GisViewCascadeHighlightScope = 'points' | 'both'
 /**
  * 点击级联高亮：点击节点时高亮它和直接相连的节点 / 线路，点击线路或通道时高亮这条线的两端。
  * 它与选中集完全分开 —— 不写 selectionKeys、不改 selected，样式也不走悬停 / 选中那一套。
+ * 通过 toggleSelect / Ctrl 取反 / deselect / selectFeatures 的 remove 或清空取消选中时，级联会一起收掉。
  * true 等价于 { enabled: true, scope: 'both' }；不配或 false 都是关闭。
  */
 export interface GisViewCascadeHighlightOptions {
@@ -6329,6 +6549,7 @@ export interface GisViewOptionChangePayload {
 		channels: boolean
 		filter: boolean
 		minimap: boolean
+		visualMap: boolean
 		features: boolean
 		quality: boolean
 		history: boolean
@@ -6708,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
 	/**
 	 * 节点标签：配了就按这个配置渲染，内容、位置、数量与显隐都可配。
 	 * 写数组就是「一个节点上显示多条标签」：数组里每一条各自有内容 / 位置 / 样式 / 显隐，
@@ -6786,7 +7015,7 @@ export interface GisViewOptions {
 	/**
 	 * 点击级联高亮（默认关）：点击节点时亮起它和直接相连的节点；scope 为 both 时连线路一起亮，
 	 * 点击线路 / 通道回线时亮起两端节点。它不进选中集，样式与悬停 / 选中分开配置，
-	 * 当前亮起的清单用 getCascadeHighlight() 读。
+	 * 当前亮起的清单用 getCascadeHighlight() 读；取消选中时同步收掉，不会留下级联残影。
 	 */
 	cascadeHighlight?: GisViewCascadeHighlightInput
 	/** 没有配置状态样式时，是否仍用尺寸 / 宽度增幅画出内置强调；默认 false（不配样式就不改变外观） */
@@ -6887,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。
@@ -6898,7 +7138,7 @@ export interface GisViewOptions {
 	 * 另有 'lineEndpoints' / 'channelEndpoints' 只在框选时要求线路 / 通道两端节点都在框内；
 	 * 可写数组任意组合，'all' / true 全开，false / null 全关。
 	 * **不写时保留旧行为**：框选只收节点，Ctrl / 多选点击仍可收节点与线路；
-	 * 写了之后框选与 Ctrl / 多选点击统一按这一份过滤（普通单选与接口 select 不受限制）。
+	 * 写了之后框选与 Ctrl / 多选点击统一按这一份过滤（普通单选、toggleSelect 的取消与接口 select 不受限制）。
 	 * 两个端点口径只影响框选，不会因为写进同一份数组就让 Ctrl 点击去猜端点。
 	 * 运行时走 updateOptions({ selectionKinds })。
 	 */
@@ -8165,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 之间），内容重新跟着数据范围居中 */
@@ -8310,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
 	/**
@@ -8342,7 +8586,7 @@ export interface GisViewInstance {
 	getSelectionData(): GisViewSelectionData
 	/**
 	 * 当前点击级联高亮的读数：来源、scope 与亮着的节点 / 线路；没有级联高亮（或功能关着）时是 null。
-	 * 它只读，不改变选中集；点空白处、换数据或关掉 cascadeHighlight 会收掉。
+	 * 它只读，不改变选中集；取消选中、点空白处、换数据或关掉 cascadeHighlight 会收掉。
 	 */
 	getCascadeHighlight(): GisViewCascadeHighlightInfo | null
 	/** 按画布 CSS 像素矩形框选；options.selectionKinds 可临时覆盖全局类型过滤 */
@@ -9098,6 +9342,8 @@ export interface GisViewEngineOptions {
 	boxSelect?: boolean
 	/** 多选开关（**缺省关**）：打开后不用按修饰键，直接单击要素就取反累加（与按住 shortcuts.multiSelect 点击同一套行为） */
 	multiSelect?: boolean
+	/** 再次选中即取消（**缺省关**），语义见 GisViewOptions.toggleSelect */
+	toggleSelect?: boolean
 	/** 框选 / Ctrl 多选允许的要素类型，写法与缺省口径见 GisViewOptions.selectionKinds */
 	selectionKinds?: GisViewSelectionKindsInput
 	selectionBoxStyle?: GisViewSelectionBoxStyle | null