gis-view-webgl2 0.1.0 → 0.1.1

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 (86) hide show
  1. package/README.md +28 -8
  2. package/dist/gis-view.css +1 -1
  3. package/dist/index.cjs +1 -1
  4. package/dist/index.d.ts +781 -246
  5. package/dist/index.js +1 -1
  6. package/docs/AI/345/257/271/350/257/235/346/261/207/346/200/273.md +129 -0
  7. package/docs/GisView.md +9 -8
  8. package/docs/GisView/345/256/236/347/216/260/345/216/237/347/220/206.md +2 -2
  9. 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 +114 -0
  10. package/docs/api/index.html +545 -59
  11. package/docs/demos/BackendSyncDemo.vue +10 -8
  12. package/docs/demos/BasicDemo.vue +101 -101
  13. package/docs/demos/BatchAddDemo.vue +5 -5
  14. package/docs/demos/ChannelDemo.vue +51 -4
  15. package/docs/demos/ConnectDemo.vue +392 -0
  16. package/docs/demos/CopyMergeDemo.vue +936 -936
  17. package/docs/demos/DecorationDraftDemo.vue +1300 -0
  18. package/docs/demos/DemoShell.vue +569 -240
  19. package/docs/demos/DragDropDemo.vue +11 -11
  20. package/docs/demos/EffectsDemo.vue +6 -6
  21. package/docs/demos/EventDemo.vue +327 -327
  22. package/docs/demos/ExtensionDemo.vue +458 -0
  23. package/docs/demos/GisViewDemo.vue +61 -48
  24. package/docs/demos/GraphicDemo.vue +338 -0
  25. package/docs/demos/LabelDemo.vue +509 -509
  26. package/docs/demos/MinimapDemo.vue +358 -0
  27. package/docs/demos/PerfDemo.vue +29 -0
  28. package/docs/demos/SearchFilterDemo.vue +412 -0
  29. package/docs/demos/StyleDemo.vue +121 -121
  30. package/docs/demos/api-index.js +87 -76
  31. package/docs/demos/demos.js +159 -135
  32. package/docs/demos/shared/demoData.js +107 -107
  33. package/docs/demos/shared/demoStyle.css +249 -249
  34. package/docs/demos/shared/fakeBackend.js +93 -6
  35. package/docs/format/03-/346/213/220/347/202/271/350/243/205/351/245/260/344/270/216/346/240/267/345/274/217.md +24 -6
  36. package/docs/format/06-/345/257/274/345/205/245/345/257/274/345/207/272/344/270/216/346/240/207/345/207/206/346/226/207/346/241/243.md +8 -6
  37. package/docs/format/07-/344/272/213/344/273/266/350/275/275/350/215/267/344/270/216/347/244/272/344/276/213/346/225/260/346/215/256.md +6 -6
  38. package/docs/guide/sample-document.html +4 -4
  39. package/docs/index.html +180 -9
  40. package/docs/internals/11-/350/246/206/347/233/226/345/261/202/346/240/207/347/255/276/344/270/216/346/217/220/347/244/272.md +1 -1
  41. package/docs/internals/13-/351/271/260/347/234/274/345/233/276.md +3 -2
  42. package/docs/internals/15-03-/351/200/220/350/275/256/350/256/260/345/275/225-/346/200/247/350/203/275/344/270/216/344/277/256/345/244/215-/344/270/213.md +16 -0
  43. 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 -0
  44. package/docs/internals/17-/350/260/203/350/257/225/344/270/216/346/211/251/345/261/225/345/273/272/350/256/256.md +1 -1
  45. package/docs/manual/02-/345/235/220/346/240/207/344/270/216/346/225/260/346/215/256.md +11 -2
  46. package/docs/manual/03-/351/205/215/347/275/256/351/241/271.md +89 -20
  47. package/docs/manual/04-/344/272/213/344/273/266/344/270/216/345/233/236/350/260/203.md +13 -8
  48. package/docs/manual/06-/346/225/260/346/215/256/344/270/216/345/234/272/346/231/257/346/233/264/346/226/260.md +11 -10
  49. package/docs/manual/07-/346/214/207/351/222/210/344/270/216/350/246/201/347/264/240/347/274/226/350/276/221.md +9 -9
  50. package/docs/manual/08-/351/200/211/344/270/255/344/270/216/346/213/220/347/202/271.md +13 -11
  51. package/docs/manual/09-/351/200/232/351/201/223/344/270/216/345/244/232/345/233/236/347/272/277.md +3 -3
  52. 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 +47 -5
  53. package/docs/manual/11-/346/240/267/345/274/217/344/270/216/350/247/204/345/210/231.md +3 -2
  54. package/docs/manual/12-/346/240/207/347/255/276/344/270/216/350/243/205/351/245/260.md +215 -2
  55. package/docs/manual/13-/345/212/250/346/225/210/344/270/216/345/233/276/345/205/203.md +6 -5
  56. package/docs/manual/14-/350/247/206/345/233/276/344/270/216/347/255/233/351/200/211.md +27 -14
  57. package/docs/manual/15-/345/257/274/345/207/272/344/270/216/351/233/206/346/210/220.md +142 -49
  58. package/docs/manual/16-/345/256/236/344/276/213/346/226/271/346/263/225/346/200/273/350/241/250.md +25 -29
  59. package/docs/manual/17-/345/217/202/346/225/260/351/200/237/346/237/245.md +47 -39
  60. package/docs/manual/18-/351/200/220/346/226/271/346/263/225/347/244/272/344/276/213.md +161 -64
  61. 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 -4
  62. package/docs/manual/20-/346/200/247/350/203/275/344/270/216/345/244/247/346/225/260/346/215/256.md +39 -2
  63. 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 +21 -5
  64. package/docs/playground/index.html +5 -5
  65. package/docs/steps/README.md +12 -10
  66. package/docs/steps/check-doc-truth.mjs +1 -1
  67. package/docs/steps/selftest-actions.html +10 -10
  68. package/docs/steps/selftest-data.html +96 -14
  69. package/docs/steps/selftest-decoration.html +577 -0
  70. package/docs/steps/selftest-demo.html +6 -5
  71. package/docs/steps/selftest-demos.html +2048 -1624
  72. package/docs/steps/selftest-docs.html +86 -14
  73. package/docs/steps/selftest-effects.html +5 -5
  74. package/docs/steps/selftest-features.html +544 -85
  75. package/docs/steps/selftest-full.html +583 -583
  76. package/docs/steps/selftest-labels.html +797 -660
  77. package/docs/steps/selftest-perf.html +1899 -1844
  78. package/docs/steps/selftest-scale.html +117 -7
  79. package/docs/steps/selftest-select.html +24 -17
  80. package/docs/steps/step-10-full.js +1 -1
  81. package/docs//346/216/245/345/217/243/345/215/217/350/256/256.md +151 -7
  82. package/docs//346/225/260/346/215/256/346/240/274/345/274/217.md +1 -1
  83. package/package.json +42 -42
  84. package/docs/demos/HistoryDemo.vue +0 -230
  85. package/docs/demos/InterfaceDemo.vue +0 -309
  86. package/docs/demos/SampleDemo.vue +0 -283
@@ -86,6 +86,14 @@ createGisView(container, { points, lines, channels })
86
86
  - **分组**:`channels[].groups[]`(`{ id?, lineIds, path? }`)。缺省一个通道一组;拆开之后每组自带成员与拐点,见「通道分组」。
87
87
  - **拐点**:就是折线的中间顶点 —— 线路的 `path` 中间项、通道的 `path`(中间项)、分组的 `groups[].path`。运行时用 `getWaypoints(lineIndex)` / `getChannelGroups(channelId)` 读,改动由 `onWaypointChange` 载荷里的 `line` / `groups[].path` 写回,见「线路拐点」「分组拐点」。
88
88
 
89
+ ### ID 解析口径
90
+
91
+ 节点 / 线路 / 通道都按 `id` 关联。为了让「按 id 定位」「筛选联动」「复制快照」「Worker 搜索」走同一份结果,组件采用以下固定口径:
92
+
93
+ - 只忽略 `undefined` / `null`;空字符串 `''` 仍是一个合法 id,需要表示「没有 id」时请留空或写 `null`。
94
+ - 同一份数据里出现重复 id 时,**按数组顺序只认第一条**;后面的同名项照常绘制,但按 id 定位、`from` / `to` 端点绑定、筛选投影与复制引用都会落到第一条。
95
+ - 这个口径对节点与线路同样成立;通道按 id 找成员回线时也取第一条。需要操作某一条重名数据时,请改用下标入口(如 `focusOn({ type: 'line', index: 3 })`)或先修正数据里的 id。
96
+
89
97
  ### 节点(GisViewPoint)
90
98
 
91
99
  | 字段 | 类型 | 说明 |
@@ -109,6 +117,7 @@ createGisView(container, { points, lines, channels })
109
117
  | `labelPosition` | `GisViewLabelPosition` | 标签贴在节点的哪一侧 |
110
118
  | `labelOffset` | `[number, number]` | 标签的额外像素偏移 |
111
119
  | `labels` | `GisViewItemLabel \| GisViewItemLabel[]` | 这个点上的标签清单(逐条写:`id` / `content` / `position` / `offset` / `style` / `hidden`…),与 `options.label` 里同 id 的那一条合并;导出数据的 `labels` 列就是它,见「标签(labels,导入即回显)」 |
120
+ | `decorations` | `GisViewPointDecoration[]` | 节点上挂的图片 / SVG:可写屏幕像素偏移(`offset` 或 `distance` + `direction`)、固定世界坐标(`anchor: 'fixed'` / `at`),并可用 `connector` 从节点中心画连接线,见「节点上的装饰」 |
112
121
  | `tooltip` | `GisViewTooltipContent \| false` | 这个点的提示内容,`false` 表示不显示 |
113
122
  | `hoverStyle` / `selectStyle` / `multiSelectStyle` / `boxSelectStyle` | `GisViewPointStyle` | 这个点自己的状态样式(按字段覆盖自身样式) |
114
123
 
@@ -141,7 +150,7 @@ createGisView(container, { points, lines, channels })
141
150
 
142
151
  ### 标签(labels,导入即回显)
143
152
 
144
- `options.label` / `options.lineLabel` 是**全局默认**,数据里还能逐条带标签:每个点 / 每条线的 `labels`(单个对象或数组)写明「这条要素上有几条标签、每条写在哪、长什么样」—— 只喂数据、一条标签配置都不写,标签照样画得出来。`exportData` / `exportPointData` / `exportLineData` / `exportChannelData` / `exportSelectionData` 的 `labels` 列就是这一份,导出再导入即回显。
153
+ `options.label` / `options.lineLabel` 是**全局默认**,数据里还能逐条带标签:每个点 / 每条线的 `labels`(单个对象或数组)写明「这条要素上有几条标签、每条写在哪、长什么样」—— 只喂数据、一条标签配置都不写,标签照样画得出来。`exportData()`(含 `scope: 'selection'` 与各 `parts` 分项)的 `labels` 列就是这一份,导出再导入即回显。
145
154
 
