gis-view-webgl2 0.1.5 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. package/README.md +6 -3
  2. package/dist/index.cjs +1 -1
  3. package/dist/index.d.ts +86 -1
  4. package/dist/index.js +1 -1
  5. package/docs/AI/345/257/271/350/257/235/346/261/207/346/200/273.md +64 -0
  6. package/docs/GisView.md +1 -1
  7. package/docs/ai/06-/344/274/232/350/257/235/347/264/242/345/274/225/344/270/216/345/244/215/346/237/245/346/226/271/346/263/225.md +55 -0
  8. package/docs/demos/MinimapDemo.vue +154 -1
  9. package/docs/demos/SearchFilterDemo.vue +113 -1
  10. package/docs/demos/api-index.js +16 -9
  11. package/docs/demos/demos.js +1 -1
  12. package/docs/internals/13-/351/271/260/347/234/274/345/233/276.md +2 -0
  13. package/docs/internals/16-01-/344/274/230/345/214/226/344/270/216/345/217/226/350/210/215-/344/270/212.md +13 -2
  14. package/docs/internals/16-03-/344/274/230/345/214/226/344/270/216/345/217/226/350/210/215-/344/270/213.md +11 -1
  15. package/docs/internals/18-/346/200/247/350/203/275/345/256/236/346/265/213/344/270/216WebGPU/350/257/204/344/274/260.md +61 -1
  16. package/docs/manual/03-/351/205/215/347/275/256/351/241/271.md +5 -4
  17. package/docs/manual/04-/344/272/213/344/273/266/344/270/216/345/233/236/350/260/203.md +2 -2
  18. package/docs/manual/05-/347/224/273/350/264/250/344/270/216/346/211/271/351/207/217/346/233/264/346/226/260.md +1 -1
  19. package/docs/manual/14-/350/247/206/345/233/276/344/270/216/347/255/233/351/200/211.md +23 -5
  20. package/docs/manual/16-/345/256/236/344/276/213/346/226/271/346/263/225/346/200/273/350/241/250.md +7 -3
  21. package/docs/manual/17-/345/217/202/346/225/260/351/200/237/346/237/245.md +10 -3
  22. package/docs/manual/18-/351/200/220/346/226/271/346/263/225/347/244/272/344/276/213.md +20 -1
  23. package/docs/manual/19-/350/257/273/346/225/260/344/270/216/346/213/226/346/213/275/351/242/204/350/247/210.md +4 -0
  24. package/docs/manual/20-/346/200/247/350/203/275/344/270/216/345/244/247/346/225/260/346/215/256.md +8 -3
  25. package/docs/manual/21-/350/257/264/346/230/216/344/270/216/345/270/270/350/247/201/351/227/256/351/242/230.md +1 -1
  26. package/docs/steps/README.md +4 -4
  27. package/docs/steps/selftest-demos.html +105 -6
  28. package/docs/steps/selftest-docs.html +3 -3
  29. package/docs/steps/selftest-full.html +42 -1
  30. package/docs/steps/selftest-perf.html +600 -421
  31. package/package.json +1 -1
@@ -7,8 +7,8 @@
7
7
  * 源码或文档改过之后重跑一遍;`node docs/steps/check-doc-coverage.mjs` 会对账。
8
8
  */
9
9
 
10
- /** { members: 257, methods: 254, properties: 3, options: 96, sections: 16 } */
11
- export const API_SUMMARY = {"members":257,"methods":254,"properties":3,"options":96,"sections":16}
10
+ /** { members: 264, methods: 259, properties: 5, options: 96, sections: 16 } */
11
+ export const API_SUMMARY = {"members":264,"methods":259,"properties":5,"options":96,"sections":16}
12
12
 
13
13
  /** 实例成员,按 docs/GisView.md「参数速查」的分组排 */
