gis-view-webgl2 0.1.5 → 0.1.6

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 并列），方便用样式表改外观 */
@@ -3794,6 +3814,8 @@ export interface GisViewDataChangePayload {
 	lines: GisViewLine[]
 	channels: GisViewChannel[]
 	counts: { points: number; lines: number; channels: number }
+	/** 数据修订号：每次数据变更 +1；只改全局配置 / 样式时不推，外部缓存据它决定要不要重算 */
+	dataVersion: number
 	/** 动到 / 删掉的节点下标（单点更新是那一个，删除是删除前的下标升序，新增是它们在数组里的位置） */
 	index?: number
 	indexes?: number[]
@@ -5433,6 +5455,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
@@ -6762,6 +6796,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 +7436,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 +7625,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
 	/**
@@ -8220,6 +8289,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 */
@@ -8679,6 +8754,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 +8776,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