146
155
  ```js
147
156
  const points = [
@@ -213,7 +222,7 @@ const next = createGisView(el, {
213
222
  前三份各看一类字段(标签 / 拐点 / 分组),`sample-full.json` 再把它们摆在同一份里:
214
223
  10 点 / 22 线 / 3 通道、5 条线路各带 3 ~ 4 个拐点、同一节点最多 4 条标签、同一线路最多 3 条标签、
215
224
  6 回通道拆 3 组且每组各带 2 个骨架拐点、23 个标记、6 条标签状态(拖过 / 改过 / 运行时加 / 隐藏)。
216
- 另有 `sample-document.json`:同一份 `sample-full.json` 的**标准文档**写法(顶层带 `format: 'gis-view'` 与 `view` 相机那一列,见「导出数据」)。演示页「完整样本」(`?demo=samples`)把五份切着看:四份普通样本用 `exportData({ format: 'input' })` 与文件逐字节对账,标准文档那一份用 `exportData({ format: 'full' })` 对账。
225
+ 另有 `sample-document.json`:同一份 `sample-full.json` 的**标准文档**写法(顶层带 `format: 'gis-view'` 与 `view` 相机那一列,见「导出数据」)。五份文件都能直接作为创建入参或整份文档回灌:四份普通样本可用 `exportData({ format: 'input' })` 与文件逐字节对账,标准文档用 `exportData({ format: 'full' })` 对账。
217
226
 
218
227
  ### 通道与分组(GisViewChannel)
219
228
 
@@ -15,6 +15,7 @@
15
15
  | `features` | `GisViewFeaturesInput` | 无(**缺省全关**) | 功能开关:预设名(`'edit'` 全开 / `'view'` 打开查看类 / `'static'` 与缺省一致(全关))、开关表或布尔值。**什么都不写时只剩画布与数据**:没写的开关跟随各自的详细配置(`interactive` / `clickable` / `draggable` / `boxSelect` / `copy.enabled`…),详细配置也没写就是关(提示 / 标签 / 鹰眼图配了才有),写了 `true` / `false` 就是强制打开 / 关闭;想一次打开一批就用 `'view'`(能平移缩放、能悬停选中看提示但改不动数据)或 `'edit'`(等价 `features: true`)。运行时用 `setFeatures()` 换、`getFeatures()` 读,见「功能开关」 |
16
16
  | `history` | `GisViewHistoryOptions` | 关 | 历史(撤销 / 重做):`true` 用缺省上限 50 条,`{ limit }` 自定义(`0` 表示不限),不配就是关。打开之后 Ctrl+Z 撤销、Ctrl+Shift+Z / Ctrl+Y 重做,接口是 `undo()` / `redo()` / `canUndo()` / `canRedo()`,见「历史」 |
17
17
  | `quality` | `GisViewQualityOptions \| GisViewQualityMode \| boolean` | `'high'` | 画质档位(自动档按渲染耗时与整帧间隔两路信号升降):`'high'` 全开 / `'balanced'` 关光晕 / `'lean'` 连装饰一起关 / `'fast'` 再降到 0.75 倍渲染分辨率,`'auto'`(也可以直接写 `true`)按这两路信号自己升降,对象写法 `{ mode, budgetMs, minScale }` 能换预算与分辨率下限。只改「画哪些批次 + 多大分辨率」,不重排场景、不动数据,见「画质」 |
18
+ | `denseMode` | `GisViewDenseModeInput` | `'auto'` | 大数据展示模式:`'auto'` 按可见节点数、屏幕密度与数据总量自动进入密集档,`'on'` / `'off'`(或 `true` / `false`)强制开关;对象写法可换 `visibleThreshold` / `densityThreshold` / `pointThreshold` 三档阈值。进入后标签自动走避让 / 截断,线路动点与节点涟漪暂停;读数看 `getStats().dense`,见「大数据展示模式(denseMode)」 |
18
19
  | `points` | `GisViewPoint[]` | `[]` | 点数据,`x` / `y` 为世界坐标(经纬度、投影米或任意平面坐标) |
19
20
  | `lines` | `GisViewLine[]` | `[]` | 线数据,`start` / `end` 支持 `{ x, y }` 或 `[x, y]`,折线用 `path`,端点可用 `from` / `to` 绑定点 id |
20
21
  | `channels` | `GisViewChannel[]` | `[]` | 通道:把若干条线路组织成并行敷设的多回线走廊,回线几何由骨架折线按偏移推导;两端可用 `from` / `to` 绑在节点上 |
@@ -24,21 +25,23 @@
24
25
  | `channelTangentInset` | `number \| null` | `null` | 两端切点往节点里收多少 CSS 像素:缺省(`null`)按成员回线里最粗那条的线宽收,线因此不会从节点边缘探出去;`0` 表示切点正好落在节点边上,**负数外收**(切点往节点外让、回线整段比节点宽);单个通道可用 `tangentInset` 覆盖;内收两侧合计最多收掉节点宽度的 40%,外收单侧最多让出 50% |
25
26
  | `channelMaxGroups` | `number` | `0` | 一条通道最多几个分组(`0` 表示不限):新增通道时用来判断还能不能变成新分组,见「新增通道」 |
26
27
  | `channelGroupMaxLines` | `number` | `0` | 一个分组最多几条回线(`0` 表示不限):新增通道时用来判断还能不能并进某一组,见「新增通道」 |
27
- | `channelDraftStyle` | `GisViewChannelDraftStyle` | 蓝色 2px + 两端圆点 | 新增通道草稿线(选好起点之后跟随光标的那条预览线)的样式:`color` / `width` / `dot` |
28
+ | `channelDraftStyle` | `GisViewChannelDraftStyle` | 蓝色 2px + 两端圆点,箭头关闭 | 新增通道草稿预览的全局样式:`color` / `width` / `dot` / `dotColor` / `arrow` / `arrowSize` / `arrowPositions` / `arrowReverse` / `arrowColor` / `circuitSpacing` / `opacity` / `customDraw`;`beginAddChannel({ channelDraftStyle })` 可按这一次草稿覆盖,`updateAddChannelStyle(patch)` 可在草稿期间增量修改 |
29
+ | `webglLayers` | `GisViewWebGLLayer[]` | `[]` | WebGL 自定义绘制层:每层提供 `draw({ gl, canvas, viewport, camera, frame, project, unproject, requestRender })`,在内置内容之后按 `order` 绘制;运行时也可用 `addWebGLLayer` / `updateWebGLLayer` / `removeWebGLLayer` 维护 |
28
30
  | `background` | `GisViewBackground` | 浅色底 | 背景层,支持底色、图片与 GeoJSON |
29
31
  | `pointStyle` | `GisViewPointStyle` | 见下 | 点的默认样式,可被单个点覆盖;运行时按字段合并用 `updatePointStyle(patch)`(`updateOptions({ pointStyle })` 是整份换) |
30
32
  | `lineStyle` | `GisViewLineStyle` | 见下 | 线的默认样式,可被单条线覆盖;运行时按字段合并用 `updateLineStyle(patch)` |
31
33
  | `pointRules` / `lineRules` | `GisViewPointRule[]` / `GisViewLineRule[]` | `[]` | 批量样式规则:按属性给点 / 线批量配色、改大小、换符号,见「批量样式规则」 |
32
34
  | `heatmap` | `GisViewHeatmap \| null` | 无 | 热力图:按业务字段的数值到渐变色带上取颜色,并可按同一个值缩放节点大小 / 线宽,作用对象可选节点 / 线路 / 通道;不配(或 `null`)就是关的,见「热力图」 |
33
- | `effects` | `GisViewEffectsInput` | 关 | 动画效果(全局缺省):线路上的跑动图标(`line`,ECharts `lines.effect` 那一类)与节点上的扩散涟漪(`point`,`effectScatter` 那一类),逐要素用 `points[].effect` / `lines[].effect` 覆盖;没配就是关的,但「只在数据里逐条配了 `effect`」的场景照样会动。`false` 或 `{ enabled: false }` 是**一处关掉**(谁都别动);运行时有 `setEffects()` / `getEffects()` / `getLineEffects()`,见「动画效果(effects)」 |
35
+ | `effects` | `GisViewEffectsInput` | 关 | 动画效果(全局缺省):线路上的跑动图标(`line`,ECharts `lines.effect` 那一类)与节点上的扩散涟漪(`point`,`effectScatter` 那一类),逐要素用 `points[].effect` / `lines[].effect` 覆盖;没配就是关的,但「只在数据里逐条配了 `effect`」的场景照样会动。`false` 或 `{ enabled: false }` 是**一处关掉**(谁都别动);运行时有 `updateOptions({ effects })` / `getEffects()` / `getLineEffects()`,见「动画效果(effects)」 |
34
36
  | `lineDirection` | `GisViewLineDirectionInput` | 关(`null`) | 线路方向箭头(全局缺省):沿线摆一串静态箭头,朝向跟着线路切向走(起点 / `from` 那一端 → 终点,`reverse` 指回上游),按弧长等分、缺省每条线只在中点一个;逐条线路用 `lines[].direction` 覆盖,写法与 `effects` 同构(`true` 用全局、对象逐字段覆盖、`false` / `null` 关掉),见「线路方向箭头(lineDirection)」 |
35
37
  | `prebake` | `GisViewPrebakeOptions \| true` | 关 | 贴图符号预热:把「这次画面会出现什么」提前告诉组件 —— 两种写法:`combos` 逐组合(精确,`getSymbolCombos()` 收出来的那份)/ `symbols × pointColors × sizes` 与 `lineColors × 线路动画图标` 全排列(省事,颜色与尺寸由同一个字段决定时会多烤很多)—— 第一帧之前就烤好,画到它们时命中的是现成的贴图(省掉解码 + 光栅化那一下);组合数与数据量无关,不配就是从前那条按需路径。读数 `getPrebake()` / `getSymbolCombos()`、手动再烤一遍 `runPrebake()`,见「贴图符号预热(prebake)」 |
36
38
  | `label` | `GisViewLabelOptions \| GisViewLabelOptions[]` | 无 | 节点标签:内容 / 位置 / 显隐 / 避让 / 拖动与编辑都可配,**写数组就是同一个节点上多条标签**,与 `lineLabel` 共用一套避让网格,见「节点标签」 |
37
39
  | `labelOptimize` | `boolean` | `false` | 标签显示优化开关:**缺省关 = 强制显示**(不避让、不按 `maxCount` 截断、不设 `scanLimit` / 扫描预算,节点 / 线路的每个可见要素该出现的标签一条不少);写 `true` 与从前一致 —— 避让 / 换落点 / 数量上限 / 候选上限全部生效。标签订得密、数据量大(十万级)时建议打开,见「标签显示优化开关」 |
38
40
  | `lineLabel` | `GisViewLineLabelOptions \| GisViewLineLabelOptions[]` | 无 | 线路标签:位置沿线走(比例 / 百分比 / 绝对距离),内容、避让、显隐都可配,与节点标签共用一套避让网格;**写数组就是同一条线上多条标签**,见「线路标签」 |
39
41
  | `labelStates` | `GisViewLabelState[]` | 无 | 标签的运行时状态(`getLabelStates()` 的那一份:拖出来的偏移、改过的内容与样式、运行时加的标签、隐藏覆盖):创建时喂回来就回显,等价于创建之后调 `setLabelStates(states)`;`updateOptions({ labelStates })` 同样认。`exportData({ format: 'input' })` 的结果里就叫 `labelStates`,存档 → 回灌直接接上 |
42
+ | `graphics` | `GisViewGraphic[]` | 无 | 与节点无关的扩展图形:按世界坐标放 SVG 路径 / 图片 / Canvas,支持锚点、偏移、旋转、透明度、`zIndex` 与 `scaleWithView`;位于画布之上、标签之下,运行时用 `addGraphic` / `addGraphics` / `updateGraphic` / `removeGraphic` / `clearGraphics` 增删改,见「扩展图形(graphic)」 |
40
43
  | `tooltip` | `GisViewTooltipOptions` | 无 | 悬停提示:点 / 线 / 通道分别配置内容,见「悬浮提示」 |
41
- | `minimap` | `GisViewMinimapOptions \| null` | 无 | 内置鹰眼图:位置、尺寸、节点 / 线路 / 视口框三份样式与交互都可配,`extent` 决定小图按数据范围还是「数据 ∪ 底图」铺(默认 `auto`,GeoJSON 底图不会缩成一个点),`zoomable` 打开后小图自身可整体放大缩小(空白处拖动可以平移小图或直接框选让主图显示过去,每格倍率 `zoomStep`),通道还能只画一根;小图同样支持规则(`pointRules` / `lineRules`,缺省沿用主图规则的颜色与层级),可以只画某几层(`levels`)、关掉分层叠画(`layered`)、按三组系数给节点与线路定尺寸(整体倍数 `pointSizeScale` / `lineWidthScale`、跟随小图倍数 `pointZoomScale` / `lineZoomScale`(只在小图自身倍数 ≠ 1 时起作用)、跟随主视图地图倍数 `pointMapZoomScale` / `lineMapZoomScale`),视口框与框选矩形的颜色 / 背景 / 边框 / 圆角也能配(`boxStyle` / `selectStyle`),`extent` 还能直接写死一份世界范围、容器可加 `className` / `style`、`draw` 钩子每帧自己往上画一层,不配则不产生任何 DOM,见「鹰眼图」 |
44
+ | `minimap` | `GisViewMinimapOptions \| null` | 无 | 内置鹰眼图:位置、尺寸、节点 / 线路 / 视口框三份样式与交互都可配,`extent` 决定小图按数据范围还是「数据 ∪ 底图」铺(默认 `auto`,GeoJSON 底图不会缩成一个点),`zoomable` 打开后小图自身可整体放大缩小(空白处拖动可以平移小图或直接框选让主图显示过去,每格倍率 `zoomStep`),通道还能只画一根;小图同样支持规则(`pointRules` / `lineRules`,缺省沿用主图规则的颜色与层级),可以只画某几层(`levels`)、关掉分层叠画(`layered`)、按三组系数给节点与线路定尺寸(整体倍数 `pointSizeScale` / `lineWidthScale`、跟随小图倍数 `pointZoomScale` / `lineZoomScale`(只在小图自身倍数 ≠ 1 时起作用)、跟随主视图地图倍数 `pointMapZoomScale` / `lineMapZoomScale`),视口框与框选矩形的颜色 / 背景 / 边框 / 圆角也能配(`boxStyle` / `selectStyle`),`extent` 还能直接写死一份世界范围、容器可加 `className` / `style`、`layers` 按 `placement` 分数据前 / 数据后、段内按 `order` 拆出多层自绘内容(旧 `draw` 钩子仍兼容并排在最后)、`onInteraction` 在手势结束时给出类型 / 世界坐标 / 相机、`maxPixelRatio` 限制备份倍率上限,不配则不产生任何 DOM,见「鹰眼图」 |
42
45
  | `filter` | `GisViewFilterInput \| null` | 无 | 初始筛选条件,等价于创建之后调用 `setFilter`,见「筛选」 |
43
46
  | `filterWorker` | `boolean \| GisViewFilterWorkerOptions` | `{ threshold: 20000 }` | 筛选是否用 Web Worker 计算:默认点 + 线总数超过阈值才用,`false` 表示始终同步算 |
44
47
  | `searchWorker` | `boolean \| GisViewSearchWorkerOptions` | `{ threshold: 20000 }` | [异步搜索](14-视图与筛选.md#搜索与定位)是否用 Web Worker 计算:默认点 + 线总数超过阈值才用,`false` 表示 `searchAsync` 也同步算;同步的 `search` 一直在主线程算,不受这一项影响 |
@@ -55,7 +58,7 @@
55
58
  | `selectionBoxStyle` | `GisViewSelectionBoxStyle` | 蓝底 0.16 透明 + 1px 蓝框 | 框选矩形的填充与边框:`fill`、`fillOpacity`、`stroke`、`strokeWidth` |
56
59
  | `selectionOnTop` | `boolean` | `true` | 选中的节点 / 拖动中的整组 / 待确认合并的目标节点,以及选中线路所在的整条通道,是否画在所有要素之上(与 `zIndex` 无关),见「选中 / 拖动的层级」 |
57
60
  | `channelSelectMode` | `'line' \| 'group' \| 'channel'` | `'line'` | 通道选中模式:点中通道里的一条回线时选中什么 —— `'line'` 只选这一条、`'group'` 连它所在的分组一起、`'channel'` 整条通道(所有分组的回线);通道以外的线路永远只选自己。Ctrl / ⌘ + 点击在 `group` / `channel` 下按整批取反;切换走 `updateOptions({ channelSelectMode })`,只重画一帧、不重排场景,见「通道选中模式」 |
58
- | `waypointEditable` | `boolean` | `false` | 是否允许编辑线路拐点(按住加点快捷键 `shortcuts.addWaypoint`(默认 Ctrl / ⌘)+ 点击添加、拖动移动、双击或删除快捷键删除),单条线可用 `waypointEditable` 覆盖;**缺省关**,写 `waypointEditable: true` 或 `features: { waypoint: true }` 才开 |
61
+ | `waypointEditable` | `boolean` | `false` | 是否允许编辑线路拐点(按住加点快捷键 `shortcuts.addWaypoint`(默认 Ctrl / ⌘)+ 点击添加、拖动移动、双击或删除快捷键删除),单条线可用 `waypointEditable` 覆盖;**缺省关**,写 `waypointEditable: true` 或 `features: { waypoint: true }` 才开。`false`(以及 `features: { waypoint: false }`)会同时关闭新增、移动与删除,没有只关其中一项的细分开关;`shortcuts.addWaypoint` 仍只决定加点的组合键 |
59
62
  | `waypointVisibility` | `'selected' \| 'always'` | `'selected'` | 拐点显示时机:`selected` 只显示选中线路(以及刚加过拐点的线路)的拐点,`always` 全部显示 |
60
63
  | `waypointStyle` / `waypointSelectStyle` | `GisViewPointStyle` | 无 | 拐点(线路 `path` 的中间顶点)的默认 / 选中样式,**支持配置**:字段与节点样式同款;缺省是白底蓝圈的 9px 圆点,`waypointSelectStyle` 没配时选中拐点用内置强调环,见「线路拐点」的「拐点样式」小节 |
61
64
  | `cursorStyle` | `GisViewCursorStyle` | 见「光标」 | 鼠标光标按分类配置:`idle` / `pan` / `box` / `drag` / `draft` / `point` / `line` / `channel` / `waypoint` 九类,每类可以给系统关键字、CSS 变量或图片(`{ url, hotspot, fallback }`),`ctrl` 里再配按住 Ctrl / ⌘ 时的替代值;节点 / 线路 / 通道还能用 `cursor` / `ctrlCursor` 逐要素覆盖,详见「光标」 |
@@ -70,7 +73,7 @@
70
73
  | `shortcuts` | `GisViewShortcuts` | 见「快捷键」 | 所有快捷键都可自定义:框选 / 多选 / 加点 / 复制 / 粘贴 / 取消 / 删除 / 适应视图,没写的动作沿用默认值,写 `false` 等于关掉这个动作的快捷键 |
71
74
  | `copy` | `GisViewCopyOptions` | 缺省关 | 复制节点(**写了这份配置才算开**,`enabled: false` 显式关掉):`enabled` 开关、`offset` 落点偏移(默认 `[28, 24]` 像素)、`autoCommit`(交互入口落地前是否自动确认:不写就是落地,`false` 停在预览态等 `commitPointCopy()` / 载荷里的 `payload.commit()`)、`idPrefix`(默认 `copy-`)、`createId` / `createItem` 定制复制品,见「节点复制」 |
72
75
  | `remove` | `GisViewRemoveOptions` | 缺省关 | 删除选中的拐点 / 线路 / 节点(**写了这份配置才算开**,`enabled: false` 显式关掉):`enabled` 开关、`scope`(`confirm()` 不带参数时的缺省范围:`'lines'` 只删选中的回线 / `'groups'` 连所在分组 / `'channels'` 连整条通道,缺省 `'lines'`)、`confirm`(不写停在 `pending` 等使用方裁决 / `false` 直接删 / 函数自行裁决,支持 Promise)。Delete 键与 `requestRemove()` 都先出一份「要删什么、连带什么」的载荷,确认之后才动数据;删节点会连挂在它身上的线路与被它锚定的通道一起删,见「删除(remove)」 |
73
- | `merge` | `GisViewMergeOptions` | 缺省关 | 合并节点(**写了这份配置才算开**,`enabled: false` 显式关掉):`enabled` 开关、`distance` 碰撞容差(CSS 像素)、`confirm`(不写停在 `pending` 等使用方裁决 / `false` 直接合并 / 函数自行裁决)、`channelGroups`(`'keep'` 各自保留分组 / `'merge'` 合成一个分组)、`createItem` 定制合并结果,见「节点合并」 |
76
+ | `merge` | `GisViewMergeOptions` | 缺省关 | 合并节点(**写了这份配置才算开**,`enabled: false` 显式关掉):`enabled` 开关、`trigger` 触发时机(`'collision'` 两个节点半径相碰 / `'center'` 拖动节点中心进入目标节点区域)、`distance` 额外像素容差、`confirm`(不写停在 `pending` 等使用方裁决 / `false` 直接合并 / 函数自行裁决)、`channelGroups`(`'keep'` 各自保留分组 / `'merge'` 合成一个分组)、`createItem` 定制合并结果,见「节点合并」 |
74
77
  | `minScale` / `maxScale` | `number` | `0.002` / `20000` | 缩放范围(像素 / 世界单位) |
75
78
  | `fitPadding` | `number` | `48` | 适应视图时四周留白(CSS 像素);留白比画布还大时按「内容至少留 48px」反过来压留白,不会把内容挤成一个点 |
76
79
  | `fitOnInit` | `boolean` | `true` | 首次拿到数据时自动适应视图;配了 `initialView` 时以它为准(`false` 只关掉「适应」,`initialView` 仍然生效,见「初始视图」) |
@@ -78,7 +81,7 @@
78
81
  | `progressiveInit` | `boolean` | `true` | 大数据(2 万点以上)初始化是否从视图中心向外发散渲染:首帧只排中心附近的一批,剩下的分帧往外补,见「大数据量」 |
79
82
  | `statsInterval` | `number` | `250` | `onStats` 的最小间隔(毫秒),`0` 表示每帧都发 |
80
83
  | `renderEmitInterval` | `number` | `400` | `onRender` 的节流间隔(毫秒),`0` 与 `onStats` 同拍(再配上 `statsInterval: 0` 就是每帧一条) |
81
- | `plugins` | `GisViewPlugin[]` | `[]` | 插件:`view => hook`,返回的 `destroy` 在实例销毁时倒序回调,见「插件」 |
84
+ | `plugins` | `GisViewPlugin[]` | `[]` | 插件:`(view, context) => hook`,返回的 `destroy` 在实例销毁时倒序回调,见「插件」 |
82
85
  | `zoomStep` | `number` | `1.4` | `zoomIn()` / `zoomOut()` 的步进倍率 |
83
86
  | `width` / `height` | `number \| string` | 容器尺寸 | 画布尺寸,数字按 CSS 像素处理 |
84
87
  | `pixelRatio` | `number` | `devicePixelRatio` | 手动指定设备像素比(夹在 0.5 ~ 3);宿主缩放(CSS `zoom` / `transform: scale`)的比例会乘在它上面,合计夹在 0.5 ~ 4 |
@@ -104,8 +107,8 @@
104
107
  | 状态样式与选中 | `pointHoverStyle` / `pointSelectStyle` · `lineHoverStyle` / `lineSelectStyle` · `pointMultiSelectStyle` / `pointBoxSelectStyle` · `lineMultiSelectStyle` · `defaultHighlight` · `selectionBoxStyle` · `selectionOnTop` · `waypointStyle` / `waypointSelectStyle` |
105
108
  | 交互开关 | `boxSelect` · `multiSelect` · `waypointEditable` · `waypointVisibility` · `interactive` · `preventContextMenu` · `clickable` · `draggable` · `liveDrag` · `shortcuts` · `copy` · `remove` · `merge` |
106
109
  | 视图与相机 | `minScale` / `maxScale` · `fitPadding` · `fitOnInit` · `initialView` · `zoomStep` |
107
- | 画质与渲染 | `quality` · `width` / `height` · `pixelRatio` · `maxCanvasPixels` · `antialias` · `interactionThinLines` · `interactionNoMsaa` · `renderer` |
108
- | 大数据(筛选 / 搜索 / 读数) | `filter` · `filterWorker` · `searchWorker` · `progressiveInit` · `statsInterval` · `renderEmitInterval` |
110
+ | 画质与渲染 | `quality` · `width` / `height` · `pixelRatio` · `maxCanvasPixels` · `antialias` · `interactionThinLines` · `interactionNoMsaa` · `renderer` · `webglLayers` |
111
+ | 大数据(筛选 / 搜索 / 读数) | `denseMode` · `filter` · `filterWorker` · `searchWorker` · `progressiveInit` · `statsInterval` · `renderEmitInterval` |
109
112
  | 外部界面与集成 | `minimap` · `plugins` · `ariaLabel` |
110
113
 
111
114
  ### 总开关与历史
@@ -252,8 +255,8 @@ view.updateOptions({ channelWidth: 0.08 }) // 没绑节点的那几条跟着
252
255
  #### `channelDraftStyle`
253
256
 
254
257
  - **类型**:`GisViewChannelDraftStyle`
255
- - **默认值**:蓝色 2px + 两端圆点
256
- - **说明**:新增通道草稿线(选好起点之后跟随光标的那条预览线)的样式:`color` / `width` / `dot`
258
+ - **默认值**:蓝色 2px + 两端圆点,箭头关闭
259
+ - **说明**:新增通道草稿预览的全局样式:`color` / `width` / `dot` / `dotColor` / `arrow` / `arrowSize` / `arrowPositions` / `arrowReverse` / `arrowColor` / `circuitSpacing` / `opacity` / `customDraw`。`kind: 'channel'` 且 `circuits > 1` 时按 `circuitSpacing` 画出平行回线;`arrowPositions` 是沿线归一化位置(单个数或数组),`customDraw` 可拿最终 GL 上下文与每条回线路径自绘;`routing: 'orthogonal'` 时折线预览同样分段绘制。真实线路箭头仍看 `direction`,预览箭头只影响草稿
257
260
  - **参考**:见「新增通道」一节,子字段在那里的表里逐个展开
258
261
 
259
262
  #### `channelSelectMode`
@@ -322,7 +325,7 @@ view.updateOptions({ heatmap: { enabled: false } }) // 关掉回正常配色
322
325
 
323
326
  - **类型**:`GisViewEffectsInput`
324
327
  - **默认值**:关
325
- - **说明**:动画效果(全局缺省):线路上的跑动图标(`line`,ECharts `lines.effect` 那一类)与节点上的扩散涟漪(`point`,`effectScatter` 那一类),逐要素用 `points[].effect` / `lines[].effect` 覆盖;没配就是关的,但「只在数据里逐条配了 `effect`」的场景照样会动。`false` 或 `{ enabled: false }` 是**一处关掉**(谁都别动);运行时有 `setEffects()` / `getEffects()` / `getLineEffects()`,见「动画效果(effects)」
328
+ - **说明**:动画效果(全局缺省):线路上的跑动图标(`line`,ECharts `lines.effect` 那一类)与节点上的扩散涟漪(`point`,`effectScatter` 那一类),逐要素用 `points[].effect` / `lines[].effect` 覆盖;没配就是关的,但「只在数据里逐条配了 `effect`」的场景照样会动。`false` 或 `{ enabled: false }` 是**一处关掉**(谁都别动);运行时有 `updateOptions({ effects })` / `getEffects()` / `getLineEffects()`,见「动画效果(effects)」
326
329
  - **参考**:见「动画效果(effects)」一节,子字段在那里的表里逐个展开
327
330
  - **示例**:
328
331
 
@@ -388,6 +391,26 @@ view.updateOptions({ prebake: { combos: view.getSymbolCombos().combos } })
388
391
  - **说明**:标签的运行时状态(`getLabelStates()` 的那一份:拖出来的偏移、改过的内容与样式、运行时加的标签、隐藏覆盖):创建时喂回来就回显,等价于创建之后调 `setLabelStates(states)`;`updateOptions({ labelStates })` 同样认。`exportData({ format: 'input' })` 的结果里就叫 `labelStates`,存档 → 回灌直接接上
389
392
  - **参考**:见「标签的拖动与编辑」一节,子字段在那里的表里逐个展开
390
393
 
394
+ #### `graphics`
395
+
396
+ - **类型**:`GisViewGraphic[]`
397
+ - **默认值**:无
398
+ - **说明**:与节点 / 线路数据无关的扩展图形层(参考 ECharts 的 `graphic`):每一条按世界坐标 `x` / `y` 锚在视图上,支持 `type: 'path' | 'image' | 'canvas'`、`anchor`、`offset`、`rotation`、`scale`、`opacity`、`visible`、`zIndex` 与 `scaleWithView`。图形排在 WebGL 画布之上、标签层之下,不参与指针拾取;相机移动 / 缩放与容器 resize 时自动重投影,PNG / SVG 导出都会带上。运行时用 `addGraphic` / `addGraphics` / `updateGraphic` / `removeGraphic` / `clearGraphics` 增删改,读回用 `getGraphic` / `getGraphics`
399
+ - **参考**:见「12 标签与装饰」的「扩展图形(graphic)」一节,逐字段写法、锚点与导出说明都在那里
400
+ - **示例**:
401
+
402
+ ```js
403
+ createGisView(container, {
404
+ graphics: [
405
+ { id: 'logo', type: 'image', src: '/logo.png', x: 120, y: 80, width: 48, height: 48, anchor: 'bottom-left' },
406
+ { id: 'frame', type: 'path', d: 'M0 0H100V60H0Z', viewBox: [0, 0, 100, 60], x: 0, y: 0, width: 120, height: 72, fill: 'none', stroke: '#2f6fd0' }
407
+ ]
408
+ })
409
+
410
+ view.addGraphic({ id: 'pin', type: 'path', d: 'M0 0L8 20L16 0Z', viewBox: [0, 0, 16, 20], x: 60, y: 40, width: 16, height: 20, fill: '#e35b5b', scaleWithView: true })
411
+ view.clearGraphics()
412
+ ```
413
+
391
414
  #### `tooltip`
392
415
 
393
416
  - **类型**:`GisViewTooltipOptions`
@@ -564,7 +587,7 @@ view.selectInBox(rect, { selectionKinds: 'channel' }) // 仅这一次只框通
564
587
 
565
588
  - **类型**:`boolean`
566
589
  - **默认值**:`false`
567
- - **说明**:是否允许编辑线路拐点(按住加点快捷键 `shortcuts.addWaypoint`(默认 Ctrl / ⌘)+ 点击添加、拖动移动、双击或删除快捷键删除),单条线可用 `waypointEditable` 覆盖;**缺省关**,写 `waypointEditable: true` 或 `features: { waypoint: true }` 才开
590
+ - **说明**:是否允许编辑线路拐点(按住加点快捷键 `shortcuts.addWaypoint`(默认 Ctrl / ⌘)+ 点击添加、拖动移动、双击或删除快捷键删除),单条线可用 `waypointEditable` 覆盖;**缺省关**,写 `waypointEditable: true` 或 `features: { waypoint: true }` 才开。`false`(以及 `features: { waypoint: false }`)会同时关闭新增、移动与删除,没有只关其中一项的细分开关;`shortcuts.addWaypoint` 仍只决定加点的组合键
568
591
  - **参考**:见「线路拐点」一节,子字段在那里的表里逐个展开
569
592
 
570
593
  #### `waypointVisibility`
@@ -662,7 +685,8 @@ view.resolveRemove('all') // 或 'points' / false
662
685
  | 字段 | 类型 | 默认值 | 说明 |
663
686
  | --- | --- | --- | --- |
664
687
  | `enabled` | `boolean` | 写了 `merge` 即 `true` | 是否启用合并;显式 `false` 关掉。`features.merge` 也能强制打开 / 关掉 |
665
- | `distance` | `number` | `0` | 额外碰撞容差(CSS 像素):两个节点画在屏幕上的半径之和再加它才算撞上,负数按 0 处理 |
688
+ | `trigger` | `'collision' \| 'center'` | `'collision'` | 触发时机:`collision` 按两个节点画在屏幕上的半径之和判断,响应更早;`center` 只要求拖动的节点中心进入目标节点的屏幕区域,更晚、更稳。两种都再叠加 `distance` 容差 |
689
+ | `distance` | `number` | `0` | 额外触发容差(CSS 像素):`collision` 加在两个节点半径之和上,`center` 加在目标节点半径上,负数按 0 处理 |
666
690
  | `confirm` | `false \| (payload) => boolean \| void \| Promise<boolean \| void>` | 不写(停在 `pending`) | 确认方式:不写时组件不弹任何界面,等使用方调 `payload.confirm()` / `resolvePointMerge()`;`false` 松手直接合并;函数自行裁决,返回 / resolve `false` 取消,返回 `undefined` 表示继续等使用方接管 |
667
691
  | `channelGroups` | `'keep' \| 'merge'` | `'keep'` | 两个节点合并后、两端撞成同一条通道时回线怎么分组:`keep` 各自保留原分组,`merge` 合成一个分组(回线取并集) |
668
692
  | `createItem` | `(source, target, context) => GisViewPoint` | 内置合并规则 | 整份接管合并后的节点数据。`context` 含双方数据 / 坐标 / 样式快照 / `lines` / `channels` / `view`;不写时按「目标优先、来源独有字段带过来、尺寸取双方最大、图标优先目标」合并,坐标与 id 始终取保留端 |
@@ -672,7 +696,7 @@ view.resolveRemove('all') // 或 'points' / false
672
696
  - **示例**:
673
697
 
674
698
  ```js
