gis-view-webgl2 0.1.4 → 0.1.5

package/dist/index.d.ts

@@ -489,9 +489,21 @@ export interface GisViewMinimapOptions {
 	/** 尺寸（CSS 像素），默认 168 × 120 */
 	width?: number
 	height?: number
+	/** 贴近主视图（或 container 指定的外部宿主）的哪个角，默认 bottom-right */
 	position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
 	/** 距离容器边缘的间距（CSS 像素），默认 12 */
 	margin?: number
+	/**
+	 * 相对 position 那个角的位移（CSS 像素，[x, y]）：x 正数向右、y 正数向下。
+	 * 四角配置都按同一直觉换算，updateOptions 改它就能动态移动整张鹰眼图。
+	 */
+	offset?: [number, number]
+	/**
+	 * 外部宿主：HTMLElement 或 CSS 选择器。给了就把小图根节点挂到它里面，position / margin / offset
+	 * 都相对这个元素；外部宿主需要 position: relative（或 absolute / fixed）才能让绝对定位按它算。
+	 * 不写 / 选择器找不到时回落到主视图根节点；运行时换容器会移动同一个根节点，不重建画布。
+	 */
+	container?: HTMLElement | string | null
 	/**
 	 * 小图背景：'inherit'（默认）画主视图那一份（底色 / 图片 / GeoJSON，含区域配色与文字）；
 	 * false / 'none' 不画；字符串是容器底色（旧写法）；对象是与 background 同结构的独立配置
@@ -504,6 +516,12 @@ export interface GisViewMinimapOptions {
 	 * 两者离得很远就是这样），只画正在看的那一份 —— 合并只会让两份都看不清
 	 */
 	extent?: GisViewMinimapExtent
+	/**
+	 * `extent: 'auto'` 时是否允许范围跟着相机收窄：默认 false，始终按「数据 ∪ 底图」铺。
+	 * 打开后，相机落在其中一份范围、而那份在合并结果里不足 6 像素时只画正在看的那一份；
+	 * 数据 / 底图内容消失、相机进出这份范围时鹰眼图会重新计算包围盒。
+	 */
+	extentFollowCamera?: boolean
 	/** 给小图容器再加一个类名（与内置的 gis-view__minimap 并列），方便用样式表改外观 */
 	className?: string
 	/** 直接落到小图容器上的内联样式（中划线 / CSS 变量键与驼峰键都认）；换配置时上一轮写过、这一轮没写的键会被清掉 */
@@ -515,7 +533,10 @@ export interface GisViewMinimapOptions {
 	draw?: (info: GisViewMinimapDrawInfo) => void
 	/** 可拆分的自定义绘制层：按 placement 分段、段内按 order，最后才轮到旧的 draw */
 	layers?: GisViewMinimapLayer[]
-	/** 小图容器的底色（CSS），默认 rgba(255, 255, 255, 0.92) */
+	/**
+	 * 小图容器的底色（CSS），默认 rgba(255, 255, 255, 0.92)。显式设置时它接管画布底色：
+	 * 继承的底图仍画图片 / GeoJSON，但不再用主图的不透明底色盖住它。
+	 */
 	backgroundStyle?: string
 	/** 小图画布备份像素比上限（默认 4）：高分屏或宿主缩放很大时可降到 1 ~ 2 降低填充开销 */
 	maxPixelRatio?: number
@@ -529,12 +550,18 @@ export interface GisViewMinimapOptions {
 	lineStyle?: GisViewMinimapLineStyle
 	/**
 	 * 节点规则：按属性给小图上的节点定颜色 / 半径 / 形状 / 层级（条件语言与主图一样）。
-	 * 不配时沿用主图的 pointRules，但只取颜色与层级：主图的尺寸是主画布上的像素，搬到小图上会糊成一片
+	 * 不配时沿用主图样式链：颜色 / 描边色 / 层级取规则，尺寸与符号取引擎最终解析结果
+	 * （点自身 > 主图 pointRules > 主图 pointStyle），圆、方、图片与 SVG 图标都会画出来
 	 */
 	pointRules?: GisViewMinimapPointRule[]
-	/** 线路规则：按属性给小图上的线路定颜色 / 线宽 / 透明度 / 层级，不配时沿用主图 lineRules（只取颜色与透明度） */
+	/** 线路规则：按属性给小图上的线路定颜色 / 线宽 / 透明度 / 层级，不配时沿用主图 lineRules（颜色 / 透明度）与样式链线宽 */
 	lineRules?: GisViewMinimapLineRule[]
-	/** 没有自己的规则时是否沿用主图的 pointRules / lineRules，默认 true；显式 false 表示小图只用 pointStyle / lineStyle */
+	/**
+	 * 没有自己的规则时是否沿用主图样式，默认 true：节点连尺寸与图标一起沿用，线路沿用颜色 / 透明度 / 线宽；
+	 * 沿用尺寸时按小图与主图 CSS 视口宽高的较小比例缩放，独立于主图相机倍数与小图自身倍数；
+	 * 小图自身多次放大时再按 pointZoomScale / lineZoomScale 联动；
+	 * 显式 false 表示小图只用 pointStyle / lineStyle
+	 */
 	inheritRules?: boolean
 	/**
 	 * 小图自己的热力图：不写就沿用主图的 options.heatmap（两边的色带与取的值完全一致，自动值域也按同一份数据算），
@@ -551,24 +578,24 @@ export interface GisViewMinimapOptions {
 	 * 主视图筛选出来的隐藏结果本来就带联动，这里管的是小图自己挡掉的那部分
 	 */
 	cascade?: GisViewFilterCascade
-	/** 节点半径的整体倍数（与主视图的 pointSizeScale 同名同义，常数倍数），默认 1 */
+	/** 节点半径的整体倍数（与主视图的 pointSizeScale 同名同义，常数倍数）：自有规则与沿用主图的节点都乘这一份，默认 1 */
 	pointSizeScale?: number
-	/** 线路宽度的整体倍数（与主视图的 lineWidthScale 同名同义），默认 1 */
+	/** 线路宽度的整体倍数（与主视图的 lineWidthScale 同名同义）：自有规则与沿用主图的线路都乘这一份，默认 1 */
 	lineWidthScale?: number
 	/**
 	 * 小图自身的倍数对节点半径的放大指数（0 表示不跟随，1 表示同倍率放大），默认 0。
 	 * 只在小图真的放大过才看得出来：zoomable 关着、或者倍数还在 1（刚好铺满）时是恒等系数；
-	 * 想让小图跟着**主视图**的缩放一起变，配的是 pointMapZoomScale
+	 * 沿用主图规则的节点也按这一份联动；主图相机倍数不会改变它们的大小
 	 */
 	pointZoomScale?: number
-	/** 小图自身的倍数对线路宽度的放大指数（0 表示不跟随），默认 0；同样只在小图倍数 ≠ 1 时起作用，跟随主视图要用 lineMapZoomScale */
+	/** 小图自身的倍数对线路宽度的放大指数（0 表示不跟随），默认 0；同样只在小图倍数 ≠ 1 时起作用，沿用主图线宽也按它联动 */
 	lineZoomScale?: number
 	/**
-	 * 主视图的地图倍数对节点半径的放大指数：0（默认）不跟随，1 与主视图同倍率放大，
-	 * 0.5 是主视图放大 4 倍、小图节点放大 2 倍。与主视图的 pointZoomScale 是同一套说法
+	 * 主视图的地图倍数对**小图自有规则 / 样式**节点半径的放大指数：0（默认）不跟随，1 与主视图同倍率放大，
+	 * 0.5 是主视图放大 4 倍、小图节点放大 2 倍。沿用主图规则的节点不吃这一份（尺寸只跟视口比例与小图自身倍数）
 	 */
 	pointMapZoomScale?: number
-	/** 主视图的地图倍数对线路宽度的放大指数（0 表示不跟随、1 同倍率），与主视图的 lineZoomScale 同一套说法 */
+	/** 主视图的地图倍数对**小图自有规则 / 样式**线路宽度的放大指数（0 不跟随、1 同倍率）；沿用主图线宽不吃这一份 */
 	lineMapZoomScale?: number
 	/** 地图倍数联动的基准比例，缺省取主视图首次适应视图时的比例（与主视图 zoomBaseScale 同源） */
 	mapZoomBaseScale?: number
@@ -582,9 +609,9 @@ export interface GisViewMinimapOptions {
 	onInteraction?: (info: GisViewMinimapInteractionInfo) => void
 	/** 长按多久算「要移动视角」（毫秒），默认 180 */
 	longPressDelay?: number
-	/** 在小图上滚轮是否缩放主图（以光标处的世界坐标为锚点），默认 true；zoomable 打开时改由 Ctrl / ⌘ + 滚轮触发 */
+	/** 在小图上滚轮是否缩放主图（以光标处的世界坐标为锚点），默认 true；zoomable: true 时改由 Ctrl / ⌘ + 滚轮触发 */
 	wheelZoom?: boolean
-	/** 鹰眼图自身的倍数：1（默认）是「刚好铺满小图」，滚轮与 setMinimapZoom 改的都是它 */
+	/** 鹰眼图自身的倍数：1（默认）是「刚好铺满小图」；手动缩放时由滚轮 / setMinimapZoom 改，跟随主图时它是基准倍数 */
 	zoom?: number
 	/** 倍数下限与上限，默认 0.5 / 8 */
 	minZoom?: number
@@ -595,16 +622,26 @@ export interface GisViewMinimapOptions {
 	zoomInStep?: number
 	/** 只覆盖「缩小」一侧的步进倍率，缺省用 zoomStep */
 	zoomOutStep?: number
-	/** 是否允许缩放鹰眼图自身（滚轮，锚点落在光标处），默认 false；打开后滚轮不再缩放主图（改为 Ctrl / ⌘ + 滚轮） */
-	zoomable?: boolean
 	/**
-	 * 开了 zoomable 之后，小图空白处（视口框之外）拖动的动作：
+	 * 缩放模式，默认 false（关闭）：
+	 * - true：手动缩放鹰眼图自身，滚轮以光标为锚点，滚轮不再缩放主图（改为 Ctrl / ⌘ + 滚轮）；
+	 * - 'follow'：整体显示范围跟随主图倍数变化，滚轮仍然缩放主图；与 true 互斥。
+	 */
+	zoomable?: boolean | 'follow'
+	/**
+	 * `zoomable: 'follow'` 时主图相对基准倍数的指数：1（默认）同倍率，0.5 表示主图放大 4 倍、鹰眼图放大 2 倍，
+	 * 0 表示鹰眼图倍数不随主图变化。最终倍数仍夹在 minZoom ~ maxZoom 之间。
+	 */
+	followZoomScale?: number
+	/**
+	 * 小图空白处（视口框之外）拖动的动作：
 	 * pan（默认）平移小图内容，box 直接拉出框选矩形（松手后主图显示框住的区域）。
-	 * 按住 Ctrl / ⌘ 拖动始终是另一个动作，两个动作不用切换配置就能用。
+	 * box 不依赖 zoomable；只有手动缩放（zoomable: true）时，按住 Ctrl / ⌘ 才会切换成另一个动作。
 	 */
 	dragAction?: 'pan' | 'box'
 	/**
-	 * 通道是否画出全部回线，默认 true；关掉（false）时一个通道只画偏移最靠中间的那一根。
+	 * 通道是否画出全部回线，默认 true；关掉（false）时一个通道分组只画一根代表线：
+	 * 按当前可见成员逐顶点取平均，双回线落在两根正中间（而不是固定挑上面 / 左边那一根）。
 	 * 通道多、底图挤的时候关掉更清爽，通道位置与走向仍然看得出来。
 	 */
 	channelCircuits?: boolean
@@ -2216,6 +2253,50 @@ export interface GisViewChannelAddSpec {
 	group?: GisViewChannelAddGroup | GisViewChannelAddGroup[]
 }
 
+/**
+ * commitAddChannel 的对象入参：可以写一份新通道 / 新线路，也可以放在 channel / line / lines 里逐段给。
+ * - 直接通道对象必须带 lineIds：每个 id 生成一条新回线，groups 是分组声明；通道 id 不参与回线 id。
+ * - 直接线路对象的业务字段透传到 lineProps；path 是中间拐点，首尾仍取 from / to。
+ * - 容器里的 line 缺省是独立线路，lines / lineData / lineItems 才是成员回线表，且 lines 优先；
+ *   空数组不覆盖草稿。channel.lineIds 只在没有成员回线表时当 id 种子。
+ * - 对象里的端点、id、名称、路径、样式与分组优先于草稿；没写的字段仍沿用当前草稿。
+ * - 容器顶层的 channel.lineProps 目前不参与合并；公共字段写顶层 lineProps，单条写 lines[i]。
+ */
+export interface GisViewChannelAddCommitInput extends Partial<GisViewChannelAddInput> {
+	/** 本次新增的通道对象（lineIds 会作为新回线 id 种子；groups 作为分组声明） */
+	channel?: GisViewChannel
+	/** 本次新增的一条线路对象（写了它就按独立线路提交） */
+	line?: GisViewLine
+	/** 本次新增的回线对象 / 数据（一条或一批，与 lineData / lineItems 同义） */
+	lines?: GisViewChannelLineData
+	/** lines 的别名（与 addChannel 的第二段同一个写法） */
+	lineData?: GisViewChannelLineData
+	/** 新通道的分组声明（与 channel.groups 同义） */
+	channelGroups?: GisViewChannelAddGroup | GisViewChannelAddGroup[]
+	/** channelGroups 的别名（与 addChannel 的第三段同一个写法） */
+	group?: GisViewChannelAddGroup | GisViewChannelAddGroup[]
+}
+
+/** 新增通道草稿端点示例点单端的样式：只写哪几项就覆盖哪几项 */
+export interface GisViewChannelDraftDotStyle {
+	/** 这一端是否画示例点，默认 true */
+	show?: boolean
+	/** 示例点半径（CSS 像素），缺省用 dot */
+	size?: number
+	/** 示例点颜色，缺省用 dots.color / dotColor / color */
+	color?: string
+	/** 形状，缺省 circle */
+	shape?: 'circle' | 'square'
+}
+
+/** 草稿两端示例点的共同样式；from / to 可以分别覆盖 */
+export interface GisViewChannelDraftDots extends GisViewChannelDraftDotStyle {
+	/** 起点的单独设置（优先于这一层的共同设置） */
+	from?: GisViewChannelDraftDotStyle
+	/** 终点的单独设置（优先于这一层的共同设置） */
+	to?: GisViewChannelDraftDotStyle
+}
+
 /** 新增通道草稿线的样式：跟随光标的那条预览线 */
 export interface GisViewChannelDraftStyle {
 	color?: string
@@ -2225,6 +2306,16 @@ export interface GisViewChannelDraftStyle {
 	dot?: number
 	/** 端点圆点颜色，缺省沿用 color */
 	dotColor?: string
+	/**
+	 * 两端示例点：false 两个都不画，true / 不写按 dot 与 dotColor 画；对象可统一设置 size / color / shape / show，
+	 * 并用 from / to 分别覆盖。示例点始终画在真正点中的节点中心（不受多回线偏移影响）。
+	 */
+	dots?: boolean | GisViewChannelDraftDots
+	/**
+	 * 示例线路的绘制层级：'above'（默认，画在真实节点之后）或 'below-points'（线 / 箭头 / customDraw 先画，
+	 * 再盖真实节点）；端点示例点始终在节点之后画，确保看得见。
+	 */
+	layer?: 'above' | 'below-points'
 	/** 预览线末端是否画方向箭头，缺省 false */
 	arrow?: boolean
 	/** 箭头大小（CSS 像素），缺省 12 */
@@ -7492,6 +7583,8 @@ export interface GisViewInstance {
 	getZoomBaseScale(): number
 	/** 重定缩放联动的基准比例：不传就取当下相机的比例（把现在这一屏当成「原样大小」），之后放大缩小都从它算倍数，返回 this */
 	setZoomBaseScale(scale?: number): GisViewInstance
+	/** 鹰眼图根节点（没配 minimap 时为 null）：拖动整张图 / 绑定自定义手势时拿它 */
+	getMinimapElement(): HTMLElement | null
 	/** 鹰眼图自身的倍数：1 是「刚好铺满小图」 */
 	getMinimapZoom(): number
 	/** 设置鹰眼图的倍数（夹在 minimap.minZoom ~ maxZoom 之间），内容重新跟着数据范围居中 */
@@ -7856,8 +7949,35 @@ export interface GisViewInstance {
 	cancelAddChannel(): GisViewInstance
 	/** 结束新增草稿并收掉视图上的示例假通道 / 线路（静默，不补 cancel）：提前结束不新建就用它 */
 	endAddChannel(): GisViewInstance
-	/** 提交草稿：resolution 缺省用草稿里的推荐方案（autoCommit 时由内部自动提交） */
-	commitAddChannel(resolution?: GisViewChannelAddInput['resolution'], options?: { auto?: boolean }): GisViewChannelAddResult
+	/**
+	 * 提交已 ready 的新增草稿（autoCommit 时由组件内部调用）。input 有五类写法：
+	 * 1. 不传 / null：用草稿的 preferred；
+	 * 2. 旧 resolution：字符串，或只含 type / groupId / groupIndex / channelId 的对象；
+	 * 3. 直接线路对象：无 lineIds，且有 from / to / path / kind: 'line' / start / end 之一；
+	 * 4. 直接通道对象：lineIds 为数组，缺省按 newChannel 落地；
+	 * 5. 容器：{ channel, line, lines, lineData, lineItems, channelGroups, group, channelProps, lineProps, resolution, ... }。
+	 *
+	 * 字段优先级：from / to = 顶层 → channel → line → lineItems 中第一个对象项 → 草稿；
+	 * path = 顶层 → line → channel → 草稿；分组 = channelGroups → group → channel.groups；
+	 * 容器 lineProps = 草稿 → 顶层 → line.lineProps → lines[i]（不读 channel.lineProps）；
+	 * channelProps = 草稿 → channel 上的业务字段 → 顶层 channelProps。直接通道对象自己的 lineProps 会生效。
+	 *
+	 * 直接通道默认新建；要并进已有通道 / 分组，用容器并显式写 resolution。
+	 * ready 里的方案对象带 enabled / count / lineIds 等读数，不能整条回传，只取
+	 * `{ type, groupId, groupIndex, channelId }` 子集。调用前草稿必须 ready，否则返回 ok: false 且不写数据。
+	 *
+	 * ```ts
+	 * view.commitAddChannel({
+	 *   resolution: { type: 'joinGroup', groupId: 'corridor-1::2' },
+	 *   lines: [{ id: 'join-1', color: '#dd4b2e' }, { id: 'join-2' }],
+	 *   lineProps: { width: 2.4 }
+	 * })
+	 * ```
+	 */
+	commitAddChannel(
+		input?: GisViewChannelAddInput['resolution'] | GisViewChannel | GisViewLine | GisViewChannelAddCommitInput,
+		options?: { auto?: boolean; continuous?: boolean; originalEvent?: Event | null }
+	): GisViewChannelAddResult
 	/** 两个节点之间的新增方案：新通道 / 新分组 / 并进某一组 / 无法添加（kind 为 'line' 时方案表是空的） */
 	getChannelAddOptions(from: string | number, to: string | number, count?: number, kind?: 'channel' | 'line'): GisViewChannelAddPlan | null
 	/**