gis-view-webgl2 0.1.11 → 0.1.13

package/docs/demos/gis-view-demo/panels/StylePanels.vue

@@ -6,7 +6,7 @@ const {
 	perItemFollow, perItemOff, applyPrebake, applyPrebakeExact, runPrebakeNow, clearPrebake, building, activePanel,
 	pointSize, lineWidth, lineTypeMode, dcLineMark, dcLineAnchor, dcLineParallel, lineDirectionMark,
 	lineDirectionCount, lineDirectionReverse, dcLineButtonText, cursorMode, pointSizeScale, lineWidthScale,
-	pointZoomScale, lineZoomScale, fitSpacing, fitSpacingMode, fitSpacingMinDistance, fitSpacingMaxDistance, fitSpacingMaxZoom, pointSpacingReadout, zoomBaseReadout,
+	pointZoomScale, lineZoomScale, fitSpacing, fitSpacingMode, fitSpacingMinDistance, fitSpacingMaxDistance, pointSpacingReadout, zoomBaseReadout,
 	pointShape, symbolByStationType, symbolIconMode, symbolStrokeWidth, pointLayering, lineLayering, perPointStyle,
 	perPointSymbol, applyRules, showLabels, labelPosition, labelMaxCount, labelVoltageScope, LABEL_VOLTAGE_SCOPES,
 	labelAvoidOverlap, labelScanMode, labelOptimize, labelTemplate, labelHtml, labelBackground, labelColor,
@@ -21,7 +21,9 @@ const {
 	heatmapDensityStyle, heatmapDensityLayer, heatmapDensityLevels, heatmapDensityRadius, heatmapDensityThreshold,
 	heatmapDensityCore, heatmapDensityGamma, heatmapDensityWeight, heatmapDensityOpacity, heatmapGlow,
 	heatmapGlowStrength, heatmapGlowLine, heatmapGlowPoint, heatmapGlowBlend, heatmapOpacityMin, heatmapOpacityMax,
-	heatmapMinimap, heatmapFieldStats, applyZoomBase, labelEditId, newLabelPosition, newLabelPositions,
+	heatmapMinimap, heatmapFieldStats, visualMapEnabled, visualMapType, visualMapInteractive, visualMapCustom,
+	visualMapOutOfRange, VISUAL_MAP_OUT_OF_RANGE_MODES,
+	visualMapReadout, visualMapLastChange, applyZoomBase, labelEditId, newLabelPosition, newLabelPositions,
 	labelEditContent, labelEditFontSize, labelEditColor, labelEditReadout, labelStateReadout, applyLabelEdit,
 	resetLabelEdit, resetAllLabels, labelRows, labelListReadout, labelRoundTripReadout, pickLabelRow, addLabelHere,
 	removeLabelHere, seedInitialLabels, roundTripLabels, saveLabelStates, restoreLabelStates, rerollHeatData,
@@ -33,6 +35,25 @@ const {
 				<div v-show="activePanel === 'style-heat'" class="demo-panel-body">
 				<div class="demo-controls">
 				<label><input v-model="heatmapEnabled" type="checkbox" /> 启用热力图</label>
+				<label><input v-model="visualMapEnabled" type="checkbox" :disabled="!heatmapEnabled" /> 显示图例（visualMap）</label>
+				<label class="demo-slider">
+					图例形态
+					<select v-model="visualMapType" :disabled="!heatmapEnabled || !visualMapEnabled">
+						<option value="ruler">连续尺 ruler</option>
+						<option value="piecewise">分段色块 piecewise</option>
+					</select>
+				</label>
+				<label><input v-model="visualMapInteractive" type="checkbox" :disabled="!heatmapEnabled || !visualMapEnabled" /> 图例可交互（点选 / 拖动区间）</label>
+				<label><input v-model="visualMapCustom" type="checkbox" :disabled="!heatmapEnabled || !visualMapEnabled" /> 完全自定义渲染</label>
+				<label class="demo-slider">
+					落选值
+					<select v-model="visualMapOutOfRange" :disabled="!heatmapEnabled || !visualMapEnabled">
+						<option v-for="item in VISUAL_MAP_OUT_OF_RANGE_MODES" :key="item.value" :value="item.value">{{ item.label }}</option>
+					</select>
+				</label>
+				<span v-if="heatmapEnabled && visualMapEnabled" class="demo-control-hint">
+					{{ visualMapReadout || (visualMapCustom ? '自定义图例：点色块按钮调用 context.setSelection / setRange；不写 target 时节点、独立线路与通道一起按 max_loading_rate 门控' : '点分段或拖动区间：不写 target 时三类一起门控；落选值默认隐藏对应网架，也可切成只退热力或仅 onChange') }}<template v-if="visualMapLastChange"> · {{ visualMapLastChange }}</template>
+				</span>
 				<label class="demo-slider">
 					作用对象
 					<select v-model="heatmapTarget" :disabled="!heatmapEnabled">
@@ -162,7 +183,7 @@ const {
 				<span class="demo-control-hint">{{ heatmapFieldStats }}</span>
 				</div>
 				<div class="demo-controls">
-				<details class="demo-hint-more"><summary>说明</summary><span class="demo-control-hint">热力图按 field 取数（这里固定 max_loading_rate）到 colors 色带上取颜色，再按 width / size 的区间用同一个比例缩放线宽与节点尺寸；优先级是「状态样式 &gt; 热力图 &gt; 要素自身 &gt; 规则 &gt; style &gt; 默认」，逐要素可以用 heatmap: false 排除、或写对象换字段 / 值域。回线自己带 max_loading_rate 就按自己的上色；自己没这个字段时才回落到所属通道的值（作用对象里要勾上通道），两边都没有就按「缺值」处理 —— 合成数据的通道与回线都带值，切「只按通道自己的值上色」就能对比「每一回各自的颜色」。节点与线路共用同一条色带：合成数据的节点与线路都按同一份「热区场」取值（几团热点），切「只按节点上色」看节点自己的颜色、切「节点 + 线路 + 通道」看两层叠在一起的效果。new.json 里线路这一列恒为 1.5、节点根本没有这一列，真实数据看不出渐变 —— 想看效果就切到「合成数据」，或在任意数据集上点上面的「重新随机」现生成一份（样例数据的线路是按序号派生的演示值）。这里的每一项都是 updateOptions({ heatmap })，数据与拾取都不动</span></details>
+				<details class="demo-hint-more"><summary>说明</summary><span class="demo-control-hint">热力图按 field 取数（这里固定 max_loading_rate）到 colors 色带上取颜色，再按 width / size 的区间用同一个比例缩放线宽与节点尺寸；优先级是「状态样式 &gt; 热力图 &gt; override 规则 &gt; 要素自身 &gt; 普通规则 &gt; style &gt; 默认」，逐要素可以用 heatmap: false 排除、或写对象换字段 / 值域。回线自己带 max_loading_rate 就按自己的上色；自己没这个字段时才回落到所属通道的值（作用对象里要勾上通道），两边都没有就按「缺值」处理 —— 合成数据的通道与回线都带值，切「只按通道自己的值上色」就能对比「每一回各自的颜色」。节点与线路共用同一条色带：合成数据的节点与线路都按同一份「热区场」取值（几团热点），切「只按节点上色」看节点自己的颜色、切「节点 + 线路 + 通道」看两层叠在一起的效果。new.json 里线路这一列恒为 1.5、节点根本没有这一列，真实数据看不出渐变 —— 想看效果就切到「合成数据」，或在任意数据集上点上面的「重新随机」现生成一份（样例数据的线路是按序号派生的演示值）。这里的每一项都是 updateOptions({ heatmap })，数据与拾取都不动</span></details>
 				</div>
 				</div>
 
@@ -271,11 +292,6 @@ const {
 					<input v-model.number="fitSpacingMaxDistance" type="number" min="1" step="1" :disabled="!fitSpacing" />
 					<span>{{ fitSpacingMaxDistance }}px</span>
 				</label>
-				<label class="demo-slider">
-					最大放大
-					<input v-model.number="fitSpacingMaxZoom" type="number" min="0" step="1" :disabled="!fitSpacing" />
-					<span>{{ fitSpacingMaxZoom > 0 ? `×${fitSpacingMaxZoom}` : '不限' }}</span>
-				</label>
 				<button type="button" @click="applyZoomBase()">以当前比例为基准</button>
 				<span class="demo-control-hint">放大与跟随缩放是两个系数：滚轮缩放时再乘一次联动系数（基准为首次适应视图的比例）；「适应节点间距」的最小 / 最大中心距二选一，首次适应与 fitView 会按所选屏幕距离调整比例，远处孤立点允许落到视口外{{ pointSpacingReadout ? ` · ${pointSpacingReadout}` : '' }}{{ zoomBaseReadout ? ` · ${zoomBaseReadout}` : '' }}</span>
 			</div>

package/docs/demos/gis-view-demo/panels/ViewPanels.vue

@@ -5,7 +5,9 @@ const {
 	backgroundMode, backgroundOpacity, BACKGROUND_SOURCES, backgroundSource, backgroundImageFit,
 	backgroundImageCorners, provinceAspectScale, provincePalette, provinceLabelShow, provinceLabelSize,
 	provinceLabelColor, provinceLoading, INITIAL_VIEW_MODES, initialViewMode, initialZoom, initialCenterText,
-	initialViewReadout, draggable, liveDrag, liveDragHint, clickable, boxSelect, multiSelect, selectionBoxMode,
+	initialViewReadout, draggable, liveDrag, liveDragHint, clickable, boxSelect, selectionBoxPersistent,
+	selectionBoxRender, selectionBoxBorderStyle, selectionBoxRadius, selectionBoxUseClassName, selectionBoxReadout,
+	readSelectionBox, clearRetainedSelectionBox, multiSelect, toggleSelect, selectionBoxMode,
 	SHORTCUT_MODES, shortcutBoxSelect, shortcutMultiSelect, shortcutAddWaypoint, shortcutDuplicate,
 	shortcutReadout, COPY_OFFSETS, copyEnabled, copyOffsetMode, mergeEnabled, mergeTrigger, MERGE_TRIGGERS,
 	mergeDistance, MERGE_CONFIRM_MODES, mergeConfirmMode, mergeChannelGroups, selectionOnTop, copyRollback,
@@ -191,6 +193,7 @@ const {
 				<label><input v-model="clickable" type="checkbox" /> 可点击</label>
 				<label><input v-model="boxSelect" type="checkbox" /> 框选</label>
 				<label><input v-model="multiSelect" type="checkbox" /> 点击多选（multiSelect：不用按修饰键，单击即取反累加）</label>
+				<label><input v-model="toggleSelect" type="checkbox" /> 再次选中即取消（toggleSelect：Ctrl 选中后也可普通点击取消）</label>
 				<label><input v-model="waypointEditable" type="checkbox" /> 可编辑拐点</label>
 				<label><input v-model="waypointAlways" type="checkbox" /> 拐点始终显示</label>
 				<label><input v-model="hoverHighlight" type="checkbox" /> 悬停强调</label>
@@ -370,14 +373,41 @@ const {
 				</label>
 				<label class="demo-slider">
 					框选矩形
-					<select v-model="selectionBoxMode">
+					<select v-model="selectionBoxMode" data-demo="selection-box-mode">
 						<option value="default">组件默认（蓝）</option>
 						<option value="amber">琥珀色 · 粗边框</option>
 						<option value="pink">粉色 · 半透明填充</option>
 						<option value="line">只描边（背景全透明）</option>
 					</select>
 				</label>
-				<span class="demo-control-hint">Ctrl + 点击 / Shift + 拖动分别走多选与框选样式；节点或线路自己配了样式时以自身的为准；「框选矩形」换的是框本身（options.selectionBoxStyle：fill / fillOpacity / stroke / strokeWidth）</span>
+				<label class="demo-slider">
+					矩形渲染
+					<select v-model="selectionBoxRender" data-demo="selection-box-render">
+						<option value="canvas">canvas（WebGL 实线直角）</option>
+						<option value="div">div（DOM，可线型 / 圆角 / 类名）</option>
+					</select>
+				</label>
+				<label><input v-model="selectionBoxPersistent" data-demo="selection-box-persistent" type="checkbox" /> 框选结束后保留矩形（框内拖动整组平移）</label>
+				<template v-if="selectionBoxRender === 'div'">
+					<label class="demo-slider">
+					边框线型
+						<select v-model="selectionBoxBorderStyle" data-demo="selection-box-border-style">
+							<option value="solid">实线</option>
+							<option value="dashed">虚线</option>
+							<option value="dotted">点线</option>
+						</select>
+					</label>
+					<label class="demo-slider">
+					圆角
+						<input v-model.number="selectionBoxRadius" data-demo="selection-box-radius" type="range" min="0" max="20" step="1" />
+						<span>{{ selectionBoxRadius }} px</span>
+					</label>
+					<label><input v-model="selectionBoxUseClassName" data-demo="selection-box-class-name" type="checkbox" /> 挂 demo-retained-box 类名（标签 + 阴影）</label>
+				</template>
+				<button type="button" data-demo="selection-box-read" @click="readSelectionBox()">读取 getSelectionBox()</button>
+				<button type="button" data-demo="selection-box-clear" @click="clearRetainedSelectionBox()">收起保留框 clearSelectionBox()</button>
+				<span class="demo-control-hint" data-demo="selection-box-readout">{{ selectionBoxReadout }}</span>
+				<span class="demo-control-hint">Shift + 拖动框选（跟随快捷键面板的「框选」档）后会保留矩形；打开「拖拽节点」时，在框内按住并拖动即可把选中的节点整组平移。节点或线路自己配了样式时以自身的为准；selectionBoxStyle 的 fill / fillOpacity / stroke / strokeWidth 管颜色与边框，div 档另有 borderStyle / radius / className。</span>
 			</div>
 
 				</div>

package/docs/demos/gis-view-demo/useGisViewDemo.js

@@ -211,7 +211,7 @@ export const useGisViewDemo = () => {
 	/**
 	 * 通道两端节点的样式：只把那一圈描边换成亮粉色做标记（节点都是白底 + 电压色描边，末端几个换个颜色才认得出；
 	 * 不能用琥珀 / 金这类颜色，525kV 那一档的描边就是琥珀色）——
-	 * 大小仍旧由电压分档决定，同一个电压等级的节点大小完全一致（点自身字段优先级最高，
+	 * 大小仍旧由电压分档决定，同一个电压等级的节点大小完全一致（普通规则只低于点自身字段、高于 pointStyle；
 	 * 这里多写一个 color 就会把白底顶掉，所以标记只动描边这一层）
 	 */
 	const ANCHOR_POINT_STYLE = {
@@ -320,13 +320,19 @@ export const useGisViewDemo = () => {
 				continue
 			}
 			const first = members[0]
+			// 通道自己也要有值：只开 channel 目标时，回线取的是这个字段，network 门控也按它判断
+			const maxLoadingRate = members.reduce((max, member) => {
+				const value = Number(member.max_loading_rate)
+				return Number.isFinite(value) ? Math.max(max, value) : max
+			}, Number.NEGATIVE_INFINITY)
 			channels.push({
 				id: channelId,
 				name: first.channel_name ?? channelId,
 				lineIds: members.map(member => member.line_id),
 				from: first.from_station,
 				to: first.to_station,
-				path: (first.coords_list ?? []).slice(1, -1).map(coordinate => [Number(coordinate[0]) || 0, Number(coordinate[1]) || 0])
+				path: (first.coords_list ?? []).slice(1, -1).map(coordinate => [Number(coordinate[0]) || 0, Number(coordinate[1]) || 0]),
+				...(Number.isFinite(maxLoadingRate) ? { max_loading_rate: maxLoadingRate } : {})
 			})
 		}
 		return { points, lines, channels }
@@ -387,13 +393,19 @@ export const useGisViewDemo = () => {
 					max_loading_rate: member.max_loading_rate
 				})
 			})
+			// 通道目标同样要能从自己的字段取到值；取成员最大值，和 new.json 里恒定的 1.5 保持同一档
+			const maxLoadingRate = members.reduce((max, member) => {
+				const value = Number(member.max_loading_rate)
+				return Number.isFinite(value) ? Math.max(max, value) : max
+			}, Number.NEGATIVE_INFINITY)
 			channels.push({
 				id: channel.channel_name,
 				name: channel.channel_name,
 				lineIds,
 				from,
 				to,
-				path: (channel.coords ?? []).slice(1, -1).map(coordinate => [Number(coordinate[0]) || 0, Number(coordinate[1]) || 0])
+				path: (channel.coords ?? []).slice(1, -1).map(coordinate => [Number(coordinate[0]) || 0, Number(coordinate[1]) || 0]),
+				...(Number.isFinite(maxLoadingRate) ? { max_loading_rate: maxLoadingRate } : {})
 			})
 		}
 		return { points, lines, channels }
@@ -587,6 +599,8 @@ export const useGisViewDemo = () => {
 	 */
 	const handleSelectChange = payload => {
 		syncSelectionFromView()
+		// 框选结束后保留框已经建立；这里顺手刷新读数，面板上的坐标不用再点一次按钮才会变。
+		readSelectionBox()
 		const ids = payload.ids.slice(0, 2).map(String).join(' / ')
 		selectChangeLabel.value = `${payload.cause} · ${payload.count} 个${payload.ids.length ? ` · ${ids}${payload.ids.length > 2 ? ' …' : ''}` : ''}`
 	}
@@ -1684,8 +1698,19 @@ export const useGisViewDemo = () => {
 		: '停手更新：拖动期间线路停在原处，松开指针后一次性跟上（大场景拖动更省）'))
 	const clickable = ref(true)
 	const boxSelect = ref(true)
+	/** 框选结束后保留矩形：框内按下并拖动会把选中的节点整组平移（线路 / 通道跟着走） */
+	const selectionBoxPersistent = ref(true)
+	/** 保留框渲染在 WebGL 还是画布上方的 DOM：div 模式才能演示线型 / 圆角 / className */
+	const selectionBoxRender = ref('div')
+	const selectionBoxBorderStyle = ref('dashed')
+	const selectionBoxRadius = ref(8)
+	const selectionBoxUseClassName = ref(true)
+	const selectionBoxReadout = ref('getSelectionBox()：—')
+	const SELECTION_BOX_CLASS = 'demo-retained-box'
 	/** 多选开关：打开后不用按修饰键，普通单击就是取反累加（走 multiSelectStyle） */
 	const multiSelect = ref(false)
+	/** 再次选中即取消：普通点击已选要素取消；Ctrl 先选中后再普通点击也会取消 */
+	const toggleSelect = ref(false)
 	/**
 	 * 框选矩形（Ctrl + 拖动时画的那个框）的样式：颜色、背景、边框都在 options.selectionBoxStyle 里配，
 	 * 与选中样式是两回事；这里给几档预设方便对比，default 就是组件自带的那份蓝。
@@ -1697,7 +1722,35 @@ export const useGisViewDemo = () => {
 		pink: { fill: '#ff9ff3', fillOpacity: 0.24, stroke: '#e056a0', strokeWidth: 1 },
 		line: { fill: '#2f6fd0', fillOpacity: 0, stroke: '#2f6fd0', strokeWidth: 1 }
 	}
-	const buildSelectionBoxStyle = () => SELECTION_BOX_STYLES[selectionBoxMode.value]
+	/**
+	 * 框的样式分两层：上面的预设只管颜色 / 填充 / 边框宽；render 与 DOM 专属项叠在后面。
+	 * className 只在 demo 里挂一个可见的标签与阴影，证明整块外观都能由使用方接管。
+	 */
+	const buildSelectionBoxStyle = () => {
+		const base = SELECTION_BOX_STYLES[selectionBoxMode.value] ?? {}
+		return {
+			...base,
+			render: selectionBoxRender.value,
+			...(selectionBoxRender.value === 'div'
+				? {
+					className: selectionBoxUseClassName.value ? SELECTION_BOX_CLASS : undefined,
+					borderStyle: selectionBoxBorderStyle.value,
+					radius: selectionBoxRadius.value
+				}
+				: {})
+		}
+	}
+	const readSelectionBox = () => {
+		const box = viewRef.value?.getSelectionBox() ?? null
+		selectionBoxReadout.value = box
+			? `getSelectionBox()：x ${box.x.toFixed(1)} · y ${box.y.toFixed(1)} · ${box.width.toFixed(1)} × ${box.height.toFixed(1)}`
+			: 'getSelectionBox()：null（还没有保留框；Shift + 拖动框选一批节点）'
+	}
+	const clearRetainedSelectionBox = () => {
+		viewRef.value?.clearSelectionBox()
+		readSelectionBox()
+		writeLastEvent('clearSelectionBox()：保留框已收起，选中集不变')
+	}
 	/**
 	 * 快捷键：组件所有快捷键都能改（options.shortcuts），这里挑「按住某键再操作」的四个动作做下拉。
 	 * 换成 Shift / Alt 之后，光标变体（cursorStyle.ctrl 与逐要素 ctrlCursor）也跟着新的修饰键走 ——
@@ -1990,7 +2043,6 @@ export const useGisViewDemo = () => {
 	const fitSpacingMode = ref('min')
 	const fitSpacingMinDistance = ref(24)
 	const fitSpacingMaxDistance = ref(480)
-	const fitSpacingMaxZoom = ref(0)
 	const pointSpacingReadout = ref('')
 	const zoomBaseReadout = ref('')
 	/** fitSpacing 只发送当前选中的距离模式，避免 minDistance 与 maxDistance 同时出现 */
@@ -1998,10 +2050,9 @@ export const useGisViewDemo = () => {
 		if (!fitSpacing.value) {
 			return false
 		}
-		const maxZoom = fitSpacingMaxZoom.value
 		return fitSpacingMode.value === 'max'
-			? { maxDistance: fitSpacingMaxDistance.value, maxZoom }
-			: { minDistance: fitSpacingMinDistance.value, maxZoom }
+			? { maxDistance: fitSpacingMaxDistance.value }
+			: { minDistance: fitSpacingMinDistance.value }
 	}
 	/** 节点形状：auto 用数据 / 规则自带的符号，其余把全部节点改成内置的圆或正方形 */
 	const pointShape = ref('auto')
@@ -2032,13 +2083,13 @@ export const useGisViewDemo = () => {
 	const lineLayering = ref(true)
 	/**
 	 * 逐点样式（默认关）：勾上之后每 43 个节点自带 color / size（就是前面那个金色节点），
-	 * 演示「节点自身字段优先于批量规则与整体配置」——同电压等级的节点这时会看起来不一样。
+	 * 演示「节点自身字段高于普通规则与整体配置（override 规则除外）」——同电压等级的节点这时会看起来不一样。
 	 */
 	const perPointStyle = ref(false)
 	/**
 	 * 逐点符号（默认关）：勾上之后每 24 个节点自带一个 symbol（琥珀色圆角方块），
 	 * 演示「单个节点可以单独配置符号」——它连批量规则都盖得住：勾上「节点形状」把整层换成圆 / 方，
-	 * 这几个节点还是它们自己的样子（点自身字段 > 规则 > pointStyle 这条链的最后一环）。
+	 * 这几个节点还是它们自己的样子（普通规则高于 pointStyle，但低于点自身字段；override 规则才会压过逐点值）。
 	 */
 	const perPointSymbol = ref(false)
 	/** 逐点符号用的样式：颜色、形状、圆角、描边都写在节点自己身上（描边用深色，白底上看不见白边） */
@@ -2197,7 +2248,7 @@ export const useGisViewDemo = () => {
 	/**
 	 * 点的批量样式规则：vn_kv 决定大小与描边色（填充固定白色），符号走 gisStyle.js 的类型表
 	 * （station 圆，其余类型都用 test.js 的 SVG 路径 —— 方框里画线那种）。
-	 * 规则按顺序命中，后命中的覆盖前面的；点自身写了的字段始终优先（勾上面板上的「逐点样式」会出现几个自带走色的金色节点，用来看这一层优先于规则）。
+	 * 规则按顺序命中，后命中的覆盖前面的；点自身写了的字段优先于普通规则，单条规则写 override: true 后才会压过它（勾上面板上的「逐点样式」会出现几个自带走色的金色节点，用来看这一层优先于普通规则）。
 	 */
 	const buildPointRules = () => [
 		// 电压分档：阈值与 getGisStyle 完全一致，节点半径与描边粗细都取它的宽度分档（1 / 2 / 3 / 4 / 5），
@@ -3729,6 +3780,19 @@ export const useGisViewDemo = () => {
 	const heatmapOpacityMax = ref(1)
 	/** 鹰眼图要不要跟着上色：勾着（缺省）就沿用主图那一份，勾掉就只给小图关 */
 	const heatmapMinimap = ref(true)
+	/** 内置图例：默认关，开启后跟随热力图的字段、值域与色带；类型可切连续尺 / 分段色块 */
+	const visualMapEnabled = ref(false)
+	const visualMapType = ref('ruler')
+	const visualMapInteractive = ref(true)
+	const visualMapCustom = ref(false)
+	const visualMapOutOfRange = ref('network')
+	const VISUAL_MAP_OUT_OF_RANGE_MODES = [
+		{ value: 'heatmap', label: '退出热力（网架恢复普通样式）' },
+		{ value: 'network', label: '隐藏对应网架' },
+		{ value: 'none', label: '保持原样（仅 onChange）' }
+	]
+	const visualMapReadout = ref('')
+	const visualMapLastChange = ref('')
 	/** 当前数据里 max_loading_rate 的读数：直接说明这一份数据「看不看得出渐变」，节点与线路分开报 */
 	const heatmapFieldStats = computed(() => {
 		const scan = (items) => {
@@ -3820,6 +3884,131 @@ export const useGisViewDemo = () => {
 				: false
 		}
 	}
+	/**
+	 * 图例配置：只演示「跟随热力图」这一种用法，target / field / domain / colors / opacity
+	 * 全部留空，由组件从当前 heatmap 继承。不写 target 时展示值域取有数据的第一类，
+	 * 选区仍门控全部启用目标；热力图关掉时图例也一并关掉，避免留下一条孤立的色带。
+	 */
+	const visualMapNumberText = (value) => {
+		const number = Number(value)
+		if (!Number.isFinite(number)) {
+			return '—'
+		}
+		return String(Number(number.toFixed(2)))
+	}
+	const handleVisualMapChange = (payload) => {
+		visualMapReadout.value = payload.type === 'piecewise'
+			? `分段：选中 ${payload.selected.length} 段${payload.selected.length ? `（${payload.selected.join(' / ')}）` : ''}`
+			: payload.range
+				? `区间：${visualMapNumberText(payload.range[0])} ~ ${visualMapNumberText(payload.range[1])}`
+				: '区间：未启用'
+		visualMapLastChange.value = `${payload.source} / ${payload.reason}${payload.originalEvent ? ` / ${payload.originalEvent.type}` : ''}`
+	}
+	/** 自定义渲染：图例选区仍会门控全部热力作用目标；额外筛选等业务联动再由 onChange 决定 */
+	const renderVisualMapCustom = (context) => {
+		const wrapper = document.createElement('div')
+		wrapper.className = 'demo-visual-map-custom'
+		const readout = document.createElement('span')
+		readout.className = 'demo-visual-map-custom__readout'
+		const actions = document.createElement('div')
+		actions.className = 'demo-visual-map-custom__actions'
+		const active = new Set(context.selected)
+		let currentRange = context.range ? [...context.range] : null
+		const syncReadout = () => {
+			readout.textContent = context.type === 'piecewise'
+				? `已选 ${active.size} 段`
+				: currentRange
+					? `${context.formatValue(currentRange[0])} ~ ${context.formatValue(currentRange[1])}`
+					: '区间未启用'
+		}
+		if (context.type === 'piecewise') {
+			const buttons = []
+			for (let index = 0; index < context.pieces.length; index += 1) {
+				const piece = context.pieces[index]
+				const button = document.createElement('button')
+				button.type = 'button'
+				button.className = 'demo-visual-map-custom__piece'
+				button.setAttribute('aria-pressed', active.has(index) ? 'true' : 'false')
+				const swatch = document.createElement('span')
+				swatch.className = 'demo-visual-map-custom__swatch'
+				swatch.style.background = piece.color
+				button.append(swatch, document.createTextNode(piece.label))
+				button.addEventListener('click', () => {
+					if (active.has(index)) {
+						active.delete(index)
+					}
+					else {
+						active.add(index)
+					}
+					const changed = context.setSelection([...active])
+					if (!changed) {
+						return
+					}
+					for (const [buttonIndex, item] of buttons) {
+						item.setAttribute('aria-pressed', active.has(buttonIndex) ? 'true' : 'false')
+					}
+					syncReadout()
+				})
+				buttons.push([index, button])
+				actions.append(button)
+			}
+		}
+		else {
+			const low = Math.min(context.domain[0], context.domain[1])
+			const high = Math.max(context.domain[0], context.domain[1])
+			const span = high - low
+			const presets = [
+				{ label: '低段', range: [low, low + span * 0.34] },
+				{ label: '中段', range: [low + span * 0.34, low + span * 0.67] },
+				{ label: '高段', range: [low + span * 0.67, high] },
+				{ label: '全量', range: [low, high] }
+			]
+			for (const preset of presets) {
+				const button = document.createElement('button')
+				button.type = 'button'
+				button.className = 'demo-visual-map-custom__piece'
+				button.textContent = preset.label
+				button.addEventListener('click', () => {
+					if (context.setRange(preset.range)) {
+						currentRange = [...preset.range]
+						syncReadout()
+					}
+				})
+				actions.append(button)
+			}
+			const reset = document.createElement('button')
+			reset.type = 'button'
+			reset.className = 'demo-visual-map-custom__piece'
+			reset.textContent = '恢复全量'
+			reset.addEventListener('click', () => {
+				if (context.clearSelection()) {
+					currentRange = [low, high]
+					syncReadout()
+				}
+			})
+			actions.append(reset)
+		}
+		syncReadout()
+		wrapper.append(readout, actions)
+		return wrapper
+	}
+	const buildVisualMapOptions = () => {
+		if (!heatmapEnabled.value || !visualMapEnabled.value) {
+			return null
+		}
+		return {
+			type: visualMapType.value,
+			title: 'max_loading_rate',
+			position: 'bottom-left',
+			tickCount: 5,
+			interactive: visualMapInteractive.value,
+			selectedMode: visualMapType.value === 'piecewise' ? 'multiple' : false,
+			calculable: visualMapType.value === 'ruler' && visualMapInteractive.value,
+			outOfRange: visualMapOutOfRange.value,
+			render: visualMapCustom.value ? renderVisualMapCustom : undefined,
+			onChange: handleVisualMapChange
+		}
+	}
 	/** 可见节点数：标签最多也就渲染这么多，面板上给个读数 */
 	const syncVisibleCount = () => {
 		visiblePointCount.value = viewRef.value?.listPoints({ visibleOnly: true }).length ?? 0
@@ -4079,18 +4268,18 @@ export const useGisViewDemo = () => {
 	/**
 	 * 缩放限制（minScale / maxScale）：相机比例的单位是「像素 / 世界单位」，
 	 * 滚轮、双击放大与程序化的 setCamera / zoomTo / zoomBy 都会被夹在这两条线之间；
-	 * 缺省 0.002 ~ 20000 等于不限制（两个数字就是组件缺省值，这里原样摆出来做对照）。
+	 * 缺省 0.002 ~ 1000000000 覆盖经纬度这类小量纲数据（两个数字就是组件缺省值，这里原样摆出来做对照）。
 	 */
 	const minScale = ref(0.002)
-	const maxScale = ref(20000)
-	const scaleLimitReadout = ref('当前未限制（组件缺省 0.002 ~ 20000 px/单位）')
+	const maxScale = ref(1000000000)
+	const scaleLimitReadout = ref('当前未限制（组件缺省 0.002 ~ 1000000000 px/单位）')
 	/** 面板读数：当前比例 + 限制区间（区间等于缺省时明说「未限制」） */
 	const syncScaleLimitReadout = () => {
 		const view = viewRef.value
 		if (!view) {
 			return
 		}
-		const limited = minScale.value > 0.0025 || maxScale.value < 19999
+		const limited = minScale.value > 0.0025 || maxScale.value < 999999999
 		scaleLimitReadout.value = `当前 ${view.getCamera().scale.toPrecision(4)} px/单位 · 限制 ${minScale.value} ~ ${maxScale.value}${limited ? '' : '（等于不限制）'}`
 	}
 	/** 把面板上的两条线写进组件（updateOptions），并立刻把当前相机夹回区间内 */
@@ -4122,7 +4311,7 @@ export const useGisViewDemo = () => {
 	/** 解除限制：回到组件缺省的两条线 */
 	const clearScaleLimits = () => {
 		minScale.value = 0.002
-		maxScale.value = 20000
+		maxScale.value = 1000000000
 		applyScaleLimits()
 	}
 	/** 撞一下上下限：喂一个远超区间的比例，相机被夹到哪里由读数说 */
@@ -4215,7 +4404,10 @@ export const useGisViewDemo = () => {
 			liveDrag: liveDrag.value,
 			clickable: clickable.value,
 			boxSelect: boxSelect.value,
+			// 框选结束后保留矩形：框内拖动整组平移选中的节点；面板可随时改，右侧读数能看到坐标
+			selectionBoxPersistent: selectionBoxPersistent.value,
 			multiSelect: multiSelect.value,
+			toggleSelect: toggleSelect.value,
 			// 快捷键：框选 / 多选 / 加点 / 复制这四个「按住 + 操作」的修饰键都能改（缺省 Ctrl / Ctrl / Ctrl / Alt）
 			shortcuts: buildShortcuts(),
 			// 节点复制：Alt 点节点跟随鼠标落地，接口复制落在节点旁边（落点偏移在 copy.offset 里）
@@ -4238,6 +4430,8 @@ export const useGisViewDemo = () => {
 			minimap: buildMinimapOptions(),
 			// 热力图：按 max_loading_rate 给线路 / 通道回线（target 带上 point 时还有节点）取色带颜色并缩放尺寸
 			heatmap: buildHeatmapOptions(),
+			// 图例：不写字段 / 值域 / 色带，默认与热力图共用同一把尺
+			visualMap: buildVisualMapOptions(),
 			pointRules: applyRules.value ? buildPointRules() : [],
 			lineRules: applyRules.value ? buildLineRules() : [],
 			label: buildLabelOptions(),
@@ -4379,7 +4573,14 @@ export const useGisViewDemo = () => {
 	watch(liveDrag, value => viewRef.value?.updateOptions({ liveDrag: value }))
 	watch(clickable, value => viewRef.value?.updateOptions({ clickable: value }))
 	watch(boxSelect, value => viewRef.value?.updateOptions({ boxSelect: value }))
+	watch(selectionBoxPersistent, value => {
+		viewRef.value?.updateOptions({ selectionBoxPersistent: value })
+		if (!value) {
+			readSelectionBox()
+		}
+	})
 	watch(multiSelect, value => viewRef.value?.updateOptions({ multiSelect: value }))
+	watch(toggleSelect, value => viewRef.value?.updateOptions({ toggleSelect: value }))
 	// 快捷键自定义：四个「按住 + 操作」的动作改完立刻下发（框选 / 多选 / 加点的修饰键同时也是光标变体的判据）
 	watch([shortcutBoxSelect, shortcutMultiSelect, shortcutAddWaypoint, shortcutDuplicate], () => {
 		viewRef.value?.updateOptions({ shortcuts: buildShortcuts() })
@@ -4395,8 +4596,11 @@ export const useGisViewDemo = () => {
 		viewRef.value?.updateOptions({ selectionOnTop: value })
 		writeLastEvent(value ? '选中抬层：开（选中的节点 / 线路画在最上层）' : '选中抬层：关（完全按 zIndex 与数据顺序画）')
 	})
-	// 框选矩形自身的样式：颜色、背景与边框宽度都在这一份里
-	watch(selectionBoxMode, () => viewRef.value?.updateOptions({ selectionBoxStyle: buildSelectionBoxStyle() }))
+	// 框选矩形自身的样式：颜色 / 边框 / 渲染方式与 DOM 专属的线型、圆角、类名都在这一份里
+	watch([selectionBoxMode, selectionBoxRender, selectionBoxBorderStyle, selectionBoxRadius, selectionBoxUseClassName], () => {
+		viewRef.value?.updateOptions({ selectionBoxStyle: buildSelectionBoxStyle() })
+		readSelectionBox()
+	})
 	watch(waypointEditable, value => viewRef.value?.updateOptions({ waypointEditable: value }))
 	watch(waypointAlways, value => viewRef.value?.updateOptions({ waypointVisibility: value ? 'always' : 'selected' }))
 	watch([pointSize, lineWidth], () => viewRef.value?.updateOptions({ pointStyle: buildPointStyle(), lineStyle: buildLineStyle(), ...hoverStylePatch() }))
@@ -4476,7 +4680,7 @@ export const useGisViewDemo = () => {
 		pointSpacingReadout.value = `可见 ${spacing.count} 个 · 最近 ${screen(spacing.minDistance)} · 最远 ${screen(spacing.maxDistance)}`
 	}
 	// 节点间距兜底：改参数不移动相机，这里补一次 fitView 让面板上立刻看到效果；关掉时也恢复普通适应
-	watch([fitSpacing, fitSpacingMode, fitSpacingMinDistance, fitSpacingMaxDistance, fitSpacingMaxZoom], ([enabled], [wasEnabled]) => {
+	watch([fitSpacing, fitSpacingMode, fitSpacingMinDistance, fitSpacingMaxDistance], ([enabled], [wasEnabled]) => {
 		const view = viewRef.value
 		if (!view) {
 			return
@@ -4845,6 +5049,11 @@ export const useGisViewDemo = () => {
 		heatmapGlow, heatmapGlowStrength, heatmapGlowLine, heatmapGlowPoint, heatmapGlowBlend, heatmapOpacityMin, heatmapOpacityMax,
 		heatmapDensity, heatmapDensityStyle, heatmapDensityLayer, heatmapDensityLevels, heatmapDensityRadius, heatmapDensityThreshold, heatmapDensityCore, heatmapDensityGamma, heatmapDensityWeight, heatmapDensityOpacity
 	], () => viewRef.value?.updateOptions({ heatmap: buildHeatmapOptions() }))
+	watch([heatmapEnabled, visualMapEnabled, visualMapType, visualMapInteractive, visualMapCustom, visualMapOutOfRange], () => {
+		visualMapReadout.value = ''
+		visualMapLastChange.value = ''
+		viewRef.value?.updateOptions({ visualMap: buildVisualMapOptions() })
+	})
 	// 小图那一份：默认沿用主图（不写 heatmap 字段），勾掉「鹰眼图沿用」就只给小图关（heatmap: false）
 	watch([heatmapEnabled, heatmapMinimap], () => viewRef.value?.updateOptions({ minimap: buildMinimapOptions() }))
 	const applyChannelOptions = () => {
@@ -6128,7 +6337,9 @@ const members = (payload.lineData ?? payload.linePropsByMember ?? []).filter(Boo
 		provinceGeoJson, provinceLoading, demoImageUrl, demoCanvasImage, DEMO_SVG_PATH, provinceGeoJsonUrl,
 		loadProvinceGeoJson, buildDemoImageUrl, buildDemoCanvasImage, INITIAL_VIEW_MODES, initialViewMode,
 		initialZoom, initialCenterText, initialViewReadout, draggable, liveDrag, liveDragHint, clickable, boxSelect,
-		multiSelect, selectionBoxMode, SELECTION_BOX_STYLES, buildSelectionBoxStyle, SHORTCUT_MODES,
+		selectionBoxPersistent, selectionBoxRender, selectionBoxBorderStyle, selectionBoxRadius,
+		selectionBoxUseClassName, selectionBoxReadout, SELECTION_BOX_CLASS, readSelectionBox,
+		clearRetainedSelectionBox, multiSelect, toggleSelect, selectionBoxMode, SELECTION_BOX_STYLES, buildSelectionBoxStyle, SHORTCUT_MODES,
 		shortcutBoxSelect, shortcutMultiSelect, shortcutAddWaypoint, shortcutDuplicate, shortcutValue, shortcutLabel,
 		shortcutReadout, buildShortcuts, COPY_OFFSETS, copyEnabled, copyOffsetMode, buildCopyOptions, pointLabel,
 		mergeEnabled, mergeTrigger, MERGE_TRIGGERS, mergeDistance, MERGE_CONFIRM_MODES, mergeConfirmMode,
@@ -6146,7 +6357,7 @@ const members = (payload.lineData ?? payload.linePropsByMember ?? []).filter(Boo
 		cascadeTriggerOnBoxSelect, cascadeReadout, buildCascadeHighlightOptions,
 		handleCascadeHighlight, readCascadeHighlight,
 		searchKeyword, searchScope, searchFocus, searchReadout, pointSizeScale, lineWidthScale, pointZoomScale,
-		lineZoomScale, fitSpacing, fitSpacingMode, fitSpacingMinDistance, fitSpacingMaxDistance, fitSpacingMaxZoom, pointSpacingReadout, zoomBaseReadout, pointShape,
+		lineZoomScale, fitSpacing, fitSpacingMode, fitSpacingMinDistance, fitSpacingMaxDistance, pointSpacingReadout, zoomBaseReadout, pointShape,
 		symbolByStationType, symbolIconMode, symbolStrokeWidth, pointLayering, lineLayering, perPointStyle,
 		perPointSymbol, PER_POINT_SYMBOL, applyRules, topVoltageOf, voltageWhen, showLabels, labelPosition,
 		labelMaxCount, labelVoltageScope, LABEL_VOLTAGE_SCOPES, topPointVoltage, labelWhen, labelAvoidOverlap,
@@ -6186,7 +6397,10 @@ const members = (payload.lineData ?? payload.linePropsByMember ?? []).filter(Boo
 		heatmapDensityStyle, heatmapDensityLayer, heatmapDensityLevels, heatmapDensityRadius, heatmapDensityThreshold,
 		heatmapDensityCore, heatmapDensityGamma, heatmapDensityWeight, heatmapDensityOpacity, heatmapGlow,
 		heatmapGlowStrength, heatmapGlowLine, heatmapGlowPoint, heatmapGlowBlend, heatmapOpacityMin,
-		heatmapOpacityMax, heatmapMinimap, heatmapFieldStats, heatDensityText, buildHeatmapOptions, syncVisibleCount,
+		heatmapOpacityMax, heatmapMinimap, heatmapFieldStats, heatDensityText, buildHeatmapOptions,
+		visualMapEnabled, visualMapType, visualMapInteractive, visualMapCustom, visualMapOutOfRange,
+		VISUAL_MAP_OUT_OF_RANGE_MODES, visualMapReadout, visualMapLastChange,
+		buildVisualMapOptions, renderVisualMapCustom, syncVisibleCount,
 		boundsOfData, currentBounds, PROVINCE_PALETTE, provinceHash, buildProvinceStyle, buildImagePlacement,
 		buildBackgroundOptions, frameProvince, applyBackground, BACKGROUND_HINTS, backgroundHint, parseInitialCenter,
 		parsePair, convertFromLngLat, convertFromScreen, buildInitialViewOptions, applyInitialViewFromControls,

package/docs/format/02-/350/212/202/347/202/271/344/270/216/347/272/277/350/267/257.md

@@ -8,7 +8,7 @@
 | `x` / `y` | `number` | **必填** | 世界坐标；单位由数据自己定（经纬度要先过 `createGeoMapper` / `lngLatToWorld` 搬成世界坐标） |
 | `name` / `label` | `string` | 无 | 业务字段：标签模板里 `{name}` / `{label}` 取的就是它，提示框同理 |
 | `vn_kv` 等业务字段 | 任意 | 无 | 组件不认识的字段一律原样留着：筛选 / 规则 / 标签 `when` 能按字段名取，导出业务口径时也照抄回去（含 `props.vn_kv` 这样的嵌套路径） |
-| `color` / `size` / `strokeColor` / `strokeWidth` | `string` / `number` | 无，回落到 `pointStyle` → `pointRules` → 内置默认 | 逐点外观，压过 `pointStyle` 与规则（优先级：状态样式 > 热力图 > 要素自身 > 规则 > `pointStyle` > 默认）；`size` 是节点宽度（圆的直径 = `size × 2 / √π`） |
+| `color` / `size` / `strokeColor` / `strokeWidth` | `string` / `number` | 无，回落到普通规则 → `pointStyle` → 内置默认 | 逐点外观：默认压过普通规则与 `pointStyle`，被 `override: true` 的规则压过（优先级：状态样式 > 热力图 > `override` 规则 > 要素自身 > 普通规则 > `pointStyle` > 默认）；`size` 是节点宽度（圆的直径 = `size × 2 / √π`） |
 | `symbol` | `GisViewSymbolInput` | `'circle'` | 内置形状的简写 `'circle'` / `'square'`，或 `{ type: 'circle' }` / `{ type: 'square', radius }` / `{ type: 'image', src }` / `{ type: 'svg', path \| markup, viewBox, fill, stroke, strokeWidth }`，见 GisView.md 的「符号」 |
 | `opacity` | `number` | `1` | `0 ~ 1`，越小越透 |
 | `zIndex` | `number` | `0` | 绘制层级：大的盖在上面，同一个值算一层；不参与状态样式，悬停 / 选中不会把它抬层 |

package/docs/format/03-/346/213/220/347/202/271/350/243/205/351/245/260/344/270/216/346/240/267/345/274/217.md

@@ -96,13 +96,13 @@ view.exportData({ format: 'test', parts: ['waypoint'] })
 | 线路标记偏移 | `lines[].decorations[].position` / `.at` | `position` 按**沿线**算（比例 / 百分比 / 世界单位距离），`at` 是**世界坐标** |
 | 节点标记偏移 | `points[].decorations[].offset` / `.distance` + `.direction` / `.at` | `offset` 与 `distance` 是**屏幕像素**（缩放时保持像素距离），`at` 是**世界坐标** |
 
-颜色与尺寸按「全局 → 规则 → 要素自身 → 状态（悬停 / 选中 / 框选）→ 热力图」逐层覆盖：
+颜色与尺寸从低到高按「全局 → 普通规则 → 要素自身 → `override` 规则 → 热力图 → 状态（悬停 / 选中 / 框选）」逐层覆盖；普通规则始终高于全局样式，只有单条规则写 `override: true` 才会压过要素自身字段：
 
 | 想改什么 | 写在哪 |
 | --- | --- |
 | 一类要素的默认外观 | `pointStyle` / `lineStyle` / `waypointStyle`，通道另有 `channelWidth` / `colors` / `lineWidth` |
-| 按业务字段批量配色 | `pointRules` / `lineRules`（条件 + 样式，见 GisView.md 的「批量样式规则」） |
-| 某一个要素 | 节点 `color` / `size` / `strokeColor` / `strokeWidth`、线路 `color` / `width` / `opacity`、通道 `colors[]` / `lineWidth` |
+| 按业务字段批量配色 | `pointRules` / `lineRules`（条件 + 样式；普通规则只补空位，单条写 `override: true` 可压过要素字段，见 GisView.md 的「批量样式规则」） |
+| 某一个要素 | 节点 `color` / `size` / `symbol` / `strokeColor` / `strokeWidth`、线路 `color` / `width` / `opacity` / `decorations`、通道 `colors[]` / `lineWidth` |
 | 悬停 / 选中 / 框选 | `pointHoverStyle` / `pointSelectStyle` / `pointMultiSelectStyle` / `pointBoxSelectStyle`、`lineHoverStyle` / `lineSelectStyle` / `lineMultiSelectStyle`，逐要素可用 `hoverStyle` / `selectStyle` / `multiSelectStyle` 覆盖 |
 | 标签 / 标记的文字与符号 | 标签 `style`（内联 CSS）+ `className`（自带类名）；标记 `color` / `strokeColor` / `strokeWidth` / `opacity` / `shadow` |