675
- createGisView(container, { merge: { enabled: true, distance: 12, confirm: true } })
699
+ createGisView(container, { merge: { enabled: true, trigger: 'center', distance: 6, confirm: false } })
676
700
  view.mergePoints('a', 'b') // 接口合并
677
701
  view.getPointMerge() // 待确认时读预览
678
702
  view.getLine('l1') // impact.lineIds 里的 id 按它查线路详情
@@ -784,8 +808,48 @@ const view = createGisView(container, { renderer: 'webgl2' }) // 连 WebGPU
784
808
  view.getRendererInfo() // { backend: 'webgl2', webgpu: { available, reason } }
785
809
  ```
786
810
 
811
+ #### `webglLayers`
812
+
813
+ - **类型**:`GisViewWebGLLayer[]`
814
+ - **默认值**:`[]`
815
+ - **说明**:WebGL 自定义绘制层。每层写 `{ id, order, enabled, draw }`,`draw({ gl, canvas, viewport, camera, frame, project, unproject, requestRender })` 在内置内容与后备缓冲贴回之后执行;`order` 从小到大排序,`enabled: false` 跳过该层。每层开画前会重置帧缓冲、viewport、混合与 scissor 等状态,前一层改过的 GL 状态不会漏给下一层。层只叠加画面,不参与拾取、场景解析或数据导出;`view.gl` 也可直接取到同一个 WebGL2 上下文
816
+ - **参考**:见「WebGL 自定义层」一节,运行动画可在 `draw` 里调用 `requestRender()`
817
+ - **示例**:
818
+
819
+ ```js
820
+ const removeLayer = view.addWebGLLayer({
821
+ id: 'overlay',
822
+ order: 10,
823
+ draw({ gl, canvas, project, requestRender }) {
824
+ const [x, y] = project(120, 30) // 世界坐标 → 画布 CSS 像素
825
+ // 在这里用自己的 shader / 缓冲区绘制;数据变化时调用 requestRender()
826
+ requestRender()
827
+ }
828
+ })
829
+
830
+ view.updateWebGLLayer('overlay', { enabled: false }) // 暂不画,但保留层
831
+ view.removeWebGLLayer('overlay') // 删除这一层
832
+ removeLayer() // 卸载函数也幂等
833
+ ```
834
+
787
835
  ### 大数据(筛选 / 搜索 / 读数)
788
836
 
837
+ #### `denseMode`
838
+
839
+ - **类型**:`GisViewDenseModeInput`
840
+ - **默认值**:`'auto'`
841
+ - **说明**:大数据展示模式:`'auto'`(缺省)按三路信号自动判定 —— 视口内可见节点达到 `visibleThreshold`(4000)、可见密度达到 `densityThreshold`(每百万 CSS 像素 3000 个),或数据总量达到 `pointThreshold`(50000);任意一项越线就进入密集档,`'on'` / `'off'`(布尔值 `true` / `false` 等价)强制开关。对象写法 `{ mode, visibleThreshold, densityThreshold, pointThreshold }` 可改阈值,阈值只认正数。判定延迟 160 ms;退出时留 22% 缓冲(回落到进入阈值的 78% 才恢复),避免在边界附近来回缩放时标签层反复重排。密集档内标签自动走避让 / 截断(与 `labelOptimize: true` 同一条路),线路动点与节点涟漪暂停,用户原来的 `effects` 配置仍保留在 `getOptions()` 里;退出后自动恢复。运行时用 `updateOptions({ denseMode })` 切换,当前档位、判定依据与可见节点数看 `getStats().dense`
842
+ - **参考**:见「大数据展示模式(denseMode)」一节,三档阈值与回滞、读数形状都在那里展开
843
+
844
+ ```js
845
+ const view = createGisView(container, {
846
+ points, lines,
847
+ denseMode: { mode: 'auto', visibleThreshold: 2500, densityThreshold: 2000 }
848
+ })
849
+ view.updateOptions({ denseMode: 'off' }) // 临时强制关闭
850
+ const { dense } = view.getStats() // { mode, active, reason, visiblePoints, thresholds… }
851
+ ```
852
+
789
853
  #### `filter`
790
854
 
791
855
  - **类型**:`GisViewFilterInput | null`
@@ -838,7 +902,7 @@ view.setFilter(null) // 清掉筛选
838
902
 
839
903
  - **类型**:`GisViewMinimapOptions | null`
840
904
  - **默认值**:无
841
- - **说明**:内置鹰眼图:位置、尺寸、节点 / 线路 / 视口框三份样式与交互都可配,`extent` 决定小图按数据范围还是「数据 ∪ 底图」铺(默认 `auto`,GeoJSON 底图不会缩成一个点),`zoomable` 打开后小图自身可整体放大缩小(空白处拖动可以平移小图或直接框选让主图显示过去,每格倍率 `zoomStep`),通道还能只画一根;小图同样支持规则(`pointRules` / `lineRules`,缺省沿用主图规则的颜色与层级),可以只画某几层(`levels`)、关掉分层叠画(`layered`)、按三组系数给节点与线路定尺寸(整体倍数 `pointSizeScale` / `lineWidthScale`、跟随小图倍数 `pointZoomScale` / `lineZoomScale`(只在小图自身倍数 ≠ 1 时起作用)、跟随主视图地图倍数 `pointMapZoomScale` / `lineMapZoomScale`),视口框与框选矩形的颜色 / 背景 / 边框 / 圆角也能配(`boxStyle` / `selectStyle`),`extent` 还能直接写死一份世界范围、容器可加 `className` / `style`、`draw` 钩子每帧自己往上画一层,不配则不产生任何 DOM,见「鹰眼图」
905
+ - **说明**:内置鹰眼图:位置、尺寸、节点 / 线路 / 视口框三份样式与交互都可配,`extent` 决定小图按数据范围还是「数据 ∪ 底图」铺(默认 `auto`,GeoJSON 底图不会缩成一个点),`zoomable` 打开后小图自身可整体放大缩小(空白处拖动可以平移小图或直接框选让主图显示过去,每格倍率 `zoomStep`),通道还能只画一根;小图同样支持规则(`pointRules` / `lineRules`,缺省沿用主图规则的颜色与层级),可以只画某几层(`levels`)、关掉分层叠画(`layered`)、按三组系数给节点与线路定尺寸(整体倍数 `pointSizeScale` / `lineWidthScale`、跟随小图倍数 `pointZoomScale` / `lineZoomScale`(只在小图自身倍数 ≠ 1 时起作用)、跟随主视图地图倍数 `pointMapZoomScale` / `lineMapZoomScale`),视口框与框选矩形的颜色 / 背景 / 边框 / 圆角也能配(`boxStyle` / `selectStyle`),`extent` 还能直接写死一份世界范围、容器可加 `className` / `style`、`layers` 按 `placement` 分数据前 / 数据后、段内按 `order` 拆出多层自绘内容(旧 `draw` 钩子仍兼容并排在最后)、`onInteraction` 在手势结束时给出类型 / 世界坐标 / 相机、`maxPixelRatio` 限制备份倍率上限,不配则不产生任何 DOM,见「鹰眼图」
842
906
  - **参考**:见「鹰眼图」一节,子字段在那里的表里逐个展开
843
907
 
844
908
  ```js
