gis-view-webgl2 0.1.3 → 0.1.5

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 (44) hide show
  1. package/README.md +17 -14
  2. package/dist/index.cjs +1 -1
  3. package/dist/index.d.ts +252 -37
  4. package/dist/index.js +1 -1
  5. package/docs/AI/345/257/271/350/257/235/346/261/207/346/200/273.md +79 -0
  6. package/docs/GisView.md +53 -53
  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 +66 -0
  8. package/docs/api/index.html +22 -8
  9. package/docs/demos/ApiCoverageDemo.vue +1 -1
  10. package/docs/demos/ConnectDemo.vue +114 -3
  11. package/docs/demos/ExtensionDemo.vue +69 -12
  12. package/docs/demos/MinimapDemo.vue +62 -16
  13. package/docs/demos/SearchFilterDemo.vue +13 -11
  14. package/docs/demos/api-index.js +26 -21
  15. package/docs/demos/demos.js +1 -1
  16. package/docs/demos/gis-view-demo/GisViewDemoCardHeader.vue +1 -0
  17. package/docs/demos/gis-view-demo/GisViewDemoStage.vue +25 -16
  18. package/docs/demos/gis-view-demo/panels/OpsPanels.vue +2 -2
  19. package/docs/demos/gis-view-demo/useGisViewDemo.js +36 -25
  20. package/docs/index.html +41 -4
  21. package/docs/internals/13-/351/271/260/347/234/274/345/233/276.md +6 -5
  22. package/docs/internals/16-01-/344/274/230/345/214/226/344/270/216/345/217/226/350/210/215-/344/270/212.md +5 -3
  23. 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 +12 -0
  24. package/docs/manual/03-/351/205/215/347/275/256/351/241/271.md +29 -6
  25. package/docs/manual/04-/344/272/213/344/273/266/344/270/216/345/233/236/350/260/203.md +7 -6
  26. package/docs/manual/08-/351/200/211/344/270/255/344/270/216/346/213/220/347/202/271.md +24 -3
  27. package/docs/manual/09-/351/200/232/351/201/223/344/270/216/345/244/232/345/233/236/347/272/277.md +1 -1
  28. package/docs/manual/10-/351/200/232/351/201/223/347/274/226/350/276/221/344/270/216/346/226/260/345/242/236.md +423 -3
  29. package/docs/manual/14-/350/247/206/345/233/276/344/270/216/347/255/233/351/200/211.md +169 -62
  30. package/docs/manual/15-/345/257/274/345/207/272/344/270/216/351/233/206/346/210/220.md +32 -3
  31. package/docs/manual/16-/345/256/236/344/276/213/346/226/271/346/263/225/346/200/273/350/241/250.md +12 -8
  32. package/docs/manual/17-/345/217/202/346/225/260/351/200/237/346/237/245.md +13 -9
  33. package/docs/manual/18-/351/200/220/346/226/271/346/263/225/347/244/272/344/276/213.md +156 -12
  34. 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 +3 -3
  35. 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 +11 -5
  36. package/docs/steps/README.md +8 -8
  37. package/docs/steps/selftest-demos.html +173 -12
  38. package/docs/steps/selftest-docs.html +33 -4
  39. package/docs/steps/selftest-features.html +91 -10
  40. package/docs/steps/selftest-full.html +315 -12
  41. package/docs/steps/selftest-perf.html +39 -1
  42. package/docs/steps/selftest-scale.html +98 -0
  43. package/docs/steps/selftest-select.html +90 -0
  44. package/package.json +1 -1
@@ -4,13 +4,13 @@
4
4
 
5
5
  ## 筛选
6
6
 
7
- `setFilter` 按属性过滤点与线,点被过滤掉时绑在它身上的线路按 `cascade` 联动消失;这个默认联动还受 `lineFollowsNode` 影响(见下):
7
+ `setFilter` 按属性过滤点与线,点被过滤掉时绑在它身上的线路按 `cascade` 联动消失;这个默认联动还受 `lineFollowsNode` 影响(见下)。`mode` 决定不命中的要素怎么处理:缺省 `'hide'` 只改变**显示集合**,原始数据与选中集都不动,被隐藏的选中项仍留在 `getSelections()` 里,条件放宽 / 清空后原样恢复高亮;`'remove'` 则把筛选结果直接从数据里删掉,走一条 `dataChange('filterRemove')`,开了历史时可以撤销。
8
8
 
9
9
  ```js
10
- // 只看 525kV 以上的节点:两端节点没了的线路(以及通道回线)一起隐藏
10
+ // 默认 hide:只看 525kV 以上的节点,两端节点没了的线路(以及通道回线)一起隐藏
11
11
  view.setFilter({ points: { vn_kv: { gte: 525 } } })
12
12
 
13
- // 只筛节点时可以写简写:与上一行完全等价(顶层出现 points / lines / cascade / worker 任一键才按完整格式解释)
13
+ // 只筛节点时可以写简写:与上一行完全等价(顶层出现 points / lines / cascade / mode / worker 任一键才按完整格式解释)
14
14
  view.setFilter({ vn_kv: { gte: 525 } })
15
15
 
16
16
  // 点条件 + 线条件 + 联动方式
@@ -20,6 +20,9 @@ view.setFilter({
20
20
  cascade: 'binding'
21
21
  })
22
22
 
23
+ // remove:不命中的点 / 线从数据里删掉(先删线路、再删节点,只发一条 filterRemove)
24
+ view.setFilter({ points: { station_type: 'coal' }, mode: 'remove' })
25
+
23
26
  // 也可以创建时给初始条件
24
27
  createGisView(container, {
25
28
  points,
@@ -48,12 +51,50 @@ normalizeFilter({ points: {}, cascade: 'both', nope: 1 }) // unknownKeys: ['nop
48
51
  | `points` | `GisViewConditionInput<GisViewPoint>` | 无 | 点条件,缺省表示不过滤点 |
49
52
  | `lines` | `GisViewConditionInput<GisViewLine>` | 无 | 线条件,缺省表示不过滤线 |
50
53
  | `cascade` | `false \| 'binding' \| 'coordinate' \| 'both'` | `lineFollowsNode` 开启时 `'binding'`,关闭时 `false` | 点被过滤后哪些线路一起消失:按 `from` / `to` 绑定、按端点坐标(端点正好落在被过滤的节点上)、两者都算、或完全不联动;显式写出的值始终优先 |
54
+ | `mode` | `'hide' \| 'remove'` | `'hide'` | 不命中的要素怎么处理:`hide` 只隐藏;`remove` 从数据里删除 `hiddenPoints` / `hiddenLines`,只发一条 `dataChange('filterRemove')` |
51
55
  | `worker` | `boolean` | 跟随 `filterWorker` | 这一次筛选是否允许放进 Worker |
52
56
 
53
- 联动只影响表现,数据本身不动:`updateData` / `updateOptions` 换了数据之后按同一个条件重算。通道回线也是普通线路,跟着同一个 `cascade` 走:`binding` / `coordinate` / `both` 时绑着被过滤节点的通道回线一起收起来,`false` 时照旧画 —— 被过滤的节点仍然当锚点用(几何不跟着筛选断,回线端点还钉在它原来的坐标上),只是节点自己不显示。`cascade: false` 时仍显示的通道宽度也按被过滤节点原本的尺寸链计算,不会因为节点不画了就改按另一端尺寸或退回默认 `channelWidth`。只有节点真的不在数据里(删掉、或者写了 `visible: false`)时,两端锚不住的通道与它的回线才整条不显示(和「两端没有节点就不显示」是同一条规则)。
57
+ `hide` 模式下的联动只影响表现,数据本身不动:`updateData` / `updateOptions` 换了数据之后按同一个条件重算。通道回线也是普通线路,跟着同一个 `cascade` 走:`binding` / `coordinate` / `both` 时绑着被过滤节点的通道回线一起收起来,`false` 时照旧画 —— 被过滤的节点仍然当锚点用(几何不跟着筛选断,回线端点还钉在它原来的坐标上),只是节点自己不显示。`cascade: false` 时仍显示的通道宽度也按被过滤节点原本的尺寸链计算,不会因为节点不画了就改按另一端尺寸或退回默认 `channelWidth`。只有节点真的不在数据里(删掉、或者写了 `visible: false`)时,两端锚不住的通道与它的回线才整条不显示(和「两端没有节点就不显示」是同一条规则)。
54
58
 
55
59
  `lineFollowsNode: false` 把「节点退场」与「线路 / 通道退场」拆开:筛选未显式写 `cascade` 时默认不再级联,隐藏、删除节点也只动节点;线路与通道继续停在最后一次解析出的坐标、骨架与宽度。条件里显式写了 `cascade` 时仍按显式值级联。筛选条件放宽或清空、被筛掉的回线重新出现后,引擎会在线路线宽解析完成后重新排一次通道偏移,通道与回线按当前宽度回到正确车道,不会保留筛选期间的旧间距。拖拽节点松手后,按端点坐标联动的筛选会按新坐标重算一次。需要「把某个要素找出来并居中」而不是隐藏其它要素时用 `search`,见「搜索与定位」。
56
60
 
61
+ ### 删除型筛选(mode: 'remove')
62
+
63
+ `mode: 'remove'` 把同一套判定算出的 `hiddenPoints` / `hiddenLines` 从数据里删掉,而不是只交给引擎隐藏。删除按「先线路、再节点」执行(先删点会让线路下标挪位),因此筛选结果里没有 id 的线路也能按删除前的下标删掉。`cascade` 仍决定哪些线路算进 `hiddenLines`,但删除集合就是筛选结果本身,不会在删节点时再按 `lineFollowsNode` 额外扩一圈。
64
+
65
+ ```js
66
+ createGisView(container, {
67
+ points, lines, channels,
68
+ filter: { points: { station_type: 'coal' }, mode: 'remove' },
69
+ onDataChange: payload => {
70
+ if (payload.type !== 'filterRemove') return
71
+ console.log(payload.pointIndexes, payload.removedPoints)
72
+ console.log(payload.removedLineIndexes, payload.removedLineItems)
73
+ }
74
+ })
75
+
76
+ view.setFilter({ lines: { vn_kv: { lt: 220 } }, mode: 'remove' })
77
+ view.getFilter() // { lines: { … }, mode: 'remove' }
78
+ view.getFilterResult() // 删除完成后 hiddenPoints / hiddenLines 都是空数组
79
+ ```
80
+
81
+ 一次删除只发一条 `dataChange('filterRemove')`:删除期间中间的 `removePoints` / `removeLines` 数据变更与 `onFilter` 都被抑制,最后按删完的数据重算一次筛选并正常派发一条 `onFilter`。载荷里与删除项相关的字段:
82
+
83
+ | 字段 | 说明 |
84
+ | --- | --- |
85
+ | `pointIndexes` | 删掉的节点下标(删除前它们在 `points` 里的位置,升序) |
86
+ | `removedPoints` | 删掉的节点数据,顺序与 `pointIndexes` 对应 |
87
+ | `lineIndexes` / `removedLineIndexes` | 删掉的线路下标(删除前它们在 `lines` 里的位置,升序,二者同一份) |
88
+ | `removedLineItems` | 删掉的线路数据,顺序与 `removedLineIndexes` 对应 |
89
+ | `lineIds` | 删掉的线路 id(没有 id 的线路不会出现在这里) |
90
+ | `count` / `removedLines` / `removedChannels` | 删掉的节点数 / 线路数 / 整条消失的通道声明数 |
91
+
92
+ 载荷里的 `points` / `lines` / `channels` 与其它数据变更一样是**删除之后的最新数据**,不是删除项;删除项看 `removedPoints` / `removedLineItems`。被删掉的要素会从选中集里移除,没被删的选中项保持原样。
93
+
94
+ 开了 `history` 时整次删除只落一步 `filterRemove`。撤销会恢复数据,但当前 `remove` 条件仍保留,历史回放本身不会再触发删除(恢复出来的不命中项会先按筛选结果隐藏);重做恢复删除结果,也不会补发第二条 `filterRemove`。历史关着时删除不可撤消。
95
+
96
+ 初始筛选在同步路径下(`filterWorker: false`、数据量低于阈值,或条件里带函数)会在 `ready` 之前完成删除;如果初始筛选走了 Worker,结果异步回来,删除与 `onFilter` 会发生在 `ready` 之后,结果回来之前先按隐藏集合画首帧。运行时 `setFilter({ … mode: 'remove' })` 同理。
97
+
57
98
  ### 大数据下的 Worker 筛选
58
99
 
59
100
  数据量大时把判定放进 Web Worker,主线程只负责应用隐藏下标:
@@ -72,28 +113,39 @@ Worker 按投影版本缓存字段投影,条件变化时只传条件本身;
72
113
 
73
114
  ## 搜索与定位
74
115
 
75
- 搜索和筛选是两件事:**筛选**(`setFilter`)决定哪些要素显示,会隐藏数据;**搜索**(`search`)只把要素找出来,不隐藏任何东西,**也不动视角**:命中连 `bounds` 一起给回来,要不要聚焦、聚焦谁由调用方自己调 `focusOn`(组件只给结果,不再替使用方决定相机):
116
+ 搜索和筛选是两件事:**筛选**(`setFilter`)默认只隐藏显示,不删数据、也不改选中集,显式写 `mode: 'remove'` 才会删;**搜索**(`search`)只把要素找出来,不隐藏任何东西,**也不动视角**:命中连 `bounds` 一起给回来,要不要聚焦、聚焦谁由调用方自己调 `focusOn`(组件只给结果,不再替使用方决定相机):
76
117
 
77
118
  ```js