14
14
  export const API_SECTIONS = [
@@ -51,13 +51,17 @@ export const API_SECTIONS = [
51
51
  { name: "zoomTo", kind: "method", params: "scale: number 目标缩放值(世界单位 → CSS 像素的比例);origin?: [x, y] 缩放中心", returns: "this", doc: "直接设成指定比例(像素 / 世界单位)", examples: [{"group":"相机与视图","code":"// zoomTo(scale, origin?):直接给目标比例(世界单位 → CSS 像素)\nview.zoomTo(12)\n","from":"header"}] },
52
52
  { name: "zoomToBounds", kind: "method", params: "bounds: GisViewBounds 要装进画面的世界矩形 [minX, minY, maxX, maxY](也认 { minX, minY, maxX, maxY });padding?: number 四周留白", returns: "this", doc: "把一段世界坐标矩形适应到视图内,退化成一点时只居中不改比例", examples: [{"group":"相机与视图","code":"// zoomToBounds(bounds, padding?):把世界矩形装进画面(数组与对象写法都认)\nview.zoomToBounds([0, 0, 400, 200], 40)\nview.zoomToBounds({ minX: 116, minY: 39, maxX: 117, maxY: 40 })\n","from":"header"}] },
53
53
  { name: "focusOn", kind: "method", params: "target: GisViewFocusTargets 要对准的东西:id / { type: 'point' | 'line' | 'channel' | 'group', id | index } / { channelId }(整条通道)/ { type: 'group', channelId?, groupId } / [x, y] 坐标 / 矩形 / { lngLat } / { center },或者一批(数组取整体包围盒)。字符串按「先节点、再线路」,裸字符串不能表示通道;同 id 用显式 type 消歧,分组必须用 type: 'group'(groupId 全局唯一时可省略 channelId)。缺省只居中、比例一点不动;options.zoom: true 才按解析出的真实范围适配,四类目标共用这一条、没有额外放大倍率;scale 优先级高于 zoom,maxZoom 只给单点 / 单线这类零面积目标补最小范围。options?: GisViewFocusOptions:zoom: true 显式适配、scale 直接给比例、center: true 显式只居中(与缺省一致)、padding 要四周留白(CSS 像素,缺省 40)、maxZoom 限制这次适配的最大比例、select 顺带选中(true 选这次目标,也可另给一批写法)、mode 决定怎么并进当前选中集。目标认不出来或参数非法时什么都不做", returns: "this(相机更新后发 onCameraChange;select 生效时另发 onSelect / onSelectChange)", doc: "把视角移到目标上:单条(搜索命中 / 要素 id / { type: 'point' | 'line' | 'channel', id | index } / { channelId } 整条通道 / { type: 'group', channelId?, groupId } / 坐标 / 矩形 / { lngLat })或一批(数组取整体包围盒 —— 搜到三个节点就是这三个点的中心当屏幕中心);字符串先节点后线路,裸字符串不表示通道,同 id 用 type 消歧,分组必须显式写 type: 'group'(全局唯一 groupId 可省略通道)。缺省只居中、比例一点不动;options.zoom: true 才按解析出的真实范围适配(节点 / 线路 / 通道 / 分组共用这一条,不额外放大),scale 优先级高于 zoom。options 还认 center: true(显式只居中,与缺省一致)、padding、maxZoom、select(顺带选中这批,mode 决定怎么并进当前选中集)", examples: [{"group":"相机与视图","code":"// focusOn(target, options?):对准一个或多个目标(id / 显式类型 / 坐标 / 矩形 / 搜索命中 / 一批)\nview.focusOn('a') // 缺省只居中,比例不动\nview.focusOn('a', { zoom: true, maxZoom: 8 }) // 显式按范围适配\nview.focusOn(['a', 'b'], { zoom: true, padding: 60, select: true })\nview.focusOn({ type: 'point', id: 'a' }) // 节点与线路同 id 时显式消歧\nview.focusOn({ type: 'line', id: 'a' })\nview.focusOn({ type: 'channel', channelId: 'c1' }) // 通道也可以直接写 { channelId: 'c1' }\nview.focusOn({ type: 'group', channelId: 'c1', groupId: 'c1::2' })\nview.focusOn({ type: 'group', groupId: 'global-group' }) // groupId 全局唯一时可省略通道\nview.focusOn([120, 80], { center: true }) // 显式只居中(与缺省一致)\nview.focusOn({ lngLat: [116.4, 39.9] })\n","from":"header"}] },
54
+ { name: "flyTo", kind: "method", params: "目标与世界坐标解析、zoom / scale / center / padding / maxZoom / select / mode 均与 focusOn 同义。options?: GisViewFlyOptions 另认 duration(毫秒,缺省 450;<= 0 立即落位)与 easing('linear' / 'ease-in' / 'ease-out' / 'ease-in-out',缺省 'ease-in-out',也可给自定义 (progress) => eased)。中心线性、比例按对数插值;系统 prefers-reduced-motion: reduce 时立即落位。再次 flyTo、用户拖拽 / 滚轮、setCamera / centerOn / zoom* / fitView / resetView / applyInitialView 都会停在当前帧", returns: "this(相机变化时发 onCameraChange;select 生效时另发选中事件)", doc: "平滑飞到与 focusOn 相同的目标:目标写法与 zoom / scale / center / padding / maxZoom / select / mode 完全同义,另认 duration(毫秒,缺省 450)与 easing(linear / ease-in / ease-out / ease-in-out 或 (progress) => progress)。中心线性插值、比例按对数插值;duration <= 0 或系统要求减少动态效果时立即落位。再次飞行、用户拖拽 / 滚轮或任何程序化改相机都会停在当前帧,不补跳到终点", examples: [{"group":"相机与视图","code":"// flyTo(target, options?):与 focusOn 同一套目标解析,平滑飞过去\nview.flyTo(hit, { zoom: true, duration: 600, easing: 'ease-in-out' })\nview.flyTo(['station-1', 'station-2'], { select: true, duration: 0 }) // 立即落位\nview.flyTo({ center: [120, 80], scale: 12, easing: progress => progress * progress })\n","from":"header"}] },
55
+ { name: "flyToCamera", kind: "method", params: "camera: GisViewCameraTarget 直接给相机目标 { center?, scale? }:没写 center / scale 的那一项沿用当前相机,不经过要素解析,也不改选中与数据;options?: GisViewFlyCameraOptions 的 duration / easing 与 flyTo 同义。中心 / 比例插值、减少动态效果、用户手势取消都走同一条相机动画", returns: "this(相机变化时发 onCameraChange;目标非法时保持当前相机)", doc: "直接飞到相机目标 { center?, scale? }:不写的那一项沿用当前相机,不经过要素解析、也不改选中与数据;duration / easing 与 flyTo 同义,参数非法时保持当前相机", examples: [{"group":"相机与视图","code":"// flyToCamera(camera, options?):直接飞相机目标;没写的 center / scale 沿用当前相机\nview.flyToCamera({ center: [120, 80], scale: 3 }, { duration: 600, easing: 'ease-out' })\nview.flyToCamera({ scale: 5 }, { duration: 0 }) // 中心不动,比例立即落到 5\nview.flyToCamera({ center: [116.4, 39.9] }) // 比例沿用当前相机\n","from":"header"}] },
54
56
  { name: "search", kind: "method", params: "input: string | GisViewSearchOptions 关键字,或 { keyword, scope, fields, limit } 这类选项。scope 可选 'points' / 'lines' / 'channels' / 'groups',也认与 focusOn 一致的单数别名 'point' / 'line' / 'channel' / 'group' 及数组;省略或写错时四类全搜。limit 对每一类分别计数。返回的 groups / hits 带分组命中(channelIndex / groupId / groupIndex,item 是轻量快照)—— 只返回结果、不动视角,要定位就自己调 focusOn(result.hits, …)", returns: "GisViewSearchResult:keyword / scope / points / lines / channels / groups / hits / total / truncated / durationMs", doc: "按关键字搜索节点 / 线路 / 通道 / 通道分组并返回命中:scope 认复数的 points / lines / channels / groups,也认与 focusOn 一致的单数别名 point / line / channel / group;结果分 points / lines / channels / groups 四类,分组命中带 channelIndex / groupId / groupIndex,可直接交给 focusOn / selectFeatures。不动视角:要不要聚焦由调用方自己调 focusOn,见「搜索与定位」", examples: [{"group":"相机与视图","code":"// search(input) / searchAsync(input):搜索(只返回结果、不动视角)\nconst hits = view.search('甲站')\nconst scoped = view.search({ keyword: '甲', scope: ['points', 'channels', 'groups'], limit: 10 })\nconst groupHits = view.search({ keyword: 'c1::2', scope: 'group' }) // 单数别名与 focusOn 一致\nview.focusOn(groupHits.groups[0], { zoom: true, select: true }) // 按整组范围适配并选中成员回线\nview.focusOn(hits.hits, { zoom: true, maxZoom: 8 }) // 命中集直接丢给 focusOn\nconst asyncHits = await view.searchAsync('甲站') // 大表走 Worker;stale 说明这一份不作数了\n","from":"header"}] },
55
57
  { name: "searchAsync", kind: "method", params: "同上;分组范围的当前轻量快照会随请求交给 Worker", returns: "Promise<GisViewSearchResult>:多一个 worker(是不是在 Worker 里算的)与 stale(回来时数据已经改过、或又搜过一次,这一份不作数了)", doc: "同一份口径的异步版:数据量大时把扫描放进 Worker(10 万点 / 10 万线下同步要占主线程 40 ms 上下的那一段),返回 Promise<GisViewSearchResult>;结果带 worker 与 stale 两个字段,见「异步搜索」", examples: [{"group":"相机与视图","code":"// search(input) / searchAsync(input):搜索(只返回结果、不动视角)\nconst hits = view.search('甲站')\nconst scoped = view.search({ keyword: '甲', scope: ['points', 'channels', 'groups'], limit: 10 })\nconst groupHits = view.search({ keyword: 'c1::2', scope: 'group' }) // 单数别名与 focusOn 一致\nview.focusOn(groupHits.groups[0], { zoom: true, select: true }) // 按整组范围适配并选中成员回线\nview.focusOn(hits.hits, { zoom: true, maxZoom: 8 }) // 命中集直接丢给 focusOn\nconst asyncHits = await view.searchAsync('甲站') // 大表走 Worker;stale 说明这一份不作数了\n","from":"header"}] },
56
58
  { name: "setCamera", kind: "method", params: "camera: Partial<GisViewCamera> 要改的相机字段 { x, y, scale }(只写一个也行)", returns: "this", doc: "读写 { center, scale }", examples: [{"group":"相机与视图","code":"// setCamera(camera) / getCamera():读写相机(只写一个字段也行)\nview.setCamera({ scale: 10 })\nview.setCamera({ x: 200, y: 120 })\nconst camera = view.getCamera()\n","from":"header"}] },
57
59
  { name: "getCamera", kind: "method", params: "无", returns: "GisViewCamera", doc: "读写 { center, scale }", examples: [{"group":"相机与视图","code":"// setCamera(camera) / getCamera():读写相机(只写一个字段也行)\nview.setCamera({ scale: 10 })\nview.setCamera({ x: 200, y: 120 })\nconst camera = view.getCamera()\n","from":"header"}] },
60
+ { name: "stopCameraAnimation", kind: "method", params: "无", returns: "this:停止当前相机飞行并停在当前帧;没有飞行时是空操作", doc: "停止当前相机飞行(停在当前帧,返回实例)/ 读当前飞行 { active, progress, duration, from, to }(没有动画时 null)", examples: [{"group":"相机与视图","code":"// stopCameraAnimation() / getCameraAnimation():停止飞行 / 读当前飞行读数(没有动画时为 null)\nconst flight = view.getCameraAnimation() // { active, progress, duration, from, to }\nview.stopCameraAnimation() // 停在当前帧,不补跳到终点\n","from":"header"}] },
61
+ { name: "getCameraAnimation", kind: "method", params: "无", returns: "GisViewCameraAnimation | null:{ active, progress, duration, from, to },progress 是时间进度(0 ~ 1),没有动画时 null", doc: "停止当前相机飞行(停在当前帧,返回实例)/ 读当前飞行 { active, progress, duration, from, to }(没有动画时 null)", examples: [{"group":"相机与视图","code":"// stopCameraAnimation() / getCameraAnimation():停止飞行 / 读当前飞行读数(没有动画时为 null)\nconst flight = view.getCameraAnimation() // { active, progress, duration, from, to }\nview.stopCameraAnimation() // 停在当前帧,不补跳到终点\n","from":"header"}] },
58
62
  { name: "getZoomBaseScale", kind: "method", params: "无", returns: "number 缩放联动的基准比例(pointZoomScale / lineZoomScale 共用那一份;缺省是首次适应视图时的 camera.scale)", doc: "读 / 重定缩放联动的基准比例(缺省是首次适应视图时的比例):不传参数就取当下相机的比例 —— 把现在这一屏当成「原样大小」,之后放大缩小都从它算倍数;配合 pointZoomScale / lineZoomScale 使用", examples: [{"group":"相机与视图","code":"// getZoomBaseScale() / setZoomBaseScale(scale?):缩放联动的基准比例(配合 pointZoomScale / lineZoomScale)\nconst zoomBase = view.getZoomBaseScale() // 基准(缺省首次适应视图时的 camera.scale)\nview.setZoomBaseScale() // 以当下这一屏为「原样大小」,之后放大缩小都从它算倍数\nview.setZoomBaseScale(2.5) // 也可以直接给一个比例\n","from":"header"}] },
59
63
  { name: "setZoomBaseScale", kind: "method", params: "scale?: number 新的基准比例;不传取当下相机的比例(把现在这一屏当成「原样大小」)", returns: "this", doc: "读 / 重定缩放联动的基准比例(缺省是首次适应视图时的比例):不传参数就取当下相机的比例 —— 把现在这一屏当成「原样大小」,之后放大缩小都从它算倍数;配合 pointZoomScale / lineZoomScale 使用", examples: [{"group":"相机与视图","code":"// getZoomBaseScale() / setZoomBaseScale(scale?):缩放联动的基准比例(配合 pointZoomScale / lineZoomScale)\nconst zoomBase = view.getZoomBaseScale() // 基准(缺省首次适应视图时的 camera.scale)\nview.setZoomBaseScale() // 以当下这一屏为「原样大小」,之后放大缩小都从它算倍数\nview.setZoomBaseScale(2.5) // 也可以直接给一个比例\n","from":"header"}] },
60
- { name: "getBounds", kind: "method", params: "无", returns: "GisViewBounds", doc: "数据范围(没有点时回退到背景 GeoJSON 的 rawBounds,也就是 aspectScale 之前的真实经纬度范围)", examples: [{"group":"相机与视图","code":"// getBounds() / getViewRect() / getViewport():数据范围 / 视口世界矩形 / 画布尺寸读数\nconst dataBounds = view.getBounds()\nconst viewRect = view.getViewRect()\nconst { cssWidth, cssHeight, pixelRatio } = view.getViewport()\n","from":"header"}] },
64
+ { name: "getBounds", kind: "method", params: "无", returns: "GisViewBounds:每次返回独立副本;重复调用命中数据包围盒缓存,改点 / 改线 / 追加或拖拽后下一次读数自动重建", doc: "数据范围(没有点时回退到背景 GeoJSON 的 rawBounds,也就是 aspectScale 之前的真实经纬度范围);每次返回独立副本,重复调用命中缓存", examples: [{"group":"相机与视图","code":"// getBounds() / getViewRect() / getViewport():数据范围 / 视口世界矩形 / 画布尺寸读数\nconst dataBounds = view.getBounds()\nconst viewRect = view.getViewRect()\nconst { cssWidth, cssHeight, pixelRatio } = view.getViewport()\n","from":"header"}] },
61
65
  { name: "getViewport", kind: "method", params: "无", returns: "{ cssWidth, cssHeight, pixelRatio, displayScale }:画布 CSS 尺寸、设备像素比与渲染分辨率比例", doc: "/** * 当前视口。", examples: [{"group":"相机与视图","code":"// getBounds() / getViewRect() / getViewport():数据范围 / 视口世界矩形 / 画布尺寸读数\nconst dataBounds = view.getBounds()\nconst viewRect = view.getViewRect()\nconst { cssWidth, cssHeight, pixelRatio } = view.getViewport()\n","from":"header"}] },
62
66
  { name: "getViewRect", kind: "method", params: "无", returns: "GisViewBounds", doc: "当前可视范围的世界坐标矩形;自建缩略图 / 坐标读数用它换算视口框,内置鹰眼图见「鹰眼图」", examples: [{"group":"相机与视图","code":"// getBounds() / getViewRect() / getViewport():数据范围 / 视口世界矩形 / 画布尺寸读数\nconst dataBounds = view.getBounds()\nconst viewRect = view.getViewRect()\nconst { cssWidth, cssHeight, pixelRatio } = view.getViewport()\n","from":"header"}] },
63
67
  { name: "isLayoutReady", kind: "method", params: "无", returns: "boolean", doc: "大数据发散渲染(progressiveInit)是否已经铺完;没铺完时标签与拾取只看得到已经画出去的那部分", examples: [{"group":"相机与视图","code":"// isLayoutReady():容器量到尺寸、首批布局完成没有\nconst layoutReady = view.isLayoutReady()\n","from":"header"}] },
@@ -106,7 +110,8 @@ export const API_SECTIONS = [
106
110
  { name: "setDropPreview", kind: "method", params: "preview: GisViewDropPreviewInput | null:kind('point' / 'line' / 'channel' / 'waypoint' / 'decoration' / 'label',缺省按 item 推断)、screen(画布 CSS 像素)或 world(世界坐标)至少给一个、item 是准备落地的那一份字段(与 addPoint / addLine 同一份)、from(line / channel 的起点);传 null 清掉预览", returns: "GisViewDropPreview | null 解析后的读数 { kind, screen, world, size, styleSize, radius, color, strokeColor, strokeWidth, opacity, symbol, width, dashed }:走的是与真实要素完全相同的样式链(规则 -> 全局样式 -> 这一份字段),styleSize 与落地后 getPointStyle().size 是同一个数(size 是这一刻画出来的宽度,不悬停 / 不选中时两者相同)", doc: "/** * 拖拽落点预览。", examples: [{"group":"坐标、拾取与读数","code":"// setDropPreview(preview) / getDropPreview():拖拽落点预览(setDropPreview(null) 清掉)\nview.setDropPreview({ kind: 'point', screen: [320, 200], item: { name: '新站' } })\nconst preview = view.getDropPreview()\nview.setDropPreview(null)\n","from":"header"}] },
107
111
  { name: "getDropPreview", kind: "method", params: "无", returns: "GisViewDropPreview | null:当前拖拽落点预览的读数,没有预览时 null", doc: "/** * 拖拽落点预览。", examples: [{"group":"坐标、拾取与读数","code":"// setDropPreview(preview) / getDropPreview():拖拽落点预览(setDropPreview(null) 清掉)\nview.setDropPreview({ kind: 'point', screen: [320, 200], item: { name: '新站' } })\nconst preview = view.getDropPreview()\nview.setDropPreview(null)\n","from":"header"}] },
108
112
  { name: "getPoint", kind: "method", params: "ref: GisViewFeatureRef 节点定位:id、下标、{ id } / { index }", returns: "GisViewPointInfo | null", doc: "按 id / 下标 / { id } / { index } 取一个节点:拾取载荷(item / x / y / layer / layerRank)之外再给一份屏幕半径 radius;找不到返回 null。自建读数面板、右键菜单用它,省掉「自己遍历 getData() + 算投影」那一段", examples: [{"group":"坐标、拾取与读数","code":"// getPoint(ref) / getLine(ref) / getChannel(ref):一个要素的几何读数\nconst pointInfo = view.getPoint('a')\nconst lineInfo = view.getLine('l1')\nconst channelInfo = view.getChannel('c1')\n","from":"header"}] },
109
- { name: "getPointStyle", kind: "method", params: "index: number 节点下标", returns: "GisViewPointStyleSnapshot | null:节点解析后的样式快照 { index, size, symbol, zIndex },size / symbol 取样式链(节点自身 > 规则 > pointStyle)定下来的那一份,含 sizeScale、不含悬停 / 选中样式与热力倍率;落点预览的读数与它同源", doc: "/** * 节点解析之后的样式快照(size / symbol / zIndex,含 sizeScale、不含状态样式与热力倍率)。", examples: [{"group":"坐标、拾取与读数","code":"// getPointStyle(index):节点解析后的样式快照(样式链定下来的那一份)\nconst pointStyle = view.getPointStyle(0)\n","from":"header"}] },
113
+ { name: "getPointStyle", kind: "method", params: "index: number 节点下标", returns: "GisViewPointStyleSnapshot | null:节点解析后的样式快照 { index, size, symbol, zIndex },size / symbol 取样式链(节点自身 > 规则 > pointStyle)定下来的那一份,含 sizeScale、不含悬停 / 选中样式与热力倍率;落点预览的读数与它同源", doc: "节点 / 线路解析之后的样式快照:节点的 size / symbol 取样式链(自身 > 规则 > 全局),线路的 width / color / opacity / zIndex 同源;不含悬停 / 选中样式、整体倍率与热力倍率,下标不存在时返回 null。合并节点与鹰眼图沿用主图尺寸时走这一份", examples: [{"group":"坐标、拾取与读数","code":"// getPointStyle(index):节点解析后的样式快照(样式链定下来的那一份)\nconst pointStyle = view.getPointStyle(0)\n","from":"header"}] },
114
+ { name: "getLineStyle", kind: "method", params: "index: number 线路在 lines 里的下标", returns: "GisViewLineStyleSnapshot | null:{ index, width, color, opacity, zIndex };width 取样式链(线路自身 > 规则 > lineStyle)定下来的原始线宽,不含 lineWidthScale / 缩放联动 / 热力倍率,color 是解析后的 RGBA(0 ~ 1)。局部更新与线路窄样式快路径之后读到的都是最新值;下标不存在时 null", doc: "节点 / 线路解析之后的样式快照:节点的 size / symbol 取样式链(自身 > 规则 > 全局),线路的 width / color / opacity / zIndex 同源;不含悬停 / 选中样式、整体倍率与热力倍率,下标不存在时返回 null。合并节点与鹰眼图沿用主图尺寸时走这一份", examples: [{"group":"坐标、拾取与读数","code":"// getLineStyle(index):线路解析后的样式快照(原始线宽 / RGBA / 透明度 / 层级)\nconst lineStyle = view.getLineStyle(0) // { index, width, color, opacity, zIndex } 或 null\n","from":"header"}] },
110
115
  { name: "getLine", kind: "method", params: "ref 线路定位(同上)", returns: "GisViewLineInfo | null", doc: "取一条线路:拾取载荷 + path / bounds / color / width(与 listLines() 的一项同一份口径),通道回线还带 channelId / groupId / channelIndex;找不到返回 null", examples: [{"group":"坐标、拾取与读数","code":"// getPoint(ref) / getLine(ref) / getChannel(ref):一个要素的几何读数\nconst pointInfo = view.getPoint('a')\nconst lineInfo = view.getLine('l1')\nconst channelInfo = view.getChannel('c1')\n","from":"header"}] },
111
116
  { name: "getChannel", kind: "method", params: "ref 通道定位:通道 id 或下标", returns: "GisViewChannelSnapshot | null", doc: "取一条通道:数据那一份(index / item / id)+ 成员表(lineIndexes / skeleton / offsets / paths)+ 分组上下文 context(几组 / 当前哪组 / 每组拐点数)、from / to / anchored / spacing;找不到返回 null", examples: [{"group":"坐标、拾取与读数","code":"// getPoint(ref) / getLine(ref) / getChannel(ref):一个要素的几何读数\nconst pointInfo = view.getPoint('a')\nconst lineInfo = view.getLine('l1')\nconst channelInfo = view.getChannel('c1')\n","from":"header"}] },
112
117
  { name: "listPoints", kind: "method", params: "options?: GisViewListOptions:indexes(只看这几个下标)、inView: boolean(只要当前视口里的)、withScreen: boolean(连屏幕坐标一起给)、visibleOnly: boolean(跳过隐藏的)、limit: number(最多几条)", returns: "GisViewListedPoint[]", doc: "按条件列节点快照 { index, item, x, y, radius, layerRank, screen? }:选项见 GisViewListOptions(indexes / inView / limit / withScreen / visibleOnly),可见判定与 isPointVisible 是同一份", examples: [{"group":"坐标、拾取与读数","code":"// listPoints(options?) / listLines(options?):按条件列一批\nconst listedPoints = view.listPoints({ limit: 5, withScreen: true })\nconst listedLines = view.listLines({ inView: true, limit: 200 })\n","from":"header"}] },
@@ -344,9 +349,11 @@ export const API_SECTIONS = [
344
349
  {
345
350
  title: "属性",
346
351
  items: [
347
- { name: "el", kind: "property", params: "HTMLElement", returns: "HTMLElement", doc: "组件插入的 .gis-view 根节点(destroy() 会移除它;容器本身不动)", examples: [{"group":"属性","code":"// el / canvas / gl:容器、画布与 WebGL2 上下文(gl 可能为 null —— 还没建好或走了别的路)\nconst host = view.el\nconst canvas = view.canvas\nconst gl = view.gl","from":"header"}] },
348
- { name: "canvas", kind: "property", params: "HTMLCanvasElement", returns: "HTMLCanvasElement", doc: "WebGL2 画布元素(导出 / 截图 / 自己叠加 DOM 时定位用它)", examples: [{"group":"坐标、拾取与读数","code":"//(pick / getContextAt / nearestPointsAt 这些吃画布像素的方法先用这一对转;自动处理 canvas rect 与宿主缩放)\nconst [sx, sy] = view.clientToScreen(event.clientX, event.clientY)\nconst [fixedX, fixedY] = view.screenToClient(320, 200) // 摆 position: fixed 的浮层 / 菜单\n","from":"header"},{"group":"属性","code":"// el / canvas / gl:容器、画布与 WebGL2 上下文(gl 可能为 null —— 还没建好或走了别的路)\nconst host = view.el\nconst canvas = view.canvas\nconst gl = view.gl","from":"header"}] },
349
- { name: "gl", kind: "property", params: "WebGL2RenderingContext | null", returns: "WebGL2RenderingContext | null", doc: "引擎拿到的 WebGL2 上下文,创建失败时 null(这时 onError 会报一条)", examples: [{"group":"属性","code":"// el / canvas / gl:容器、画布与 WebGL2 上下文(gl 可能为 null —— 还没建好或走了别的路)\nconst host = view.el\nconst canvas = view.canvas\nconst gl = view.gl","from":"header"}] },
352
+ { name: "el", kind: "property", params: "HTMLElement", returns: "HTMLElement", doc: "组件插入的 .gis-view 根节点(destroy() 会移除它;容器本身不动)", examples: [{"group":"属性","code":"// el / canvas / gl / cameraAnimating / dataVersion:容器、画布、WebGL2 上下文、相机是否在飞行、数据修订号\nconst host = view.el\nconst canvas = view.canvas\nconst gl = view.gl\nconst cameraAnimating = view.cameraAnimating\nconst dataVersion = view.dataVersion // 数据变更 +1;只改全局样式 / 配置不变","from":"header"}] },
353
+ { name: "canvas", kind: "property", params: "HTMLCanvasElement", returns: "HTMLCanvasElement", doc: "WebGL2 画布元素(导出 / 截图 / 自己叠加 DOM 时定位用它)", examples: [{"group":"坐标、拾取与读数","code":"//(pick / getContextAt / nearestPointsAt 这些吃画布像素的方法先用这一对转;自动处理 canvas rect 与宿主缩放)\nconst [sx, sy] = view.clientToScreen(event.clientX, event.clientY)\nconst [fixedX, fixedY] = view.screenToClient(320, 200) // 摆 position: fixed 的浮层 / 菜单\n","from":"header"},{"group":"属性","code":"// el / canvas / gl / cameraAnimating / dataVersion:容器、画布、WebGL2 上下文、相机是否在飞行、数据修订号\nconst host = view.el\nconst canvas = view.canvas\nconst gl = view.gl\nconst cameraAnimating = view.cameraAnimating\nconst dataVersion = view.dataVersion // 数据变更 +1;只改全局样式 / 配置不变","from":"header"}] },
354
+ { name: "gl", kind: "property", params: "WebGL2RenderingContext | null", returns: "WebGL2RenderingContext | null", doc: "引擎拿到的 WebGL2 上下文,创建失败时 null(这时 onError 会报一条)", examples: [{"group":"属性","code":"// el / canvas / gl / cameraAnimating / dataVersion:容器、画布、WebGL2 上下文、相机是否在飞行、数据修订号\nconst host = view.el\nconst canvas = view.canvas\nconst gl = view.gl\nconst cameraAnimating = view.cameraAnimating\nconst dataVersion = view.dataVersion // 数据变更 +1;只改全局样式 / 配置不变","from":"header"}] },
355
+ { name: "cameraAnimating", kind: "property", params: "boolean", returns: "boolean", doc: "相机是否正在飞行(只读)。按钮据此在「飞向 / 停止」之间切换,不触发重绘", examples: [{"group":"属性","code":"// el / canvas / gl / cameraAnimating / dataVersion:容器、画布、WebGL2 上下文、相机是否在飞行、数据修订号\nconst host = view.el\nconst canvas = view.canvas\nconst gl = view.gl\nconst cameraAnimating = view.cameraAnimating\nconst dataVersion = view.dataVersion // 数据变更 +1;只改全局样式 / 配置不变","from":"header"}] },
356
+ { name: "dataVersion", kind: "property", params: "number", returns: "number", doc: "数据修订号(只读):每次数据变更 +1,onDataChange 载荷里是同一个数;只改全局配置 / 样式不推。外部缓存、Worker 请求与增量计算据它判断是否重算", examples: [{"group":"属性","code":"// el / canvas / gl / cameraAnimating / dataVersion:容器、画布、WebGL2 上下文、相机是否在飞行、数据修订号\nconst host = view.el\nconst canvas = view.canvas\nconst gl = view.gl\nconst cameraAnimating = view.cameraAnimating\nconst dataVersion = view.dataVersion // 数据变更 +1;只改全局样式 / 配置不变","from":"header"}] },
350
357
  ]
351
358
  },
352
359
  ]
@@ -385,7 +392,7 @@ export const API_OPTIONS = [
385
392
  { name: "labelStates", type: "GisViewLabelState[]", defaultValue: "无", doc: "标签的运行时状态(getLabelStates() 的那一份:拖出来的偏移、改过的内容与样式、运行时加的标签、隐藏覆盖):创建时喂回来就回显,等价于创建之后调 setLabelStates(states);updateOptions({ labelStates }) 同样认。exportData({ format: 'input' }) 的结果里就叫 labelStates,存档 → 回灌直接接上" },
386
393
  { name: "graphics", type: "GisViewGraphic[]", defaultValue: "无", doc: "与节点无关的扩展图形:按世界坐标放 SVG 路径 / 图片 / Canvas,支持锚点、偏移、旋转、透明度、zIndex 与 scaleWithView;位于画布之上、标签之下,运行时用 addGraphic / addGraphics / updateGraphic / removeGraphic / clearGraphics 增删改,见「扩展图形(graphic)」" },
387
394
  { name: "tooltip", type: "GisViewTooltipOptions", defaultValue: "无", doc: "悬停提示:点 / 线 / 通道分别配置内容,见「悬浮提示」" },
388
- { name: "minimap", type: "GisViewMinimapOptions | null", defaultValue: "无", doc: "内置鹰眼图:位置、尺寸、节点 / 线路 / 视口框三份样式与交互都可配,extent 决定小图按数据范围还是「数据 ∪ 底图」铺(默认 auto,GeoJSON 底图不会缩成一个点),extentFollowCamera 默认 false、打开后才允许 auto 范围随相机收窄。zoomable 三态互斥:false 关闭、true 手动缩放小图自身、'follow' 让整体范围跟随主图(followZoomScale 是主图倍数的指数,跟随模式下 setMinimapZoom / zoomMinimapBy 不抢控制权);空白处拖动可平移小图或直接框选让主图显示过去(dragAction,box 不依赖缩放,手动模式下 Ctrl / ⌘ 才切换动作),每格倍率 zoomStep。通道还能只画一根;小图同样支持规则(pointRules / lineRules,缺省沿用主图规则的颜色、层级、最终节点尺寸与图标、样式链线宽,节点 / 线路尺寸按两边视口比例缩放且不受主图相机倍数影响),可以只画某几层(levels)、关掉分层叠画(layered)、按三组系数给节点与线路定尺寸(整体倍数 pointSizeScale / lineWidthScale 对自有与继承要素都生效;跟随小图倍数 pointZoomScale / lineZoomScale 在小图自身放大时也作用于继承要素;跟随主视图地图倍数 pointMapZoomScale / lineMapZoomScale 只作用于自有规则 / 样式),视口框与框选矩形的颜色 / 背景 / 边框 / 圆角也能配(boxStyle / selectStyle),extent 还能直接写死一份世界范围、容器可加 className / style、layers 按 placement 分数据前 / 数据后、段内按 order 拆出多层自绘内容(旧 draw 钩子仍兼容并排在最后)、onInteraction 在手势结束时给出类型 / 世界坐标 / 相机、maxPixelRatio 限制备份倍率上限,不配则不产生任何 DOM,见「鹰眼图」" },
395
+ { name: "minimap", type: "GisViewMinimapOptions | null", defaultValue: "无", doc: "内置鹰眼图:位置、尺寸、节点 / 线路 / 视口框三份样式与交互都可配,extent 决定小图按数据范围还是「数据 ∪ 底图」铺(默认 auto,GeoJSON 底图不会缩成一个点),extentFollowContent 默认 false,首次铺好后内容变化不再改小图范围;extentFollowCamera 默认 false、打开后才允许 auto 范围随相机收窄。zoomable 三态互斥:false 关闭、true 手动缩放小图自身、'follow' 让整体范围跟随主图(followZoomScale 是主图倍数的指数,跟随模式下 setMinimapZoom / zoomMinimapBy 不抢控制权);空白处拖动可平移小图或直接框选让主图显示过去(dragAction,box 不依赖缩放,手动模式下 Ctrl / ⌘ 才切换动作),每格倍率 zoomStep。通道还能只画一根;小图同样支持规则(pointRules / lineRules,缺省沿用主图规则的颜色、层级、最终节点尺寸与图标、样式链线宽,节点 / 线路尺寸按两边视口比例缩放且不受主图相机倍数影响),可以只画某几层(levels)、关掉分层叠画(layered)、按三组系数给节点与线路定尺寸(整体倍数 pointSizeScale / lineWidthScale 对自有与继承要素都生效;跟随小图倍数 pointZoomScale / lineZoomScale 在小图自身放大时也作用于继承要素;跟随主视图地图倍数 pointMapZoomScale / lineMapZoomScale 只作用于自有规则 / 样式),视口框与框选矩形的颜色 / 背景 / 边框 / 圆角也能配(boxStyle / selectStyle),extent 还能直接写死一份世界范围、容器可加 className / style、layers 按 placement 分数据前 / 数据后、段内按 order 拆出多层自绘内容(旧 draw 钩子仍兼容并排在最后)、onInteraction 在手势结束时给出类型 / 世界坐标 / 相机、maxPixelRatio 限制备份倍率上限,不配则不产生任何 DOM,见「鹰眼图」" },
389
396
  { name: "filter", type: "GisViewFilterInput | null", defaultValue: "无", doc: "初始筛选条件,等价于创建之后调用 setFilter;mode 缺省 'hide',写 'remove' 则删除不命中的要素,见「筛选」" },
390
397
  { name: "filterWorker", type: "boolean | GisViewFilterWorkerOptions", defaultValue: "{ threshold: 20000 }", doc: "筛选是否用 Web Worker 计算:默认点 + 线总数超过阈值才用,false 表示始终同步算" },
391
398
  { name: "searchWorker", type: "boolean | GisViewSearchWorkerOptions", defaultValue: "{ threshold: 20000 }", doc: "[异步搜索](14-视图与筛选.md#搜索与定位)是否用 Web Worker 计算:默认点 + 线总数超过阈值才用,false 表示 searchAsync 也同步算;同步的 search 一直在主线程算,不受这一项影响" },
@@ -445,7 +452,7 @@ export const API_OPTIONS = [
445
452
  { name: "pixelRatio", type: "number", defaultValue: "devicePixelRatio", doc: "手动指定设备像素比(夹在 0.5 ~ 3);宿主缩放(CSS zoom / transform: scale)的比例会乘在它上面,合计夹在 0.5 ~ 4" },
446
453
  { name: "maxCanvasPixels", type: "number", defaultValue: "4000000", doc: "画布总像素预算:cssWidth × cssHeight × 倍率² 超过它时按 sqrt(预算 / CSS 面积) 压渲染倍率(全屏与高分屏不因像素数翻十倍而掉帧);传 0 不设上限" },
447
454
  { name: "antialias", type: "boolean", defaultValue: "开(软件光栅自动关)", doc: "画布是否开 MSAA。同一份十万级线段实测:MSAA 4× 下单帧光栅化是关掉时的近 5 倍(见「画质」里的实测表),关掉能明显提速、代价是线条与圆形边缘有锯齿;当前实际状态见 getStats().antialias(软件光栅下引擎默认关,写 true 可强制打开)" },
448
- { name: "interactionThinLines", type: "boolean", defaultValue: "true", doc: "交互期细线快路径:可见线段全部细到 3px 以内且没有虚线时,拖动 / 缩放期间改用 gl.LINES 画(1 设备像素、无光晕与虚线),停手立刻回到四边形展开。位置不跳、悬停 / 选中不受影响;这一帧走没走快路径见 getStats().thinLines,实测见「画质」" },
455
+ { name: "interactionThinLines", type: "boolean", defaultValue: "true", doc: "交互期细线快路径:可见线段最大半宽 ≤ 0.6 设备像素(dpr = 1 时约 1.2px 线宽)且整批没有虚线时,拖动 / 缩放期间改用 gl.LINES 画(1 设备像素、无光晕与虚线),停手立刻回到四边形展开。2px 实线不会走这一档,但全实线四边形另有轻量片元。位置不跳、悬停 / 选中不受影响;这一帧走没走快路径见 getStats().thinLines,实测见「画质」" },
449
456
  { name: "interactionNoMsaa", type: "boolean", defaultValue: "true", doc: "非 MSAA 后备缓冲(交互 / 动画期):拖动 / 缩放 / 框选期间与动画在跑的那些帧,整帧先画进一张不带 MSAA 的后备贴图,帧末整幅贴回画布;停手(或动画停帧)之后那一帧照旧直接画进带 MSAA 的画布,所以静止画面逐像素不变(代价是这些活动帧的边缘暂时没有抗锯齿)。十万级实测交互期单帧 133 → 36.6 ms、拖动 p50 130 → 16 ~ 22 ms,动画帧 212 → 53 ms/帧(只开涟漪 187 → 48、只开线路动点 199 → 47);透明底 / 自定义底色的导出场景与没开 MSAA 的画布不走这条,这一帧走没走见 getStats().noMsaa,实测见「画质」" },
450
457
  { name: "renderer", type: "'auto' | 'webgl2' | 'webgpu'(也认布尔开关)", defaultValue: "'auto'", doc: "渲染后端开关:当前实装的绘制后端只有 WebGL2 —— 十万级下 frameMs 只有 0.05 ~ 0.2 ms,开销在填充率与 DOM 覆盖层上,换 WebGPU 省不到(第 18 章),所以 'auto' 只会在后台探一次 WebGPU 能力、绘制仍走 WebGL2,'webgl2' 连探测都不跑(无 GPU 的远程桌面里省一次 requestAdapter),'webgpu' 探完明确报一句「已回退 WebGL2、为什么」;true / false 等价于 'webgpu' / 'webgl2'。读数用 getRendererInfo(),见「渲染后端(WebGPU 开关)」" },
451
458
  { name: "ariaLabel", type: "string", defaultValue: "GIS 视图", doc: "画布的无障碍名称" },
@@ -57,7 +57,7 @@ export const DEMOS = [
57
57
  id: 'minimap',
58
58
  title: '鹰眼图配置',
59
59
  group: 'interact',
60
- blurb: '尺寸 / 位置 / 范围 / 规则 / 层级 / 小图缩放与备份倍率一页调完;另有两层自定义绘制演示 layers 的扩展方式。',
60
+ blurb: '尺寸 / 位置 / 范围 / 规则 / 层级 / 小图缩放与备份倍率一页调完;范围默认锁定、筛选不跳,顶部手柄可拖动整张鹰眼图并复位;另有两层自定义绘制演示 layers 的扩展方式。',
61
61
  doc: DOC_VIEW,
62
62
  component: () => import('./MinimapDemo.vue')
63
63
  },
@@ -5,9 +5,11 @@
5
5
  - **底图**:`minimap.js` 把节点与线条直接写进一块离屏像素缓冲(`ImageData`),按「层级 + 颜色 + 线宽 + 透明度」分桶后再画 —— 绘制次数随分桶数走,不随数据量走;底图只在数据或筛选结果变化时重画;节点像素结果按「数据引用 + 尺寸 + 范围 + 变换 + 样式」缓存,同一份数据前后两次重画直接复用(十万点重铺 20ms → 0.3ms),数据范围也按数据对象进 `WeakMap`。
6
6
  - **视口框**:单独一个 DOM 元素,相机变化只改 `transform`(不重画底图),所以拖动小图不掉帧。
7
7
  - **挂载与位置**:`minimap.container` 接受 `HTMLElement` 或选择器,把 `.gis-view__minimap` 根节点挂到外部宿主;换容器只 `append` 同一根节点,画布、缓存与事件监听都不重建,`destroy()` 从当前宿主摘掉。`offset` 是相对 `position` 角落的 `[x, y]` 位移(正数向右 / 向下),`updateOptions` 只改 `left` / `right` / `top` / `bottom`,因此整图拖动不需要重画小图;根节点通过 `getMinimapElement()` 暴露给外部手势。
8
+ - **整图拖动示例**:`docs/demos/MinimapDemo.vue` 在根节点顶部追加一个独立手柄,手柄的 `pointerdown` 直接 `stopPropagation`,窗口级 `pointermove` / `pointerup` 累计位移并写回 `minimap.offset`;小图内部的框选、平移与视口框拖动都不受影响。方向键按 2px(Shift 10px)微调,复位按钮把 `offset` 写回 `[0, 0]`。
8
9
  - **规则**:小图可以有自己的 `pointRules` / `lineRules`(颜色、半径 / 线宽、形状、层级),不配时沿用主图样式链:颜色 / 描边色 / 层级取规则,节点尺寸与符号取引擎最终解析结果(点自身 > 主图规则 > `pointStyle`),线路线宽取样式链的原始线宽(不含主图整体倍数 / 缩放联动 / 热力倍数)。`inheritSize` / `inheritWidth` 标记的节点 / 线路再乘一次「小图 CSS 视口宽高 ÷ 主图 CSS 视口宽高」的较小比例(`inheritedSizeFactor()`),这一份只跟两边视口尺寸有关,主图相机缩放不会改继承要素的大小;小图自身放大时仍可按 `pointZoomScale` / `lineZoomScale` 叠加,`pointSizeScale` / `lineWidthScale` 对自有与继承要素统一生效,`pointMapZoomScale` / `lineMapZoomScale` 只作用于小图自有规则 / 样式。小图自己的尺寸不受视口比例这一步影响。圆形按主图的面积对齐系数还原真实直径;图片 / SVG 图标与自定义图元异步解码后单独盖在点层上,解码前先用小图基准尺寸的圆 / 方回落,完成后只失效点层并补一帧。
9
10
  - **交互**:视口框上按下 = 拖框;空白处长按(`longPressDelay`)= 视角跟随;`zoomable` 三态互斥:`true` 手动缩放小图自身(滚轮按 `zoomStep`、锚点落光标处,Ctrl / ⌘ + 滚轮留给主图),`'follow'` 让整体范围跟随主图(`followZoomScale` 是主图倍数的指数,`setMinimapZoom` / `zoomMinimapBy` 不抢控制权),`false` 只缩放主图。`dragAction` 决定空白处拖动是平移小图还是框选,`box` 不依赖 `zoomable`;只有手动模式按住 Ctrl / ⌘ 才自动切到另一个动作。拖框与视角跟随带来的相机变化是「程序化」的:标签层不进交互态(`hideOnInteract` 不会把主视图的标签收起来),拖动结束补一次真实排版。每次真正有位移的手势结束时通过 `onInteraction` 发一条 `{ type, originalEvent, local, world, zoom, extent, camera, viewport }`(`type` 为 `box-drag` / `select` / `pan` / `zoom` / `wheel-main` / `long-press`);无位移的点击不发,`pointermove` 不逐帧回调,长按在触发跟随时发。
10
11
  - **范围**:`extent` 决定小图按哪段世界范围铺 —— `measure(data)` 量出可见数据的范围,`backgroundBoundsOf(background)` 量出底图范围(GeoJSON 用画出来的 `bounds`,图片用四角 quad 的包围盒),`auto`(默认)取两者的并集,`data` 只看数据(旧行为),`background` 只看底图。数据为空时 `measure()` 返回 `null`、不会当成「范围是正负一」;修掉的问题见 15.12。`extentFollowCamera` 默认 `false`,`auto` 始终用并集,外围内容消失不会让包围盒与视口框跳动;打开后才有例外:相机正落在其中一份范围里、而那一份在并集里连 6 个像素都占不到时(数据还没映射到底图坐标系就是这样)只画正在看的那一份;`followFocusedExtent()` 在相机挪进 / 挪出这份小范围时补一次重画 —— 判断只用上一次重画缓存的两份范围,每帧几次比较。
12
+ - **内容范围锁定**:`extentFollowContent` 默认 `false`。`resolveExtent()` 首次拿到当前模式需要的数据 / 底图范围后把它放进 `pinnedExtent`,之后筛选、删除、隐藏或新增内容只重画可见要素,不再改 `bounds` / `scale` / 中心,视口框也就不会跟着外围内容消失而漂移;打开开关后每次重画都用当前可见内容重算。显式修改 `extent`(模式或固定范围对象按值比较)会清掉锁定,立刻按新配置铺;切换 `extentFollowContent` 会重新锁定当前内容。`extentFollowCamera` 的相机取舍也使用锁定后的两份范围。
11
13
  - **通道**:`channelCircuits: false` 时每个分组按当前可见成员逐顶点平均成一根代表线,双回线因此落在两根正中间,三回线落在中间那条;只剩一条可见成员时就是它自己,顶点数对不上时退回第一条可见成员(底图分辨率本来就在一像素上下,多回线只会糊成一片)。
12
14
  - **背景**:默认 `background: 'inherit'`,直接拿引擎解析好的那份背景在 Canvas2D 上重画:底色铺满,图片按 quad 拆成两组三角形做仿射 + 裁剪(任意四边形都不会画歪),GeoJSON 面用奇偶规则填充(洞自动镂空)、纯线几何的区域再描一遍、点要素画成固定 1.2px 半径的小圆;底图的线宽(取配置值、最低 0.4px 保可见)与区域文字字号(固定档,夹在 5 ~ 12px)都是小图上的固定像素,不乘「小图视口 ÷ 主图视口」的比例 —— 缩放主视图时底图不会单独放大 / 缩小(本轮删掉了 `mapRatio`,见 15.17)。也可以给 `minimap.background` 单独配一份(结构与主视图的 `background` 完全一致,只是换 Canvas2D 画)。`backgroundStyle` 显式设置时由容器 CSS 接管底色:继承或独立的底图仍画图片与 GeoJSON,但画布底色改成透明,不再用主图的不透明底色盖住容器;不写时仍按主图底色铺满。区域文字先量「区域在小图上的屏幕矩形 ≥ 文字尺寸 × 0.85」再画,放不下就整条跳过(缩略图上那些小块本来也读不出来);能画的按区域从大到小排,和已经放下的标签重叠就跳过 —— 小图上几十个区域各画一行字只会叠成一团。
13
15
  - **扩展层**:`layers` 接收一组 `{ id?, order?, placement?, enabled?, draw }`。`placement: 'below-data'` 在内置线路 / 节点之前执行,适合网格、分区底色;`'above-data'`(缺省)在数据之后执行,适合指北针、业务标记。两段内部各按 `order` 从小到大,相同或缺省 `order` 按数组顺序。`setOptions` 时把过滤、排序与分段结果缓存成两条数组,绘制帧只遍历当前段,不再每帧 `map` / `filter` / `sort`。每个回调独立 `save` / `restore`,一层改过的画布状态不会漏进下一层;`enabled: false` 可临时关掉一层,旧的单层 `draw` 保持兼容并固定最后执行,回调里的 `stage` 为 `'overlay'`。这样网格、指北针、业务标记可以各自维护,不必把所有内容堆进一个钩子。
@@ -266,9 +266,20 @@
266
266
 
267
267
  ② 也在本轮落了地(见 15.55):写实例的那几个口子(`writeCircle` / `writeLine` / `writeSpriteInstance`、追加点的那一段循环、`patchPointSlots` 的贴图分支)就地记光晕账本(`heat > 0 && opacity > 0`,与解析那一趟同一份口径),补丁路径不再置 `heatGlowDirty`,`refreshHeatGlow` 只剩「补丁改过解析结果」(换热力图配置)这一条兜底;顺手把样式快路径漏写回的 `point.heat` 补上(线路那侧的 `refreshLine` 一直有)。
268
268
 
269
- ### 16.34 线路侧的「只换线色 / 线宽」窄路(候选,本轮量过)
269
+ ### 16.34 线路侧的「只换线色 / 线宽」窄路(已完成,本轮)
270
270
 
271
- 点侧有 15.53 / 15.54 两条链的窄路,线侧还没有:`updateOptions({ lineStyle })` 里只动线色 / 线宽时,线路那一半照旧整份重解析(线侧解析结果的字段比点少,颜色与线宽都在同一条 `refreshLine` 里)。本轮给基准页加了 `lineStyleColor` / `lineStyleWidth` 两个 op 量过一遍:20 万条线只换线色 62 / 56 / 45.5 / 43 / 44.1 / 41.3 ms,profile 里 `applyResolvedStyles` 只占 18.1%,其余是 `patchLineSlots`(16.0%)+ `refreshLine`(13.4%)+ `patchLineSlotsInner`(12.8%)与实例缓冲上传 —— 重解析这一半只占三成上下,窄路能省的上限就是这十几毫秒,而线侧本来就要整批重写槽位(线色进实例数据、线宽还要过细线账本)。等「大部分线自带颜色 / 线宽」这种数据真的出现、或者槽位那一半也变窄了再做。
271
+ 点侧在 15.53 / 15.54 已有尺寸链 / 配色链两条窄路,线侧原先仍是整份重解析:`updateOptions({ lineStyle })` 只动线色 / 线宽时,规则、热力、虚线、阴影、动点与方向箭头都要重新归一化,`resolveLineStyleInto` 还会再走一遍完整对象写入。上一轮量过 20 万线,重解析约占三成、槽位补丁与实例上传占大头,因此把它留成候选;这一轮先把最常走的基准样式补丁收掉,同时让窄路与整份解析共用同一份取值链,避免两套实现以后漂开。
272
+
273
+ **改法**:从 `line.js` 抽出 `resolveLinePaintInto(target, line, style, defaults, state, heat, rule)`,只负责「基准宽 / 实际半宽 / 颜色 / 透明度」;`resolveLineStyleInto` 继续在它之上补 `zIndex` / 拐角 / 虚线 / 阴影 / 效果 / 方向。`engine.js` 新增 `NARROW_LINE_STYLE_BUCKETS` 与 `lineStyleNarrowChange()`:只在补丁确实动到 `width` / `color` / `opacity`、且没有线路规则 / 热力图、`effects` 与 `lineDirection` 引用未变时命中;`applyLineNarrowFast()` 逐条重算 paint,结果与上一轮相同就不进补丁列表,最后仍走 `patchLineSlots(changedLines, true)`。逐线自己写死的字段和状态样式继续优先;线宽变化会让交互期细线的账本作废,但不再重跑线型、阴影、动点等结构输入。`getLineStyle(index)` 读到的也是这条链落下来的最新快照。
274
+
275
+ 1000 点 + 50000 线连续 5 次换色 / 换宽(无头 Chrome + SwiftShader,`scripts/bench-scale.mjs`):
276
+
277
+ | 操作 | 改前(稳态) | 改后(稳态) |
278
+ | --- | --- | --- |
279
+ | `lineStyle.color` 换色 | 10.1 ~ 11.7 ms | **6.1 ~ 7.4 ms** |
280
+ | `lineStyle.width` 换宽 | 9.2 ~ 10.4 ms | **5.8 ~ 6.4 ms** |
281
+
282
+ 改后 profile 顶部是 `patchLineSlotsInner` 30.8% / `patchLineSlots` 17.3% / `applyLineNarrowFast` 13.0%,`resolveLinePaintInto` 3.8%;原先整份路里占大头的 `applyResolvedStyles` 与 `refreshLine` 不再出现。首轮仍有 18.9 / 17.3 ms(槽位表与交互期细线账本首次重建),稳态收益约 40%。正确性侧:`selftest-perf.html` 核对窄路后的 `getLineStyle`、逐线自身线宽 / 颜色优先、虚线不被覆盖,以及存在线路规则时回退整份解析;`selftest-demos.html` 核对 demo 的换色 / 加宽与 `dataVersion` 不递增。
272
283
 
273
284
  ### 16.35 通道回线拖动剩下的账(已完成,见 15.61)
274
285
 
@@ -1,6 +1,6 @@
1
1
  # 16-03 优化与取舍(下)
2
2
 
3
- > 16.57 ~ 16.73:坐标、通道、筛选与文档口径的取舍。
3
+ > 16.57 ~ 16.75:坐标、通道、筛选、相机快路径与文档口径的取舍。
4
4
 
5
5
  ## 16 还能怎么优化(续)
6
6
 
@@ -140,6 +140,16 @@
140
140
  - **为什么 `exportViewportData` 的结果要展开补元数据**:自定义适配器只负责业务结构,不知道视口范围;`viewRect` / `margin` 是这次查询的上下文,必须由 `exportViewportData` 统一补上,且不能覆盖适配器同名字段之外的内容。对象结果才展开、非对象原样返回,避免适配器返回 `null` 时凭空造一个对象。
141
141
  - **为什么严格契约放在 demos 自测里**:这两个接口是「演示即文档」的一部分,后端同学拿到的第一个可执行样例就是假后端。把 400 / 409 断言放在 `selftest-demos.html`,每次演示页回归都会重新验证契约,不需要另起一套测试设施。
142
142
 
143
+ ### 16.75 程序化相机运动为什么也走交互快路径、聚合关闭为什么不能再整份重排(本轮已做 / 留档)
144
+
145
+ - **根因不在绘制,而在「谁算运动帧」**:`zoomBy` / `setCamera` / `centerOn` / `flyToCamera` 都只改相机再 `notifyCameraChange()`,并不经过 `beginInteraction()`。轻量画法的判定只看 `interacting` 或动画,于是同一份十万级场景,用户拖一下能走细线与非 MSAA 后备缓冲,外部控件调一次缩放却仍按全质量画。这一轮把「程序化相机运动」记成一个 160 ms 的短窗口,`offscreenFrame` 与 `thinLinesDrawn` 共用同一套判定;每次真实位置变化重新计时,停稳后补一张全质量帧,并刷新通道宽度、恢复符号预烤。
146
+ - **为什么要比较相机位置,而不是每次 `setCamera` 都续期**:业务侧常把 `setCamera` 放在定时器或响应式同步里,即使视角没变也会反复调用。若无条件续期,画面会永久停在轻量档,线宽、圆头与 MSAA 都回不来。现在的 `cameraMotionLast` 只认真实变化的中心 / 比例;同一位置重复调用既不进入快路径,也不会重置停稳计时。
147
+ - **为什么关闭聚合也要单独处理**:旧代码只要 `camera.scale !== clusterScale` 就标 `clusterDirty`,而 `flushPointClusterLayout()` 无条件调用 `layoutScene()`。聚合没开时,这一趟没有任何成员可算,却会把十万级点的实例缓冲整份重写上传 —— 缩放看起来慢,慢在这里而不是 WebGL 绘制。现在只在聚合启用且当前档可能聚合、或上一帧确实有聚合圆 / 隐藏点时才标脏;关闭聚合且没有旧画面时只清标记。跨出 `maxZoom`、改配置、数据 / 选中 / 拖动变化仍立即重排,避免为了省一次计算让状态延迟生效。
148
+ - **为什么相机引起的聚合变化可以晚一帧**:聚合半径是屏幕像素,运动过程中每帧都重算成员只会把主线程占满,而圆本身的成员变化在快速缩放里很难看清。于是只把「纯相机缩放导致的成员变化」推迟到停稳后,拖动期间沿用上一组成员是同一口径;平移不改比例,一次都不标脏。
149
+ - **为什么停稳条件不能只看「画过轻量帧」**:聚合成员被推迟时,如果场景没有线、又显式 `interactionNoMsaa: false`,这一轮可能没有任何轻量几何,但 `clusterDirty` 仍在。停稳计时器现在同时检查 `cameraMotionFastDrawn` 与「被相机推迟的聚合脏」,后者也补一帧,否则聚合会停在旧缩放档。`selftest-perf.html` 用 12000 点、无边、关后备缓冲的场景专门钉住这一条。
150
+ - **为什么不改公开接口**:快路径只改「什么时候画成哪一档」,相机、聚合、选项与返回结构都没变,不使用这条路的调用方行为不变;`getStats().thinLines` / `noMsaa` 仍是最近一帧的真实读数,静态画面照旧回到全质量。
151
+ - **验证**:`node --check`、`npx tsc --noEmit`、`node docs/steps/gen-api-index.mjs --check`、`npm run check:docs`(264 个实例成员 / 96 个 options / 250 个数据字段 / 43 个事件 / 17 个功能开关)、四页自测 `full 94` / `demos 365` / `docs 134` / `perf 181` 共 **774** 条通过 / 0 失败、`npm run build` 与 `git diff --check` 全部通过。10 万点 / 5 万线实测连续缩放 p50 **67.9 → 22.5 ms**、p95 **76.2 → 25.1 ms**、avg **60.77 → 20.57 ms**;平移 p50 17.1 → 17.2 ms(帧节拍波动),`refresh()` 56.2 → 53.7 ms。profile 显示剩余成本主要是 GPU 光栅化 / 帧节拍,`render` 自身约 0.1%,因此本轮收益应表述为「省掉整份重排与上传、运动期省掉 MSAA 细线光栅化」,不是「单帧渲染降到 1 ms」。
152
+
143
153
  ---
144
154
 
145
155
  [← 16-02 优化与取舍(中)](16-02-%E4%BC%98%E5%8C%96%E4%B8%8E%E5%8F%96%E8%88%8D-%E4%B8%AD.md) · [实现原理目录](../GisView实现原理.md) · [17 调试与扩展建议 →](17-%E8%B0%83%E8%AF%95%E4%B8%8E%E6%89%A9%E5%B1%95%E5%BB%BA%E8%AE%AE.md)
@@ -2,7 +2,7 @@
2
2
 
3
3
  > 十五轮实测数据、瓶颈定位与 WebGPU 值不值得上。
4
4
 
5
- 结论先说:**当前瓶颈不在 GPU,也不在 WebGL 的绘制提交上,所以换成 WebGPU(或把渲染挪进 Worker)都不会带来明显收益**。
5
+ 结论先说:**绘制提交与 JS 不是当前瓶颈;十万级长线的主要剩余成本是 GPU 填充率,换 WebGPU(或把渲染挪进 Worker)不会减少相同像素量的填充,因此仍不会带来明显收益**。
6
6
  十万级数据下真正的开销在 JS / DOM 侧,几轮优化都落在这里:先是标签覆盖层的候选上限(`label.scanLimit`,0.8 → 36.5 FPS),
7
7
  再是把标签图层做成「交互期整体变换 + 停手后重排」,平移 / 缩放 / 拖点从此与「关掉标签」同档(17.9 / 13.5 / 20.1 → 55 ~ 58 FPS),
8
8
  整屏框选也从 97 ms 降到 52 ms;随后一轮把「整组拖动」的增量补丁补齐到每个实例批次(点线按槽位合并上传、圆头批次欠账到松手后分摊补齐),
@@ -263,6 +263,66 @@
263
263
 
264
264
  优化后的 5 次读数依次是 5.6 / 6.3 / 6.3 / 6.4 / 10.7 ms;同页新增三条断言分别核对条数与线路实例数不变、通道声明未变时派生折线原样保留、换通道骨架时线路几何必须重推。该快路只对原样回灌生效,内容真的换了或删除导致下标平移时仍走原来的整份 / 增量路径。
265
265
 
266
+ #### 第十七轮:线路样式窄路 —— 只换线宽 / 颜色不再重跑整份解析
267
+
268
+ 上一轮把「同一批点线原样回灌」收掉,这一轮继续看样式面板上最常发生的补丁:只拖线宽、只换线色。点侧已有尺寸 / 配色两条窄路,线侧仍会在 `resolveLineStyleInto` 里重跑规则、热力、虚线、阴影与效果归一化。现在把「基准宽 / 实际半宽 / 颜色 / 透明度」抽成 `resolveLinePaintInto`(整份解析与窄路共用),命中窄路时逐条只重算这四项并补实例槽位;规则、热力图、虚线、方向箭头等结构输入存在时仍回退整份解析。`getLineStyle(index)` 读的是同一条链的最新结果。
269
+
270
+ 1000 点 + 50000 线,连续 5 次交替(`node scripts/bench-scale.mjs --points=1000 --lines=50000 --gpu=true`;profile 时另用临时表达式文件挂 `--profileFile`,跑完即删):
271
+
272
+ | 操作 | 改前 | 改后 | 稳态收益 |
273
+ | --- | --- | --- | --- |
274
+ | 只换 `lineStyle.color` | 27 / 11.7 / 10.1 / 10.1 / 10.5 ms | 18.9 / 10.8 / 7.4 / 6.1 / 6.6 ms | 约 40% |
275
+ | 只换 `lineStyle.width` | 20.4 / 10.4 / 9.2 / 10.2 / 10.4 ms | 17.3 / 7.8 / 6.2 / 5.8 / 6.4 ms | 约 40% |
276
+
277
+ 首轮包含槽位表与交互期细线账本的首次重建;稳态从 9 ~ 11.7 ms 降到 5.8 ~ 7.4 ms。改后的 CPU profile(42 ms 采样窗口,208 samples):`patchLineSlotsInner` 30.8%、`patchLineSlots` 17.3%、`applyLineNarrowFast` 13.0%、`estimateLinePatchRuns` 8.7%、`bufferSubData` 5.8%、`resolveLinePaintInto` 3.8%;原先的 `applyResolvedStyles` / `refreshLine` 已不在热点列表里。这说明剩余成本主要是「实例槽位补丁 + 上传」,继续压缩解析侧能拿的收益已经很小。
278
+
279
+ 正确性回归:`selftest-perf.html` 新增 4 条断言,覆盖窄路后 `getLineStyle` 的最新读数、`dataVersion` 不递增、逐线自身线宽 / 颜色优先、虚线图案不被覆盖,以及存在线路规则时回退整份解析且规则仍压过新的全局样式;另加 1 条 DIAG 记录 2000 线的窄路耗时。`selftest-demos.html` 覆盖 `flyToCamera`、`getLineStyle`、`dataVersion` 三个 demo 读数与 `onDataChange` 同步。
280
+
281
+ #### 第十八轮:程序化相机运动复用交互快路径,关闭聚合不再空转整排
282
+
283
+ 这一轮先查「没有指针事件时,相机 API 为什么没吃到交互期的优化」。`zoomBy` / `setCamera` / `centerOn` / `flyToCamera` 最终都走 `notifyCameraChange()`,但轻量画法的判定只看 `interacting` 与动画,所以外部控件、定时视角同步与飞行动画仍按全质量路径绘制。另一半问题是聚合脏标记:只要缩放比例变了就无条件 `clusterDirty = true`,即使 `pointCluster` 根本没开,下一帧也会跑一次 `layoutScene()` 并重写 / 上传整份点实例缓冲。
284
+
285
+ 现在的口径:
286
+
287
+ - **聚合只在该算的时候算**:关闭聚合、当前缩放档不聚合且上一帧也没有聚合圆 / 隐藏点时,`flushPointClusterLayout()` 只收掉脏标记,不调用 `layoutScene()`。真正跨出聚合档、关配置、改数据 / 选中 / 拖动时仍立即重排,不能延迟状态生效。
288
+ - **相机运动期只推迟成员关系**:相机导致的聚合成员变化先沿用上一档,停稳后一次重算;平移不标聚合脏,因为聚合半径是屏幕像素、比例没变。
289
+ - **程序化运动复用两种轻量画法**:真实相机位置变化后 160 ms 内,非 MSAA 后备缓冲与 `gl.LINES` 细线路径同时生效;每次真实变化重新计时,同一位置重复 `setCamera` 不续期。停稳后补一张全质量帧,刷新通道宽度并恢复符号预烤。
290
+ - **停稳条件不只盯轻量帧**:如果当前场景没有线、又显式关了 `interactionNoMsaa`,运动帧可能一种轻量几何都没画;只要还有被推迟的聚合重排,计时器也补一帧,避免聚合结果停在旧缩放档。
291
+
292
+ 实测环境与命令:无头 Chrome + ANGLE(AMD Radeon Graphics,D3D11),1280×800,10 万点 / 5 万线,`quality: 'high'`:
293
+
294
+ ```powershell
295
+ node scripts/bench-scale.mjs --points=100000 --lines=50000 --gpu=true --panFrames=40 --zoomFrames=30
296
+ ```
297
+
298
+ | 指标 | 改前 | 改后 |
299
+ | --- | --- | --- |
300
+ | 连续缩放 p50 | 67.9 ms | **22.5 ms** |
301
+ | 连续缩放 p95 | 76.2 ms | **25.1 ms** |
302
+ | 连续缩放 avg | 60.77 ms | **20.57 ms** |
303
+ | 连续平移 p50 | 17.1 ms | 17.2 ms(不变,属于帧节拍波动) |
304
+ | `refresh()` | 56.2 ms | **53.7 ms** |
305
+
306
+ 改后终态读数为 `thinLines: false`、`noMsaa: false`、`frameMs: 0.10`;CPU profile 里主要是 idle / program,`render` 自身约占 0.1%。所以这里的收益不是把引擎单帧压到 1 ms,而是消除了「关闭聚合时每次缩放都整份重排 + 上传」以及运动期的 MSAA / 细线光栅化成本;剩余时间基本是 GPU 光栅化与 60 Hz 帧节拍。`selftest-perf.html` 增加 7 条断言(其中 1 条覆盖没有轻量帧时的延迟聚合补算),四页回归 `full 94 / demos 365 / docs 134 / perf 181` 共 **774** 条通过 / 0 失败;公开实例成员、options 与数据字段计数不变。
307
+
308
+ #### 第十九轮:线片段着色管线专用化
309
+
310
+ 这一轮先回答「为什么上一轮之后还是感觉没提升多少」。10 万线交互的 CPU profile 仍约 **98.6% idle**、`render` 自身约 **0.1%**,说明主线程不是瓶颈;上一轮省掉的是场景重排、实例上传与相机排帧。剩余成本落在 GPU:`gl.LINES` 细线虽然已经避开细长三角形,但片元仍复用了通用线路着色器,逐像素执行虚线取模、`smoothstep`、边缘覆盖率与光晕分支,即使这一遍画的是 1px 实线。
311
+
312
+ - `THIN_LINE_FRAGMENT_SHADER`:交互期 `gl.LINES` 只把实例颜色写到输出,顶点侧也不再携带虚线 / 边缘 / 光晕 varying。
313
+ - `SOLID_LINE_FRAGMENT_SHADER`:整批无虚线且这一遍不是热力光晕的四边形线路只算颜色与(非 MSAA 帧的)覆盖率;有虚线或光晕仍走 `LINE_FRAGMENT_SHADER`。
314
+ - `engine.js` 的 `drawLineBatch` 按批选择管线,`refreshLineThinLedger` 同时提供「是否全实线」;端点圆头保持绘制,所有交互帧仍是全分辨率,停稳 160 ms 后照旧补 MSAA 静态帧。
315
+
316
+ 实测环境:无头 Chrome + ANGLE(AMD Radeon Graphics,D3D11),1280×800,`quality: 'high'`,三次运行取中位。
317
+
318
+ | 场景 | 改前 p50 / p95 | 改后 p50 / p95 |
319
+ | --- | --- | --- |
320
+ | 10 万点 / 5 万线缩放 | 23.2 / 28.6 ms | **16.7 / 16.8 ~ 16.9 ms** |
321
+ | 10 万点 / 10 万线缩放 | 42.6 / 46.3 ms | **18.0 / 21.4 ms** |
322
+ | 10 万点 / 10 万线、2px 实线(只走四边形轻量片元) | 82.4 / — | **63.9 / — ms** |
323
+
324
+ 16 ~ 18 ms 已接近 60Hz 帧节拍,不能再用它宣称无上限提升;要继续明显提速,只能减少可见线段数或屏幕覆盖面积。细线快路径的实际门槛是最大半宽 ≤ 0.6 设备像素且无虚线(dpr = 1 时约 1.2px 线宽),2px 实线不会走 `gl.LINES`,这也是「某些场景感觉提升有限」的直接原因。`selftest-perf.html` 新增 1 条像素级对拍,验证细线与四边形在同一交互状态下位置 / 颜色一致、不会整批画丢;该页 182 / 1(共 183 条,标签读数失败在 HEAD 已复现)。
325
+
266
326
  ### WebGPU 值不值得上
267
327
 
268
328
  | 维度 | 现状 | WebGPU 能带来的变化 |
@@ -43,7 +43,7 @@
43
43
  | `labelStates` | `GisViewLabelState[]` | 无 | 标签的运行时状态(`getLabelStates()` 的那一份:拖出来的偏移、改过的内容与样式、运行时加的标签、隐藏覆盖):创建时喂回来就回显,等价于创建之后调 `setLabelStates(states)`;`updateOptions({ labelStates })` 同样认。`exportData({ format: 'input' })` 的结果里就叫 `labelStates`,存档 → 回灌直接接上 |
44
44
  | `graphics` | `GisViewGraphic[]` | 无 | 与节点无关的扩展图形:按世界坐标放 SVG 路径 / 图片 / Canvas,支持锚点、偏移、旋转、透明度、`zIndex` 与 `scaleWithView`;位于画布之上、标签之下,运行时用 `addGraphic` / `addGraphics` / `updateGraphic` / `removeGraphic` / `clearGraphics` 增删改,见「扩展图形(graphic)」 |
45
45
  | `tooltip` | `GisViewTooltipOptions` | 无 | 悬停提示:点 / 线 / 通道分别配置内容,见「悬浮提示」 |
46
- | `minimap` | `GisViewMinimapOptions \| null` | 无 | 内置鹰眼图:位置、尺寸、节点 / 线路 / 视口框三份样式与交互都可配,`extent` 决定小图按数据范围还是「数据 ∪ 底图」铺(默认 `auto`,GeoJSON 底图不会缩成一个点),`extentFollowCamera` 默认 `false`、打开后才允许 `auto` 范围随相机收窄。`zoomable` 三态互斥:`false` 关闭、`true` 手动缩放小图自身、`'follow'` 让整体范围跟随主图(`followZoomScale` 是主图倍数的指数,跟随模式下 `setMinimapZoom` / `zoomMinimapBy` 不抢控制权);空白处拖动可平移小图或直接框选让主图显示过去(`dragAction`,`box` 不依赖缩放,手动模式下 Ctrl / ⌘ 才切换动作),每格倍率 `zoomStep`。通道还能只画一根;小图同样支持规则(`pointRules` / `lineRules`,缺省沿用主图规则的颜色、层级、最终节点尺寸与图标、样式链线宽,节点 / 线路尺寸按两边视口比例缩放且不受主图相机倍数影响),可以只画某几层(`levels`)、关掉分层叠画(`layered`)、按三组系数给节点与线路定尺寸(整体倍数 `pointSizeScale` / `lineWidthScale` 对自有与继承要素都生效;跟随小图倍数 `pointZoomScale` / `lineZoomScale` 在小图自身放大时也作用于继承要素;跟随主视图地图倍数 `pointMapZoomScale` / `lineMapZoomScale` 只作用于自有规则 / 样式),视口框与框选矩形的颜色 / 背景 / 边框 / 圆角也能配(`boxStyle` / `selectStyle`),`extent` 还能直接写死一份世界范围、容器可加 `className` / `style`、`layers` 按 `placement` 分数据前 / 数据后、段内按 `order` 拆出多层自绘内容(旧 `draw` 钩子仍兼容并排在最后)、`onInteraction` 在手势结束时给出类型 / 世界坐标 / 相机、`maxPixelRatio` 限制备份倍率上限,不配则不产生任何 DOM,见「鹰眼图」 |
46
+ | `minimap` | `GisViewMinimapOptions \| null` | 无 | 内置鹰眼图:位置、尺寸、节点 / 线路 / 视口框三份样式与交互都可配,`extent` 决定小图按数据范围还是「数据 ∪ 底图」铺(默认 `auto`,GeoJSON 底图不会缩成一个点),`extentFollowContent` 默认 `false`,首次铺好后内容变化不再改小图范围;`extentFollowCamera` 默认 `false`、打开后才允许 `auto` 范围随相机收窄。`zoomable` 三态互斥:`false` 关闭、`true` 手动缩放小图自身、`'follow'` 让整体范围跟随主图(`followZoomScale` 是主图倍数的指数,跟随模式下 `setMinimapZoom` / `zoomMinimapBy` 不抢控制权);空白处拖动可平移小图或直接框选让主图显示过去(`dragAction`,`box` 不依赖缩放,手动模式下 Ctrl / ⌘ 才切换动作),每格倍率 `zoomStep`。通道还能只画一根;小图同样支持规则(`pointRules` / `lineRules`,缺省沿用主图规则的颜色、层级、最终节点尺寸与图标、样式链线宽,节点 / 线路尺寸按两边视口比例缩放且不受主图相机倍数影响),可以只画某几层(`levels`)、关掉分层叠画(`layered`)、按三组系数给节点与线路定尺寸(整体倍数 `pointSizeScale` / `lineWidthScale` 对自有与继承要素都生效;跟随小图倍数 `pointZoomScale` / `lineZoomScale` 在小图自身放大时也作用于继承要素;跟随主视图地图倍数 `pointMapZoomScale` / `lineMapZoomScale` 只作用于自有规则 / 样式),视口框与框选矩形的颜色 / 背景 / 边框 / 圆角也能配(`boxStyle` / `selectStyle`),`extent` 还能直接写死一份世界范围、容器可加 `className` / `style`、`layers` 按 `placement` 分数据前 / 数据后、段内按 `order` 拆出多层自绘内容(旧 `draw` 钩子仍兼容并排在最后)、`onInteraction` 在手势结束时给出类型 / 世界坐标 / 相机、`maxPixelRatio` 限制备份倍率上限,不配则不产生任何 DOM,见「鹰眼图」 |
47
47
  | `filter` | `GisViewFilterInput \| null` | 无 | 初始筛选条件,等价于创建之后调用 `setFilter`;`mode` 缺省 `'hide'`,写 `'remove'` 则删除不命中的要素,见「筛选」 |
48
48
  | `filterWorker` | `boolean \| GisViewFilterWorkerOptions` | `{ threshold: 20000 }` | 筛选是否用 Web Worker 计算:默认点 + 线总数超过阈值才用,`false` 表示始终同步算 |
49
49
  | `searchWorker` | `boolean \| GisViewSearchWorkerOptions` | `{ threshold: 20000 }` | [异步搜索](14-视图与筛选.md#搜索与定位)是否用 Web Worker 计算:默认点 + 线总数超过阈值才用,`false` 表示 `searchAsync` 也同步算;同步的 `search` 一直在主线程算,不受这一项影响 |
@@ -93,7 +93,7 @@
93
93
  | `pixelRatio` | `number` | `devicePixelRatio` | 手动指定设备像素比(夹在 0.5 ~ 3);宿主缩放(CSS `zoom` / `transform: scale`)的比例会乘在它上面,合计夹在 0.5 ~ 4 |
94
94
  | `maxCanvasPixels` | `number` | `4000000` | 画布总像素预算:`cssWidth × cssHeight × 倍率²` 超过它时按 `sqrt(预算 / CSS 面积)` 压渲染倍率(全屏与高分屏不因像素数翻十倍而掉帧);传 `0` 不设上限 |
95
95
  | `antialias` | `boolean` | 开(软件光栅自动关) | 画布是否开 MSAA。同一份十万级线段实测:MSAA 4× 下单帧光栅化是关掉时的近 5 倍(见「画质」里的实测表),关掉能明显提速、代价是线条与圆形边缘有锯齿;当前实际状态见 `getStats().antialias`(软件光栅下引擎默认关,写 `true` 可强制打开) |
96
- | `interactionThinLines` | `boolean` | `true` | 交互期细线快路径:可见线段全部细到 3px 以内且没有虚线时,拖动 / 缩放期间改用 `gl.LINES` 画(1 设备像素、无光晕与虚线),停手立刻回到四边形展开。位置不跳、悬停 / 选中不受影响;这一帧走没走快路径见 `getStats().thinLines`,实测见「画质」 |
96
+ | `interactionThinLines` | `boolean` | `true` | 交互期细线快路径:可见线段最大半宽 ≤ 0.6 设备像素(dpr = 1 时约 1.2px 线宽)且整批没有虚线时,拖动 / 缩放期间改用 `gl.LINES` 画(1 设备像素、无光晕与虚线),停手立刻回到四边形展开。2px 实线不会走这一档,但全实线四边形另有轻量片元。位置不跳、悬停 / 选中不受影响;这一帧走没走快路径见 `getStats().thinLines`,实测见「画质」 |
97
97
  | `interactionNoMsaa` | `boolean` | `true` | 非 MSAA 后备缓冲(交互 / 动画期):拖动 / 缩放 / 框选期间与动画在跑的那些帧,整帧先画进一张不带 MSAA 的后备贴图,帧末整幅贴回画布;停手(或动画停帧)之后那一帧照旧直接画进带 MSAA 的画布,所以静止画面逐像素不变(代价是这些活动帧的边缘暂时没有抗锯齿)。十万级实测交互期单帧 133 → 36.6 ms、拖动 p50 130 → 16 ~ 22 ms,动画帧 212 → 53 ms/帧(只开涟漪 187 → 48、只开线路动点 199 → 47);透明底 / 自定义底色的导出场景与没开 MSAA 的画布不走这条,这一帧走没走见 `getStats().noMsaa`,实测见「画质」 |
98
98
  | `renderer` | `'auto' \| 'webgl2' \| 'webgpu'`(也认布尔开关) | `'auto'` | 渲染后端开关:当前实装的绘制后端只有 WebGL2 —— 十万级下 `frameMs` 只有 0.05 ~ 0.2 ms,开销在填充率与 DOM 覆盖层上,换 WebGPU 省不到(第 18 章),所以 `'auto'` 只会在后台探一次 WebGPU 能力、绘制仍走 WebGL2,`'webgl2'` 连探测都不跑(无 GPU 的远程桌面里省一次 `requestAdapter`),`'webgpu'` 探完明确报一句「已回退 WebGL2、为什么」;`true` / `false` 等价于 `'webgpu'` / `'webgl2'`。读数用 `getRendererInfo()`,见「渲染后端(WebGPU 开关)」 |
99
99
  | `ariaLabel` | `string` | `GIS 视图` | 画布的无障碍名称 |
@@ -887,7 +887,7 @@ view.updateOptions({ quality: 'high' })
887
887
 
888
888
  - **类型**:`boolean`
889
889
  - **默认值**:`true`
890
- - **说明**:交互期细线快路径:可见线段全部细到 3px 以内且没有虚线时,拖动 / 缩放期间改用 `gl.LINES` 画(1 设备像素、无光晕与虚线),停手立刻回到四边形展开。位置不跳、悬停 / 选中不受影响;这一帧走没走快路径见 `getStats().thinLines`,实测见「画质」
890
+ - **说明**:交互期细线快路径:可见线段最大半宽 ≤ 0.6 设备像素(dpr = 1 时约 1.2px 线宽)且整批没有虚线时,拖动 / 缩放期间改用 `gl.LINES` 画(1 设备像素、无光晕与虚线),停手立刻回到四边形展开。2px 实线不会走这一档,但全实线四边形另有轻量片元。位置不跳、悬停 / 选中不受影响;这一帧走没走快路径见 `getStats().thinLines`,实测见「画质」
891
891
  - **参考**:见「MSAA 与交互期细线」一节,子字段在那里的表里逐个展开
892
892
 
893
893
  #### `interactionNoMsaa`
@@ -1004,7 +1004,7 @@ view.setFilter(null) // 清掉筛选
1004
1004
 
1005
1005
  - **类型**:`GisViewMinimapOptions | null`
1006
1006
  - **默认值**:无
1007
- - **说明**:内置鹰眼图:位置、尺寸、节点 / 线路 / 视口框三份样式与交互都可配;`position` / `margin` 定角落,`offset` 相对角落动态移动整张图,`container` 可挂到外部 `div`(`getMinimapElement()` 取根节点做整图拖动)。`extent` 决定小图按数据范围还是「数据 ∪ 底图」铺(默认 `auto`,GeoJSON 底图不会缩成一个点),`extentFollowCamera` 默认 `false`、打开后才允许 `auto` 范围随相机收窄,避免外围要素消失时包围盒与视口框跳动。`zoomable` 三态互斥:`false` 关闭、`true` 手动缩放小图自身、`'follow'` 让整体范围跟随主图(`followZoomScale` 是主图倍数的指数;跟随模式下 `setMinimapZoom` / `zoomMinimapBy` 不抢控制权,`zoom` 是基准倍数);空白处拖动可平移小图或直接框选让主图显示过去(`dragAction`,`box` 不依赖缩放,手动模式下 Ctrl / ⌘ 才切换动作),每格倍率 `zoomStep`。通道关闭 `channelCircuits` 时按当前可见成员逐顶点平均成一根居中代表线;小图同样支持规则(`pointRules` / `lineRules`,缺省沿用主图规则的颜色 / 层级、最终节点尺寸与图标及样式链线宽,节点 / 线路尺寸按两边视口比例缩放且不受主图相机倍数影响),可以只画某几层(`levels`)、关掉分层叠画(`layered`)、按三组系数给节点与线路定尺寸(整体倍数 `pointSizeScale` / `lineWidthScale` 对自有与继承要素都生效;跟随小图倍数 `pointZoomScale` / `lineZoomScale` 在小图自身放大时也作用于继承要素;跟随主视图地图倍数 `pointMapZoomScale` / `lineMapZoomScale` 只作用于自有规则 / 样式),视口框与框选矩形的颜色 / 背景 / 边框 / 圆角也能配(`boxStyle` / `selectStyle`),`backgroundStyle` 显式设置时接管画布底色,`extent` 还能直接写死一份世界范围、容器可加 `className` / `style`、`layers` 按 `placement` 分数据前 / 数据后、段内按 `order` 拆出多层自绘内容(旧 `draw` 钩子仍兼容并排在最后)、`onInteraction` 在手势结束时给出类型 / 世界坐标 / 相机、`maxPixelRatio` 限制备份倍率上限,不配则不产生任何 DOM,见「鹰眼图」
1007
+ - **说明**:内置鹰眼图:位置、尺寸、节点 / 线路 / 视口框三份样式与交互都可配;`position` / `margin` 定角落,`offset` 相对角落动态移动整张图,`container` 可挂到外部 `div`(`getMinimapElement()` 取根节点做整图拖动)。`extent` 决定小图按数据范围还是「数据 ∪ 底图」铺(默认 `auto`,GeoJSON 底图不会缩成一个点);`extentFollowContent` 默认 `false`,首次铺好后筛选 / 显隐 / 增删内容不再改范围与缩放,打开后才跟进当前可见内容;`extentFollowCamera` 默认 `false`、打开后才允许 `auto` 范围随相机收窄。`zoomable` 三态互斥:`false` 关闭、`true` 手动缩放小图自身、`'follow'` 让整体范围跟随主图(`followZoomScale` 是主图倍数的指数;跟随模式下 `setMinimapZoom` / `zoomMinimapBy` 不抢控制权,`zoom` 是基准倍数);空白处拖动可平移小图或直接框选让主图显示过去(`dragAction`,`box` 不依赖缩放,手动模式下 Ctrl / ⌘ 才切换动作),每格倍率 `zoomStep`。通道关闭 `channelCircuits` 时按当前可见成员逐顶点平均成一根居中代表线;小图同样支持规则(`pointRules` / `lineRules`,缺省沿用主图规则的颜色 / 层级、最终节点尺寸与图标及样式链线宽,节点 / 线路尺寸按两边视口比例缩放且不受主图相机倍数影响),可以只画某几层(`levels`)、关掉分层叠画(`layered`)、按三组系数给节点与线路定尺寸(整体倍数 `pointSizeScale` / `lineWidthScale` 对自有与继承要素都生效;跟随小图倍数 `pointZoomScale` / `lineZoomScale` 在小图自身放大时也作用于继承要素;跟随主视图地图倍数 `pointMapZoomScale` / `lineMapZoomScale` 只作用于自有规则 / 样式),视口框与框选矩形的颜色 / 背景 / 边框 / 圆角也能配(`boxStyle` / `selectStyle`),`backgroundStyle` 显式设置时接管画布底色,`extent` 还能直接写死一份世界范围、容器可加 `className` / `style`、`layers` 按 `placement` 分数据前 / 数据后、段内按 `order` 拆出多层自绘内容(旧 `draw` 钩子仍兼容并排在最后)、`onInteraction` 在手势结束时给出类型 / 世界坐标 / 相机、`maxPixelRatio` 限制备份倍率上限,不配则不产生任何 DOM,见「鹰眼图」
1008
1008
  - **参考**:见「鹰眼图」一节,子字段在那里的表里逐个展开
1009
1009
 
1010
1010
  ```js
@@ -1018,6 +1018,7 @@ createGisView(container, {
1018
1018
  container: '#minimap-host',
1019
1019
  backgroundStyle: 'rgba(255, 255, 255, 0.92)',
1020
1020
  extent: 'auto',
1021
+ extentFollowContent: false,
1021
1022
  extentFollowCamera: false,
1022
1023
  dragAction: 'box',
1023
1024
  zoomable: 'follow',
@@ -36,7 +36,7 @@
36
36
  | `onCameraChange` | `GisViewCamera` | 平移或缩放后触发 |
37
37
  | `onViewport` | `GisViewViewport` | 视口尺寸 / 显示比例变化(画布按新尺寸重铺之后才发):`{ cssWidth, cssHeight, pixelRatio, displayScale }`,自建面板与小图按它跟着调整 |
38
38
  | `onStats` | `GisViewEngineStats` | 渲染统计(点数、线数、线路批次真正铺的段数 `lineInstances`、符号数、绘制次数、`fps` / `idle` / 帧耗时、拾取耗时 `pickMs`、密度场读数 `heatDensity`,以及这一帧的光栅与线段路径 `antialias` / `software` / `thinLines`),按 `statsInterval` 节流(默认 250ms 一次)。静止画面按需渲染,这时 `idle` 为 `true`、`fps` 为 `0`,`frameMs` 是最近一帧的耗时;首帧一定会报一次(面板打开就有读数,不会一直空着) |
39
- | `onDataChange` | `GisViewDataChangePayload` | 数据变更的统一出口:调用接口改数据、拖拽 / 复制 / 合并落地、拐点增删、通道新增 / 移除 / 分组都会发,载荷带动作 `type`、最新数据与条数,见「数据变更与其它事件」 |
39
+ | `onDataChange` | `GisViewDataChangePayload` | 数据变更的统一出口:调用接口改数据、拖拽 / 复制 / 合并落地、拐点增删、通道新增 / 移除 / 分组都会发,载荷带动作 `type`、数据修订号 `dataVersion`、最新数据与条数,见「数据变更与其它事件」 |
40
40
  | `onSelectChange` | `GisViewSelectChangePayload` | 选中集变化:只在选中集真的变了时发一条(框选过程中的重复同步与数据补发都不发),接口选中也走它;载荷带 `ids` / `count` / 各类型条数与来源 `cause` |
41
41
  | `onShortcut` | `GisViewShortcutPayload` | 快捷键命中:`action`(`cancel` / `copy` / `paste` / `remove` / `fitView` / `undo` / `redo`)、`key` 与 `handled`(组件有没有接住,`false` 时可以接着做自己的处理 —— 没得撤销 / 重做时也是 `false`) |
42
42
  | `onRender` | `GisViewRenderPayload` | 节流过的帧回调:`onStats` 的读数 + `frame` / `interval` / `timestamp` 与当前 `camera`,间隔见 `renderEmitInterval` |
@@ -53,7 +53,7 @@
53
53
 
54
54
  组件的交互回调很多(选中、拖拽、复制、合并、拐点、通道…),要把「数据变了」写回自己的状态不必每个都接一遍:
55
55
  `onDataChange` 是数据变更的统一出口,`type` 说明这次是什么动作,`points` / `lines` / `channels`
56
- 就是组件内部那一份数据(只读引用),`counts` 是三个条数。
56
+ 就是组件内部那一份数据(只读引用),`counts` 是三个条数,`dataVersion` 是数据修订号:每次数据变更 +1,只改全局配置 / 样式时不递增。
57
57
 
58
58
  ```js
59
59
  const view = createGisView('#map', {
@@ -40,7 +40,7 @@ getStats().quality // onStats 里也是同一份读数:读数面
40
40
  | `gl.LINES`(每段两个顶点) | 112 ms/帧 | 23 ms/帧 |
41
41
 
42
42
  - **`antialias`**(缺省开):MSAA 会把这类细长三角形放大约 5 倍,是最省事的一根杠杆 —— 关掉线条边缘会有锯齿(点与圆符号本来就有距离场抗锯齿,几乎看不出来)。软件光栅(远程桌面 / 驱动被拉黑回落 SwiftShader)下引擎自动关掉它;读数看 `getStats().antialias`。
43
- - **`interactionThinLines`**(缺省开):交互期细线快路径 —— 可见线段全部细到 3px 以内、且整批没有虚线时,拖动 / 缩放期间改用 `gl.LINES` 画(1 设备像素、不画光晕),停手立刻回到带像素宽度与虚线的四边形展开。两种画法共用同一张实例缓冲,所以位置不会跳、选中与悬停都不受影响,只是交互那几帧的线更细更硬。同一页交替开关实测:交互期帧耗时 p50 **194 ~ 208 ms → 132 ~ 139 ms**,同一 2.2 s 窗口的帧数 **13 → 19 ~ 24**;这一帧走没走快路径看 `getStats().thinLines`。
43
+ - **`interactionThinLines`**(缺省开):交互期细线快路径 —— 可见线段最大半宽 ≤ 0.6 设备像素(dpr = 1 时约 1.2px 线宽)、且整批没有虚线时,拖动 / 缩放期间改用 `gl.LINES` 画(1 设备像素、不画光晕),停手立刻回到带像素宽度与虚线的四边形展开。2px 实线不会走这一档,但全实线四边形另有轻量片元;两种画法共用同一张实例缓冲,所以位置不会跳、选中与悬停都不受影响,只是交互那几帧的线更细更硬。同一页交替开关实测:交互期帧耗时 p50 **194 ~ 208 ms → 132 ~ 139 ms**,同一 2.2 s 窗口的帧数 **13 → 19 ~ 24**;这一帧走没走快路径看 `getStats().thinLines`。
44
44
  - **`interactionNoMsaa`**(缺省开):上一轮把账拆到「MSAA 4× 把细长三角形放大约 5 倍」,那就干脆不带 MSAA 画 —— 拖动 / 缩放 / 框选期间与动画在跑的那些帧,整帧先画进一张不带 MSAA 的后备贴图(分辨率跟画布一致,画布尺寸变了当帧重建;建不出来就放弃这一档、这一帧照旧直接画),帧末用一笔满屏四边形整幅贴回画布;停手 160ms(或动画停帧)之后的下一帧照旧直接画进带 MSAA 的画布,所以**静止画面一个像素都没变**,缺的只是这些活动帧的边缘抗锯齿。真机实测(898×558 画布、10 万点 / 12 万线、`quality: 'high'`):交互期单帧(`readPixels` 强制同步读回)**133 → 36.6 ms**,真实输入长跑(120 步)拖动 p50 **130 → 16 ~ 22 ms**、缩放 p50 **239.5 → 16.7 ms**、平移 p95 **129 → 17 ms**;同一台机器上的动画帧(10 万点 + 12 万线、涟漪与线路动点都开)**212 → 53 ms/帧**(只开涟漪 187 → 48 ms、只开线路动点 199 → 47 ms,2.6 s 窗口里的帧数 12 ~ 15 → 49 ~ 57);同一交互状态下开 / 关后备缓冲各抓一帧整幅对拍,差异像素 6.4%、平均差 0.53 / 255(都在抗锯齿边缘上)。这一帧走没走看 `getStats().noMsaa`,`updateOptions({ interactionNoMsaa })` 可以运行时改;透明底 / 自定义底色的导出场景(要逐像素可控)与本来就没开 MSAA 的画布不走这条。
45
45
  - **点符号的方框也留了一圈**(这一轮):上一条「静止画面一个像素都没变」当初对线路成立、对**节点符号并不成立** —— `gl.POINTS` 的方框正好是形状的外接框,MSAA 那一遍按方框的采样覆盖率合成、光栅化又按「像素中心落在方框内」判覆盖,方框边压住描边的那圈像素于是只在 MSAA 那一遍被削掉;交互期走非 MSAA 后备缓冲时没人削它,拖动节点就是「描边一厚一薄、一动一动」。现在方框每边多留 1 个设备像素(`shaders.js` 的 `POINT_EDGE_PAD`):顶点着色器按 `size + 2` 定 `gl_PointSize` 并传出 `v_quadRatio = quadSize / size`,片元里把 `gl_PointCoord` 缩回形状自身的尺度,距离场与线宽一个字节都没动。真机(`antialias: true`)对拍:同一节点拖动帧与松手后的静止帧**逐像素一致(差异 0 字节)**,改之前同一窗口差异 86 字节 / 最大差 35;代价是方框面积大了一圈,10 万点满屏实测 10 → 11.8 ms/帧(0.5 个设备像素实测还躲不干净,所以取 1.0)。
46
46
  - **贴图符号的方框吸附到设备像素边界的「栅格」上**(这一轮,接着上一条):上一条管的是 `gl.POINTS` 那条形状管线,SVG / 图片走的是四边形贴图 —— 它的吸附一直在**引擎像素**坐标里做(上一轮那版 `floor(anchor - halfSize) + halfSize` 只挪了「吸中心还是吸边」),而引擎像素坐标的原点在**画布中心**(`gl_Position = pixel * 2 / resolution`)、画布中心又正好落在某个设备像素的中心上:设备像素的边界在引擎坐标里是一张固定的栅格 —— 分辨率是偶数时落在整数上、奇数时落在半整数上(就是「分辨率一半」的小数部分)。只在整数上吸附的话,奇数分辨率(DPR 1.5、奇数宽度的画布)下四条边全压在设备像素中心上:MSAA 那一遍按采样点给半格覆盖率、非 MSAA 那一遍(`interactionNoMsaa`)按「像素中心在方框里」判覆盖、整个像素丢,于是拖动 / 缩放 / 平移期间图标最外圈那圈描边整行消失、停手又回来(「一闪一闪」),与图标的尺寸、圆方都无关(上一轮「只在奇数尺寸时露出来」是 318×238 那块偶数画布带出来的读数)。现在 `SPRITE_VERTEX_SHADER` 按这张栅格吸附:`vec2 grid = fract(u_resolution * 0.5); anchor = floor(clip * 0.5 * u_resolution + u_offsetPx - halfSize - grid) + halfSize + grid;` —— 四条边永远落在设备像素边界上,两条路径要么整格画、要么整格不画;偶数分辨率退化成上一轮那一行、逐像素不变(318×238 画布上 20 / 21 / 22 px × 四个位置共 12 个图标与旧写法 0 差异),贴图也还是 1:1 落在屏幕上。真机对拍(`antialias: true`):319×238 画布上 20 / 21 px 的贴图符号旧写法「平移帧 vs 交互帧」差 120 / 126 字节、本轮 0;DPR 1.5 的 449×357 画布上中心吸附 / 上一轮那行 / 本轮是 298 / 255、373 / 255、0 / 0。
@@ -165,10 +165,22 @@ view.focusOn('station-1024', { center: true }) // 要素:id / { ty
165
165
  view.focusOn({ type: 'channel', channelId: 'channel-a' }, { center: true }) // 通道:取它范围的中心
166
166
  view.focusOn({ lngLat: [116.4, 39.9] }, { center: true }) // 配了 GeoJSON 底图时按经纬度
167
167
  view.focusOn({ minX: 116, minY: 39, maxX: 117, maxY: 40 }, { center: true }) // 一段范围:取中心
168
+
169
+ // flyTo:目标与选项和 focusOn 完全一致,只多 duration / easing,把相机平滑飞过去
170
+ view.flyTo(hit, { zoom: true, duration: 600, easing: 'ease-in-out' })
171
+ view.flyTo(grouped, { zoom: true, select: true })
172
+ view.flyTo('station-1024', { duration: 0 }) // 立即落位,不播动画
173
+ view.stopCameraAnimation() // 停在当前帧,不补跳到终点
174
+ const flight = view.getCameraAnimation() // { active, progress, duration, from, to } 或 null
175
+ const flying = view.cameraAnimating // 只读:按钮在「飞向 / 停止」之间切换
168
176
  ```
169
177
 
170
178
  字符串 / 数字仍然兼容旧写法:先按节点 id 找,再按线路 id 找;同一个 id 同时出现在节点与线路里时用 `{ type: 'point' | 'line', id }` 消歧。裸字符串不表示通道;整条通道可以写 `{ channelId }`,要和通用 `id` / `index` 写法区分时再用 `{ type: 'channel', ... }`。分组必须写 `{ type: 'group', channelId?, groupId }`,`groupId` 在全部通道里唯一时可以省略通道。节点、线路、通道与分组都先解析成世界坐标范围;**缺省只按这个范围的中心调 `centerOn`,比例一点不动**,要适配就显式写 `zoom: true`,这时才交给 `zoomToBounds` 按解析出的真实 `bounds` 计算,没有为某类目标额外乘放大倍率。`scale` 的优先级高于 `zoom`;`maxZoom` 只给单点 / 单线这类零面积目标补最小范围。
171
179
 
180
+ 需要动画过渡时把同一个目标与选项交给 `flyTo`:默认 450 ms,中心线性、比例按对数插值;`easing` 可写 `'linear'` / `'ease-in'` / `'ease-out'` / `'ease-in-out'` 或自定义函数。`duration <= 0` 与系统 `prefers-reduced-motion: reduce` 都直接落位。飞行中用户拖拽 / 滚轮、再次 `flyTo`,或调用 `setCamera` / `centerOn` / `zoomTo` / `fitView` / `resetView` / `applyInitialView` 都会停在当前帧;`stopCameraAnimation()` 也是同一口径,`cameraAnimating` / `getCameraAnimation()` 用来驱动停止按钮与进度读数。
181
+
182
+ 如果目标本来就是一份相机读数(例如保存 / 恢复视图、`getCamera()` 的回灌、或外部时间轴算出来的中心与比例),用 `flyToCamera({ center?, scale? }, { duration, easing })` 直接飞向它:缺省的字段沿用当前相机,不经过要素解析,也不改选中与数据;`duration <= 0` 同样立即落位。它和 `setCamera` 的分工是「要不要过渡」:`setCamera` 当场落位,`flyToCamera` 走同一套飞行动画与取消口径。
183
+
172
184
  | `focusOn` 的选项 | 说明 |
173
185
  | --- | --- |
174
186
  | `zoom: true` | 显式要求按目标范围适配视图;不写就只居中、比例不动 |
@@ -193,7 +205,7 @@ view.focusOn({ minX: 116, minY: 39, maxX: 117, maxY: 40 }, { center: true }) //
193
205
  - 默认全字段模式会跳过 `symbol` / `style` / `tooltip` 这类外观结构;但 `fields` 显式点名时按路径直接读取,不受这条跳过规则限制。例如 `fields: ['symbol']`、`fields: ['style.color']` 能命中对应值。
194
206
  - 搜索基于当前数据:`hide` 模式下被隐藏的要素仍在数据里,因此仍然可以被搜到;`remove` 模式下已经删掉的要素搜不到。`scope` 写错或传空数组时会回落到四类全搜;重复线路 id 按数据里的第一条解析(见 [ID 解析口径](02-坐标与数据.md#id-解析口径))。
195
207
 
196
- 搜索**不动视角**:命中里带着 `bounds`,要定位就自己调 `focusOn(result.hits, …)` —— 缺省只把一批命中的整体中心当屏幕中心;要按范围适配就写 `{ zoom: true }`,`{ select: true }` 还能顺带把它们选上。`zoom` / `scale` / `padding` / `maxZoom` 属于 `focusOn` 的选项,搜索本身没有这些参数。
208
+ 搜索**不动视角**:命中里带着 `bounds`,要定位就自己调 `focusOn(result.hits, …)` —— 缺省只把一批命中的整体中心当屏幕中心;要按范围适配就写 `{ zoom: true }`,`{ select: true }` 还能顺带把它们选上。需要平滑过渡就把同一份调用换成 `flyTo(result.hits, { zoom: true, duration: 600 })`。`zoom` / `scale` / `padding` / `maxZoom` / `duration` / `easing` 属于定位方法的选项,搜索本身没有这些参数。
197
209
 
198
210
  匹配的是要素自己的字段:`id`、`name`、`from` / `to`,以及任意业务字段——`props` 这类普通对象会再往里摊一层,所以 `props.vn_kv` 里的值也能搜到;样式与符号字段不参与匹配。**通道连成员回线一起搜**:命中的是通道里的某条回线时,命中里会带上 `channelIndex`、`memberIndex`(第几回,0 开始)与 `memberLineIndex` / `memberLineId`,`bounds` 也换成那条回线的范围,`focusOn(hit)` 会把中心移到通道里的这条线路上,`focusOn(hit, { zoom: true })` 才按它的范围适配;反过来搜线路时,属于通道的线路也会带上 `channelIndex` / `memberIndex`。
199
211
 
@@ -230,6 +242,8 @@ const search = async keyword => {
230
242
 
231
243
  同步的 `search` 与 `searchAsync` 在**同一个数据版本 + 同一个请求**上结果逐字段一致(四类命中、命中的字段与值、`item` 引用、`bounds`);分组范围的当前轻量快照会随请求交给 Worker,分组字段或分组 id 改过之后也不会拿旧快照匹配。环境不支持 Worker、数据量不到阈值或 Worker 报错时,`searchAsync` 会退回同步计算再 resolve,调用方不用写两条路。
232
244
 
245
+ 这个「数据版本」现在也对外开放为只读属性 `view.dataVersion`:每次数据变更(`updatePoint` / `updateLine` / 批量补丁 / 拖拽落地 / 增删 / 撤销重做 / 换数据)递增,样式类 `updateOptions` / `updateLineStyle` 不递增,`onDataChange` 载荷里的 `dataVersion` 与它同一时刻同一个数。外部搜索缓存、增量统计或「这份结果是否过期」的判定可以直接比它,不必自己维护修订号;要读某条线路当前解析后的线宽 / 颜色快照用 `getLineStyle(index)`。
246
+
233
247
  ## 初始视图
234
248
 
235
249
  不配 `initialView` 时,首次拿到数据会 `fitView()`:整个数据范围铺满画布。数据一多,一屏全是点线看不出重点,`initialView` 用一份配置决定首屏落在哪里:
@@ -396,6 +410,8 @@ createGisView(container, {
396
410
  // 范围:'auto'(默认)数据与底图合起来、'data' 只看数据(老行为)、'background' 只看底图
397
411
  // 也能直接写死一份世界范围:extent: { minX: 0, minY: 0, maxX: 1000, maxY: 800 }(固定按它铺,不跟数据与底图走)
398
412
  extent: 'auto',
413
+ // 动态范围是否跟着当前可见内容重算:默认 false,首次铺好后筛选 / 隐藏 / 删除都不会改小图范围
414
+ extentFollowContent: false,
399
415
  // 仅 extent: 'auto' 生效;默认 false 始终按数据 ∪ 底图,打开后才允许按相机位置收窄
400
416
  extentFollowCamera: false,
401
417
  // 小图背景:inherit(默认,复用主视图解析好的背景)/ false 关掉 / 对象自己配一份
@@ -475,7 +491,8 @@ createGisView(container, {
475
491
  | `container` | `HTMLElement \| string \| null` | 无(主视图根节点) | 把鹰眼图挂到外部 `div`:可传元素或 CSS 选择器。给了就把同一根节点移进它,`position` / `margin` / `offset` 都相对这个宿主;宿主需要 `position: relative`(或 `absolute` / `fixed`)。选择器找不到时回落到主视图根节点;运行时换容器只移动节点,不重建画布。用 `view.getMinimapElement()` 可以拿到这个根节点做整图拖动 |
476
492
  | `padding` | `number` | `0.04` | 数据四周留白,取短边比例 |
477
493
  | `extent` | `'auto' \| 'data' \| 'background' \| GisViewBounds \| [[number, number], [number, number]]` | `'auto'` | 小图按哪段世界范围铺:`auto` 取「数据范围 ∪ 底图范围」,`data` 只看数据(旧行为),`background` 只看底图;数据与 GeoJSON 底图不在一个坐标系时,`auto` 能把两者一起框进小图,底图不会缩成一个点/糊成一片。也可以直接写一份世界范围(`{ minX, minY, maxX, maxY }`,也认 `[[minX, minY], [maxX, maxY]]`):固定按它铺,不跟数据与底图走 |
478
- | `extentFollowCamera` | `boolean` | `false` | `extent: 'auto'` 时是否允许包围盒跟着相机收窄。默认关闭,始终按「数据 ∪ 底图」铺,数据变化或相机进出某一份范围时包围盒与视口框不会自己跳;打开后,相机正落在其中一份范围里、而那一份合并后连 6 个像素都占不到时,只画正在看的那一份(数据还没映射到底图、两者离得很远时最明显),相机挪进 / 挪出会各重画一次 |
494
+ | `extentFollowContent` | `boolean` | `false` | 动态范围是否跟着当前可见内容重算。默认关闭:首次拿到数据 / 底图范围后锁住小图的世界范围,筛选、删除、隐藏或新增要素都不会改缩放与中心,外围内容消失时鹰眼图和视口框不会自己跳;打开后,每次数据或筛选结果变化都会按当前内容重算。显式改 `extent`(包括直接写固定范围)始终立即生效 |
495
+ | `extentFollowCamera` | `boolean` | `false` | `extent: 'auto'` 时是否允许包围盒跟着相机收窄。默认关闭,始终按「数据 ∪ 底图」铺;打开后,相机正落在其中一份范围里、而那一份合并后连 6 个像素都占不到时,只画正在看的那一份(数据还没映射到底图、两者离得很远时最明显),相机挪进 / 挪出会各重画一次。`extentFollowContent: false` 时参与比较的是锁定下来的那一份数据 / 底图范围 |
479
496
  | `className` / `style` | `string` / `Record<string, string \| number>` | 无 | 小图容器自己的类名与内联样式(中划线 / CSS 变量键与驼峰键都认):想按自己的设计系统改外观时用;换配置时上一轮写过、这一轮没写的键会被清掉 |
480
497
  | `draw` | `(info: GisViewMinimapDrawInfo) => void` | 无 | 兼容旧写法的最终一层:在所有 `layers` 之后、视口框之前调用(`info.stage === 'overlay'`;视口框由 DOM 画在它上面)。`info` 里是 `context`(已按备份像素比缩放好,直接按 CSS 像素画)、`canvas`、`width` / `height` / `ratio`、`extent` / `bounds` / `scale` / `zoom`、`project` / `unproject`(与内置图层同一套投影)与这一帧的 `data` / `background`;钩子里改过的上下文状态由组件 save / restore 收好,不会漏进下一帧 |
481
498
  | `layers` | `GisViewMinimapLayer[]` | 无 | 可拆分的自定义绘制层:每项写 `{ id?, order?, placement?, enabled?, draw }`。`placement: 'below-data'` 画在内置线路 / 节点之前,`'above-data'`(默认)画在之后;同一段内按 `order` 从小到大,相同或未写时按数组顺序。每层独立 `save` / `restore`,一层改过的画布状态不会串到下一层;`enabled: false` 可临时关掉一层。回调里的 `stage` 就是当前段,旧的单层 `draw` 固定最后执行。排序在 `updateOptions` 时缓存,绘制帧不再逐层排序 |
@@ -511,7 +528,7 @@ createGisView(container, {
511
528
 
512
529
  规则的用法与主图一致(同一套条件语言、按顺序命中、后命中的覆盖前面的),但只管小图的画法:节点按 `zIndex` 分层,`levels` 只留下指定层的节点,`layered: false` 时不排序、按数据顺序画;线路按「层级 + 颜色 + 线宽 + 透明度」分桶,一桶一条路径、一次 `stroke`,规则再多也不会把小图的绘制次数拉爆。没配自己的规则时(`inheritRules !== false`)完整沿用主图样式链:颜色 / 描边色 / 层级来自主图规则,节点尺寸与图标取主图最终解析出的那一份(点自身 > `pointRules` > `pointStyle`),线路线宽取主图样式链解析出的原始值,再按小图与主图 CSS 视口宽高的较小比例缩一次(不跟主图相机倍数走)—— 圆、方、图片、SVG 与自定义图元都保留主图的形状,但不会在小图上仍和主图一样大。显式配了小图自己的 `pointRules` / `lineRules`(或 `inheritRules: false`)时,对应的尺寸 / 线宽不受这一步影响,仍由小图自己的规则与样式决定;只配 `pointStyle` / `lineStyle` 不会单独关掉继承。节点的颜色取规则里的 `strokeColor`、没有才回落 `color`:主图的节点是白底 + 一圈电压色的描边,小图上一个点是一块实心像素,不这样取就会画成一堆白点(自己配的小图规则同样可以写 `strokeColor`)。
513
530
 
514
- **动态位置与外部挂载**:`offset` 是整张鹰眼图相对当前角落的位移,最适合做「拖动整个小图」的底移量 —— 指针每移动一段,就把累计位移写回 `updateOptions`;`position` / `margin` 仍决定基准角落。
531
+ **动态位置与外部挂载**:`offset` 是整张鹰眼图相对当前角落的位移,最适合做「拖动整个小图」的底移量 —— 指针每移动一段,就把累计位移写回 `updateOptions`;`position` / `margin` 仍决定基准角落。`docs/demos/MinimapDemo.vue`(`?demo=minimap`)在小图顶部内置了一个「拖动整图」手柄:把 `getMinimapElement()` 返回的根节点当作拖动目标,指针位移累计到 `offset`,同时保留了小图内部的框选 / 平移手势;右侧还有「整图位置复位」按钮可以直接回到 `[0, 0]`。
515
532
 
516
533
  ```js
517
534
  const minimapHost = document.querySelector('#minimap-slot')
@@ -548,7 +565,7 @@ console.log(minimapElement?.parentElement === minimapHost) // true
548
565
 
549
566
  `container` 写元素或选择器都可以;外部宿主要设成 `position: relative`(`absolute` / `fixed` 也行),否则绝对定位会继续向上找基准。换容器只是移动同一个 `.gis-view__minimap` 根节点,画布、缓存与事件监听都保留;`destroy()` 会把它从当前外部宿主里一并摘掉。没配 `minimap` 时 `getMinimapElement()` 返回 `null`。
550
567
 
551
- `levels` 挡掉的节点会按 `cascade`(默认 `'binding'`)把连在它们身上的线路一起隐藏 —— 与主视图筛选的联动是同一套写法、同一个默认值:只看某几层的电压时,层外的节点与它们的线路一起消失,不会在小图上留下一堆凭空断掉的线。`cascade: 'coordinate'` 认的是端点坐标(线路数据只有 `path`、没有 `from` / `to` 时用它),`'both'` 两种写法都认,`false` 表示挡掉节点时线路照旧画。联动只影响小图的画法:数据、主视图、主视图的筛选结果都不动;小图的范围也跟着剩下的可见要素走(`measure` 只量小图真正画出来的节点与线路)。
568
+ `levels` 挡掉的节点会按 `cascade`(默认 `'binding'`)把连在它们身上的线路一起隐藏 —— 与主视图筛选的联动是同一套写法、同一个默认值:只看某几层的电压时,层外的节点与它们的线路一起消失,不会在小图上留下一堆凭空断掉的线。`cascade: 'coordinate'` 认的是端点坐标(线路数据只有 `path`、没有 `from` / `to` 时用它),`'both'` 两种写法都认,`false` 表示挡掉节点时线路照旧画。联动只影响小图的画法:数据、主视图、主视图的筛选结果都不动;`measure` 只量小图真正画出来的节点与线路,但 `extentFollowContent: true` 时范围才跟着剩下的可见要素重算,默认锁定首次范围,避免筛选后整张小图缩放漂移。
552
569
 
553
570
  小图的尺寸系数分三组,前两组对所有节点 / 线路生效,第三组只作用于小图自有规则 / 样式:`pointSizeScale` / `lineWidthScale` 是整体倍数(常数,屏幕上恒定),`pointZoomScale` / `lineZoomScale` 跟的是**小图自身的倍数**(手动缩放 `zoomable: true` 或跟随主图 `zoomable: 'follow'` 都会改这个倍数;小图倍数到 4 倍时,`pointZoomScale: 0.5` 让节点半径放大 2 倍、`1` 是同倍率放大、`0` 保持不变;沿用主图的节点 / 线路也按这一份联动),`pointMapZoomScale` / `lineMapZoomScale` 跟的是**主视图的地图倍数**(相机比例 ÷ 基准,基准就是主视图 `pointZoomScale` 用的那一份,可以用 `mapZoomBaseScale` 覆盖):主图放大 4 倍时 `0.5` 让小图节点放大 2 倍、`1` 同倍率;这一组只作用于小图自有规则 / 样式;沿用主图时节点尺寸与线宽按「小图视口 ÷ 主图视口」换算,主图放大缩小不会改变它们的大小(两边视口尺寸变化除外)。注意前两个指数量的是**小图自身的倍数**:小图没开 `zoomable`、或者倍数还在 `1`(刚好铺满)时它们是恒等系数,怎么调都看不出变化;只想让小图的整体显示范围跟着主图缩放,用 `zoomable: 'follow'`。
554
571
 
@@ -567,7 +584,7 @@ console.log(minimapElement?.parentElement === minimapHost) // true
567
584
 
568
585
  只有手动缩放(`zoomable: true`)时,按住 Ctrl / ⌘ 才会把 `dragAction` 换成另一个动作;关闭缩放 / 跟随主图时修饰键不改变动作,不能把唯一可用的框选换没。`pan` 需要小图倍数大于 1 才有可移动余量;关闭手动缩放时,`pan` 档的空白处长按仍跟着主图视角走,想直接框选就把 `dragAction` 设成 `'box'`。平移过内容之后,小图不再自动把内容拉回视口框(否则一边看别处一边被拽回去);手动模式下 `setMinimapZoom` / 关掉再打开 `zoomable` 会回到居中,跟随主图时倍数与居中由主图决定。滚轮(或手动模式下的 `zoomMinimapBy`)以光标处的世界坐标为锚点改倍数,每一格的倍率就是 `zoomStep`(放大用 `zoomInStep`、缩小用 `zoomOutStep` 可以单独覆盖,缺省都用 `zoomStep`),`getMinimapZoom` / `setMinimapZoom` 读写当前倍数(夹在 `minZoom` ~ `maxZoom`)。`channelCircuits: false` 时每个通道分组只画一根代表线:`collectMinimapData()` 按 `getChannelMembers()` 找到这一组当前仍可见的回线,逐顶点取平均,双回线正好落在两根中间、三回线落在中间那条;底图的分辨率本来就在一个像素上下,多回线挤在一起只会糊成一片。
569
586
 
570
- 小图的范围(`extent`)默认是 `auto`:取「筛选后可见数据的范围」与「底图范围」的并集(GeoJSON 底图用画出来的 `bounds`,图片底图用四角算出的范围),所以数据与 GeoJSON 不在一个坐标系时两者会一起进小图 —— 底图铺满小图、数据落在自己该在的位置,不会出现「按数据范围缩放、底图缩成一个点或糊成一片」的旧问题。`extent: 'data'` 退回旧行为(只看数据),`extent: 'background'` 只看底图范围;数据为空时 `auto` 直接取底图范围。**`extentFollowCamera` 默认 `false`**:数据因筛选 / 显隐 / 增删变化时包围盒不会自行收窄,外围要素消失也不会让可视图突然换尺寸或让视口框跳位置。打开后才在相机落在数据 / 底图其中一份、且另一份在合并范围里小到不足 6 像素时,按正在看的那一份收窄;相机挪进 / 挪出会各补一次重画。
587
+ 小图的范围(`extent`)默认是 `auto`:取「筛选后可见数据的范围」与「底图范围」的并集(GeoJSON 底图用画出来的 `bounds`,图片底图用四角算出的范围),所以数据与 GeoJSON 不在一个坐标系时两者会一起进小图 —— 底图铺满小图、数据落在自己该在的位置,不会出现「按数据范围缩放、底图缩成一个点或糊成一片」的旧问题。`extent: 'data'` 退回旧行为(只看数据),`extent: 'background'` 只看底图范围;数据为空时 `auto` 直接取底图范围。**`extentFollowContent` 默认 `false`**:首次铺好后锁定数据与底图的世界范围,筛选 / 显隐 / 增删只会重画内容,不会改小图缩放、中心或视口框位置;打开后才按当前可见内容重算。`extentFollowCamera` 也默认 `false`:仅在打开后在相机落在数据 / 底图其中一份、且另一份在合并范围里小到不足 6 像素时,按正在看的那一份收窄;相机挪进 / 挪出会各补一次重画。
571
588
 
572
589
  **配置、扩展与开销**:`extent` 除了三档预设,还能直接写一份世界范围(`{ minX, minY, maxX, maxY }` 或 `[[minX, minY], [maxX, maxY]]`)—— 固定按它铺、不跟数据与底图走,「只看某个片区」或者让两张小图的视野对齐(前后对比、打印出图)时用;容器还能加 `className` 与 `style`(中划线 / CSS 变量键与驼峰键都认,换配置时上一轮写过、这一轮没写的键会清掉),按自己的设计系统做阴影、字号、层级这类外观不必再绕 `backgroundStyle`。**可扩展**:`layers` 把每帧的自定义内容拆成一组互不干扰的绘制层 —— `placement` 决定画在数据前还是数据后,同段内按 `order` 从小到大,独立 `save` / `restore`,适合把网格、分区底色、指北针、业务标记分开维护;排序与分段在 `updateOptions` 时缓存,绘制帧只遍历当前段,层数多也不会每帧重复排序;旧的单层 `draw` 继续兼容,`stage` 固定为 `overlay` 并排在最后。回调拿到 `context`(已经按备份像素比缩放好,直接按 CSS 像素画)、`width` / `height` / `ratio`、当前 `extent` / `bounds` / `scale` / `zoom` 与 `project` / `unproject`(与内置图层同一套投影),以及这一帧的 `data` 与 `background`。`maxPixelRatio` 是性能旋钮:默认 4,实际倍率取 `devicePixelRatio × 宿主显示比例` 与该上限的较小值;小图在高分屏 / 宿主放大时不必无限加像素,调到 1 ~ 2 能省填充率。
573
590
 
@@ -590,6 +607,7 @@ console.log(minimapElement?.parentElement === minimapHost) // true
590
607
  | `project(x, y)` / `unproject(x, y)` ↔ `clientToScreen(clientX, clientY)` / `screenToClient(x, y)` ↔ `clientToWorld(clientX, clientY)` / `worldToClient(x, y)` | 同一套换算链的三档入口:`project` / `unproject` 收**画布 CSS 像素**,`clientTo*` 这一对吃鼠标事件里的 `clientX` / `clientY`(自动减 canvas rect、除宿主缩放)只换到画布像素,再接一层就是世界坐标(`clientToWorld` / `worldToClient`);经纬度那一对是 `lngLatToScreen` / `screenToLngLat` |
591
608
  | `fitView(padding?)` / `applyInitialView()` / `resetView()` / `zoomToBounds(bounds, padding?)` | 视角的四个语义:适应**数据范围**(并记下首次落位)/ 按 `options.initialView` 落位(可反复调用)/ 回到**首次落位那一刻**的相机 / 按给定的世界坐标范围适应 |
592
609
  | `focusOn(ref, options?)` ↔ `zoomToBounds(bounds, padding?)` | `focusOn` 认要素(id / 下标 / 搜索命中 / 坐标 / 矩形 / 一批),缺省只按范围中心居中;写 `{ zoom: true }` 才走适应那一条,另带 `center` / `scale` / `maxZoom` / `select` 这些选项 |
610
+ | `flyTo(target, options?)` ↔ `focusOn(target, options?)` | 同一套目标与选项解析,区别只在落位方式:`focusOn` 立即改相机,`flyTo` 默认用 450 ms 平滑过去,并多认 `duration` / `easing`;需要随时停在当前帧用 `stopCameraAnimation()` |
593
611
  | `pick(x, y)` ↔ `pickAt(clientX, clientY)` | 坐标口径不同:`pick` 收画布 CSS 像素,`pickAt` 直接吃鼠标事件里的客户端坐标(结果里另加 `target` 与 `lngLat`) |
594
612
  | `hoverAt(clientX, clientY)` / `clearHover()` / `getHover()` | 三个动作:程序化悬停 / 撤掉并补发 `onHover(null)` / 读当前那一份(`hoverAt` 的返回与 `onHover` 载荷同一份) |
595
613
  | `getData()` / `getVisibleData()` / `getOptions()` | 读的层不同:全量数据副本(含拖拽后的最新坐标)/ 筛掉隐藏之后的点与线 / 整份配置与数据 |