@@ -847,9 +911,14 @@ createGisView(container, {
847
911
  enabled: true,
848
912
  width: 220,
849
913
  height: 130,
850
- position: 'right-bottom',
914
+ position: 'bottom-right',
851
915
  levels: [1, 5, 20],
852
- pointStyle: { color: '#2f6fed' }
916
+ pointStyle: { color: '#2f6fed' },
917
+ layers: [
918
+ { id: 'grid', placement: 'below-data', draw: ({ context, width, height }) => { /* 网格 */ } },
919
+ { id: 'north', placement: 'above-data', draw: ({ context, width }) => { /* 指北针 */ } }
920
+ ],
921
+ onInteraction: info => console.log(info.type, info.world)
853
922
  }
854
923
  })
855
924
  ```
@@ -858,14 +927,14 @@ createGisView(container, {
858
927
 
859
928
  - **类型**:`GisViewPlugin[]`
860
929
  - **默认值**:`[]`
861
- - **说明**:插件:`view => hook`,返回的 `destroy` 在实例销毁时倒序回调,见「插件」
930
+ - **说明**:插件:`(view, context) => hook`,返回的 `destroy` 在实例销毁时倒序回调,见「插件」
862
931
  - **参考**:见「插件」一节,子字段在那里的表里逐个展开
863
932
  - **示例**:
864
933
 
865
934
  ```js