78
119
  // 关键字可以是字符串,也可以是配置对象
79
120
  const result = view.search('望京')
80
- view.search({ keyword: '525 变电站', scope: 'channels', limit: 50 })
121
+ view.search({ keyword: '525 变电站', scope: ['channels', 'groups'], limit: 50 })
122
+ view.search({ keyword: 'channel-a', scope: 'group' }) // 单数别名与 focusOn 的目标类型一致
81
123
 
82
124
  result.total // 命中总数
83
- result.points / result.lines / result.channels // 三类各自的命中
84
- result.hits // 三类合集,顺序是节点、线路、通道
125
+ result.points / result.lines / result.channels / result.groups // 四类各自的命中
126
+ result.hits // 四类合集,顺序是节点、线路、通道、分组
85
127
  result.truncated // 命中数达到 limit 被截断
86
128
  result.durationMs
87
129
 
88
130
  // 一条命中带命中的字段、值与范围,用来回写界面或自己定位(这份最小场景里搜不到时 hit 是 undefined)
89
131
  const hit = result.hits[0]
90
- hit?.kind // 'point' | 'line' | 'channel'
91
- hit?.index // 点 / 线在数据里的下标,通道是通道下标
92
- hit?.id / hit?.item / hit?.bounds // 范围可以直接交给 zoomToBounds
132
+ hit?.kind // 'point' | 'line' | 'channel' | 'group'
133
+ hit?.index // 点 / 线在数据里的下标,通道是通道下标,分组是 groups 结果里的下标
134
+ hit?.id / hit?.item / hit?.bounds // 范围可以直接交给 zoomToBounds / focusOn
93
135
  hit?.field / hit?.value // 命中的是哪个字段、字段值是什么(如 'props.vn_kv')
136
+ hit?.channelIndex / hit?.memberIndex // 线路 / 通道命中的所属通道与第几回(通道命中自身字段时没有 memberIndex)
137
+ hit?.memberLineIndex / hit?.memberLineId // 通道因某条成员回线命中时,那条回线在 lines 里的下标与 id
138
+ hit?.groupId / hit?.groupIndex // 分组命中:分组 id 与它在所属通道里的序号(从 0 起)
139
+
140
+ // 分组命中可以直接交给 focusOn / selectFeatures,与手写 { type: 'group', channelIndex, groupId } 等价
141
+ const grouped = view.search({ keyword: 'group-2', scope: 'group' }).groups[0]
142
+ view.focusOn(grouped) // 只把中心移到这一组,比例不动
143
+ view.focusOn(grouped, { zoom: true }) // 显式按这一组的真实 bounds 适配
144
+ view.selectFeatures(grouped) // 选中这一组的全部成员回线
94
145
 
95
146
  // focusOn:把视角移到目标上 —— 单条、一批、只居中都由它一条搞定
96
- view.focusOn(hit) // 一条命中:按它的范围适配视图
147
+ view.focusOn(hit) // 一条命中:缺省只居中,比例一点不动
148
+ view.focusOn(hit, { zoom: true }) // 显式按命中范围适配视图
97
149
  view.focusOn('station-1024', { scale: 12 }) // 直接给比例
98
150
  view.focusOn({ type: 'point', id: 'station-1024' }) // 节点 / 线路同 id 时显式消歧
99
151
  view.focusOn({ type: 'line', id: 'station-1024' })
@@ -102,10 +154,10 @@ view.focusOn({ type: 'channel', channelId: 'channel-a' }) // 通道也可以直
102
154
  view.focusOn({ type: 'group', channelId: 'channel-a', groupId: 'group-2' })
103
155
  view.focusOn({ type: 'group', groupId: 'group-2' }) // groupId 全局唯一时可省略通道
104
156
  view.focusOn([116.4, 39.9]) // 一个坐标点:只居中,比例不动
105
- view.focusOn(['station-1', 'station-2', 'station-3']) // 一批:取整体包围盒 —— 这三个点的中心当屏幕中心
106
- view.focusOn(['station-1', 'station-2'], { select: true }) // 顺带把它们选上(与接口选中同一份 state)
107
- view.focusOn('station-1', { maxZoom: 8 }) // 单个节点这种零面积目标也能放大到 8 倍
108
- view.focusOn({ minX: 116, minY: 39, maxX: 117, maxY: 40 }, { padding: 60 })
157
+ view.focusOn(['station-1', 'station-2', 'station-3']) // 一批:整体中心当屏幕中心,比例不动
158
+ view.focusOn(['station-1', 'station-2'], { select: true, zoom: true }) // 适配范围并顺手选上
159
+ view.focusOn('station-1', { zoom: true, maxZoom: 8 }) // 零面积目标也能放大到 8 倍
160
+ view.focusOn({ minX: 116, minY: 39, maxX: 117, maxY: 40 }, { zoom: true, padding: 60 })
109
161
 
110
162
  // 只挪中心、比例一点都不动:focusOn(target, { center: true })
111
163
  view.focusOn([116.4, 39.9], { center: true }) // 世界坐标(数组 / { x, y } 都认)
@@ -115,36 +167,39 @@ view.focusOn({ lngLat: [116.4, 39.9] }, { center: true }) // 配了 GeoJSON 底
115
167
  view.focusOn({ minX: 116, minY: 39, maxX: 117, maxY: 40 }, { center: true }) // 一段范围:取中心
116
168
  ```
117
169
 
118
- 字符串 / 数字仍然兼容旧写法:先按节点 id 找,再按线路 id 找;同一个 id 同时出现在节点与线路里时用 `{ type: 'point' | 'line', id }` 消歧。裸字符串不表示通道;整条通道可以写 `{ channelId }`,要和通用 `id` / `index` 写法区分时再用 `{ type: 'channel', ... }`。分组必须写 `{ type: 'group', channelId?, groupId }`,`groupId` 在全部通道里唯一时可以省略通道。节点、线路、通道与分组都先解析成世界坐标范围再交给同一条 `zoomToBounds` 路径,聚焦比例口径一致,没有为某类目标额外乘放大倍率。
170
+ 字符串 / 数字仍然兼容旧写法:先按节点 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` 只给单点 / 单线这类零面积目标补最小范围。
119
171
 
120
172
  | `focusOn` 的选项 | 说明 |
121
173
  | --- | --- |
122
- | `scale` | 直接设成这个比例,不再按范围适配 |
123
- | `center: true` | 只把中心挪过去、比例一点不动(原来 `centerOn` 的能力并到了这里) |
124
- | `padding` | 按范围适配时四周留白(CSS 像素,缺省 40) |
125
- | `maxZoom` | 适配时的最大比例:单个节点 / 一条直线没有面积,靠它撑出一个最小范围 |
174
+ | `zoom: true` | 显式要求按目标范围适配视图;不写就只居中、比例不动 |
175
+ | `scale` | 直接设成这个比例,不再按范围适配(优先级高于 `zoom`);线路 / 通道 / 分组不会在此基础上再自动放大 |
176
+ | `center: true` | 显式只把中心挪过去、比例一点不动(与缺省行为一致,保留旧写法) |
177
+ | `padding` | 按范围适配(`zoom: true`)时四周留白(CSS 像素,缺省 40) |
178
+ | `maxZoom` | 适配(`zoom: true`)时的最大比例:单个节点 / 一条直线没有面积,靠它撑出一个最小范围 |
126
179
  | `select: true`(或另给一批写法) | 把这些被聚焦的要素同时变成选中状态(与接口选中同一份 state) |
127
180
  | `mode` | 配合 `select`:这一批怎么并进当前选中集(`replace` 缺省 / `add` / `toggle` / `remove`) |
128
181
 
129
182
  | 字段 | 类型 | 默认值 | 说明 |
130
183
  | --- | --- | --- | --- |
131
184
  | `keyword` | `string` | 无 | 关键字:空格分隔多个词时要在同一个字段里全部出现才命中,不区分大小写 |
132
- | `scope` | `'points' \| 'lines' \| 'channels'` 或它们的数组 | 三类都搜 | 搜索范围 |
185
+ | `scope` | `'points' \| 'lines' \| 'channels' \| 'groups'` 或它们的数组;也认单数别名 `'point'` / `'line'` / `'channel'` / `'group'` | 四类都搜 | 搜索范围 |
133
186
  | `fields` | `string[]` | 要素的全部字段 | 限定参与匹配的字段路径,如 `['name', 'props.vn_kv']` |
134
187
  | `limit` | `number` | `200` | 每类的命中上限,`0` 表示不限 |
