gis-view-webgl2 0.1.5 → 0.1.7

package/dist/index.d.ts

@@ -13,6 +13,20 @@ export interface GisViewCamera {
 	scale: number
 }
 
+/** 直接飞相机时的目标：两项都可省略，没写的那一项沿用当前相机 */
+export interface GisViewCameraTarget {
+	center?: [number, number]
+	scale?: number
+}
+
+/** flyToCamera 的选项：时长与缓动，语义与 flyTo 完全一致 */
+export interface GisViewFlyCameraOptions {
+	/** 飞行时长（毫秒），缺省 450；<= 0 时立即落位 */
+	duration?: number
+	/** 缓动，缺省 'ease-in-out'；中心线性插值，比例按对数插值 */
+	easing?: GisViewCameraEasing
+}
+
 export interface GisViewViewport {
 	/** 视口的 CSS 宽度（**布局像素**：宿主用 CSS zoom / transform 放大时，它不变、视觉尺寸才变） */
 	cssWidth: number
@@ -516,10 +530,16 @@ export interface GisViewMinimapOptions {
 	 * 两者离得很远就是这样），只画正在看的那一份 —— 合并只会让两份都看不清
 	 */
 	extent?: GisViewMinimapExtent
+	/**
+	 * 动态范围是否跟着当前可见内容重算：默认 false。首次拿到数据 / 底图范围后锁住世界范围，
+	 * 筛选、删除、隐藏或新增内容都不会改小图的缩放与中心，外围内容消失时鹰眼图和视口框不会自己跳；
+	 * 打开后才按当前可见数据与底图重新计算。显式改 extent（含直接写固定范围）始终立即生效。
+	 */
+	extentFollowContent?: boolean
 	/**
 	 * `extent: 'auto'` 时是否允许范围跟着相机收窄：默认 false，始终按「数据 ∪ 底图」铺。
 	 * 打开后，相机落在其中一份范围、而那份在合并结果里不足 6 像素时只画正在看的那一份；
-	 * 数据 / 底图内容消失、相机进出这份范围时鹰眼图会重新计算包围盒。
+	 * 相机进出这份范围时鹰眼图会重新计算包围盒；extentFollowContent 关闭时用的是锁定下来的那一份范围。
 	 */
 	extentFollowCamera?: boolean
 	/** 给小图容器再加一个类名（与内置的 gis-view__minimap 并列），方便用样式表改外观 */
@@ -2704,6 +2724,11 @@ export interface GisViewPickResult extends GisViewFeatureKey {
 	groupIndex?: number
 	/** 命中的是通道内的回线时，这一组的读数（成员、拐点数、骨架），结构与 getChannelGroups 的一项一致 */
 	group?: GisViewChannelGroupInfo & { groupIndex: number; lineCount: number; waypointCount: number }
+	/**
+	 * 命中的是通道内的回线时，同一通道全部分组的读数（按声明顺序，每项 groupIndex 是组号）。
+	 * `group` 是当前命中的那一组，`groups` 是整条通道的分组表；通道外的线路没有这两个字段。
+	 */
+	groups?: Array<GisViewChannelGroupInfo & { groupIndex: number; lineCount: number; waypointCount: number }>
 }
 
 /** 点聚合配置：true 等价于开着一份缺省档；对象写法可逐项覆盖。 */
@@ -2772,8 +2797,46 @@ export type GisViewClusterClickPayload = GisViewClusterPickResult & {
 	action: GisViewPointerAction
 }
 
+/**
+ * 一条被选中的通道的上下文：通道本身、当前组与全部分组。
+ * 单通道选中时这些字段直接摊平到选中载荷顶层；多通道时改为 channelContexts 里的一项，不会两处重复。
+ */
+export interface GisViewSelectionChannelContext {
+	channelId: string | number
+	channelIndex: number
+	channel: GisViewChannel
+	/** 当前组：真实点击 / selectAt 是命中的那一组；框选 / 按引用接口是选中集里第一条通道回线所在的组 */
+	groupId: string | number
+	groupIndex: number
+	group: GisViewChannelGroupInfo & { groupIndex: number; lineCount: number; waypointCount: number }
+	/** 同一通道的全部分组（按声明顺序；同一条通道内与其他载荷项共享这一份数组） */
+	groups: Array<GisViewChannelGroupInfo & { groupIndex: number; lineCount: number; waypointCount: number }>
+	/** 本次选中集里属于这条通道的回线下标 / id */
+	lineIndexes: number[]
+	lineIds: Array<string | number>
+}
+
+/** 选中载荷里的通道上下文字段：只有一条通道时摊平，多通道时只保留 channelContexts */
+export interface GisViewSelectionChannelFields {
+	channelId?: string | number
+	channelIndex?: number
+	channel?: GisViewChannel
+	groupId?: string | number
+	groupIndex?: number
+	group?: GisViewChannelGroupInfo & { groupIndex: number; lineCount: number; waypointCount: number }
+	groups?: Array<GisViewChannelGroupInfo & { groupIndex: number; lineCount: number; waypointCount: number }>
+	/** 选中集涉及多条通道时才有（按选中顺序）；单通道不创建这一份，直接读顶层平铺字段 */
+	channelContexts?: GisViewSelectionChannelContext[]
+}
+
+/** describeSelection 的返回值：要素读数 + 与选中载荷同一套通道上下文字段 */
+export interface GisViewDescribedSelection extends GisViewSelectionChannelFields {
+	items: GisViewPickResult[]
+}
+
 /** 选中事件载荷：点击选中为 0 / 1 个要素，Shift 框选为框内全部节点（随 shortcuts.boxSelect 改变） */
-export interface GisViewSelectPayload {
+export interface GisViewSelectPayload extends GisViewSelectionChannelFields {
+	/** 选中项；通道回线只带 channelId / channelIndex / groupId / groupIndex 标量归属，分组读数看顶层或 channelContexts */
 	items: GisViewPickResult[]
 	/** 框选时的画布 CSS 像素矩形，点击选中为 null */
 	box: GisViewRect | null
@@ -2881,7 +2944,8 @@ export interface GisViewSelectionData {
  * 选中集变更载荷：与 onSelect 的区别是这个只在「选中集真的变了」时发一条，
  * 接口选中（select / clearSelection / selectInBox）也会发。
  */
-export interface GisViewSelectChangePayload extends GisViewSelectionInfo {
+export interface GisViewSelectChangePayload extends GisViewSelectionInfo, GisViewSelectionChannelFields {
+	/** 与对应 onSelect 载荷共用同一批对象；通道回线不重复挂 group / groups */
 	items: GisViewPickResult[]
 	/** 框选时的矩形，其余为 null */
 	box: GisViewRect | null
@@ -3116,6 +3180,8 @@ export interface GisViewPointerPayload {
 	groupIndex?: number
 	/** 命中的是通道内的回线时，这一组的读数 */
 	group?: GisViewChannelGroupInfo & { groupIndex: number; lineCount: number; waypointCount: number }
+	/** 命中的是通道内的回线时，同一通道全部分组的读数；`group` 是当前这组，`groups` 是整条通道 */
+	groups?: Array<GisViewChannelGroupInfo & { groupIndex: number; lineCount: number; waypointCount: number }>
 	/** 命中通道回线时的分组上下文：action.target 为 channel，按它直接渲染通道菜单 */
 	channelContext?: GisViewChannelContext
 	/** 命中多成员聚合时：聚合 id、成员数、成员下标 / id、包围盒与屏幕半径 */
@@ -3794,6 +3860,8 @@ export interface GisViewDataChangePayload {
 	lines: GisViewLine[]
 	channels: GisViewChannel[]
 	counts: { points: number; lines: number; channels: number }
+	/** 数据修订号：每次数据变更 +1；只改全局配置 / 样式时不推，外部缓存据它决定要不要重算 */
+	dataVersion: number
 	/** 动到 / 删掉的节点下标（单点更新是那一个，删除是删除前的下标升序，新增是它们在数组里的位置） */
 	index?: number
 	indexes?: number[]
@@ -5433,6 +5501,18 @@ export interface GisViewPointStyleSnapshot {
 	zIndex: number
 }
 
+/** 一条线路解析之后的样式快照：getLineStyle() 的返回 */
+export interface GisViewLineStyleSnapshot {
+	index: number
+	/** 样式链（线路自身 > 规则 > lineStyle）定下来的原始线宽，不含 lineWidthScale 与缩放联动 */
+	width: number
+	/** 解析后的 RGBA 颜色，四个分量都在 0 ~ 1 */
+	color: [number, number, number, number]
+	/** 0 ~ 1 */
+	opacity: number
+	zIndex: number
+}
+
 /** 合并时给的上下文：merge.createItem 会拿到它 */
 export interface GisViewMergeContext {
 	sourceIndex: number
@@ -6535,6 +6615,16 @@ export interface GisViewOptions {
 	maxCanvasPixels?: number
 	ariaLabel?: string
 	onReady?: (payload: GisViewReadyPayload) => void
+	/**
+	 * 本次选中操作：真实单击 / Ctrl 与 multiSelect 取反 / 框选 / selectAt 每次成功操作都发；
+	 * selectFeatures / deselect / focusOn({ select }) 等按引用接口只在选中集实际变化时发。
+	 * 清空与取反取没了时载荷是 null。onSelectChange 仍只在选中集实际变化时发。
+	 * 真实点击的派发顺序是 onClick → onSelect → onSelectChange；单通道选中时载荷顶层带
+	 * channelId / group / groups，多通道看 channelContexts。items 里的回线只带 channelId /
+	 * channelIndex / groupId / groupIndex 这些标量归属，不重复挂 group / groups；需要分组读数
+	 * 从顶层或 channelContexts 取。onSelect 与 onSelectChange 各自可独立订阅，两条载荷引用同一份
+	 * items 与分组数组，不会深拷贝；按只读使用，不要在回调里改载荷。
+	 */
 	onSelect?: (payload: GisViewSelectPayload | null) => void
 	/** 单击要素或空白处 */
 	onClick?: (payload: GisViewClickPayload | null) => void
@@ -6610,8 +6700,11 @@ export interface GisViewOptions {
 	 */
 	onDataChange?: (payload: GisViewDataChangePayload) => void
 	/**
-	 * 选中集变化：与 onSelect 的区别有两点 —— 只在选中集真的变了时发一条（框选拖动 / 数据补发不会重复发），
-	 * 并且接口选中（select / clearSelection / selectInBox）也走这里；载荷带 ids / count / 各类型条数与来源 cause。
+	 * 选中集变化：覆盖所有来源（点击 / 框选 / selectFeatures / deselect / selectAt / selectInBox），
+	 * 且只在选中集真的变了时发一条；载荷带 ids / count / 各类型条数与来源 cause。
+	 * 与 onSelect 共用同一份选中集；需要「任何来源只通知一次」时优先订阅这一条。
+	 * 通道上下文与 onSelect 同一份：单通道摊平 channelId / group / groups，多通道给 channelContexts；
+	 * 不与 items 重复，两个事件共享同一批对象引用（按只读使用）。
 	 */
 	onSelectChange?: (payload: GisViewSelectChangePayload) => void
 	/**
@@ -6762,6 +6855,26 @@ export interface GisViewFocusOptions {
 	mode?: GisViewSelectMode
 }
 
+/** 相机飞行的缓动：字符串预设，或 (progress 0~1) => eased 0~1 的自定义函数 */
+export type GisViewCameraEasing = 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out' | ((progress: number) => number)
+
+/** flyTo 的选项：目标解析、选中与缩放语义与 focusOn 完全一致，另加时长与缓动 */
+export interface GisViewFlyOptions extends GisViewFocusOptions {
+	/** 飞行时长（毫秒），缺省 450；<= 0 时立即落位 */
+	duration?: number
+	/** 缓动，缺省 'ease-in-out'；中心线性插值，比例按对数插值 */
+	easing?: GisViewCameraEasing
+}
+
+/** 相机飞行的实时读数：progress 是时间进度（0~1），不是缓动后的值 */
+export interface GisViewCameraAnimation {
+	active: boolean
+	progress: number
+	duration: number
+	from: GisViewCamera
+	to: GisViewCamera
+}
+
 /** 导出图片的选项 */
 export interface GisViewExportImageOptions {
 	/**
@@ -7382,6 +7495,10 @@ export interface GisViewInstance {
 	readonly el: HTMLElement
 	readonly canvas: HTMLCanvasElement
 	readonly gl: WebGL2RenderingContext | null
+	/** 相机是否正在执行 flyTo 的飞行动画；只读，不触发重绘 */
+	readonly cameraAnimating: boolean
+	/** 数据修订号：数据变更后 +1；只改全局配置 / 样式不变，外部缓存与增量计算据此判断是否重算 */
+	readonly dataVersion: number
 	/** 请求重画一帧：自定义 WebGL 层的数据源变了、组件自己不知道时调用 */
 	requestRender(): GisViewInstance
 	/**
@@ -7567,6 +7684,17 @@ export interface GisViewInstance {
 	 * `{ select: true, mode }` 顺手把这些要素选上。认不出目标时什么都不做，返回实例便于链式调用。
 	 */
 	focusOn(target: GisViewFocusTargets, options?: GisViewFocusOptions): GisViewInstance
+	/** 平滑飞向与 focusOn 相同的目标；duration / easing 只影响这一次调用 */
+	flyTo(target: GisViewFocusTargets, options?: GisViewFlyOptions): GisViewInstance
+	/**
+	 * 直接飞向一个相机目标 `{ center?, scale? }`：不写的那一项沿用当前相机，不经过要素解析。
+	 * duration / easing 与 flyTo 同义；参数非法时保持当前相机。
+	 */
+	flyToCamera(camera: GisViewCameraTarget, options?: GisViewFlyCameraOptions): GisViewInstance
+	/** 停掉正在跑的相机飞行（停当前帧、不补跳终点）；没有动画时是空操作 */
+	stopCameraAnimation(): GisViewInstance
+	/** 当前相机飞行读数；没有动画时 null */
+	getCameraAnimation(): GisViewCameraAnimation | null
 	/** 按关键字搜索节点 / 线路 / 通道：只返回命中（不改数据、不改筛选、也不动视角），聚焦与选中交给使用方 */
 	search(input: string | GisViewSearchOptions): GisViewSearchResult
 	/**
@@ -7670,9 +7798,17 @@ export interface GisViewInstance {
 	/**
 	 * 按浏览器客户端坐标拾取（鼠标事件里的 clientX / clientY）：与指针事件载荷同一份读数，另加 target
 	 * （'point' / 'line' / 'channel'）与 lngLat（配了 GeoJSON 底图才有）；没命中返回 null。
+	 * 命中通道回线时给 group（当前这一组）与 groups（同一通道的全部分组）。
 	 * 只读 —— 不改选中、不动光标。自建浮层 / 自定义菜单 / 拖拽放下时「问一下这儿是什么」用它
 	 */
 	pickAt(clientX: number, clientY: number): GisViewPickAtResult | null
+	/**
+	 * 按客户端坐标做一次「普通单击选中」：与画布点击共用命中顺序与选中状态，
+	 * 通道回线按 channelSelectMode 摊开。空白 / 聚合圆返回 null 且不改选中。
+	 * 立即生效，不等待 selectTrigger: 'dblClick'，也不派发 onClick / onDblClick；选中集实际变化时发
+	 * onSelect / onSelectChange。已知节点 / 线路 id 时直接用 selectFeatures，不必先求坐标。
+	 */
+	selectAt(clientX: number, clientY: number): GisViewSelectPayload | null
 	/**
 	 * 程序化悬停（参数就是鼠标事件里的 clientX / clientY）：让指针「停」到这个位置上 ——
 	 * 悬停高亮、光标与 onHover 都按它更新（外部列表 / 表格 hover 到某一行时联动高亮图上的要素）。
@@ -7699,7 +7835,8 @@ export interface GisViewInstance {
 	getLineChannel(ref: GisViewFeatureRef): GisViewLineChannelInfo | null
 	/**
 	 * 让一批东西变成选中状态（接口选中）：与点击选中走同一份 state，因此 getSelections / getSelectionData
-	 * getSelectionData 立刻就能读回来。认这些写法（见 GisViewSelectionRef）：
+	 * 立刻就能读回来。会同步选中样式与读数；选中集实际变化时发 onSelect 与 onSelectChange（cause: api）。
+	 * 认这些写法（见 GisViewSelectionRef）：
 	 * ① 节点：id、`{ type: 'point', index: 3 }`、一批 id 与对象混着写；
 	 * ② 通道：`{ type: 'channel', channelId: 'channel-a' }` 选整条通道的回线，
 	 *    `{ channelId, groupId }` / `{ type: 'group', channelId, groupId }` 选某一组
@@ -7720,7 +7857,8 @@ export interface GisViewInstance {
 	 * 把这些从当前选中集里去掉，其余选中原样留着 —— `deselect('p-1')` 取消一个节点、
 	 * `deselect({ type: 'channel', channelId: 'channel-a' })` 取消整条通道的回线。
 	 * 一个目标都不给（不传 / 传 null）等于取消全部（与 selectFeatures(null) 同一件事），
-	 * 传空数组是「没有目标」，什么都不做；认不出来的条目跳过
+	 * 传空数组是「没有目标」，什么都不做；认不出来的条目跳过。改变选中集时发
+	 * onSelect 与 onSelectChange（cause: api）。
 	 */
 	deselect(refs?: GisViewSelectionRefs): GisViewInstance
 	/** 当前选中集的原始条目（`{ type, index, item, ... }`，与指针载荷同一份口径），不做整理、不读包围盒 */
@@ -8220,6 +8358,12 @@ export interface GisViewInstance {
 	 * 拖拽落点预览拿它核对「预览与落地同一个尺寸」，合并取双方较大值走的也是这一份；下标不存在返回 null
 	 */
 	getPointStyle(index: number): GisViewPointStyleSnapshot | null
+	/**
+	 * 线路解析之后的样式快照（width / color / opacity / zIndex）：width 取样式链
+	 * （线路自身 > 规则 > lineStyle）定下来的原始线宽，不含 lineWidthScale / 缩放联动与热力倍率；
+	 * 下标不存在时返回 null。鹰眼图沿用主图线路宽度时用的就是它。
+	 */
+	getLineStyle(index: number): GisViewLineStyleSnapshot | null
 	/** 按 id / 下标取一条线路（拾取载荷 + path / bounds / color / width）；找不到返回 null */
 	getLine(ref: GisViewFeatureRef): GisViewLineInfo | null
 	/** 按 id / 下标取一条通道（数据那一份 + 成员表 + 分组上下文）；找不到返回 null */
@@ -8502,11 +8646,17 @@ export interface GisViewEngineOptions {
 	onCursor?: (coordinate: [number, number] | null) => void
 	onHover?: (payload: GisViewHoverPayload) => void
 	/**
+	 * 点击 / 框选路径（真实点击 / Ctrl 多选 / 框选（含 selectInBox）/ 空白清空）与 selectAt 每次成功操作都发；
+	 * selectFeatures / deselect / focusOn({ select }) 等按引用接口只在选中集实际变化时发。
+	 * 要统一监听所有来源并且避免点击同一要素时重复通知，请用 onSelectChange。
+	 * 真实点击的顺序是 onClick → onSelect → onSelectChange；Ctrl / multiSelect 取反与框选没有 onClick，
+	 * 顺序是 onSelect → onSelectChange。单通道选中时载荷顶层带 channelId / group / groups，多通道看 channelContexts。
+	 * items 里的回线只有标量归属，不重复挂 group / groups；两条回调共享同一批对象引用。
 	 * 载荷为 null（没有选中任何要素）时的补充读数：mode 说明这一下是哪一种选中方式 ——
 	 * 'multi' 是 Ctrl 点击取反取没了、'box' 是框选没框到东西；originalEvent 是那一次指针事件
 	 * （载荷里没有它时靠这一份读修饰键）。其余清空路径不带第二个参数
 	 */
-	onSelect?: (payload: GisViewSelectPayload | null, detail?: { mode?: 'single' | 'multi' | 'box'; originalEvent?: Event | null }) => void
+	onSelect?: (payload: GisViewSelectPayload | null, detail?: { mode?: 'single' | 'multi' | 'box'; originalEvent?: Event | null; defer?: boolean }) => void
 	onClick?: (payload: GisViewClickPayload | null) => void
 	/** 点中多成员聚合圆（引擎不选中成员，普通点击回调不会同时触发） */
 	onClusterClick?: (payload: GisViewClusterClickPayload, event: Event) => void
@@ -8553,6 +8703,8 @@ export interface GisViewEngine {
 	describe(selection: GisViewFeatureKey): GisViewPickResult | null
 	/** 批量把要素下标还原成拾取结果，框选与受控选中都用它 */
 	describeAll(selection: GisViewFeatureKey[]): GisViewPickResult[]
+	/** 批量还原并补通道上下文：单通道摊平 channelId / group / groups，多通道给 channelContexts */
+	describeSelection(selection: GisViewFeatureKey[], preferredGroupId?: string | number): GisViewDescribedSelection
 	/** 按画布 CSS 像素矩形框选，返回框内要素；第二段兼容旧的 Event 或 { selectionKinds, originalEvent } */
 	selectInBox(box: GisViewRect, options?: GisViewSelectInBoxOptions | Event | null): GisViewPickResult[]
 	/** 拐点增删改，insertIndex 缺省时按直线上离目标最近的线段插入 */
@@ -8679,6 +8831,8 @@ export interface GisViewEngine {
 	 * 合并节点取双方最大尺寸、图标优先目标用的就是它；下标不存在时返回 null
 	 */
 	getPointStyle(index: number): GisViewPointStyleSnapshot | null
+	/** 线路解析之后的样式快照（width / color / opacity / zIndex）；下标不存在时返回 null */
+	getLineStyle(index: number): GisViewLineStyleSnapshot | null
 
 	/** 某个下标的节点当前还在不在图上：被过滤 / 隐藏掉的不算 */
 	isPointVisible(index: number): boolean
@@ -8699,6 +8853,14 @@ export interface GisViewEngine {
 	forEachPointInView(rect: GisViewBounds, visit: (index: number, item: GisViewPoint, x: number, y: number, radius: number) => void | boolean): void
 	getCamera(): GisViewCamera
 	setCamera(camera: Partial<GisViewCamera>): void
+	/** 只算目标相机、不动画面；视口还没量出来时返回 null */
+	getCameraForBounds(bounds: GisViewBounds, padding?: number): GisViewCamera | null
+	/** 相机飞行：target 是终点的 { center, scale }，duration / easing 只影响这一次 */
+	flyCamera(target: GisViewCamera, options?: Pick<GisViewFlyOptions, 'duration' | 'easing'>): boolean
+	/** 停掉相机飞行，返回是否真的停了一条正在跑的动画 */
+	stopCameraAnimation(): boolean
+	getCameraAnimation(): GisViewCameraAnimation | null
+	isCameraAnimating(): boolean
 	zoomBy(factor: number, origin?: [number, number]): void
 	zoomTo(scale: number, origin?: [number, number]): void
 	zoomToBounds(bounds: GisViewBounds, padding?: number): void
@@ -8771,6 +8933,8 @@ export interface GisViewEngine {
 	pick(x: number, y: number): GisViewHitResult | null
 	/** 与组件实例的 pickAt 同一份：按浏览器客户端坐标拾取（引擎不等 DOM 事件，直接给 clientX / clientY） */
 	pickAtClient(clientX: number, clientY: number): GisViewHitResult | null
+	/** 与组件实例的 selectAt 同一份：按客户端坐标走一次普通单击选中（通道按 channelSelectMode 摊开） */
+	selectAtClient(clientX: number, clientY: number): GisViewSelectPayload | null
 	/** 程序化悬停（客户端坐标）：让指针「停」在这儿，悬停高亮 / 光标 / onHover 一起更新，返回这一次的读数 */
 	hoverAtClient(clientX: number, clientY: number): GisViewHoverPayload | null
 	/** 取消程序化悬停：清掉高亮与读数并补发 onHover(null) */