866
935
  const view = createGisView(container, {
867
- plugins: [view => ({
868
- destroy() { /* 插件自己的清理 */ }
936
+ plugins: [(view, context) => ({
937
+ destroy() { /* context.apiVersion 当前为 1 */ }
869
938
  })]
870
939
  })
871
940
  ```
@@ -19,12 +19,13 @@
19
19
  | `onPointer` | `GisViewPointerState` | 光标每次移动(含移出画布)都发:`{ inside, screen, world, lngLat }`,屏幕坐标是画布 CSS 像素、`lngLat` 要有 GeoJSON 背景才有;`getPointer()` 随时能读同一份,移出时 `inside: false` |
20
20
  | `onPointDrag` | `GisViewPointDragPayload` | 拖拽点:`phase` 为 `start` / `drag` / `end`,载荷带最新坐标、本次移动的全部节点 `points` 与跟随移动的线路 `lines` |
21
21
  | `onPointCopy` | `GisViewPointCopyPayload \| GisViewBatchCopyPayload` | 复制节点:`phase` 为 `start` / `move` / `commit` / `end` / `cancel`(复制到剪贴板另有 `clipboard`,批量复制 / 整组粘贴是 `batch`),`commit` 阶段可以 `payload.cancel()` 取消、`payload.update()` / `setItem()` 改数据;`clipboard` 载荷带整组 `sources` / `items` / `lines` / `channels` / `count` / `anchor`,`batch` 载荷另带 `indexes` / `lineSources` / `channelSources` / `revert()`,见「节点复制」 |
22
- | `onPointMerge` | `GisViewPointMergePayload \| GisViewMergeResult \| GisViewMergeFailure \| GisViewMergeSelectedPayload` | 合并节点:拖到另一个节点上时先发 `pending`(组件不弹任何界面,在回调里调 `payload.confirm()` / `cancel()` 裁决,或存下来自己接界面),之后发 `confirm`(载荷里的 `item` 是合并结果,可改 / 可取消)、`cancel`,数据并完 / 并失败再发一条 `merge`(`ok: true` / `ok: false`);框选 / 多选之后调 `mergeSelectedPoints()` 时**逐对发 `merge`**,收尾再发一条 `phase: 'mergeSelected'` 的汇总(`merged` 逐对列出、`skipped` 说明谁没并进去),见「节点合并」 |
22
+ | `onPointMerge` | `GisViewPointMergePayload \| GisViewMergeResult \| GisViewMergeFailure \| GisViewMergeSelectedPayload` | 合并节点:拖到另一个节点上时先发 `pending`(组件不弹任何界面,在回调里调 `payload.confirm()` / `cancel()` 裁决,或存下来自己接界面),之后发 `confirm`(载荷里的 `item` 是合并结果,可改 / 可取消)、`cancel`,数据并完 / 并失败再发一条 `merge`(`ok: true` / `ok: false`);拖拽入口的载荷带 `trigger`(`'collision'` / `'center'`),说明这一次按哪种时机命中;框选 / 多选之后调 `mergeSelectedPoints()` 时**逐对发 `merge`**,收尾再发一条 `phase: 'mergeSelected'` 的汇总(`merged` 逐对列出、`skipped` 说明谁没并进去),见「节点合并」 |
23
23
  | `onRemove` | `GisViewRemovePayload` | 删除请求(Delete 键 / `requestRemove()`):`pending` 时给一份载荷说明要删什么、连带什么、能按哪些范围删(`points` / `lines` / `waypoints` / `groups` / `channels` / `actions` / `counts`),确认之后发 `phase: 'remove'`(`result` 是结果)、取消发 `phase: 'cancel'`;组件不弹任何界面,弹不弹、怎么弹都由使用方决定(在回调里调 `payload.confirm(scope)` / `payload.cancel()`,或存下来自己接界面),见「删除(remove)」 |
24
24
  | `onWaypointChange` | `GisViewWaypointPayload` | 拐点新增 / 选中 / 删除与拖动,`phase` 为 `add` / `select` / `remove` 或拖动时的 `start` / `move` / `end`,载荷带最新线路数据与所属集合的 `group_id`;通道内的回线共用骨架,载荷是**被操作的那条回线**的推导结果。同步后端只接改变数据的 `add` / `remove` / `end`,并用 `getChannelGroupWaypoints().path` 提交整份骨架,见「通道与多回线」 |
25
25
  | `onChannelContextMenu` | `GisViewChannelContextPayload \| null` | 右键点中通道回线:给出这条通道的上下文(有几组、当前是哪一组、分组列表与可用交互),点空白处给 `null`(用它收框);**落在节点上时也给 `null`**(点的层级高于线,见「通道右键交互框」) |
26
- | `onChannelDraft` | `GisViewChannelDraftPayload` | 新增通道草稿:`start` / `from` / `ready` / `pick` / `restart` / `cancel` / `commit` / `blocked`,两个节点的信息与可选方案都在载荷里,见「新增通道」 |
26
+ | `onChannelDraft` | `GisViewChannelDraftPayload` | 新增通道草稿:`start` / `from` / `ready` / `pick` / `restart` / `cancel` / `commit` / `blocked`,两个节点的信息、`routing` / `path` 与可选方案都在载荷里(`path` 是中间拐点),见「新增通道」 |
27
27
  | `onChannelDraftClick` | `GisViewChannelDraftPayload` | 草稿里**每点一次**都发一条:`step` 为 `1` 时拿到起点、`2` 时拿到终点(线路到此结束);加上 `phase: 'pick'` 时是点在空白或点回起点;载荷与 `onChannelDraft` 相同 |
28
+ | `onDecorationDraft` | `GisViewDecorationDraftPayload` | 动态装饰器草稿:`start` 开启 → `hover` 跟随命中线路或节点 / `leave` 移出收掉 → 左键在目标上松开发 `ready`(空白处不发)→ `commit` / `cancel`;`target` 为 `line` / `point` / `both`,`scope` 为 `line` / `group` / `channel`,节点侧 `placement` 为 `offset` / `fixed` / `pointer`,白名单、上限与重复策略见「动态装饰器草稿」 |
28
29
  | `onChannelGroupChange` | `GisViewChannelGroupChangePayload` | 分组变化:拆分 / 合并 / 挪线 / 新建组(`action.type` 为 `splitGroups` / `mergeGroups` / `moveLine` / `addGroup`)与整份声明跟着补丁换(`setGroups`,`updateChannel` 写 `groups` / `lineIds`);`action` 带这一笔的 `groupId` / `groupIds` / `lineIds`(`updateLine` 顺带挪组时 `action.via` 为 `'updateLine'`),`item` / `groups` 是与 `dataChange('channelGroups')` 同一份的最新读数。同步后端时用 `getChannelGroups(channelId)` 提交整份声明,不按 action 猜 delta,见「通道分组」 |
29
30
  | `onLabelDrag` | `GisViewLabelDragPayload` | 标签被拖走(`draggable`):`phase` 为 `start` / `move` / `end`,载荷带 `kind`(`point` / `line`)、`index` / `id` / `item`、当前偏移 `offset`、起手时的 `startOffset` 与本次位移 `delta`(CSS 像素),见「标签的拖动与编辑」 |
30
31
  | `onLabelClick` | `GisViewLabelClickPayload` | 点了一下标签(`editable`,位移小于 3 px 才算点选):载荷带 `kind` / `index` / `id` / `item`、当前 `offset` 与这一条的状态读数 `state`,使用方按它选中这一条 |
@@ -77,14 +78,14 @@ const view = createGisView('#map', {
77
78
 
78
79
  | 载荷字段 | 说明 |
79
80
  | --- | --- |
80
- | `type` | 动作名:`updateData` / `updatePoints` / `updateLines` / `updateChannels` / `updateOptions` / `updateBackground` / `updatePoint` / `updateLine` / `updateChannel` / `pointDrag` / `copyPoint` / `copyPoints` / `mergePoints` / `waypoint` / `addChannel` / `addChannels` / `addChannelGroups` / `addLine` / `addPoints` / `addLines` / `removePoints` / `removeSelected` / `removeLines` / `removeLine` / `removeChannel` / `channelGroups` / `batch` |
81
+ | `type` | 动作名:`updateData` / `updatePoints` / `updateLines` / `updateOptions` / `updateBackground` / `updatePoint` / `updateLine` / `updateChannel` / `pointDrag` / `copyPoint` / `copyPoints` / `mergePoints` / `waypoint` / `addChannel` / `addChannels` / `addChannelGroups` / `addLine` / `addPoints` / `addLines` / `removePoints` / `removeSelected` / `removeLines` / `removeLine` / `removeChannel` / `channelGroups` / `batch` |
81
82
  | `points` / `lines` / `channels` | 变更之后的最新数据(组件内部那一份的引用,只读,不要就地改) |
82
83
  | `counts` | `{ points, lines, channels }` 三个条数 |
83
84
  | `ok` / `reason` | 这一次调用成没成(`addPoints` / `addLines` / `removePoints` 这类批量接口会带上),`reason` 说明没成的原因 |
84
85
  | 动作专属字段 | 拖拽带 `movedPoints` / `movedLines`,复制带 `item` / `source` / `revert()`(`copyPoints` / 整组粘贴另有 `sources` / `items` / `indexes` / `lines` / `channels` / `count`),合并带 `source` / `target` / `removedLines` / `mergedChannels`,拐点带 `lineIndex` / `pathIndex` / `phase`,新增带 `lineIds` / `lineIndex` / `channelId` / `groupId`(`addPoints` / `addLines` 另有 `indexes` / `items` / `position`:新要素在数组里的位置与加进去的那几条,`addChannelGroups` 另有 `results` / `groupIds` / `items`),删除带 `indexes` / `item` / `removedLineIds`,分组带 `index` / `groups` / `action`(细分动作,与 `onChannelGroupChange` 同一份);批量补丁(`patchPoints` / `patchLines`)的 `updatePoints` / `updateLines` 带 `indexes` / `items` / `count` / `skipped`,`removeSelected` 带 `pointIds` / `lineIds` / `pointIndexes` / `lineIndexes` / `removedChannels` |
85
86
 
86
87
  `onSelectChange` 与 `onSelect` 的区别只有一个:**只在选中集真的变了时发** —— 框选过程中的重复同步、
87
- 数据变化引起的补发都不发;并且**接口选中**(`select()` / `select(null)` / `selectInBox()`)也会发
88
+ 数据变化引起的补发都不发;并且**接口选中**(`selectFeatures()` / `selectFeatures(null)` / `selectInBox()`)也会发
88
89
  (引擎那条 `setSelection` 自己不派发 onSelect,组件层在这里补上)。载荷里的 `cause` 说明这次是怎么选上的:
89
90
  `click`(指针点击)/ `boxSelect`(框选)/ `keyboard`(Esc 清空)/ `api`(接口调用)。
90
91
 
@@ -158,7 +159,7 @@ view.off('*') // 不传 handler = 摘掉这个事件的全部订阅,返回摘
158
159
  | 高频事件不白算 | 组件内部按「有没有人订阅」短路(`count(name) \|\| count('*')`):没人听的时候不构造载荷,`pointer` / `hover` / `render` 这些每帧级别的事件也可以直接订阅 |
159
160
  | 订阅时机 | 创建时的 `ready` 与首次 `dataChange` 发生在 `createGisView` 返回之前,这两条要在 options 里写回调(`onReady` 等) |
160
161
 
161
- 全部事件名(与 `EVENT_NAMES` 一致):`ready`、`error`、`warning`、`viewport`、`cameraChange`、`cursor`、`hover`、`pointer`、`pointerDown`、`pointerUp`、`contextMenu`、`click`、`dblClick`、`labelClick`、`labelDrag`、`labelChange`、`labelContextMenu`、`labelDblClick`、`select`、`selectChange`、`pointDrag`、`pointCopy`、`pointMerge`、`remove`、`waypointChange`、`channelContextMenu`、`channelDraft`、`channelDraftClick`、`channelGroupChange`、`dataChange`、`dataRendered`、`filter`、`history`、`featureChange`、`qualityChange`、`optionChange`、`shortcut`、`stats`、`render`、`destroy`,加上 `'*'`。
162
+ 全部事件名(与 `EVENT_NAMES` 一致):`ready`、`error`、`warning`、`viewport`、`cameraChange`、`cursor`、`hover`、`pointer`、`pointerDown`、`pointerUp`、`contextMenu`、`click`、`dblClick`、`labelClick`、`labelDrag`、`labelChange`、`labelContextMenu`、`labelDblClick`、`select`、`selectChange`、`pointDrag`、`pointCopy`、`pointMerge`、`remove`、`waypointChange`、`channelContextMenu`、`channelDraft`、`channelDraftClick`、`decorationDraft`、`channelGroupChange`、`dataChange`、`dataRendered`、`filter`、`history`、`featureChange`、`qualityChange`、`optionChange`、`shortcut`、`stats`、`render`、`destroy`,加上 `'*'`。
162
163
 
163
164
  ## 功能开关
164
165
 
@@ -172,23 +173,27 @@ createGisView('#map', {
172
173
  points, lines,
173
174
  features: { drag: true, label: false } // 打开「拖动节点」、关掉「节点标签」
174
175
  })
176
+ createGisView('#map', {
177
+ points, lines,
178
+ features: { waypoint: false } // 新增 / 移动 / 删除拐点一起关掉
179
+ })
175
180
  ```
176
181
 
177
182
  | 预设 | 效果 |
178
183
  | --- | --- |
179
184
  | `'edit'` | 全开(编辑类也一起打开),等价于 `features: true` |
180
185
  | `'view'` | 只读浏览:一次打开查看类(平移缩放、悬停、选中、右键回调、键盘),`boxSelect` / `drag` / `waypoint` / `copy` / `merge` / `remove` / `channelDraft` / `channelMenu` 仍关着 —— 「能看能选、改不动数据」 |
181
- | `'static'` | 静态图:与缺省一致(全关),只剩画布与数据;留着这个名字方便「从全开切回静态」 |
186
+ | `'static'` | 静态图:显式全关(含标签 / 提示 / 鹰眼图),只剩画布与数据;留着这个名字方便「从全开切回静态」 |
182
187
 
183
188
  | 开关 | 关掉之后 | 没写时跟随 |
184
189
  | --- | --- | --- |
185
190
  | `pan` | 拖拽平移 | `interactive === true`(缺省关) |
186
191
  | `zoom` | 滚轮缩放 | `interactive === true`(缺省关) |
187
192
  | `hover` | 悬停拾取(`onHover` 与悬停样式) | `clickable === true`(缺省关) |
188
- | `select` | 点击选中(`select()` / `selectInBox()` 这些接口不受限) | `clickable === true`(缺省关) |
193
+ | `select` | 点击选中(`selectFeatures()` / `selectInBox()` 这些接口不受限) | `clickable === true`(缺省关) |
189
194
  | `boxSelect` | Shift + 拖动框选(可用 `shortcuts.boxSelect` 改) | `boxSelect === true`(缺省关) |
190
195
  | `drag` | 拖动节点(含整组拖动) | `draggable === true`(缺省关) |
191
- | `waypoint` | 线路拐点的添加 / 拖动 / 删除 | `waypointEditable === true`(缺省关) |
196
+ | `waypoint` | 线路拐点的新增 / 移动 / 删除(一道总闸,不做细分) | `waypointEditable === true`(缺省关) |
192
197
  | `copy` | Alt 点击复制与复制接口 | 写了 `copy` 且 `copy.enabled !== false`(缺省关) |
193
198
  | `merge` | 拖到另一个节点上合并 | 写了 `merge` 且 `merge.enabled !== false`(缺省关) |
194
199
  | `remove` | Delete 删除选中的拐点 / 线路 / 节点(先出删除载荷,确认之后才动数据) | 写了 `remove` 且 `remove.enabled !== false`(缺省关) |
@@ -7,7 +7,7 @@
7
7
  一个实例可以反复换数据:切场景(场站与通道整批都变了)、从别的接口再拉一份、按批把通道补进来,
8
8
  都不必 `destroy()` 再重建(重建会丢掉相机、筛选、选中与标签状态)。
9
9
 
10
- ### 整份换:updateData / updateChannels
10
+ ### 整份换:updateData(含通道声明)
11
11
 
12
12
  ```js
13
13
  // 换点与线(通道不动)——与从前一致
@@ -19,14 +19,14 @@ view.updateData(points, lines, channels)
19
19
  // 单对象写法:只换给出的那几列(没给的不动)
20
20
  view.updateData({ lines: nextLines, channels: nextChannels })
21
21
 
22
- // 接口返回的数据先按自己的字段映射成这三列(见下面「接口列名不一样」与 demo/InterfaceDemo.vue)
22
+ // 接口返回的数据先按自己的字段映射成这三列(见下面「接口列名不一样」)
23
23
  view.updateData(res.points, res.lines, res.channels)
24
24
 
25
25
  // 只想换通道声明(回线怎么分组、骨架拐点在哪):场站与回线数据一个都不动
26
- view.updateChannels(nextChannels)
26
+ view.updateData({ channels: nextChannels })
27
27
  ```
28
28
 
29
- `updateChannels` 与 `updateChannel` 的分工:后者是按 id 给**一条**通道打补丁(`updateChannel('c1', { lineIds: [...] })` —— 补丁里的 `lineIds` 是这条通道成员的**整表**,增删线路就是改它:写回声明前与 `groups` 调和,不在表里的成员从各组剔掉、空组去掉,新成员补进第一组,组剔完回「整条通道一组」);前者是**整份换**、点不出某一条。两个入口写完都会把引擎算出的最终分组(分组 id、拐点路径)写回数据副本 —— 声明里没写分组 id 时引擎按「单组用通道 id、多组 `通道id::1` / `通道id::2`…」补(走 `splitChannelGroups` 这类分组编辑接口时第一组沿用通道 id、新组从 `::2` 起),写回后 `exportData` 再回灌不会换一组新 id 把分组骨架丢掉。声明里认不出的成员 id 会报一句 `onWarning`(引擎那边是静默忽略,不问就查不出);`updateChannel` 找不到通道、没给补丁也各报一句。`updateChannel` 还有第四段 `lineIds`(单独成参数):传了就是**整表对齐** —— 与第三段的线路数组一起,表里有、数据里没有的当场建,表里有的逐条改,表里没有了的旧成员**直接从数据里删掉**(视图跟着少);不传就只改成员回线自己的字段、不动数量。第二段补丁里的 `lineIds` 是「换声明」的老写法:少了只把成员移出通道(数据留着 + 提示一句,与 `removeChannelLines` 同一口径),要少了删就用第四段。 这一份调和不止打补丁这一条路:**整份提交**的几个入口(建视图 / `updateChannels` / `updateOptions({ channels })` / `updateData({ channels })` / `importData`)逐条走同一份规则 —— 写了非空 `lineIds` 的声明以它为准、`groups` 按它收窄(`updateChannels` 不再「给什么原样照收」);内部写回(`splitChannelGroups` / `mergeChannelGroups` / `updateChannel`)也会把 `lineIds` 对齐到各组,拆 / 并 / 挪组之后把声明原样整份重提交一遍,成员一个都不会被收窄剔掉。
29
+ `updateData({ channels })` 与 `updateChannel` 的分工:后者是按 id 给**一条**通道打补丁(`updateChannel('c1', { lineIds: [...] })` —— 补丁里的 `lineIds` 是这条通道成员的**整表**,增删线路就是改它:写回声明前与 `groups` 调和,不在表里的成员从各组剔掉、空组去掉,新成员补进第一组,组剔完回「整条通道一组」);前者是**整份换**、点不出某一条。两个入口写完都会把引擎算出的最终分组(分组 id、拐点路径)写回数据副本 —— 声明里没写分组 id 时引擎按「单组用通道 id、多组 `通道id::1` / `通道id::2`…」补(走 `splitChannelGroups` 这类分组编辑接口时第一组沿用通道 id、新组从 `::2` 起),写回后 `exportData` 再回灌不会换一组新 id 把分组骨架丢掉。声明里认不出的成员 id 会报一句 `onWarning`(引擎那边是静默忽略,不问就查不出);`updateChannel` 找不到通道、没给补丁也各报一句。`updateChannel` 还有第四段 `lineIds`(单独成参数):传了就是**整表对齐** —— 与第三段的线路数组一起,表里有、数据里没有的当场建,表里有的逐条改,表里没有了的旧成员**直接从数据里删掉**(视图跟着少);不传就只改成员回线自己的字段、不动数量。第二段补丁里的 `lineIds` 是「换声明」的老写法:少了只把成员移出通道(数据留着 + 提示一句,与 `removeChannelLines` 同一口径),要少了删就用第四段。 这一份调和不止打补丁这一条路:**整份提交**的几个入口(建视图 / `updateOptions({ channels })` / `updateData({ channels })` / `importData`)逐条走同一份规则 —— 写了非空 `lineIds` 的声明以它为准、`groups` 按它收窄(整份提交不再「给什么原样照收」);内部写回(`splitChannelGroups` / `mergeChannelGroups` / `updateChannel`)也会把 `lineIds` 对齐到各组,拆 / 并 / 挪组之后把声明原样整份重提交一遍,成员一个都不会被收窄剔掉。
30
30
 
31
31
  `updateData` 与 `importData` 的分工:`updateData` 换的是数据那几列;`importData` 还认 `labelStates` /
32
32
  `view` / `filter`(整份文档回灌,见「标准数据文档(full):接收 == 导出」)。两者换完都会按同一个筛选
@@ -114,13 +114,13 @@ loading.value = false
114
114
  - 反过来的写法(先 `await` 接口、再建实例)也能用,只是首屏是「白屏 / 骨架」而不是「空场景 + 网格」;这样写时记得在组件卸载 / 路由离开时 `destroy()`,并且接口回调里对实例做一次存在性判断(窗口期内组件可能已经没了)。
115
115
  - 首屏的主线程开销不在建实例(毫秒级),而在数据到货那一次的建场景 / 重排:大屏可以先把实例摆好、`whenDataRendered` 收 loading,两件事天然并行。
116
116
 
117
- 运行中的写法见 `docs/demos/InterfaceDemo.vue`(演示页签「接口数据」):`onMounted` 里先建实例,「模拟接口(延迟 900ms)」先清空 + 挂 loading,900 ms 后回来再 `updateData` + `whenDataRendered()`。
117
+ 运行中的写法可以直接照上面两段:在 `onMounted` 里先建实例,接口回来再 `updateData` + `whenDataRendered()`;需要模拟延迟时在调用方加一个 `await new Promise(resolve => setTimeout(resolve, 900))`。
118
118
 
119
119
  ### 接口列名不一样:映射放在调用方
120
120
 
121
121
  组件只认 `points` / `lines` / `channels` 三列 —— 后端返回别的列名(比如 `station_data` / `channel_data`)
122
- 时,在调用方映射一次再喂进来,组件一个字节都不用改。`docs/demos/InterfaceDemo.vue`(演示页签「接口数据」)
123
- 就是一份完整的例子:`real.json` 在页面里映射成三列,切场景走 `updateData`、通道分批到货走 `addChannels`、
122
+ 时,在调用方映射一次再喂进来,组件一个字节都不用改。下面就是一份完整映射:
123
+ 切场景走 `updateData`、通道分批到货走 `addChannels`、
124
124
  收 loading 走 `whenDataRendered()`。
125
125
 
126
126
  ```js
@@ -209,7 +209,7 @@ if (moved.length) {
209
209
  - **哪些算「位置变过」**:拖动落地、`updatePoint` / `patchPoints` 改坐标、`movePoint`,以及撤销 / 重做退回别的坐标都算;只改名字 / 颜色这种不动坐标的改动不在里面。同一个节点改两次只有一条(按 id 去重、取最新坐标)。
210
210
  - **删掉的节点不留记录**:`removePoints` 之后 `getMovedPoints()` 里没有它(账本顺手清掉),所以「取差异 → 发接口 → 对账」这条回路不会往已经删掉的节点上发请求。
211
211
  - **新加进来的节点先记不报**:`addPoints` / `addPoint` 以加入时的坐标入账 —— 刚加不算「变过」,之后被挪才算。
212
- - **整份换数据 = 重新对账**:`updateData` / `updatePoints` / `importData` / `updateOptions` 里换 `points` 都会以新数据为基准对齐,换完读是空表。
212
+ - **整份换数据 = 重新对账**:`updateData` / `importData` / `updateOptions` 里换 `points` 都会以新数据为基准对齐,换完读是空表。
213
213
  - `clearMovedPoints()` 不传引用 = 全部对账;传一个或一批只清这些(写法与 `removePoints` 一致:id / 下标 / `{ id }` / `{ index }`,认不出来的跳过并记一条提醒);空数组是「没有目标」,什么都不做;返回实例本身,可以链式调。
214
214
  - 这本账是**只读差异**,不落历史、不发事件:`getMovedPoints()` 本身不改数据,读到的记录会一直留着,直到 `clearMovedPoints` 或整份换数据。
215
215
 
@@ -279,7 +279,8 @@ view.getChannelGroupWaypoints(added.channelId, split.ok ? split.groupId : undefi
279
279
  view.getParallelGroups()
280
280
  ```
281
281
 
282
- 三条口径:
282
+ 四条口径:
283
+ - **新增时的线路 / 通道 `path` 口径**:`addLine` / `addChannel(..., kind: 'line')` 的 `routing: 'orthogonal'` 会自动补一个先横后纵的 90° 拐点;输入里的 `path` 一律按**中间拐点**解释,独立线路落地成 `[起点, ...中间拐点, 终点]` 的完整 `path`,新建通道 / 分组只把中间拐点写进骨架。`beginAddChannel` 草稿用同一份解析,预览与落地一致。
283
284
 
284
285
  - **返回里带下标**:`addPoint` / `addPoints` / `addLines` 的 `indexes` 是追加后在数组里的位置(老数据一个都不动),后续 `updatePoint` / `updateLine` 直接拿它当 id 用;`addChannel` 给的是 `lineIndex` / `channelIndex` / `groupId`。
285
286
  - **事件与历史**:新增发 `dataChange`(`addPoints` / `addLines` / `addLine` / `addChannel` / `addChannels` / `addChannelGroups`),分组改动另发 `channelGroups`(`onChannelGroupChange`,见「通道分组」);`addPoints` / `addLines` / `addChannels` / `addChannelGroups` / `addWaypoints` 的批量写法都只记一步历史、只发一条数据变更,`options.emit: false` 只落地不通知。开着历史时每一步都可撤销。
@@ -311,7 +312,7 @@ view.updateOptions({ history: { limit: 100 } }) // 换上限(0 表示不限
311
312
  view.updateOptions({ history: false }) // 关掉,两份栈一起清
312
313
  ```
313
314
 
314
- 打开之后**每一次真的改了数据的操作都会记一条**:拖动节点、复制、合并、拐点增删、新增通道 / 线路、通道分组、删除,以及 `updateData` / `updatePoints` / `updateLines` / `updatePoint` / `updateLine` / `updateChannel` / `updateOptions` 这些接口调用。快捷键也接上了:`Ctrl+Z` 撤销、`Ctrl+Shift+Z`(再认 `Ctrl+Y`)重做,写法可以在 `shortcuts` 里改(动作名 `undo` / `redo`),没得撤销 / 重做时 `onShortcut` 的 `handled` 为 `false`。
315
+ 打开之后**每一次真的改了数据的操作都会记一条**:拖动节点、复制、合并、拐点增删、新增通道 / 线路、通道分组、删除,以及 `updateData` / `patchPoints` / `patchLines` / `updatePoint` / `updateLine` / `updateChannel` / `updateOptions` 这些接口调用。快捷键也接上了:`Ctrl+Z` 撤销、`Ctrl+Shift+Z`(再认 `Ctrl+Y`)重做,写法可以在 `shortcuts` 里改(动作名 `undo` / `redo`),没得撤销 / 重做时 `onShortcut` 的 `handled` 为 `false`。
315
316
 
316
317
  记的是**改动本身**(哪几个下标、改前是什么、改后是什么),不是整份数据的快照:拖一次节点与拖十万个节点都只按实际改动量付费,一次操作的连续过程(按下 → 拖动 → 停手)只留一条记录,撤销时回到起点的那些「空拖动」不会进历史。撤销 / 重做会走一遍完整的「换数据」流程 —— 筛选重算、引擎重同步、标签与小图重画,并按 id 重新选中(下标平移之后选中的还是原来那几个)。
317
318
 
@@ -40,7 +40,7 @@ createGisView(container, {
40
40
 
41
41
  | 字段 | 取值 | 说明 |
42
42
  | --- | --- | --- |
43
- | `action.type` | 动作名 | 按下时是**意图**(`dragPoint` 拖节点 / `dragWaypoint` 拖拐点 / `boxSelect` 框选 / `pan` 平移 / `copy` 复制 / `channelDraft` 点两次加通道 / `contextMenu` 右键 / `click` 普通左键),松开时是**刚做完的那件事**(没拖就是 `click`),点击时是**真正发生的那一件**(`select` 选中 / `clearSelection` 点空白 / `click` 没开选中时的点击);拐点是 `addWaypoint` / `removeWaypoint` / `selectWaypoint` / `dragWaypoint`,标签是 `selectLabel` / `dragLabel` / `contextMenu` / `dblClick`,选中集是 `select` / `toggleSelect` / `boxSelect` / `clearSelection`,悬停固定是 `hover` |
43
+ | `action.type` | 动作名 | 按下时是**意图**(`dragPoint` 拖节点 / `dragWaypoint` 拖拐点 / `boxSelect` 框选 / `pan` 平移 / `copy` 复制 / `channelDraft` 点两次加通道 / `decorationDraft` 动态装饰器草稿 / `contextMenu` 右键 / `click` 普通左键),松开时是**刚做完的那件事**(没拖就是 `click`),点击时是**真正发生的那一件**(`select` 选中 / `clearSelection` 点空白 / `click` 没开选中时的点击);拐点是 `addWaypoint` / `removeWaypoint` / `selectWaypoint` / `dragWaypoint`,标签是 `selectLabel` / `dragLabel` / `contextMenu` / `dblClick`,选中集是 `select` / `toggleSelect` / `boxSelect` / `clearSelection`,悬停固定是 `hover` |
44
44
  | `action.target` | `point` / `line` / `channel` / `waypoint` / `label` / `selection` / `empty` | 点在了什么上面:通道回线的 `type` 也是 `line`,但要按通道处理,所以 `target` 单独给 `channel`;点空白是 `empty`;拐点与标签各有自己的 `waypoint` / `label` |
45
45
  | `action.data` | 对象 / `null` | 按 `target` 直接取到的那份数据:节点 / 线路是数据里那个对象(与 `getData()` 同一份引用)、通道回线是通道定义、选中集是这一批 `items`、拐点是 `{ lineIndex, pathIndex, coordinate, line }`、标签是 `{ label, parent }`、空白处是 `null` |
46
46
  | `action.button` | `left` / `middle` / `right` / `none` | 鼠标键名,与载荷里的 `button` 数字一一对应;悬停没有按键,固定是 `'none'` |
@@ -119,7 +119,7 @@ createGisView(container, {
119
119
  event.preventDefault() // 自己弹菜单
120
120
  if (payload.type === 'point' && !payload.wasSelected) {
121
121
  // 右键落在没选中的节点上:先把它选上,再按「选中集」弹面板(落在已选中的节点上就保留整份多选)
122
- view.select(payload.item.id)
122
+ view.selectFeatures(payload.item.id)
123
123
  }
124
124
  openMenu({ target: payload.item, selection: payload.selection, coordinate: payload.world })
125
125
  }
@@ -232,7 +232,7 @@ onPointDrag: payload => {
232
232
  }
233
233
  ```
234
234
 
235
- 组内节点之间有连线时不会互相拉扯:连线的两端都在组里,两个端点各按自己的位移量移动。Shift 框选与 Ctrl 点击得到的选中集合完全等价,`getSelectionData().ids` 读回的结果可以再喂给 `select()`。
235
+ 组内节点之间有连线时不会互相拉扯:连线的两端都在组里,两个端点各按自己的位移量移动。Shift 框选与 Ctrl 点击得到的选中集合完全等价,`getSelectionData().ids` 读回的结果可以再喂给 `selectFeatures()`。
236
236
 
237
237
  关闭拖拽:
238
238
 
@@ -430,11 +430,11 @@ view.on('pointCopy', async payload => {
430
430
 
431
431
  ## 节点合并
432
432
 
433
- 把一个节点拖到另一个节点身上(两个节点画在屏幕上的半径之和以内,`merge.distance` 是额外的像素容差),松手时不会直接合并,而是进入**待确认**:目标节点按悬停样式亮一下、并抬到最上层,同时派发 `onPointMerge` 的 `phase: 'pending'`。确认之后两个节点的数据并成一个:**缺省保留碰撞目标**(结果留在目标节点上,拖动的来源节点从数据里消失),也可以在确认时写 `keep: 'source'` 反过来保留正在拖动的节点。取消则被拖动的节点连同跟随它的线路一起回到原位,并补发一条 `onPointDrag` 的 `end` 载荷。
433
+ 把一个节点拖到另一个节点身上,松手时不会直接合并,而是进入**待确认**:目标节点按悬停样式亮一下、并抬到最上层,同时派发 `onPointMerge` 的 `phase: 'pending'`。触发时机由 `merge.trigger` 决定:`'collision'`(缺省)在两个节点画在屏幕上的半径之和进入范围时触发;`'center'` 要求拖动的节点中心点进入目标节点的屏幕区域,更晚、更不容易误触;两种都再叠加 `merge.distance` 的像素容差。载荷里的 `trigger` 就是这一次命中的档位。确认之后两个节点的数据并成一个:**缺省保留碰撞目标**(结果留在目标节点上,拖动的来源节点从数据里消失),也可以在确认时写 `keep: 'source'` 反过来保留正在拖动的节点。取消则被拖动的节点连同跟随它的线路一起回到原位,并补发一条 `onPointDrag` 的 `end` 载荷。
434
434
 
435
435
  ### 对话框自己写
436
436
 
437
- 组件**不带任何对话框**:它只提供数据(事件载荷)与方法,确认界面自己写。`pending` 停在那里等使用方裁决 —— 在回调里直接调 `payload.confirm(options)` / `payload.cancel()`,或者把载荷存下来、用自己的弹窗按钮触发;用 `getPointMerge()` / `resolvePointMerge(true | false, options?)` / `confirmPointMerge(options?)` 也能从外面读和裁决。确认参数是 `{ keep?: 'target' | 'source', item?: 节点字段补丁 }`:`keep` 选保留碰撞目标还是拖动的来源,`item` 改写最终节点的名称 / 分区 / 颜色 / 尺寸 / 图标 / 描边等字段;位置与 id 始终取保留端。
437
+ 组件**不带任何对话框**:它只提供数据(事件载荷)与方法,确认界面自己写。`pending` 停在那里等使用方裁决 —— 在回调里直接调 `payload.confirm(options)` / `payload.cancel()`,或者把载荷存下来、用自己的弹窗按钮触发;用 `getPointMerge()` / `resolvePointMerge(true | false, options?)` 也能从外面读和裁决。确认参数是 `{ keep?: 'target' | 'source', item?: 节点字段补丁 }`:`keep` 选保留碰撞目标还是拖动的来源,`item` 改写最终节点的名称 / 分区 / 颜色 / 尺寸 / 图标 / 描边等字段;位置与 id 始终取保留端。
438
438
 
439
439
  **确认前先看影响多少条线路 / 通道、再按 id 查详情**:`pending`、`confirm` 与 `getPointMerge()` 返回的 `state` 载荷都带 `impact`(`GisViewMergeImpact | null`)。线路侧:`impact.lineCount` 是这次合并会改写或删除的线路并集(同一条线只算一次),`linesChanged` / `removedLines` 分别与落地结果里的同名字段同一口径,`lineIds` / `removedLineIds` 给出具体线路 id(没有 id 时是 lines 下标)。通道侧:`channelsChanged` / `removedChannels` / `mergedChannels` 是三个读数,`channelIds` / `channelsChangedIds` / `removedChannelIds` / `mergedChannelIds` 是对应的 id 明细;`mergedChannelIds` 是被并进保留通道、之后不再单独存在的那些通道。`pending` 阶段按缺省 `keep: 'target'` 预演;在 `confirm` 阶段按最终 `keep` 重算,所以切换保留方向之后读到的才是最终影响。
440
440
 
@@ -443,7 +443,7 @@ view.on('pointCopy', async payload => {
443
443
  ```js
444
444
  let pending = null
445
445
  const view = createGisView(container, {
446
- merge: { distance: 6 }, // 额外的碰撞容差(CSS 像素)
446
+ merge: { trigger: 'center', distance: 6 }, // 中心进入目标区域;再留 6px 额外容差
447
447
  onPointMerge: payload => {
448
448
  if (payload.phase === 'pending') {
449
449
  pending = payload // 自己的确认框:确认按钮里调 payload.confirm({ keep, item })
@@ -473,7 +473,7 @@ pending.confirm({
473
473
 
474
474
  // 从外面裁决与 payload.confirm 同一份参数
475
475
  view.resolvePointMerge(true, { keep: 'source', item: { name: '合并后的站点' } })
476
- view.confirmPointMerge({ keep: 'target', item: { size: 16 } })
476
+ view.resolvePointMerge(true, { keep: 'target', item: { size: 16 } })
477
477
  ```
478
478
 
479
479
  三种确认方式由 `merge.confirm` 决定(不写就是「什么都不做,停在 pending」):
@@ -587,8 +587,8 @@ view.mergeSelectedPoints({
587
587
 
588
588
  // 拖动合并的裁决:pending / confirm 载荷都带 source / target / item
589
589
  view.getPointMerge()?.confirm()
590
- view.confirmPointMerge() // resolvePointMerge(true) 的别名
591
- view.cancelPointMerge() // resolvePointMerge(false) 的别名:拖动的节点回原位,数据不动
590
+ view.resolvePointMerge(true) // 确认
591
+ view.resolvePointMerge(false) // 取消:拖动的节点回原位,数据不动
592
592
  ```
593
593
 
594
594
  删节点用 `view.removePoints('a')` / `view.removePoints({ index: 2 })` / 数组:绑在它上面的线路一并删掉,声明了它当端点的整条通道(含成员回线)跟着删。