135
188
 
136
189
  补充口径:
137
190
 
138
- - `limit` 按「节点 / 线路 / 通道」三类分别计数;省略或写成非数字 / `NaN` 时回落到默认 `200`,不会退化成不限。`0` 与负数都表示不限。
191
+ - `limit` 按「节点 / 线路 / 通道 / 分组」四类分别计数;省略或写成非数字 / `NaN` 时回落到默认 `200`,不会退化成不限。`0` 与负数都表示不限。
139
192
  - `fields` 会忽略空项并去重;数组为空或没有有效字段路径时,与不写 `fields` 一样按全部字段处理。
140
193
  - 默认全字段模式会跳过 `symbol` / `style` / `tooltip` 这类外观结构;但 `fields` 显式点名时按路径直接读取,不受这条跳过规则限制。例如 `fields: ['symbol']`、`fields: ['style.color']` 能命中对应值。
141
- - 搜索始终基于全量数据,不受当前 `setFilter` 影响:被筛选隐藏的要素仍然可以被搜到。`scope` 写错或传空数组时会回落到三类全搜;重复线路 id 按数据里的第一条解析(见 [ID 解析口径](02-坐标与数据.md#id-解析口径))。
194
+ - 搜索基于当前数据:`hide` 模式下被隐藏的要素仍在数据里,因此仍然可以被搜到;`remove` 模式下已经删掉的要素搜不到。`scope` 写错或传空数组时会回落到四类全搜;重复线路 id 按数据里的第一条解析(见 [ID 解析口径](02-坐标与数据.md#id-解析口径))。
195
+
196
+ 搜索**不动视角**:命中里带着 `bounds`,要定位就自己调 `focusOn(result.hits, …)` —— 缺省只把一批命中的整体中心当屏幕中心;要按范围适配就写 `{ zoom: true }`,`{ select: true }` 还能顺带把它们选上。`zoom` / `scale` / `padding` / `maxZoom` 属于 `focusOn` 的选项,搜索本身没有这些参数。
142
197
 
143
- 搜索**不动视角**(`focus` / `scale` / `padding` 三个选项随之取消):命中里带着 `bounds`,要定位就自己调 `focusOn(result.hits, …)` —— 一批命中的整体中心就是屏幕中心,`{ select: true }` 还能顺带把它们选上。
198
+ 匹配的是要素自己的字段:`id`、`name`、`from` / `to`,以及任意业务字段——`props` 这类普通对象会再往里摊一层,所以 `props.vn_kv` 里的值也能搜到;样式与符号字段不参与匹配。**通道连成员回线一起搜**:命中的是通道里的某条回线时,命中里会带上 `channelIndex`、`memberIndex`(第几回,0 开始)与 `memberLineIndex` / `memberLineId`,`bounds` 也换成那条回线的范围,`focusOn(hit)` 会把中心移到通道里的这条线路上,`focusOn(hit, { zoom: true })` 才按它的范围适配;反过来搜线路时,属于通道的线路也会带上 `channelIndex` / `memberIndex`。
144
199
 
145
- 匹配的是要素自己的字段:`id`、`name`、`from` / `to`,以及任意业务字段——`props` 这类普通对象会再往里摊一层,所以 `props.vn_kv` 里的值也能搜到;样式与符号字段不参与匹配。**通道连成员回线一起搜**:命中的是通道里的某条回线时,命中里会带上 `channelIndex`、`memberIndex`(第几回,0 开始)与 `memberLineIndex` / `memberLineId`,`bounds` 也换成那条回线的范围,`focusOn(hit)` 因此会直接定位到通道里的这条线路;反过来搜线路时,属于通道的线路也会带上 `channelIndex` / `memberIndex`。
200
+ **分组按分组自身字段匹配**(`id` / `channelId` / `channelIndex` / `groupIndex` / `lineCount` / `anchored` / `edited` 等)。命中项的 `item` 是轻量快照(含成员下标 `lineIndexes` 与成员 id `lineIds`,不含骨架 / 回线几何),同时带上 `channelIndex`、`groupId`、`groupIndex`;`bounds` 由这一组的骨架与成员线算出,所以 `focusOn(hit, { zoom: true })` 会按整组范围适配,`selectFeatures(hit)` 会选中组内全部回线。分组搜索结果在 `result.groups`,也包含在 `result.hits` 里。
146
201
 
147
- 搜索是同步、只读的:不改数据、不改筛选、不产生额外的渲染状态,按关键字顺序返回。要「隐藏不符合条件的要素」用 `setFilter`;要「找出来」用 `search`,要「居中 / 放大过去」自己调 `focusOn`。
202
+ 搜索是同步、只读的:不改数据、不改筛选、不产生额外的渲染状态,按关键字顺序返回。要「只隐藏不符合条件的要素」用默认的 `setFilter`(`mode: 'hide'`),要「从数据里删掉」显式写 `mode: 'remove'`;要「找出来」用 `search`,要「居中 / 放大过去」自己调 `focusOn`。
148
203
 
149
204
  ### 异步搜索:`searchAsync`
150
205
 
@@ -153,13 +208,14 @@ view.focusOn({ minX: 116, minY: 39, maxX: 117, maxY: 40 }, { center: true }) //
153
208
  ```js
154
209
  // 每次调用都会 resolve 自己那一次的命中;worker 说明这一份是在哪算的
155
210
  const result = await view.searchAsync('望京')
156
- view.searchAsync({ keyword: '525 变电站', scope: 'channels' })
211
+ view.searchAsync({ keyword: '525 变电站', scope: ['channels', 'groups'] })
212
+ view.searchAsync({ keyword: 'channel-a', scope: 'group' })
157
213
 
158
214
  // 连着敲字:先回来的那几份带着 stale,界面上该丢掉(视角也不会跟着它动)
159
215
  let latest = 0
160
216
  const search = async keyword => {
161
217
  const token = ++latest
162
- const result = await view.searchAsync({ keyword, focus: false })
218
+ const result = await view.searchAsync({ keyword })
163
219
  if (result.stale || token !== latest) return
164
220
  render(result)
165
221
  }
@@ -172,7 +228,7 @@ const search = async keyword => {
172
228
  | `worker` | `boolean` | 这一份是在 Worker 里算的(`false` 表示这条路上退回了同步计算) |
173
229
  | `stale` | `boolean` | 结果回来时数据已经改过、或者又发过一次搜索:下标与内容都可能不作数了 |
174
230
 
175
- 同步的 `search` 与 `searchAsync` 在**同一个数据版本 + 同一个请求**上结果逐字段一致(命中、命中的字段与值、`item` 引用、`bounds`)。环境不支持 Worker、数据量不到阈值或 Worker 报错时,`searchAsync` 会退回同步计算再 resolve,调用方不用写两条路。
231
+ 同步的 `search` 与 `searchAsync` 在**同一个数据版本 + 同一个请求**上结果逐字段一致(四类命中、命中的字段与值、`item` 引用、`bounds`);分组范围的当前轻量快照会随请求交给 Worker,分组字段或分组 id 改过之后也不会拿旧快照匹配。环境不支持 Worker、数据量不到阈值或 Worker 报错时,`searchAsync` 会退回同步计算再 resolve,调用方不用写两条路。
176
232
 
177
233
  ## 初始视图
178
234
 
@@ -209,9 +265,9 @@ createGisView(container, {
209
265
  「本来铺得好好的,新加一个远处的节点,整幅视图缩了一圈、两点之间的可视距离变短」——根因是**自动适应读的是数据包围盒**:新节点把包围盒撑大,`fitView()` 按更大的范围重算 `scale`,比例一变小,节点之间的屏幕距离就跟着短(节点自己的屏幕尺寸由 `pointSizeScale` 那一对系数决定,没跟着缩,看着就更挤)。先想清楚「视野由谁说了算」,再按场景选:
210
266
 
211
267
  1. **视野只由业务范围决定(推荐)**:配 `initialView: { bounds, padding }`(或 `mode: 'center'` + `scale`)把首屏钉在一块业务范围上 —— `bounds` 不跟着数据长,新节点进来包围盒变大也不影响相机;数据分布本来就广时,业务范围与数据边界分开正是想要的。
212
- 2. **新节点不进自动适应**:`fitView()` 只手动调(首屏一次、切数据集一次),`addPoint` / `addPoints` 追加之后组件不会自动适应;要展示新节点就 `focusOn(id)` 或高亮 / `setDropPreview`,别整幅重适应。
268
+ 2. **新节点不进自动适应**:`fitView()` 只手动调(首屏一次、切数据集一次),`addPoint` / `addPoints` 追加之后组件不会自动适应;要展示新节点就 `focusOn(id, { zoom: true })` 或高亮 / `setDropPreview`,别整幅重适应。
213
269
  3. **只平移不改比例**:`setCamera({ center })` 或 `focusOn(id, { center: true })` —— 中心挪过去、`scale` 一点不动,两点之间的屏幕距离就不变。
214
- 4. **按「节点间距」而不是「包围盒」算适应**:`focusOn([...几个代表性要素])` / `zoomToBounds(业务范围)`;也可以给 `minScale` 一个下界,缩到这条线就停住。
270
+ 4. **按「节点间距」而不是「包围盒」算适应**:`focusOn([...几个代表性要素], { zoom: true })` / `zoomToBounds(业务范围)`;也可以给 `minScale` 一个下界,缩到这条线就停住。
215
271
  5. **想让节点本身不跟着缩**:`pointZoomScale` / `lineZoomScale` 调小(`0` = 完全不跟随地图缩放),尺寸主要由 `pointSizeScale` / `lineWidthScale` 的常数倍数决定 —— 比例被带跑时至少节点不会一起变小。
216
272
 
217
273
  6. **给节点最小间距兜底(先试它)**:打开 `fitSpacing` —— 适应视图时按可见节点最近中心距反推比例,远处孤立点撑大包围盒也不会再把主体压成一团;孤立点允许落到视口外,必要时用 `maxZoom` 限制放大倍数,见「适应视图的节点间距(fitSpacing)」。
@@ -257,7 +313,7 @@ view.updateOptions({ fitSpacing: false }) // 关掉,下一次 fitView 恢复
257
313
 
258
314
  几个约定:
259
315
 
260
- - **默认关**,打开后只影响「默认 fit 模式下的首次适应」与手动 `fitView()`;`zoomToBounds()` / `focusOn()` 仍按指定范围算,不会强行套节点间距。
316
+ - **默认关**,打开后只影响「默认 fit 模式下的首次适应」与手动 `fitView()`;`zoomToBounds()` / `focusOn(..., { zoom: true })` 仍按指定范围算,不会强行套节点间距。
261
317
  - 只统计**筛选 / 隐藏之后仍然可见**的节点。完全重合的坐标不算有效间距(否则两个重叠点会让整套兜底失效);少于两个不同位置时不调整。
262
318
  - **只放大、不跳视点**:`fitSpacing` 不重算中心,也不挑一对节点居中。需要改变中心时用 `initialView.center` / `initialView.bounds`、`focusOn()` 或 `setCamera({ center })`。
263
319
  - `minDistance` 是节点**中心之间**的屏幕距离(CSS 像素),默认 `24`。想给节点本身和描边留更多空隙就调大。
@@ -332,13 +388,20 @@ createGisView(container, {
332
388
  height: 132,
333
389
  position: 'bottom-right',
334
390
  margin: 12,
391
+ // 相对当前角落的位移(CSS 像素):x 正数向右、y 正数向下;updateOptions 改它就能移动整张图
392
+ offset: [0, 0],
393
+ // 外部宿主:HTMLElement 或选择器;不写就挂在主视图根节点。外部宿主需要 position: relative
394
+ // container: document.querySelector('#my-minimap-host'),
335
395
  padding: 0.04, // 数据四周留白,取短边比例
336
396
  // 范围:'auto'(默认)数据与底图合起来、'data' 只看数据(老行为)、'background' 只看底图
337
397
  // 也能直接写死一份世界范围:extent: { minX: 0, minY: 0, maxX: 1000, maxY: 800 }(固定按它铺,不跟数据与底图走)
338
398
  extent: 'auto',
399
+ // 仅 extent: 'auto' 生效;默认 false 始终按数据 ∪ 底图,打开后才允许按相机位置收窄
400
+ extentFollowCamera: false,
339
401
  // 小图背景:inherit(默认,复用主视图解析好的背景)/ false 关掉 / 对象自己配一份
340
402
  background: 'inherit',
341
- backgroundStyle: 'rgba(255, 255, 255, 0.92)', // 小图容器自身的 CSS 底色
403
+ // 显式设置时接管画布底色:继承的底图仍画图片 / GeoJSON,但不再用主图底色盖住它
404
+ backgroundStyle: 'rgba(255, 255, 255, 0.92)',
342
405
  borderColor: '#d7e2ef',
343
406
  radius: 6,
344
407
  pointStyle: { color: '#4b8dff', size: 1.4 },
@@ -348,13 +411,13 @@ createGisView(container, {
348
411
  lineWidthScale: 1,
349
412
  pointMapZoomScale: 0.5, // 主图放大 4 倍,小图节点放大 2 倍(基准缺省取主图适应视图时的比例)
350
413
  lineMapZoomScale: 0.5,
351
- // 小图自己的规则:颜色、半径 / 线宽、形状、层级都能按属性给;不配就沿用主图规则的颜色与层级
414
+ // 小图自己的规则:颜色、半径 / 线宽、形状、层级都能按属性给;不配就沿用主图样式(含尺寸与图标)
352
415
  pointRules: [
353
416
  { when: { vn_kv: { gte: 500 } }, style: { color: '#ff4d4f', size: 1.8, shape: 'square', zIndex: 2 } },
354
417
  { when: { vn_kv: { lt: 500 } }, style: { color: '#8c9aae', size: 1.2, zIndex: 1 } }
355
418
  ],
356
419
  lineRules: [{ when: { vn_kv: { gte: 500 } }, style: { color: '#ff8a3d', width: 1.2, opacity: 0.9, zIndex: 1 } }],
357
- inheritRules: true, // 没配自己的规则时才沿用主图的(只取颜色 / 描边色 / 透明度 / 层级,主图的尺寸是主画布上的像素)
420
+ inheritRules: true, // 没配自己的规则时才沿用主图:颜色 / 透明度 / 层级 + 最终节点尺寸与图标、线路线宽
358
421
  levels: [1, 2], // 只画这两层(按规则的 zIndex 分层,没写 zIndex 算第 0 层);不配就是全画
359
422
  cascade: 'binding', // 被 levels 挡掉的节点,连在它身上的线路一起隐藏;写法与筛选的 cascade 一样
360
423
  layered: true, // 分层叠画:zIndex 大的盖在上面;关掉就按数据顺序画
@@ -368,13 +431,14 @@ createGisView(container, {
368
431
  // 一次手势完成后的回调(无位移的点击不发):载荷带 type / local / world / zoom / extent / camera / viewport
369
432
  onInteraction: info => console.log(info.type, info.world),
370
433
  longPressDelay: 180,
371
- zoomable: false, // 打开后小图自身也能整体放大缩小,滚轮与下面这组倍数都归它
372
- zoom: 1, // 初始倍数,1 表示「刚好铺满小图」
434
+ zoomable: false, // false 关闭;true 手动缩放小图;'follow' 整体范围跟随主图。true 与 'follow' 互斥
435
+ followZoomScale: 1, // 仅 'follow' 生效:主图倍数的指数,1 同倍率、0.5 为主图放大 4 倍时小图放大 2 倍
436
+ zoom: 1, // 小图倍数;手动模式是初始值,跟随模式是基准倍数。1 表示「刚好铺满小图」
373
437
  minZoom: 0.5,
374
438
  maxZoom: 8,
375
439
  zoomStep: 1.4, // 每一次放大 / 缩小的倍率(滚轮一格、zoomInStep / zoomOutStep 可分别覆盖)
376
- dragAction: 'pan', // 开了 zoomable 之后,空白处拖动是平移小图(默认)还是直接框选
377
- channelCircuits: true, // 通道画全部回线;false 时一个通道只画偏移最靠中间的那一根
440
+ dragAction: 'pan', // 空白处拖动是平移小图(默认,需手动缩放)还是直接框选;box 不依赖 zoomable
441
+ channelCircuits: true, // 通道画全部回线;false 时每组按可见成员逐顶点平均成一根居中代表线
378
442
  // 容器外观:附加类名 + 内联样式(中划线 / CSS 变量与驼峰键都认,换配置时旧键会清掉)
379
443
  className: 'my-minimap',
380
444
  style: { boxShadow: '0 2px 10px rgba(0, 0, 0, 0.18)' },
@@ -407,64 +471,107 @@ createGisView(container, {
407
471
  | `width` / `height` | `number` | `168` / `120` | 小图尺寸(CSS 像素) |
408
472
  | `position` | `'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'` | `'bottom-right'` | 贴在画布的哪一角 |
409
473
  | `margin` | `number` | `12` | 与画布边缘的距离(CSS 像素) |
474
+ | `offset` | `[number, number]` | `[0, 0]` | 相对 `position` 那个角的位移(CSS 像素):`x` 正数向右、`y` 正数向下。`updateOptions({ minimap: { ...old, offset: [x, y] } })` 就能动态移动整张鹰眼图,四个角都按同一套方向换算 |
475
+ | `container` | `HTMLElement \| string \| null` | 无(主视图根节点) | 把鹰眼图挂到外部 `div`:可传元素或 CSS 选择器。给了就把同一根节点移进它,`position` / `margin` / `offset` 都相对这个宿主;宿主需要 `position: relative`(或 `absolute` / `fixed`)。选择器找不到时回落到主视图根节点;运行时换容器只移动节点,不重建画布。用 `view.getMinimapElement()` 可以拿到这个根节点做整图拖动 |
410
476
  | `padding` | `number` | `0.04` | 数据四周留白,取短边比例 |
411
- | `extent` | `'auto' \| 'data' \| 'background' \| GisViewBounds \| [[number, number], [number, number]]` | `'auto'` | 小图按哪段世界范围铺:`auto` 取「数据范围 ∪ 底图范围」,`data` 只看数据(旧行为),`background` 只看底图;数据与 GeoJSON 底图不在一个坐标系时,`auto` 能把两者一起框进小图,底图不会缩成一个点/糊成一片。例外:相机正落在其中一份范围里、而那一份合并后连 6 个像素都占不到时,`auto` 只画正在看的那一份(数据还没映射到底图、两者离得很远就是这样),相机挪进 / 挪出会各重画一次。也可以直接写一份世界范围(`{ minX, minY, maxX, maxY }`,也认 `[[minX, minY], [maxX, maxY]]`):固定按它铺,不跟数据与底图走 |
477
+ | `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 个像素都占不到时,只画正在看的那一份(数据还没映射到底图、两者离得很远时最明显),相机挪进 / 挪出会各重画一次 |
412
479
  | `className` / `style` | `string` / `Record<string, string \| number>` | 无 | 小图容器自己的类名与内联样式(中划线 / CSS 变量键与驼峰键都认):想按自己的设计系统改外观时用;换配置时上一轮写过、这一轮没写的键会被清掉 |
413
480
  | `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 收好,不会漏进下一帧 |
414
481
  | `layers` | `GisViewMinimapLayer[]` | 无 | 可拆分的自定义绘制层:每项写 `{ id?, order?, placement?, enabled?, draw }`。`placement: 'below-data'` 画在内置线路 / 节点之前,`'above-data'`(默认)画在之后;同一段内按 `order` 从小到大,相同或未写时按数组顺序。每层独立 `save` / `restore`,一层改过的画布状态不会串到下一层;`enabled: false` 可临时关掉一层。回调里的 `stage` 就是当前段,旧的单层 `draw` 固定最后执行。排序在 `updateOptions` 时缓存,绘制帧不再逐层排序 |
415
482
  | `maxPixelRatio` | `number` | `4` | 小图画布备份像素比的上限(实际倍率 = `min(devicePixelRatio × 宿主显示比例, maxPixelRatio)`,夹在 1 ~ 4)。默认 4 保留高分屏清晰度;小图尺寸大或高分屏填充压力高时降到 1 ~ 2 可明显减少像素填充,代价是缩略图边缘变软 |
416
483
  | `background` | `'inherit' \| false \| 'none' \| GisViewBackground \| string` | `'inherit'` | 小图画什么底图:`inherit` 复用主视图解析好的背景(底色 / 图片 / GeoJSON 的逐区域配色与区域文字都跟着),传对象就是小图自己的一份(结构与主视图的 `background` 完全一致,用 Canvas2D 画),`false` / `'none'` 关掉;传字符串按旧行为当容器底色 |
417
- | `backgroundStyle` | `string` | `'rgba(255, 255, 255, 0.92)'` | 小图容器自己的 CSS 底色,垫在 `background` 下面(想让小图透出主视图底色就写 `transparent`) |
484
+ | `backgroundStyle` | `string` | `'rgba(255, 255, 255, 0.92)'` | 小图容器自己的 CSS 底色。**显式设置时接管画布底色**:继承 / 独立的底图仍画图片与 GeoJSON,但画布不再铺一层不透明底色把它盖住;不写时保持旧行为。想要完全透出宿主就写 `transparent` |
418
485
  | `borderColor` / `borderWidth` / `radius` | `string` / `number` | `#d7e2ef`、1px、6px | 小图自身的外观 |
419
- | `pointStyle` | `{ color?, strokeColor?, size? }` | `#4b8dff` / `1.2` | 节点的颜色与画在小图上的半径,与主图样式无关;节点画在线路之上。小图上的点是一块**实心像素**,配了 `strokeColor` 就优先取它当填充色 —— 主图那套「白底 + 彩色描边」的规则沿用过来时,画出来就是描边色而不是白点 |
486
+ | `pointStyle` | `{ color?, strokeColor?, size? }` | `#4b8dff` / `1.2` | 小图自己的节点颜色与半径(CSS 像素),用于没有自己的 `pointRules` / 不继承主图样式时的回落;节点画在线路之上。小图上的点是一块**实心像素**,配了 `strokeColor` 就优先取它当填充色 —— 主图那套「白底 + 彩色描边」的规则沿用过来时,画出来就是描边色而不是白点 |
420
487
  | `lineStyle` | `{ color?, width?, opacity? }` | `#8fb2d8` / `1` / `0.55` | 线路的颜色、线宽与透明度,`opacity: 0` 就是不画线 |
421
488
  | `pointRules` | `GisViewMinimapPointRule[]` | 无 | 小图自己的节点规则:按属性给每个节点定颜色 / 半径 / 形状(`'circle'` / `'square'`)/ 层级,条件语言与主图的 `pointRules` 完全一样;规则里没写的字段回落到 `pointStyle` |
422
489
  | `lineRules` | `GisViewMinimapLineRule[]` | 无 | 小图自己的线路规则:颜色 / 线宽 / 透明度 / 层级,规则里没写的字段回落到 `lineStyle` |
423
490
  | `heatmap` | `GisViewHeatmap \| false` | 沿用主图 | 小图自己的热力图:不写就沿用主图的 `options.heatmap`(同一份色带与自动值域),写对象就单独换一份,`false` 表示小图不按热力着色(主图照旧),见「热力图」 |
424
- | `inheritRules` | `boolean` | `true` | 没配自己的规则时是否沿用主图的 `pointRules` / `lineRules`:只取颜色、透明度与层级这些**没有量纲**的字段(主图的 `size` / `width` 是主画布上的像素,照搬到小图上会糊成一片),尺寸仍由小图的 `pointStyle` / `lineStyle` 决定;显式 `false` 表示小图只用自己那份样式 |
491
+ | `inheritRules` | `boolean` | `true` | 没配自己的规则时是否沿用主图样式:节点取主图规则的颜色 / 描边色 / 层级,并沿主图最终解析出的尺寸与图标(点自身 > 规则 > `pointStyle`,圆、方、图片、SVG 与自定义图元都认);沿用尺寸 / 线宽时还会乘一次**小图与主图 CSS 视口宽高的较小比例**,只跟两边视口尺寸有关,不随主图相机倍数变化,小图比主图小时节点与线路不会仍顶着和主图一样的尺寸。线路沿用颜色 / 透明度与样式链线宽。显式 `false` 表示小图只用自己那份 `pointStyle` / `lineStyle` |
425
492
  | `levels` | `number[]` | 无 | 只画这些层级的节点:层级取规则的 `zIndex`(没写算第 0 层),不配表示全部画;「每一层显示什么级别」就是它 —— 按电压写了 `zIndex` 之后,只看 500kV 以上就写 `levels: [500, 1000]` |
426
493
  | `cascade` | `false \| 'binding' \| 'coordinate' \| 'both'` | `'binding'` | 被 `levels` 挡掉的节点,连在它们身上的线路怎么跟着隐藏:`binding` 按 `from` / `to` 绑定、`coordinate` 按端点坐标(端点正好落在被挡掉的节点上)、`both` 两者都算、`false` 不联动。与主视图筛选的 `cascade` 是同一套说法 —— 主视图筛掉的要素本来就带联动,这里管的是小图**自己**挡掉的那部分;只看某几层时不会留下一堆凭空断掉的线 |
427
494
  | `layered` | `boolean` | `true` | 节点是否分层叠画:`zIndex` 大的后画、盖在上面;关掉就按数据顺序画(同坐标的节点谁在上面看数据顺序) |
428
- | `pointSizeScale` / `lineWidthScale` | `number` | `1` | 节点半径 / 线宽的**整体倍数**(常数,与小图倍数无关),与主视图的 `pointSizeScale` / `lineWidthScale` 同名同义,乘在 `pointStyle` / 规则给出的尺寸上 |
429
- | `pointZoomScale` / `lineZoomScale` | `number` | `0` | 小图**自身**倍数对节点半径 / 线宽的放大指数:`0` 不跟随、`1` 与小图同倍率放大,`0.5` 是小图放大 4 倍、节点放大 2 倍(`zoomable` 打开后放大小图,节点与线路跟着变大,放大多少就是它) |
430
- | `pointMapZoomScale` / `lineMapZoomScale` | `number` | `0` | **主视图地图倍数**对节点半径 / 线宽的放大指数:`0` 不跟随、`1` 与主视图同倍率放大、`0.5` 是主视图放大 4 倍、小图节点放大 2 倍;与主视图的 `pointZoomScale` / `lineZoomScale` 是同一套说法,缩放主视图时小图上的节点 / 线路跟着变大小(相机一变就重铺一次像素) |
495
+ | `pointSizeScale` / `lineWidthScale` | `number` | `1` | 节点半径 / 线宽的**整体倍数**(常数,与小图自身倍数、主图相机倍数都无关),与主视图的 `pointSizeScale` / `lineWidthScale` 同名同义;自有规则 / 样式与沿用主图的节点 / 线路都乘这一份(继承尺寸先按两图比例缩放,再叠这一层) |
496
+ | `pointZoomScale` / `lineZoomScale` | `number` | `0` | 小图**自身**倍数对节点半径 / 线宽的放大指数:`0` 不跟随、`1` 与小图同倍率放大,`0.5` 是小图放大 4 倍、节点放大 2 倍;手动缩放(`zoomable: true`)与跟随主图(`zoomable: 'follow'`)都会改变小图倍数,因此这两种模式下都能看到效果;沿用主图的节点 / 线路也按这一份联动,但主图相机本身不会直接改它们的大小 |
497
+ | `pointMapZoomScale` / `lineMapZoomScale` | `number` | `0` | **主视图地图倍数**对节点半径 / 线宽的放大指数:`0` 不跟随、`1` 与主视图同倍率放大、`0.5` 是主视图放大 4 倍、小图节点放大 2 倍;只作用于小图自有规则 / 样式,沿用主图的节点 / 线路不吃这一份(它们按两边视口比例缩放,主图相机变化不改大小) |
431
498
  | `mapZoomBaseScale` | `number` | 主视图适应视图时的比例 | 上面这组联动的基准比例,缺省与主视图共用同一份(主视图的 `zoomBaseScale` 或首次适应视图时的比例),等于它时联动系数为 1 |
432
499
  | `boxStyle` | `{ fill?, fillOpacity?, stroke?, strokeWidth?, strokeStyle?, radius?, shadow? }` | 蓝底 0.14 + 1px 蓝框 | 视口框(代表当前视口)的样式:填充色与不透明度、边框颜色 / 宽度 / 线型(`solid` / `dashed` / `dotted`,`strokeWidth: 0` 不画边框)、圆角与 CSS `box-shadow` |
433
500
  | `selectStyle` | `GisViewMinimapBoxStyle` | 沿用 `boxStyle`(虚线框、填充 0.12) | 拖动时拉出的框选矩形单独覆盖的样式字段,没写的字段继续沿用 `boxStyle` —— 只换底色 / 边框色就能和视口框区分开 |
434
501
  | `interactive` | `boolean` | `true` | 是否允许在小图上拖动 |
435
502
  | `onInteraction` | `(info: GisViewMinimapInteractionInfo) => void` | 无 | 一次手势真正完成时通知一条:`type` 为 `box-drag` / `select` / `pan` / `zoom` / `wheel-main` / `long-press`;载荷带 `local` / `world`、小图倍数 `zoom`、当前范围 `extent`、相机 `camera` 与视口 `viewport`。没有位移的点击不触发,`pointermove` 期间也不逐帧回调;长按在触发跟随的那一刻回调。适合同步业务状态、埋点或驱动外部图例 |
436
503
  | `longPressDelay` | `number` | `180` | 空白处按住多久之后开始跟着拖(毫秒) |
437
- | `wheelZoom` | `boolean` | `true` | 是否允许在小图上用滚轮缩放**主图**(锚点落在光标处);`zoomable` 打开时主图改成 Ctrl / ⌘ + 滚轮 |
438
- | `zoomable` | `boolean` | `false` | 鹰眼图自身是否可以整体放大缩小:打开后滚轮直接缩放小图(锚点落在光标处),Ctrl / ⌘ + 滚轮仍然缩放主图 |
439
- | `zoom` / `minZoom` / `maxZoom` | `number` | `1` / `0.5` / `8` | 小图自身的倍数与范围:`1` 是刚刚铺满,`zoom` 是初始值,`setMinimapZoom` / `zoomMinimapBy` 与滚轮都在这个范围里夹取;`updateOptions` 里改了 `zoom` 或关掉 `zoomable` 会重置回铺满 |
504
+ | `wheelZoom` | `boolean` | `true` | 是否允许在小图上用滚轮缩放**主图**(锚点落在光标处);`zoomable: true` 时主图改成 Ctrl / ⌘ + 滚轮,`zoomable: 'follow'` 仍直接缩放主图 |
505
+ | `zoomable` | `boolean \| 'follow'` | `false` | 缩放模式:`false` 关闭;`true` 手动缩放小图自身(滚轮以光标为锚点,Ctrl / ⌘ + 滚轮留给主图);`'follow'` 让整体显示范围跟随主图倍数变化,滚轮仍缩放主图。`true` 与 `'follow'` 互斥,跟随模式下 `setMinimapZoom` / `zoomMinimapBy` 不抢控制权 |
506
+ | `followZoomScale` | `number` | `1` | 仅 `zoomable: 'follow'` 生效:主图相对基准倍数的指数。`1` 同倍率、`0.5` 是主图放大 4 倍时小图放大 2 倍、`0` 表示小图倍数不随主图变化;结果仍夹在 `minZoom` ~ `maxZoom` 之间 |
507
+ | `zoom` / `minZoom` / `maxZoom` | `number` | `1` / `0.5` / `8` | 小图自身的倍数与范围:`1` 是刚刚铺满;`zoom` 在手动模式下是初始值、在跟随模式下是基准倍数。`setMinimapZoom` / `zoomMinimapBy` 与手动滚轮都在这个范围里夹取;`updateOptions` 里改了 `zoom` 或切换缩放模式会按新模式重置/重算 |
440
508
  | `zoomStep` | `number` | `1.4` | 每一次放大 / 缩小的倍率:滚轮一格正好一个步进(连续滚动按比例取幂,单次最多两步),`zoomMinimapBy` 传的就是这个系数;`zoomInStep` / `zoomOutStep` 可以只覆盖放大或缩小一侧 |
441
- | `dragAction` | `'pan' \| 'box'` | `'pan'` | 开了 `zoomable` 之后,小图空白处(视口框之外)拖动的动作:`pan` 平移小图内容(主图不动,内容夹在数据范围里),`box` 直接拉出框选矩形;按住 Ctrl / ⌘ 拖动始终是另一个动作 |
442
- | `channelCircuits` | `boolean` | `true` | 通道是否画出全部回线:`false` 时一个通道只画偏移最靠中间的那一根(通道走向仍然看得出来),通道多的底图更清爽 |
509
+ | `dragAction` | `'pan' \| 'box'` | `'pan'` | 小图空白处(视口框之外)拖动的动作:`pan` 平移小图内容(主图不动,内容夹在数据范围里,需手动缩放才有可移动余量),`box` 直接拉出框选矩形让主图显示过去。`box` 不依赖 `zoomable`,关闭缩放时也能直接框选;只有手动缩放模式下,按住 Ctrl / ⌘ 才切换成另一个动作 |
510
+ | `channelCircuits` | `boolean` | `true` | 通道是否画出全部回线:`false` 时每个分组按当前可见成员逐顶点取平均,只画一根居中的代表线(双回线落在两根正中间,三回线落在中间那条),通道走向仍然看得出来,通道多的底图更清爽 |
511
+
512
+ 规则的用法与主图一致(同一套条件语言、按顺序命中、后命中的覆盖前面的),但只管小图的画法:节点按 `zIndex` 分层,`levels` 只留下指定层的节点,`layered: false` 时不排序、按数据顺序画;线路按「层级 + 颜色 + 线宽 + 透明度」分桶,一桶一条路径、一次 `stroke`,规则再多也不会把小图的绘制次数拉爆。没配自己的规则时(`inheritRules !== false`)完整沿用主图样式链:颜色 / 描边色 / 层级来自主图规则,节点尺寸与图标取主图最终解析出的那一份(点自身 > `pointRules` > `pointStyle`),线路线宽取主图样式链解析出的原始值,再按小图与主图 CSS 视口宽高的较小比例缩一次(不跟主图相机倍数走)—— 圆、方、图片、SVG 与自定义图元都保留主图的形状,但不会在小图上仍和主图一样大。显式配了小图自己的 `pointRules` / `lineRules`(或 `inheritRules: false`)时,对应的尺寸 / 线宽不受这一步影响,仍由小图自己的规则与样式决定;只配 `pointStyle` / `lineStyle` 不会单独关掉继承。节点的颜色取规则里的 `strokeColor`、没有才回落 `color`:主图的节点是白底 + 一圈电压色的描边,小图上一个点是一块实心像素,不这样取就会画成一堆白点(自己配的小图规则同样可以写 `strokeColor`)。
513
+
514
+ **动态位置与外部挂载**:`offset` 是整张鹰眼图相对当前角落的位移,最适合做「拖动整个小图」的底移量 —— 指针每移动一段,就把累计位移写回 `updateOptions`;`position` / `margin` 仍决定基准角落。
515
+
516
+ ```js
517
+ const minimapHost = document.querySelector('#minimap-slot')
518
+ const minimapHandle = document.querySelector('#minimap-handle')
519
+ view.updateOptions({ minimap: { ...view.getOptions().minimap, container: minimapHost } })
520
+
521
+ // 整图拖动:用宿主里的拖动条累计指针位移,再写回 offset;小图内容与视口框都不会重建
522
+ let drag = null
523
+ minimapHandle.addEventListener('pointerdown', event => {
524
+ const [offsetX, offsetY] = view.getOptions().minimap?.offset ?? [0, 0]
525
+ drag = { pointerX: event.clientX, pointerY: event.clientY, offsetX, offsetY }
526
+ minimapHandle.setPointerCapture(event.pointerId)
527
+ })
528
+ minimapHandle.addEventListener('pointermove', event => {
529
+ if (!drag) return
530
+ const options = view.getOptions().minimap
531
+ view.updateOptions({
532
+ minimap: {
533
+ ...options,
534
+ offset: [
535
+ drag.offsetX + event.clientX - drag.pointerX,
536
+ drag.offsetY + event.clientY - drag.pointerY
537
+ ]
538
+ }
539
+ })
540
+ })
541
+ const stopDrag = () => { drag = null }
542
+ minimapHandle.addEventListener('pointerup', stopDrag)
543
+ minimapHandle.addEventListener('pointercancel', stopDrag)
443
544
 
444
- 规则的用法与主图一致(同一套条件语言、按顺序命中、后命中的覆盖前面的),但只管小图的画法:节点按 `zIndex` 分层,`levels` 只留下指定层的节点,`layered: false` 时不排序、按数据顺序画;线路按「层级 + 颜色 + 线宽 + 透明度」分桶,一桶一条路径、一次 `stroke`,规则再多也不会把小图的绘制次数拉爆。没配自己的规则时沿用主图规则的颜色 / 透明度 / 层级(`inheritRules !== false`):主图按电压配色时小图自动同色,但主图那几十像素的尺寸不会搬过来 —— 小图上的半径仍然由 `pointStyle.size`(默认 1.2)与规则自己的 `size` 决定。节点的颜色取规则里的 `strokeColor`、没有才回落 `color`:主图的节点是白底 + 一圈电压色的描边,小图上一个点是一块实心像素,不这样取就会画成一堆白点(自己配的小图规则同样可以写 `strokeColor`)。
545
+ const minimapElement = view.getMinimapElement()
546
+ console.log(minimapElement?.parentElement === minimapHost) // true
547
+ ```
548
+
549
+ `container` 写元素或选择器都可以;外部宿主要设成 `position: relative`(`absolute` / `fixed` 也行),否则绝对定位会继续向上找基准。换容器只是移动同一个 `.gis-view__minimap` 根节点,画布、缓存与事件监听都保留;`destroy()` 会把它从当前外部宿主里一并摘掉。没配 `minimap` 时 `getMinimapElement()` 返回 `null`。
445
550
 
446
551
  `levels` 挡掉的节点会按 `cascade`(默认 `'binding'`)把连在它们身上的线路一起隐藏 —— 与主视图筛选的联动是同一套写法、同一个默认值:只看某几层的电压时,层外的节点与它们的线路一起消失,不会在小图上留下一堆凭空断掉的线。`cascade: 'coordinate'` 认的是端点坐标(线路数据只有 `path`、没有 `from` / `to` 时用它),`'both'` 两种写法都认,`false` 表示挡掉节点时线路照旧画。联动只影响小图的画法:数据、主视图、主视图的筛选结果都不动;小图的范围也跟着剩下的可见要素走(`measure` 只量小图真正画出来的节点与线路)。
447
552
 
448
- 小图的尺寸系数与主视图一一对应,三组各管一件事、相乘叠加:`pointSizeScale` / `lineWidthScale` 是整体倍数(常数,屏幕上恒定),`pointZoomScale` / `lineZoomScale` 跟的是**小图自身的倍数**(`zoomable` 打开、小图放大到 4 倍时,`pointZoomScale: 0.5` 让节点半径放大 2 倍、`1` 是同倍率放大、`0` 保持不变),`pointMapZoomScale` / `lineMapZoomScale` 跟的是**主视图的地图倍数**(相机比例 ÷ 基准,基准就是主视图 `pointZoomScale` 用的那一份,可以用 `mapZoomBaseScale` 覆盖):主图放大 4 倍时 `0.5` 让小图节点放大 2 倍、`1` 同倍率;配了这一组之后相机一变小图就重铺一次像素(只挪视口框不够用了),没配时一次比较都不做。注意前两个指数的「倍数」量的是**小图自身的倍数**:小图没开 `zoomable`、或者倍数还在 `1`(刚好铺满)时它们是恒等系数,怎么调都看不出变化;想让小图跟着主视图的缩放一起变,要配的是后面那组 `pointMapZoomScale` / `lineMapZoomScale`。
553
+ 小图的尺寸系数分三组,前两组对所有节点 / 线路生效,第三组只作用于小图自有规则 / 样式:`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'`。
449
554
 
450
- 小图的背景默认跟主视图一致(`background: 'inherit'`):底色、图片、GeoJSON 的填充 / 描边 / 逐区域配色与区域文字都换到小图自己的尺子上重画 —— GeoJSON 的线宽(最低 0.4px 保可见)、点要素半径(固定 1.2px)与区域文字字号(固定档,夹在 5 ~ 12px)都是小图上的固定像素,不再乘「小图比例 ÷ 主图比例」:缩放主视图时底图不会单独跟着放大 / 缩小,底图也不跟 `pointMapZoomScale` / `lineMapZoomScale` 走(那两个指数只管节点与线路),区域装不下这行字(屏幕矩形比文字小)就整条跳过;排布时按区域从大到小放,和已经放下的标签重叠的也跳过 —— 小图上几十个区域各画一行字只会叠成一团,最后一条都读不出来;图片按四角或 `fit` 算出的四边形做仿射 + 裁剪贴图(任意四边形都不会画歪),GeoJSON 面用奇偶规则填充(洞自动镂空)、纯线几何的区域再描一遍。也可以给 `minimap.background` 单独配一份(结构与主视图的 `background` 一样:`color` / `image` / `geoJson` / `geoJsonStyle` / `opacity`),「主图画数据、小图画行政边界」这类分工就很直接;`backgroundStyle` 是小图容器自己的 CSS 底色,垫在背景下面。主视图换了背景(`updateBackground` / `updateOptions({ background })`)小图会自动跟着重画。
555
+ 小图的背景默认跟主视图一致(`background: 'inherit'`):底色、图片、GeoJSON 的填充 / 描边 / 逐区域配色与区域文字都换到小图自己的尺子上重画 —— GeoJSON 的线宽(最低 0.4px 保可见)、点要素半径(固定 1.2px)与区域文字字号(固定档,夹在 5 ~ 12px)都是小图上的固定像素,不再乘「小图比例 ÷ 主图比例」:缩放主视图时底图不会单独跟着放大 / 缩小,底图也不跟 `pointMapZoomScale` / `lineMapZoomScale` 走(那两个指数只管小图自有规则 / 样式的节点与线路),区域装不下这行字(屏幕矩形比文字小)就整条跳过;排布时按区域从大到小放,和已经放下的标签重叠的也跳过 —— 小图上几十个区域各画一行字只会叠成一团,最后一条都读不出来;图片按四角或 `fit` 算出的四边形做仿射 + 裁剪贴图(任意四边形都不会画歪),GeoJSON 面用奇偶规则填充(洞自动镂空)、纯线几何的区域再描一遍。也可以给 `minimap.background` 单独配一份(结构与主视图的 `background` 一样:`color` / `image` / `geoJson` / `geoJsonStyle` / `opacity`),「主图画数据、小图画行政边界」这类分工就很直接。`backgroundStyle` 是容器的 CSS 底色;显式设置时它接管画布底色,继承或独立的底图仍画图片与 GeoJSON,但画布不再铺主图的不透明底色,不写时仍按主图底色铺满。主视图换了背景(`updateBackground` / `updateOptions({ background })`)小图会自动跟着重画。
451
556
 
452
- 交互与开销:**在框上按下直接拖框**(世界位移 = 屏幕位移 ÷ 小图比例),**空白处单击不改变视角**,按住超过 `longPressDelay` 才进入「跟着拖」,拖动过程中始终跟着光标;光标停在小图上滚动滚轮按光标位置缩放主图(`wheelZoom: false` 关掉)。每个有位移的手势结束时可通过 `onInteraction` 收到一条通知,不必自己在小图 DOM 上再挂一套指针监听。底图画的是筛选之后真正画出来的线,通道骨架与回线都在内(直接问引擎要几何,不用自己再推一遍通道偏移),画法是先铺线、再把节点整层盖上去 —— 节点层级高于线路,密集底图上的节点不会被线咬掉。底图只在数据或筛选结果变化时重画(节点直接写进像素缓冲,十万级也只在重建时花一次时间),相机变化只改视口框的 `transform`,所以拖动小图不掉帧。小图还会缓存**上一次的节点像素结果**与**数据范围**:一次改动排在前后两帧各重画一次(引擎重排之后要再取一次几何),第二次与第一次的数据、范围、尺寸完全一样时直接复用那份像素,十万点下第二次重画从 ~20ms 降到 0.3ms(配了 `pointMapZoomScale` / `lineMapZoomScale` 时把「主视图倍数」也并进缓存的键,倍数变了才重铺);`extent: auto` 的取舍跟相机有关,相机挪进 / 挪出那份小范围时才补一次重画(每帧只做几次比较,判断用的范围是缓存的)。小图拖框 / 小图滚轮带来的相机变化不算主画布上的交互:配了 `hideOnInteract` 的图层不会在这时被收起来,拖动结束还会补一次真实排版 —— 不会出现「动一下鹰眼图,主视图标签全没了」。真在主画布上拖动过之后、两层标签同时收着时,收尾计时器也照样挂上 —— 覆盖层停手的收尾是无条件的,不会因为「两层都在收着、当下没东西可排」把恢复一起跳过。
557
+ 交互与开销:**在框上按下直接拖框**(世界位移 = 屏幕位移 ÷ 小图比例),**空白处单击不改变视角**;未手动缩放且 `dragAction` 为 `pan` 时,按住超过 `longPressDelay` 才进入「跟着拖」;`dragAction: 'box'` 或手动缩放时,空白处按住即按对应动作开始,拖动过程中始终跟着光标;光标停在小图上滚动滚轮按光标位置缩放主图(`wheelZoom: false` 关掉)。每个有位移的手势结束时可通过 `onInteraction` 收到一条通知,不必自己在小图 DOM 上再挂一套指针监听。底图画的是筛选之后真正画出来的线,通道骨架与回线都在内(直接问引擎要几何,不用自己再推一遍通道偏移),画法是先铺线、再把节点整层盖上去 —— 节点层级高于线路,密集底图上的节点不会被线咬掉。底图只在数据或筛选结果变化时重画(节点直接写进像素缓冲,十万级也只在重建时花一次时间),相机变化只改视口框的 `transform`,所以拖动小图不掉帧。小图还会缓存**上一次的节点像素结果**与**数据范围**:一次改动排在前后两帧各重画一次(引擎重排之后要再取一次几何),第二次与第一次的数据、范围、尺寸完全一样时直接复用那份像素,十万点下第二次重画从 ~20ms 降到 0.3ms(配了 `pointMapZoomScale` / `lineMapZoomScale`(或存在沿用主图线宽的线路)时把「主视图倍数 / 两边视口比例」也并进缓存的键,倍数变了才重铺);打开 `extentFollowCamera` 后 `extent: auto` 的取舍才跟相机有关,相机挪进 / 挪出那份小范围时才补一次重画(每帧只做几次比较,判断用的范围是缓存的)。小图拖框 / 小图滚轮带来的相机变化不算主画布上的交互:配了 `hideOnInteract` 的图层不会在这时被收起来,拖动结束还会补一次真实排版 —— 不会出现「动一下鹰眼图,主视图标签全没了」。真在主画布上拖动过之后、两层标签同时收着时,收尾计时器也照样挂上 —— 覆盖层停手的收尾是无条件的,不会因为「两层都在收着、当下没东西可排」把恢复一起跳过。
453
558
 
454
559
  线路层另有自己的离屏 canvas 与缓存:缓存键包含画布尺寸、范围、投影、小图倍率与线路样式,命中时整层直接合成,不再重复投影与描边;`collectMinimapData()` 复制路径时顺路算出每条线的包围盒,完全落在小图视野外的线不建路径。只有布局尺寸实际变化时才重设 canvas 尺寸,单纯补画或移动视口框不会清空这份缓存。
455
560
 
456
- `zoomable: true` 之后小图自身也能整体放大缩小,空白处的拖动换成下面两种动作(单击不再需要长按,空白处不再走 `longPressDelay` 那条路):
561
+ `zoomable` 有三种互斥的模式:`false`(默认)只看固定范围,滚轮缩放主图;`true` 手动缩放小图自身(滚轮以光标为锚点,Ctrl / ⌘ + 滚轮仍留给主图);`'follow'` 让整个小图的显示范围跟随主图倍数变化(滚轮仍直接缩放主图,`followZoomScale` 是主图相对基准倍数的指数,`0` 表示不跟随、`1` 同倍率、`0.5` 是主图放大 4 倍时小图放大 2 倍;`zoom` 在这里是基准倍数,结果仍夹在 `minZoom` ~ `maxZoom`)。跟随模式下 `setMinimapZoom` / `zoomMinimapBy` 不抢控制权,倍数始终由主图决定。
562
+
563
+ 空白处拖动的两种动作由 `dragAction` 决定:
457
564
 
458
565
  - **平移小图**(`dragAction: 'pan'`,默认):光标往哪拖,小图内容跟着走,主图不动;内容夹在数据范围内,拖到头就停住。主图视口框跟着内容一起挪,必要时会贴在边上指示方向。
459
- - **框选显示**(`dragAction: 'box'`,或按住 Ctrl / ⌘ 拖动):在小图上拉出一个矩形(虚线框),松手后主图直接适应到框住的那块区域 —— 与主图自己的 Shift + 拖动框选(可改 `shortcuts.boxSelect`)是同一套手势。
566
+ - **框选显示**(`dragAction: 'box'`,或手动缩放时按住 Ctrl / ⌘ 拖动):在小图上拉出一个矩形(虚线框),松手后主图直接适应到框住的那块区域 —— 与主图自己的 Shift + 拖动框选(可改 `shortcuts.boxSelect`)是同一套手势。**`box` 不依赖 `zoomable`**,缩放关闭或跟随主图时也能直接在空白处框选。
460
567
 
461
- 两个动作不用来回改配置:`dragAction` 配的是「不按修饰键时」的动作,按住 Ctrl / ⌘ 就是另一个。平移过内容之后,小图不再自动把内容拉回视口框(否则一边看别处一边被拽回去);`setMinimapZoom` / 关掉再打开 `zoomable` 会回到居中。滚轮(或 `zoomMinimapBy`)以光标处的世界坐标为锚点改倍数,每一格的倍率就是 `zoomStep`(放大用 `zoomInStep`、缩小用 `zoomOutStep` 可以单独覆盖,缺省都用 `zoomStep`),`getMinimapZoom` / `setMinimapZoom` 读写当前倍数(夹在 `minZoom` ~ `maxZoom`)。`channelCircuits: false` 时小图上一个通道只画偏移最靠中间的那一根回线:它按 `getChannelMembers()` 给的下标与偏移挑成员,底图的分辨率本来就在一个像素上下,多回线挤在一起只会糊成一片。
568
+ 只有手动缩放(`zoomable: true`)时,按住 Ctrl / ⌘ 才会把 `dragAction` 换成另一个动作;关闭缩放 / 跟随主图时修饰键不改变动作,不能把唯一可用的框选换没。`pan` 需要小图倍数大于 1 才有可移动余量;关闭手动缩放时,`pan` 档的空白处长按仍跟着主图视角走,想直接框选就把 `dragAction` 设成 `'box'`。平移过内容之后,小图不再自动把内容拉回视口框(否则一边看别处一边被拽回去);手动模式下 `setMinimapZoom` / 关掉再打开 `zoomable` 会回到居中,跟随主图时倍数与居中由主图决定。滚轮(或手动模式下的 `zoomMinimapBy`)以光标处的世界坐标为锚点改倍数,每一格的倍率就是 `zoomStep`(放大用 `zoomInStep`、缩小用 `zoomOutStep` 可以单独覆盖,缺省都用 `zoomStep`),`getMinimapZoom` / `setMinimapZoom` 读写当前倍数(夹在 `minZoom` ~ `maxZoom`)。`channelCircuits: false` 时每个通道分组只画一根代表线:`collectMinimapData()` 按 `getChannelMembers()` 找到这一组当前仍可见的回线,逐顶点取平均,双回线正好落在两根中间、三回线落在中间那条;底图的分辨率本来就在一个像素上下,多回线挤在一起只会糊成一片。
462
569
 
463
- 小图的范围(`extent`)默认是 `auto`:取「筛选后可见数据的范围」与「底图范围」的并集(GeoJSON 底图用画出来的 `bounds`,图片底图用四角算出的范围),所以数据与 GeoJSON 不在一个坐标系时两者会一起进小图 —— 底图铺满小图、数据落在自己该在的位置,不会出现「按数据范围缩放、底图缩成一个点或糊成一片」的旧问题。`extent: 'data'` 退回旧行为(只看数据),`extent: 'background'` 只看底图范围;数据为空时 `auto` 直接取底图范围。数据用 `createGeoMapper` 映射过之后两者本来就在同一个坐标系里,`auto` 下小图与主图的视野完全一致。
570
+ 小图的范围(`extent`)默认是 `auto`:取「筛选后可见数据的范围」与「底图范围」的并集(GeoJSON 底图用画出来的 `bounds`,图片底图用四角算出的范围),所以数据与 GeoJSON 不在一个坐标系时两者会一起进小图 —— 底图铺满小图、数据落在自己该在的位置,不会出现「按数据范围缩放、底图缩成一个点或糊成一片」的旧问题。`extent: 'data'` 退回旧行为(只看数据),`extent: 'background'` 只看底图范围;数据为空时 `auto` 直接取底图范围。**`extentFollowCamera` 默认 `false`**:数据因筛选 / 显隐 / 增删变化时包围盒不会自行收窄,外围要素消失也不会让可视图突然换尺寸或让视口框跳位置。打开后才在相机落在数据 / 底图其中一份、且另一份在合并范围里小到不足 6 像素时,按正在看的那一份收窄;相机挪进 / 挪出会各补一次重画。
464
571
 
465
572
  **配置、扩展与开销**:`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 能省填充率。
466
573
 
467
- 视口框的拖角编辑(曾经的 `boxEditable` / `boxHandleSize` 与四角把手)已按需求整块去掉:框上不再有把手,视口框只能整体拖动;改主图视野用滚轮 / 框选(`zoomable`)或 `fitBounds` 这类实例方法。
574
+ 视口框的拖角编辑(曾经的 `boxEditable` / `boxHandleSize` 与四角把手)已按需求整块去掉:框上不再有把手,视口框只能整体拖动;改主图视野用 `wheelZoom` 滚轮、`dragAction: 'box'` 框选,或 `fitBounds` / `zoomTo` / `setCamera` 这类实例方法。
468
575
 
469
576
  ## 近义入口与别名
470
577
 
@@ -482,7 +589,7 @@ createGisView(container, {
482
589
  | `addChannel` 顶层 `channelId` / `groupId` / `groupIndex` ↔ `resolution: { type: 'joinGroup', … }` | 同一件事的两种写法(与 `updateLine` 的分组指令同款):并进已有通道时指定「哪条通道、哪一组」;只给 `channelId` 按这条通道自己的推荐顺序挑(新分组 → 第一个能并的分组)。结果里的 `channelLineIds` 是更新后的完整成员表,见「新增通道」 |
483
590
  | `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` |
484
591
  | `fitView(padding?)` / `applyInitialView()` / `resetView()` / `zoomToBounds(bounds, padding?)` | 视角的四个语义:适应**数据范围**(并记下首次落位)/ 按 `options.initialView` 落位(可反复调用)/ 回到**首次落位那一刻**的相机 / 按给定的世界坐标范围适应 |
485
- | `focusOn(ref, options?)` ↔ `zoomToBounds(bounds, padding?)` | `focusOn` 认要素(id / 下标 / 搜索命中 / 坐标 / 矩形 / 一批),内部算出范围再走适应那一条,另带 `center` / `scale` / `maxZoom` / `select` 这些选项 |
592
+ | `focusOn(ref, options?)` ↔ `zoomToBounds(bounds, padding?)` | `focusOn` 认要素(id / 下标 / 搜索命中 / 坐标 / 矩形 / 一批),缺省只按范围中心居中;写 `{ zoom: true }` 才走适应那一条,另带 `center` / `scale` / `maxZoom` / `select` 这些选项 |
486
593
  | `pick(x, y)` ↔ `pickAt(clientX, clientY)` | 坐标口径不同:`pick` 收画布 CSS 像素,`pickAt` 直接吃鼠标事件里的客户端坐标(结果里另加 `target` 与 `lngLat`) |
487
594
  | `hoverAt(clientX, clientY)` / `clearHover()` / `getHover()` | 三个动作:程序化悬停 / 撤掉并补发 `onHover(null)` / 读当前那一份(`hoverAt` 的返回与 `onHover` 载荷同一份) |
488
595
  | `getData()` / `getVisibleData()` / `getOptions()` | 读的层不同:全量数据副本(含拖拽后的最新坐标)/ 筛掉隐藏之后的点与线 / 整份配置与数据 |
@@ -40,7 +40,7 @@ await view.exportImage({ type: 'svg', background: 'none', download: '线路图.s
40
40
 
41
41
  导出用的是当前这一帧的实际画面:位图内部先同步重画一帧再取像素 —— 透明底与换底色这两种写法出的都是「只给导出用」的那一帧,读完像素立刻补画一帧正常画面的把画布还原,屏幕上不会停在导出那一版。整个过程不需要开 `preserveDrawingBuffer`,所以也没有常驻的额外显存开销。
42
42
 
43
- `type: 'svg'` 走的是矢量:线(含虚线图案与相位)、点(内置圆 / 方与 SVG 符号)、线路装饰、拐点、GeoJSON 区域、扩展图形与标签都是真正的 SVG 元素,颜色 / 线宽 / 线型取的就是当前那一帧解析出来的值(悬停、选中样式同样在内),放大到任意倍都不糊。PNG / JPEG / WebP 这一支先画引擎画布,再按「扩展图形 → 标签」叠上去,所以 `graphics` 里的 SVG 路径、图片与 Canvas 都在合成结果里。两点差异:热力密度场是烘焙出来的贴图、不进 SVG;位图符号(`symbol.type: 'image'`)、自定义图元(`registerSymbol` 的画笔)与图片 / Canvas 图形都以 `<image href>` 出现(前者引用原地址,后两者是原图或 data URL),把导出的 svg 当图片内嵌到别的页面时,跨域图片与外部字体会被浏览器挡掉(直接打开 svg 文件没问题)。需要那一份矢量数据自己拼别的格式时,用 `view.snapshotScene({ background, labels })`(它已经带上 `graphics`),或用导出的 `buildSceneSvg(scene, { scale })`;`svgDataUrl(markup)` 是把一段 SVG 标记转成 `data:` URL 的小工具(组件内部导 svg 图片时走它,自己拿到标记要拼进 `<img src>` 或 CSS 时也可以直接用)。
43
+ `type: 'svg'` 走的是矢量:线(含虚线图案与相位)、点(内置圆 / 方与 SVG 符号)、线路装饰、拐点、GeoJSON 区域、扩展图形与标签都是真正的 SVG 元素,颜色 / 线宽 / 线型取的就是当前那一帧解析出来的值(悬停、选中样式同样在内),放大到任意倍都不糊。SVG 符号里的 `currentStrokeColor` 取该节点当前解析出的描边色(逐点 / 规则 / 状态样式都算),不会再回落到白色;`currentColor` 仍取填充色。PNG / JPEG / WebP 这一支先画引擎画布,再按「扩展图形 → 标签」叠上去,所以 `graphics` 里的 SVG 路径、图片与 Canvas 都在合成结果里。两点差异:热力密度场是烘焙出来的贴图、不进 SVG;位图符号(`symbol.type: 'image'`)、自定义图元(`registerSymbol` 的画笔)与图片 / Canvas 图形都以 `<image href>` 出现(前者引用原地址,后两者是原图或 data URL),把导出的 svg 当图片内嵌到别的页面时,跨域图片与外部字体会被浏览器挡掉(直接打开 svg 文件没问题)。需要那一份矢量数据自己拼别的格式时,用 `view.snapshotScene({ background, labels })`(它已经带上 `graphics`),或用导出的 `buildSceneSvg(scene, { scale })`;`svgDataUrl(markup)` 是把一段 SVG 标记转成 `data:` URL 的小工具(组件内部导 svg 图片时走它,自己拿到标记要拼进 `<img src>` 或 CSS 时也可以直接用)。
44
44
 
45
45
  ## 导出选中的节点
46
46
 
@@ -352,7 +352,7 @@ const focusSelectionPlugin = view => {
352
352
  }
353
353
  const selection = view.getSelections()
354
354
  if (selection.length) {
355
- view.focusOn(selection, { padding: 80 })
355
+ view.focusOn(selection, { zoom: true, padding: 80 })
356
356
  }
357
357
  }
358
358
  window.addEventListener('keydown', onKeydown)
@@ -385,7 +385,35 @@ dispose() // 卸载:跑上面那个 destroy,从实例的清理列表里摘
385
385
  - 与插件并列的另一条扩展点是**自定义图元**:插件加的是「视图级行为」(快捷键、面板、URL 同步…),自定义图元加的是「点怎么画」—— 注册一支画笔 `view.registerSymbol('三角', painter)`,或在数据里写 `{ type: 'custom', draw }`,见「自定义图元」一节。
386
386
  - 第三条扩展点是**自定义条件运算符**:插件加行为、图元加画法,运算符加的是「条件语言里的判定动词」—— `view.registerOperator('mod2', value => current => …)` 之后规则 / 筛选 / 标签的 `when` 都能写 `{ vn_kv: { mod2: true } }`,见「条件语言 → 自定义运算符」。
387
387
 
388
- ### 五类扩展点怎么选
388
+ ## 实例命令
389
+
390
+ `registerCommand` 把「业务动作」注册到当前视图实例上,适合面板按钮、快捷键和外接工具栏共用同一个入口。命令只在当前实例有效,不进全局注册表;handler 同步执行,拿到原样传入的 payload 与冻结的 `{ view, name }` 上下文:
391
+
392
+ ```js
393
+ // 业务动作注册一次,按钮 / 快捷键 / 宿主脚本都走 executeCommand
394
+ const dispose = view.registerCommand('focusHighestLoad', (payload = {}, context) => {
395
+ const threshold = Number(payload.threshold ?? 0.8)
396
+ const hit = view.search({ keyword: String(threshold), scope: 'points' }).points[0]
397
+ if (!hit) {
398
+ return { focused: false, threshold }
399
+ }
400
+ context.view.focusOn(hit.id, { select: true, zoom: true, maxZoom: 12 })
401
+ return { focused: true, id: hit.id, command: context.name }
402
+ })
403
+
404
+ view.listCommands() // ['focusHighestLoad']
405
+ const result = view.executeCommand('focusHighestLoad', { threshold: 0.85 })
406
+ // 成功:{ ok: true, name: 'focusHighestLoad', value: { focused: true, ... } }
407
+ // 未注册 / 名字非法 / handler 抛错:{ ok: false, name, reason }
408
+ dispose() // 幂等注销;同名已被后来者覆盖时不会误删
409
+ ```
410
+
411
+ - 名字会 `trim`;同名再注册以后一次为准,覆盖不会改变它在 `listCommands()` 里的位置。返回的注销函数只摘掉自己那一份注册。
412
+ - 名字为空 / handler 不是函数只报一条 `onWarning`,本次注册不生效;执行未注册的命令同样走 warning 并返回 `ok: false`。
413
+ - handler 抛出的异常由组件收成 `onError`,`executeCommand` 返回 `{ ok: false, name, reason }`,不会把异常甩给调用方。
414
+ - 命令是同步调用;要串异步流程就让 handler 自己启动 Promise,再用事件 / 状态读数回报结果。`view.destroy()` 会清空实例命令表。
415
+
416
+ ### 六类扩展点怎么选
389
417
 
390
418
  | 扩展点 | 适合做什么 | 作用域 | 清理方式 |
391
419
  | --- | --- | --- | --- |
@@ -394,6 +422,7 @@ dispose() // 卸载:跑上面那个 destroy,从实例的清理列表里摘
394
422
  | `view.registerOperator(name, test)` | 给规则 / 筛选 / 标签增加条件动词,例如 `mod2`、`evenIndex` | 模块级条件运算符表,同页所有实例共享 | 返回幂等注销函数,只删除自己这次注册;注销后旧条件按「不成立」处理 |
395
423
  | `view.addWebGLLayer(layer)` | 直接拿组件的 WebGL2 上下文画自定义标记、特效或调试几何;层画在内置内容之后,不参与拾取与数据导出 | 单个视图实例 | 返回卸载函数;也可用 `updateWebGLLayer` / `removeWebGLLayer` / `clearWebGLLayers` 维护,画布外还可通过 `view.gl` 直接取上下文 |
396
424
  | `defineExportFormat(name, adapter)` | 把标准文档映射成后端 DTO、业务表列名或项目自己的嵌套结构(同步导出器) | 模块级导出格式表,所有实例的 `exportData` 共享 | 返回幂等清理函数,只删除自己这次注册;需要按名字全局摘除时用 `unregisterExportFormat(name)` |
425
+ | `view.registerCommand(name, handler)` | 把业务动作注册成命令:面板按钮、快捷键与宿主脚本共用 `executeCommand` 入口,handler 里可继续调任意实例 API | 单个视图实例 | 返回幂等注销函数;同名覆盖时旧卸载函数不会误删新命令,`view.destroy()` 会清空命令表 |
397
426
 
398
427
  ## 自建界面
399
428