gis-view-webgl2 0.1.7 → 0.1.9

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 (70) hide show
  1. package/README.md +14 -11
  2. package/dist/gis-view.css +1 -1
  3. package/dist/index.cjs +1 -1
  4. package/dist/index.d.ts +445 -241
  5. package/dist/index.js +1 -1
  6. package/docs/AI/345/257/271/350/257/235/346/261/207/346/200/273.md +65 -498
  7. package/docs/GisView.md +1 -1
  8. package/docs/GisView/345/256/236/347/216/260/345/216/237/347/220/206.md +1 -1
  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 -478
  10. package/docs/demos/BasicDemo.vue +144 -27
  11. package/docs/demos/BatchAddDemo.vue +133 -7
  12. package/docs/demos/ChannelDemo.vue +61 -0
  13. package/docs/demos/ConnectDemo.vue +164 -33
  14. package/docs/demos/CopyMergeDemo.vue +144 -42
  15. package/docs/demos/EventDemo.vue +29 -24
  16. package/docs/demos/LabelDemo.vue +5 -5
  17. package/docs/demos/api-index.js +53 -41
  18. package/docs/demos/gis-view-demo/GisViewDemoCardHeader.vue +1 -1
  19. package/docs/demos/gis-view-demo/GisViewDemoStage.vue +1 -1
  20. package/docs/demos/gis-view-demo/panels/DataPanels.vue +1 -1
  21. package/docs/demos/gis-view-demo/useGisViewDemo.js +31 -33
  22. package/docs/format/02-/350/212/202/347/202/271/344/270/216/347/272/277/350/267/257.md +1 -0
  23. package/docs/format/04-/351/200/232/351/201/223/344/270/216/346/240/207/347/255/276.md +3 -0
  24. 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 +8 -7
  25. package/docs/from0/05-/347/233/270/346/234/272/344/270/216/344/272/244/344/272/222.md +1 -1
  26. package/docs/from0/07-/351/200/232/351/201/223/345/210/206/347/273/204/344/270/216/345/244/232/345/233/236/347/272/277.md +26 -10
  27. package/docs/index.html +136 -13
  28. package/docs/internals/15-04-/351/200/220/350/275/256/350/256/260/345/275/225-/347/203/255/345/212/233/345/233/276/344/270/216/346/200/247/350/203/275.md +10 -0
  29. package/docs/manual/02-/345/235/220/346/240/207/344/270/216/346/225/260/346/215/256.md +1 -1
  30. package/docs/manual/03-/351/205/215/347/275/256/351/241/271.md +82 -14
  31. package/docs/manual/04-/344/272/213/344/273/266/344/270/216/345/233/236/350/260/203.md +23 -17
  32. package/docs/manual/05-/347/224/273/350/264/250/344/270/216/346/211/271/351/207/217/346/233/264/346/226/260.md +65 -0
  33. 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 +9 -10
  34. 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 +100 -40
  35. package/docs/manual/08-/351/200/211/344/270/255/344/270/216/346/213/220/347/202/271.md +11 -7
  36. package/docs/manual/09-/351/200/232/351/201/223/344/270/216/345/244/232/345/233/236/347/272/277.md +66 -6
  37. 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 +226 -493
  38. package/docs/manual/12-/346/240/207/347/255/276/344/270/216/350/243/205/351/245/260.md +28 -5
  39. package/docs/manual/14-/350/247/206/345/233/276/344/270/216/347/255/233/351/200/211.md +46 -14
  40. package/docs/manual/15-/345/257/274/345/207/272/344/270/216/351/233/206/346/210/220.md +5 -2
  41. package/docs/manual/16-/345/256/236/344/276/213/346/226/271/346/263/225/346/200/273/350/241/250.md +34 -29
  42. package/docs/manual/17-/345/217/202/346/225/260/351/200/237/346/237/245.md +30 -22
  43. package/docs/manual/18-/351/200/220/346/226/271/346/263/225/347/244/272/344/276/213.md +168 -81
  44. 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 +1 -1
  45. package/docs/manual/20-/346/200/247/350/203/275/344/270/216/345/244/247/346/225/260/346/215/256.md +5 -3
  46. 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 +9 -6
  47. package/docs/steps/README.md +201 -120
  48. package/docs/steps/bench-scale.html +1 -1
  49. package/docs/steps/index.html +222 -6
  50. package/docs/steps/selftest-actions.html +26 -25
  51. package/docs/steps/selftest-data.html +1 -1
  52. package/docs/steps/selftest-demos.html +290 -16
  53. package/docs/steps/selftest-docs.html +17 -6
  54. package/docs/steps/selftest-features.html +594 -54
  55. package/docs/steps/selftest-full.html +3 -3
  56. package/docs/steps/selftest-labels.html +82 -1
  57. package/docs/steps/selftest-perf.html +62 -7
  58. package/docs/steps/selftest-select.html +71 -6
  59. package/docs/steps/step-05-pick.js +4 -8
  60. package/docs/steps/step-07-channels.js +3 -5
  61. package/docs/steps/step-08-labels.js +3 -3
  62. package/docs/steps/step-10-full.js +3 -3
  63. package/docs/steps/step-12-events.js +41 -24
  64. package/docs//344/273/2160/345/210/260/345/256/214/346/225/264/347/232/204/345/256/236/347/216/260.md +1 -0
  65. package/package.json +1 -1
  66. package/docs/ai/01-/350/265/267/346/272/220/344/270/216/350/277/231/344/273/275/346/261/207/346/200/273/347/232/204/347/224/261/346/235/245.md +0 -29
  67. package/docs/ai/02-/346/214/211/345/206/205/345/256/271/345/210/206/347/261/273-/350/277/231/344/270/200/350/267/257/351/203/275/345/234/250/346/224/271/344/273/200/344/271/210.md +0 -66
  68. package/docs/ai/03-/351/207/215/350/246/201/351/227/256/347/255/224/351/200/211/357/274/210/344/270/200/357/274/211/357/274/232/351/200/211/345/236/213/351/200/232/351/201/223/344/270/216/346/240/267/345/274/217.md +0 -178
  69. package/docs/ai/04-/351/207/215/350/246/201/351/227/256/347/255/224/351/200/211/357/274/210/344/272/214/357/274/211/357/274/232/344/272/244/344/272/222/346/200/247/350/203/275/344/270/216/346/225/260/346/215/256.md +0 -140
  70. package/docs/ai/05-/351/207/215/350/246/201/351/227/256/347/255/224/351/200/211/357/274/210/344/270/211/357/274/211/357/274/232/345/256/277/344/270/273/346/227/201/346/224/257/344/270/216/346/224/266/345/217/243.md +0 -43
@@ -7,20 +7,20 @@
7
7
  | 字段 | 载荷 | 说明 |
8
8
  | --- | --- | --- |
9
9
  | `onReady` | `{ canvas, gl }` | WebGL2 上下文与缓冲区就绪 |
10
- | `onSelect` | `GisViewSelectPayload \| null` | 选中操作回调:回答「这一下选了什么」。真实单击 / Ctrl / `multiSelect` 取反 / 框选 / `selectAt()` 每次成功操作都发(清空与「取反取没了」的载荷是 `null`);`selectFeatures()` / `deselect()` / `focusOn({ select })` 等按引用接口只在选中集实际变化时发。载荷带 `items` / `box` / `originalEvent` / `mode`;单通道时顶层还有 `channelId` / `channelIndex` / `channel` / `groupId` / `groupIndex` / `group` / `groups`,多通道看 `channelContexts`,`items[]` 里的回线只带 `channelId` / `channelIndex` / `groupId` / `groupIndex` 标量归属,不重复挂 `group` / `groups` |
11
- | `onClick` | `GisViewClickPayload \| null` | 单击要素或空白处(空白处为 `null`):`type` / `item` / `index` / `screen` / `coordinate` / `button` / `selection` / `originalEvent` 之外还有 `action`(`type` 是 `select` / `toggleSelect` / `clearSelection` / `click`,`double` 说明这一下是不是双击里的第二下,`press` / `duration` / `longPress` 说明这一次按下想做什么、按了多久、算不算长按),见「指针事件」。`selectTrigger: 'dblClick'` 时第一下只发 `action.type: 'click'`,第二下才应用选中并带 `double: true` |
12
- | `onClusterClick` | `GisViewClusterClickPayload` | 点中多成员聚合圆:带 `id` / `count` / `pointIndexes` / `pointIds` / `bounds` / `radius` / `coordinate` / `screen` / `selection` / `action`(`action.type` 恒为 `clusterClick`、`action.target` 为 `cluster`)。这一条**不会同时发 `onClick`**,也不会改动选中集;聚合圆内部的原始节点不参与普通点击 |
10
+ | `onSelect` | `GisViewSelectPayload \| null` | 选中操作回调:回答「这一下选了什么」。真实单击 / Ctrl / `multiSelect` 取反 / 框选 / `selectAt()` 每次成功操作都发(清空与「取反取没了」的载荷是 `null`);`selectFeatures()` / `deselect()` / `focusOn({ select })` 等按引用接口只在选中集实际变化时发。载荷带 `items` / `box` / `originalEvent` / `mode`;单通道时顶层还有 `channelId` / `channelIndex` / `channel` / `groupId` / `groupIndex` / `group` / `groups` / `lineIndexes` / `lineIds`,多通道看 `channelContexts`。`items[]` 里的回线不挂任何通道字段,归属统一从外层映射或 `getLineChannel()` 取 |
11
+ | `onClick` | `GisViewClickPayload \| null` | 单击要素或空白处(空白处为 `null`):命中数据读 `type` / `index` / `item` / `screen` / `coordinate`,`selected` / `wasSelected` 是点完之后 / 点之前的选中态快照;按键、修饰键与指针位置读 `originalEvent`,整份选中集读数用 `view.getSelectionInfo()`(回调里就是 `payload.item` 所在视图的那一份)。另有 `action`(`type` 是 `select` / `toggleSelect` / `clearSelection` / `click`,`double` 说明这一下是不是双击里的第二下,`press` / `duration` / `longPress` 说明这一次按下想做什么、按了多久、算不算长按),见「指针事件」。`selectTrigger: 'dblClick'` 时第一下只发 `action.type: 'click'`,第二下才应用选中并带 `double: true` |
12
+ | `onClusterClick` | `GisViewClusterClickPayload` | 点中多成员聚合圆:带 `id` / `count` / `pointIndexes` / `pointIds` / `bounds` / `radius` / `coordinate` / `screen` / `originalEvent` / `action`(`action.type` 恒为 `clusterClick`、`action.target` 为 `cluster`)。这一条**不会同时发 `onClick`**,也不会改动选中集;聚合圆内部的原始节点不参与普通点击。选中集读数用 `getSelectionInfo()` |
13
13
  | `onDblClick` | `GisViewClickPayload \| null` | 双击要素或空白处(320ms / 6px 内连续两次单击):`action.type` 是 `dblClick`、`action.double` 为 `true`。普通双击在两种 `selectTrigger` 下都会于第二下派发;`dblClick` 模式下选中 / 清空 / 多选取反也在这一下应用,`click` 模式下第一下已经应用过。`click` 模式的 Ctrl / `multiSelect` 取反快捷路保持原口径,不额外发 `onClick` / `onDblClick` |
14
- | `onPointerDown` | `GisViewPointerPayload` | 左键 / 中键 / 右键按下:命中的要素、`button` / `buttons` 与光标位置;`action.type` 是这一次按下的**意图**(`dragPoint` / `dragWaypoint` / `boxSelect` / `pan` / `copy` / `channelDraft` / `contextMenu`…),`action.target` 说明点的是什么、`action.data` 直接给到那份数据,见「指针事件」 |
14
+ | `onPointerDown` | `GisViewPointerPayload` | 左键 / 中键 / 右键按下:命中的要素与光标位置在载荷顶层;`action.type` 是这一次按下的**意图**(`dragPoint` / `dragWaypoint` / `boxSelect` / `pan` / `copy` / `channelDraft` / `contextMenu`…),`action.target` 说明点的是什么。点 / 线读 `item`,通道回线读 `channel` / `channelContext`,鼠标键、修饰键与 clientX / clientY 读 `originalEvent`,见「指针事件」 |
15
15
  | `onPointerUp` | `GisViewPointerPayload` | 左键 / 中键 / 右键抬起,与 `onPointerDown` 成对:`action.type` 是**刚做完的那件事**(拖过就是 `dragPoint` / `dragWaypoint` / `boxSelect` / `pan`,没拖就是 `click`),`action.moved` 说明这一次是拖还是点,另带 `action.press`(按下时的意图)/ `duration`(按了多久)/ `longPress`(长按) |
16
16
  | `onContextMenu` | `GisViewPointerPayload` | 每一次右键:点、线、通道、空白都只发这一条(要素信息在载荷里);`action.type` 固定是 `contextMenu`、`action.target` 说明点的是点 / 线 / 通道 / 空白。命中通道回线时,同一载荷另带 `channelContext`(几组 / 当前哪组 / 可用交互),不再有单独的通道右键回调。要自己弹菜单就在回调里渲染。**右键回调缺省关**(`contextMenu` / `interactive` 都没写时组件不接右键),写 `interactive: true` / `contextMenu: true` 或 `features: 'view'` 才发;接住右键时系统菜单默认已被收掉(`preventContextMenu` 缺省 `true`),想看系统菜单写 `preventContextMenu: false` |
17
17
  | `onCascadeHighlight` | `GisViewCascadeHighlightInfo \| null` | 点击级联高亮变了:载荷带来源 `origin`(节点 / 线路 / 通道回线)、范围 `scope` 与亮着的 `points` / `lines` / `pointIndexes` / `lineIndexes`,与 `getCascadeHighlight()` 同一份;点空白或关掉开关时是 `null`。这条高亮不改选中集,事件总线名为 `cascadeHighlight` |
18
- | `onHover` | `GisViewHoverPayload \| null` | 悬停要素变化(空白处 / 移出画布是 `null`):与拾取结果同一份读数(`type` / `index` / `item` + 通道字段,另有光标位置 `x` / `y` / `world` / `clientX` / `clientY`、选中集 `selection` 与 `lngLat`)+ `action`(`type` 恒为 `hover`、`target` 说明停在什么上面、`button` 是 `none`、`modifiers` 是当下的修饰键);程序化悬停 `hoverAt()` 也走同一条 |
18
+ | `onHover` | `GisViewHoverPayload \| null` | 悬停要素变化(空白处 / 移出画布是 `null`):与拾取结果同一份读数(`type` / `index` / `item` + 通道字段,另有光标位置 `x` / `y` / `world` 与 `lngLat`)+ `action`(`type` 恒为 `hover`、`target` 说明停在什么上面);指针正好停在最近一次指针事件上时 `originalEvent` 是那一次事件,按键、修饰键与 clientX / clientY 从它读。选中集总读数用 `getSelectionInfo()`;程序化悬停 `hoverAt()` 也走同一条 |
19
19
  | `onFilter` | `GisViewFilterResult` | 筛选完成(含 Worker 异步返回):隐藏的点 / 线下标、剩余可见数量、是否用了 Worker 与计算耗时。`filter.mode: 'remove'` 时删除完成后只发最终一次,`hiddenPoints` / `hiddenLines` 为空 |
20
20
  | `onCursor` | `[number, number] \| null` | 光标世界坐标,移出画布时为 `null` |
21
21
  | `onPointer` | `GisViewPointerState` | 光标每次移动(含移出画布)都发:`{ inside, screen, world, lngLat }`,屏幕坐标是画布 CSS 像素、`lngLat` 要有 GeoJSON 背景才有;`getPointer()` 随时能读同一份,移出时 `inside: false` |
22
22
  | `onPointDrag` | `GisViewPointDragPayload` | 拖拽点:`phase` 为 `start` / `drag` / `end`,载荷带最新坐标、本次移动的全部节点 `points` 与跟随移动的线路 `lines` |
23
- | `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()`,见「节点复制」 |
23
+ | `onPointCopy` | `GisViewPointCopyPayload \| GisViewBatchCopyPayload` | 复制节点:`phase` 为 `start` / `move` / `commit` / `end` / `cancel`(复制到剪贴板另有 `clipboard`,批量复制 / 整组粘贴是 `batch`),`commit` 阶段可以 `payload.cancel()` 取消、`payload.update()` 改数据;落点与最新节点都读 `payload.item`(批量看 `items[0]`),不再另挂 `point` / `coordinate`。`clipboard` 载荷带整组 `sources` / `items` / `lines` / `channels` / `count` / `anchor`,`batch` 载荷另带 `indexes` / `lineSources` / `channelSources` / `revert()`,见「节点复制」 |
24
24
  | `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` 说明谁没并进去),见「节点合并」 |
25
25
  | `onRemove` | `GisViewRemovePayload` | 删除请求(Delete 键 / `requestRemove()`):`pending` 时给一份载荷说明要删什么、连带什么、能按哪些范围删(`points` / `lines` / `waypoints` / `groups` / `channels` / `actions` / `counts`),确认之后发 `phase: 'remove'`(`result` 是结果)、取消发 `phase: 'cancel'`;组件不弹任何界面,弹不弹、怎么弹都由使用方决定(在回调里调 `payload.confirm(scope)` / `payload.cancel()`,或存下来自己接界面),见「删除(remove)」 |
26
26
  | `onWaypointChange` | `GisViewWaypointPayload` | 拐点新增 / 选中 / 删除与拖动,`phase` 为 `add` / `select` / `remove` 或拖动时的 `start` / `move` / `end`,载荷带最新线路数据与所属集合的 `group_id`;通道内的回线共用骨架,载荷是**被操作的那条回线**的推导结果。同步后端只接改变数据的 `add` / `remove` / `end`,并用 `getChannelGroupWaypoints().path` 提交整份骨架,见「通道与多回线」 |
@@ -30,10 +30,11 @@
30
30
  | `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,见「通道分组」 |
31
31
  | `onLabelDrag` | `GisViewLabelDragPayload` | 标签被拖走(`draggable`):`phase` 为 `start` / `move` / `end`,载荷带 `kind`(`point` / `line`)、`index` / `id` / `item`、当前偏移 `offset`、起手时的 `startOffset` 与本次位移 `delta`(CSS 像素),见「标签的拖动与编辑」 |
32
32
  | `onLabelClick` | `GisViewLabelClickPayload` | 点了一下标签(`editable`,位移小于 3 px 才算点选):载荷带 `kind` / `index` / `id` / `item`、当前 `offset` 与这一条的状态读数 `state`,使用方按它选中这一条 |
33
- | `onLabelContextMenu` | `GisViewLabelPointerPayload` | 在标签上按右键(`draggable` / `editable` 任开一个):载荷与 `onLabelClick` 同一份读数,另带 `clientX` / `clientY`(菜单按它定位)与原始 `contextmenu` 事件;系统菜单按 `preventContextMenu` 收(缺省收),要弹自己的菜单就接这一条 |
33
+ | `onLabelContextMenu` | `GisViewLabelPointerPayload` | 在标签上按右键(`draggable` / `editable` 任开一个):载荷与 `onLabelClick` 同一份读数,菜单定位与按键读 `payload.originalEvent.clientX` / `clientY`;系统菜单按 `preventContextMenu` 收(缺省收),要弹自己的菜单就接这一条 |
34
34
  | `onLabelDblClick` | `GisViewLabelPointerPayload` | 双击标签(开关同上):载荷与 `onLabelContextMenu` 一致(原始事件是 `dblclick`),用它开自己的编辑框 |
35
35
  | `onLabelChange` | `GisViewLabelChangePayload` | 标签状态变了:`action` 为 `update`(`updateLabel`)/ `reset`(`resetLabel`)/ `resetAll`(`resetLabels`)/ `add`(`addLabel`)/ `remove`(`removeLabel`)/ `restore`(`setLabelStates`),批量的三条各发 `addAll` / `updateAll` / `removeAll`;载荷带 `kind` / `index` / `id` 与 `patch` / `state` / `removed`,批量那三条另带 `count` 与 `added` / `updated` / `items` / `skipped`;面板按它回显 |
36
36
  | `onCameraChange` | `GisViewCamera` | 平移或缩放后触发 |
37
+ | `onIdle` | `GisViewIdlePayload` | 用户操作空闲达到 `idleTimeout` 时回调一次:`idleTime` 是距创建或上一次指针 / 滚轮 / 键盘操作的毫秒数,`timeout` 是这次生效的阈值。每个空闲段只触发一次,下一次用户操作后重新计时;程序化 API 调用不重置计时。事件总线名为 `idle`,见「14 视图与筛选」的「比例读写、画布事件与空闲检测」 |
37
38
  | `onViewport` | `GisViewViewport` | 视口尺寸 / 显示比例变化(画布按新尺寸重铺之后才发):`{ cssWidth, cssHeight, pixelRatio, displayScale }`,自建面板与小图按它跟着调整 |
38
39
  | `onStats` | `GisViewEngineStats` | 渲染统计(点数、线数、线路批次真正铺的段数 `lineInstances`、符号数、绘制次数、`fps` / `idle` / 帧耗时、拾取耗时 `pickMs`、密度场读数 `heatDensity`,以及这一帧的光栅与线段路径 `antialias` / `software` / `thinLines`),按 `statsInterval` 节流(默认 250ms 一次)。静止画面按需渲染,这时 `idle` 为 `true`、`fps` 为 `0`,`frameMs` 是最近一帧的耗时;首帧一定会报一次(面板打开就有读数,不会一直空着) |
39
40
  | `onDataChange` | `GisViewDataChangePayload` | 数据变更的统一出口:调用接口改数据、拖拽 / 复制 / 合并落地、拐点增删、通道新增 / 移除 / 分组都会发,载荷带动作 `type`、数据修订号 `dataVersion`、最新数据与条数,见「数据变更与其它事件」 |
@@ -108,19 +109,24 @@ const view = createGisView('#map', {
108
109
  | `selectTrigger: 'dblClick'` 的第二下 | `onClick → onSelect → onSelectChange`(有变化时)`→ onDblClick` |
109
110
 
110
111
  `onSelect` 与 `onSelectChange` 带同一份通道上下文:选中集只涉及**一条通道**时,载荷顶层平铺
111
- `channelId` / `channelIndex` / `channel` / `groupId` / `groupIndex` / `group` / `groups`;`group` 是当前组
112
- (真实单击 / `selectAt` 是命中的那一组,框选与按引用接口是选中集里第一条通道回线所在的组),`groups`
113
- 是整条通道的全部分组。选中集涉及**多条通道**时顶层不再摊平,改看 `channelContexts`(每项带这组字段与
114
- 本次选中的 `lineIndexes` / `lineIds`)。单通道不会再额外造一份 `channelContexts`。两个事件共享同一批
115
- `items` 与分组数组引用,不会深拷贝;`items[]` 里每条回线只保留标量归属字段,需要分组读数从顶层
116
- 或 `channelContexts` 查,不再给每条回线重复挂 `group` / `groups`。纯节点或空选中没有这些通道字段。
112
+ `channelId` / `channelIndex` / `channel` / `groupId` / `groupIndex` / `group` / `groups` 与本次选中的
113
+ `lineIndexes` / `lineIds`;`group` 是当前组(真实单击 / `selectAt` 是命中的那一组,框选与按引用接口是
114
+ 选中集里第一条通道回线所在的组),`groups` 是整条通道的全部分组。选中集涉及**多条通道**时顶层不再摊平,
115
+ 改看 `channelContexts`(每项带这组字段与本次选中的 `lineIndexes` / `lineIds`)。单通道不会再额外造一份
116
+ `channelContexts`。两个事件共享同一批 `items`、分组对象与数组引用,不会深拷贝。
117
+
118
+ `items[]` 里的通道回线**不再挂任何通道字段**(`channelId` / `channelIndex` / `channel` / `groupId` /
119
+ `groupIndex` / `group` / `groups` / `lineIndexes` / `lineIds`)。要用 `items` 反查归属,按选中的线路下标
120
+ 查外层的 `lineIndexes` / `lineIds`,再对应顶层上下文或 `channelContexts`;只问一条线路时也可以直接调
121
+ `getLineChannel(index)`。`groups[].lineIds` 是整组成员,外层 `lineIndexes` / `lineIds` 是本次选中子集,
122
+ 两者语义不同。纯节点或空选中没有这些通道字段。
117
123
 
118
124
  `cause` 取 `click`(指针点击)/ `boxSelect`(框选)/ `keyboard`(Esc 清空)/ `api`(接口调用)。
119
125
 
120
126
  `action` 是更细的一份判读(与指针事件同一套写法):`action.type` 是 `select`(点中一个或接口选中)/
121
127
  `toggleSelect`(Ctrl 点击取反,取反取没了也是它)/ `boxSelect`(框选,没框到东西也是它)/
122
- `clearSelection`(点空白、Esc 或接口清空),`action.target` 是 `selection` / `empty`,`action.data` 就是
123
- 这一批 `items`,`action.modifiers` 是这一次的修饰键。单击触发模式下,Ctrl 取反与框选这两条路**不经过 `onClick`**;
128
+ `clearSelection`(点空白、Esc 或接口清空),`action.target` 是 `selection` / `empty`;这一批数据直接读载荷的
129
+ `items`,修饰键读 `originalEvent`。单击触发模式下,Ctrl 取反与框选这两条路**不经过 `onClick`**;
124
130
  点空白仍会发 `onClick`(载荷为 `null`),顺序同样是 `onClick → onSelect → onSelectChange(有变化时)`。`selectTrigger: 'dblClick'`
125
131
  时第一下仍会发 `onClick`,第二下应用选中 / 取反 / 清空后按 `onClick → onSelect → onSelectChange(有变化时)→ onDblClick` 派发。
126
132
  要按操作分支的面板认这一个字段:
@@ -184,12 +190,12 @@ view.off('*') // 不传 handler = 摘掉这个事件的全部订阅,返回摘
184
190
  | 约定 | 说明 |
185
191
  | --- | --- |
186
192
  | 事件名与回调一一对应 | `dataChange` 就是 `onDataChange`、`selectChange` 就是 `onSelectChange`,载荷完全同一份;`GisViewEventMap` 是事件名到载荷的类型表,`EVENT_NAMES` 是运行时的名字数组 |
187
- | 要 DOM 事件的三个 | `pointerDown` / `pointerUp` / `contextMenu` 的载荷是 `{ payload, event }`(与回调的两个参数一一对应),其余事件的载荷与回调相同 |
193
+ | 指针类事件只有一个参数 | `pointerDown` / `pointerUp` / `contextMenu` 的回调收一份载荷,事件总线订阅时也是同一份直接载荷;原始 DOM 事件读 `payload.originalEvent`,不再额外包 `{ payload, event }` |
188
194
  | 回调抛错不扩散 | 订阅者抛错只走 `onError`:不打断其它订阅者,也不影响组件自己的流程 |
189
195
  | 高频事件不白算 | 组件内部按「有没有人订阅」短路(`count(name) \|\| count('*')`):没人听的时候不构造载荷,`pointer` / `hover` / `render` 这些每帧级别的事件也可以直接订阅 |
190
196
  | 订阅时机 | 创建时的 `ready` 与首次 `dataChange` 发生在 `createGisView` 返回之前,这两条要在 options 里写回调(`onReady` 等) |
191
197
 
192
- 全部事件名(与 `EVENT_NAMES` 一致):`ready`、`error`、`warning`、`viewport`、`cameraChange`、`cursor`、`hover`、`pointer`、`pointerDown`、`pointerUp`、`contextMenu`、`click`、`clusterClick`、`dblClick`、`labelClick`、`labelDrag`、`labelChange`、`labelContextMenu`、`labelDblClick`、`select`、`selectChange`、`cascadeHighlight`、`pointDrag`、`pointCopy`、`pointMerge`、`remove`、`waypointChange`、`channelDraft`、`channelDraftClick`、`decorationDraft`、`channelGroupChange`、`dataChange`、`dataRendered`、`filter`、`history`、`featureChange`、`qualityChange`、`optionChange`、`shortcut`、`stats`、`render`、`destroy`,加上 `'*'`。
198
+ 全部事件名(与 `EVENT_NAMES` 一致):`ready`、`error`、`warning`、`viewport`、`cameraChange`、`idle`、`cursor`、`hover`、`pointer`、`pointerDown`、`pointerUp`、`contextMenu`、`click`、`clusterClick`、`dblClick`、`labelClick`、`labelDrag`、`labelChange`、`labelContextMenu`、`labelDblClick`、`select`、`selectChange`、`cascadeHighlight`、`pointDrag`、`pointCopy`、`pointMerge`、`remove`、`waypointChange`、`channelDraft`、`channelDraftClick`、`decorationDraft`、`channelGroupChange`、`dataChange`、`dataRendered`、`filter`、`history`、`featureChange`、`qualityChange`、`optionChange`、`shortcut`、`stats`、`render`、`destroy`,加上 `'*'`。
193
199
 
194
200
  ## 功能开关
195
201
 
@@ -65,6 +65,71 @@ view.batch(() => {
65
65
 
66
66
  口径:**回调里的调用照常立刻生效**(数据、渲染都是即时的,不是事务、也不延后),收尾合并成一条 `onDataChange` 与一步历史;`changes` 按调用顺序列出每一步,要知道具体改了哪些下标就从它读。可以嵌套,只有最外层收尾;回调抛错照常往外抛(已经改过的数据不负责回滚),但收尾与刷新一定会执行。
67
67
 
68
+ ### 批量增删改场站 / 线路 / 通道 / 分组
69
+
70
+ 场站与线路本身就有批量入口:`addPoints` / `addLines`、`patchPoints(entries, patch?)` / `patchLines(entries, patch?)`、`removePoints(refs)` / `removeLines(ids)`。通道目前是单条 `updateChannel` / `removeChannel`,分组是单条 `splitChannelGroups` / `removeChannelGroup`(`addChannelGroups` 可一次加多组);多条通道一起改时用 `batch` 包住循环,仍然只记一步历史、只发一条 `batch` 数据变更。
71
+
72
+ ```js
73
+ // 批量修改:场站、线路、通道一起改
74
+ view.batch(() => {
75
+ view.patchPoints([
76
+ { id: 'station-a', name: 'A 站(改)' },
77
+ { id: 'station-b', zone_name: '新分区' }
78
+ ])
79
+ view.patchLines([{ id: 'line-1' }, { id: 'line-2' }], { color: '#2f6fd0', width: 2.2 })
80
+ for (const channelId of ['corridor-1', 'corridor-2']) {
81
+ view.updateChannel(channelId, { width: 2.4 })
82
+ }
83
+ }, { label: '批量修改场站 / 线路 / 通道' })
84
+
85
+ // 批量删除:通道先删,再删场站与线路;删场站会级联线路 / 通道,后两步按删除后的 id 重新过滤
86
+ view.batch(() => {
87
+ for (const channelId of ['corridor-1', 'corridor-2']) {
88
+ view.removeChannel(channelId)
89
+ }
90
+ view.removePoints(['station-a', 'station-b'])
91
+ const alive = new Set(view.getData().lines.map(line => String(line.id)))
92
+ const remaining = ['line-1', 'line-2'].filter(id => alive.has(String(id)))
93
+ if (remaining.length) {
94
+ view.removeLines(remaining)
95
+ }
96
+ }, { label: '批量删除场站 / 线路 / 通道' })
97
+ ```
98
+
99
+ 分组也可以按通道逐条批处理:
100
+
101
+ ```js
102
+ // 多条通道一次重排分组;每条通道只调一次整份 groups
103
+ view.batch(() => {
104
+ for (const channel of view.getOptions().channels ?? []) {
105
+ const groups = view.getChannelGroups(channel.id)
106
+ const lineIds = groups.flatMap(group => group.lineIds)
107
+ if (lineIds.length >= 2) {
108
+ const cut = Math.ceil(lineIds.length / 2)
109
+ view.splitChannelGroups(channel.id, [lineIds.slice(0, cut), lineIds.slice(cut)])
110
+ }
111
+ }
112
+ }, { label: '批量重排通道分组' })
113
+
114
+ // 删除多条通道的末组:回线并回相邻组,数据不丢
115
+ view.batch(() => {
116
+ for (const channel of view.getOptions().channels ?? []) {
117
+ const groups = view.getChannelGroups(channel.id)
118
+ if (groups.length > 1) {
119
+ view.removeChannelGroup(channel.id, groups[groups.length - 1].id)
120
+ }
121
+ }
122
+ }, { label: '批量删除通道分组' })
123
+ ```
124
+
125
+ 要点:
126
+
127
+ - **一步历史**:外层 `batch` 收尾只留下一条 `{ type: 'batch', changes: [...] }`;`changes` 按实际调用顺序列出每一条 `updatePoints` / `updateLines` / `updateChannel` / `removeChannel` / `splitChannelGroups` 等,撤销 / 重做整批回放。
128
+ - **添加也能配合**:`addPoints` / `addLines` / `addChannels` 本身一次可加多条;要和其它类型混在一个编辑动作里时同样放进 `batch`。
129
+ - **删场站会级联**:`removePoints` 会连带删除绑定线路与以它为端点的通道。批内后续若还要按 id 删线路,先重新读 `getData()` 过滤仍存在的 id(示例里的 `alive`),不要盲删已随场站消失的条目。
130
+ - **通道分组**:`splitChannelGroups` 一次换整份 `groups`,`addChannelGroups` 一次加多组,`removeChannelGroup` 删一组并把回线并回相邻组;要摘回线但保留数据用 `removeChannelLines`。
131
+ - **结果读数在回调外取**:`batch` 返回回调的返回值;各方法自己的 `count` / `indexes` / `ok` 可在回调里先存到变量,收尾后再展示或提交后端。
132
+
68
133
  收尾这一次刷新也是合并过的:**筛选重算一遍**(不是每次改动一遍)、标签整层重排一次、提示框与鹰眼图各补一次,`onFilter` 跟着只发一条。前面那条路上最贵的是筛选:开着筛选时每改一个要素都要重跑一遍判定,改五百个节点就是五百遍。现在筛选的字段投影带缓存(`filter.js` 的 `createFilterProjectionCache`),批量里改过的下标只补那几条、收尾统一算一次。
69
134
 
70
135
  实测(20000 点 / 20000 线,`cascade: 'binding'` 的筛选开着,`filterWorker: false`,基准页 `docs/steps/bench-filter.html` 在改造前后各跑一遍):同样改 500 个节点(两边都包在 `batch()` 里),改造前 4687 ~ 6382 ms,现在 152 ms —— 改造前每改一个节点都要重跑一遍筛选判定,节点又常绑着被筛掉的线(塞进补丁槽位必然失败,于是退化成整份重排);不开筛选时同一批量是 145 ms → 142 ms,筛选开着时的批量已经回到不筛选时的量级。连换 10 次筛选条件从 84 ms 降到 57 ms,默认全字段 `search` 从 11 ms 降到 3 ms。
@@ -44,7 +44,7 @@ view.updateData({ channels: nextChannels })
44
44
  view.addPoint({ id: 's-1', x: 116.4, y: 39.9, name: '甲站' })
45
45
  view.addPoints(stations) // 返回 { ok, count, indexes, items }
46
46
 
47
- // 通道(新签名:通道信息 + 线路数组 line_data,见「新增通道」;旧写法 { from, to, circuits } 照样认)
47
+ // 通道(通道信息 + 线路数组 lineData,见「新增通道」)
48
48
  view.addChannel({ from: 's-1', to: 's-2', name: '甲通道' }, [{ id: 'c-1' }, { id: 'c-2' }])
49
49
  view.addChannels(channelDeclarations) // 批量版:逐条落地,只重排一次、只记一步历史、只发一条 addChannels
50
50
  ```
@@ -52,7 +52,7 @@ view.addChannels(channelDeclarations) // 批量版:逐条落地,只
52
52
  两条新增路线的分工:`addPoint` / `addPoints` / `addLines` 追加的是「现成的数据对象」;
53
53
  `addChannel` / `addChannels` / `addLine` 是按两端节点新建(通道声明一起改)。`addChannels` 的返回里
54
54
  `results` 与传入顺序一一对应(失败的条目也在里面,按各自的 `reason` 读),`lineIds` / `channelIds`
55
- 只列成功那几条;批量落地后新回线整批选中,与单条 `addChannel` 的手感一致。十万级数据下批量新增只付
55
+ 只列成功那几条;新增类方法缺省都不改选中集,需要选中时显式传 `options.select: true`。十万级数据下批量新增只付
56
56
  一次场景重排,比逐条 `addChannel` 少几十上百次整份重建。新增类方法的完整清单(节点 / 线路 / 通道 / **分组** / **拐点**)与返回口径见「按方法新增要素」。
57
57
 
58
58
  补点 / 补线的代价与「场景铺到哪一步」无关:发散渲染还没铺完时又来一批(「刚删完紧接着补」这种最常见的
@@ -321,12 +321,11 @@ const geometryOnly = view.getChangedLines({ reasons: ['path'] })
321
321
  | --- | --- | --- | --- |
322
322
  | 节点(一条 / 一批) | `addPoint(item, options?)` / `addPoints(items, options?)` | 与数据里的 `points[]` 同一份字段(`id` / `x` / `y` / 样式 / 业务字段) | 单条是 `{ ok, count, indexes, items, index, item }`、批量去掉 `index` / `item`;追加进 `points`,走引擎的增量追加(见「动态换数据与加载完成」) |
323
323
  | 线路(现成数据,一条 / 一批) | `addLines(items, options?)` | 与数据里的 `lines[]` 同一份字段(`id` / `from` / `to` / `path`…),**不挂通道** | `{ ok, count, indexes, items }`;追加进 `lines` |
324
- | 独立线路(按两端节点新建) | `addLine(input, lineData?)` | `from` / `to` 必填,`circuits` 一次几回,`lineProps` / `lineId` / `name`…;第二段与 `addChannel` 的线路数组同一份写法(每项可以只写一个 id:裸字符串 / 数字按 `{ id }` 收) | 与 `addChannel` 同一份结果(`kind: 'line'`),落地后新回线自动选中 |
325
- | 通道(新签名,只新建) | `addChannel(spec, lineData?, group?)` | 第一段 `{ from, to, name?, id?, …通道字段 }`;第二段线路数组 line_data(一条或一批,字符串 / 数字按 id 认,对象浅拷)—— **按每项 id 建 `lineIds`**;第三段可选分组信息 `{ id?, lineIds?, path? }`(单个 / 一组一个);两个节点之间已有通道时整条失败(**第二段 / 第三段显式给了**才算新签名,只写 `{ from, to }` 的照旧按方案表分流),见「新增通道」 | 与下面旧写法同一份结果(`channelLineIds` 是落地后通道的完整成员表);通道声明与回线一起落地,自动选中 |
326
- | 通道(旧写法:按方案表) | `addChannel(input)` | `from` / `to` 必填;`circuits`、`resolution`(`'newChannel'` / `{ type: 'newGroup' }` / `{ type: 'joinGroup', groupId }`)或顶层简写 `channelId` / `groupId` / `groupIndex`(并进已有通道,见「新增通道」)、`channelProps` / `lineProps` / `linePropsByMember` / `name` / `path` | `{ ok, reason?, plan, resolution, kind, circuits, line, lineId, lineIds, lines, lineIndex, channelId, groupId, channelLineIds, channelIndex }`(`channelLineIds` 是落地后通道的完整成员表 —— 并进已有通道时就是更新过的 `lineIds`);通道声明与回线一起落地,自动选中 |
327
- | 通道(已有通道:新加一组 / 并进某一组) | `addChannelGroupLines(channelId, lineData, groupInfo?)` / `joinChannelGroupLines(channelId, groupId, lineData)` | 第二段都是线路数组 line_data(按每项 id 建回线);新加一组可用 `groupInfo` 给组 id 与骨架,并进某一组用 `groupId`(认分组 id 也认序号,从 0 起,不传就挑第一个还能并的) | 与 `addChannel` 同一份结果;`channelLineIds` 是更新后的完整成员表 |
328
- | 通道(一批) | `addChannels(items, options?)` | 每一项与 `addChannel` 同一套写法 | `{ ok, count, results, lineIds, channelIds, items }`:`results` 与传入顺序一一对应,失败的在各自 `reason` 里;只重排一次、只记一步历史 |
329
- | 通道(已有通道:一次加多组) | `addChannelGroups(channelId, groups, options?)` | `groups` 每项 `{ id?, path?, lineData \| lines \| lineItems }`,线路数据与 `addChannel` 第二段同一份写法 | `{ ok, count, results, lineIds, groupIds, groups }`:逐组落地但只记一步历史、只发一条 `addChannelGroups` 数据变更;`options.emit: false` 只落地不通知 |
324
+ | 独立线路(按两端节点新建) | `addLine(spec, lineData?, options?)` | `from` / `to` 必填;`spec` 可写 `name?` / `id?` / `lineProps?` / `path?` / `routing?` / `lineData?`,第二段 `lineData` 一条或一批(每项可以只写一个 id:裸字符串 / 数字按 `{ id }` 收);`options?: { emit?, select? }` | 与 `addChannel` 同一份结果结构(`kind: 'line'`);缺省不改变选中集,`select: true` 才选中新回线 |
325
+ | 通道(只新建) | `addChannel(spec, lineData?, group?, options?)` | 第一段 `{ from, to, name?, id?, channelProps?, path?, routing?, lineData?, group? }`;第二段线路数组 lineData(一条或一批)—— **按每项 id 建 `lineIds`**;第三段可选分组信息 `{ id?, lineIds?, path? }`;`options?: { emit?, select? }`。两个节点之间已有通道时整条失败,见「新增通道」 | `{ ok, reason?, plan, resolution, kind, circuits, line, lineId, lineIds, lines, lineIndex, channelId, groupId, channelLineIds, channelIndex }`;缺省不改变选中集,`select: true` 才选中新回线 |
326
+ | 通道(已有通道:新加一组 / 并进某一组) | `addChannelGroupLines(channelId, lineData?, groupInfo?, options?)` / `joinChannelGroupLines(channelId, groupId?, lineData?, options?)` | 第二段都是线路数组 lineData(按每项 id 建回线);新加一组可用 `groupInfo` 给组 id 与骨架,并进某一组用 `groupId`(认分组 id 也认序号,从 0 起,不传就挑第一个还能并的);`options?: { emit?, select? }` | 与 `addChannel` 同一份结果;`channelLineIds` 是更新后的完整成员表;缺省不选中,`select: true` 才选中新回线 |
327
+ | 通道(一批) | `addChannels(items, options?)` | 每一项与 `addChannel` 第一段同一套写法,可在项内写 `lineData` / `group`;`options?: { emit?, select? }` | `{ ok, count, results, lineIds, channelIds, items }`:`results` 与传入顺序一一对应,失败的在各自 `reason` 里;只重排一次、只记一步历史;缺省不选中,`select: true` 才选中全部成功的新回线 |
328
+ | 通道(已有通道:一次加多组) | `addChannelGroups(channelId, groups, options?)` | `groups` 每项 `{ id?, groupId?, path?, lineData? \| lines? }`,线路数据与 `addChannel` 第二段同一份写法;`lineItems` 已移除;`options?: { emit?, label?, select? }` | `{ ok, count, results, lineIds, groupIds, groups }`:逐组落地但只记一步历史、只发一条 `addChannelGroups` 数据变更;缺省不选中,`select: true` 才选中新回线 |
330
329
  | 分组(把回线拆成新组) | `addChannelGroup(channelId, lineIds, options?)` | 要拆出去的回线 `lineIds`;`options.path` 给新组骨架(缺省沿用来源组、`path: []` 要一条直连);`options.id` 指定组 id,撞上这条通道已有分组时拒绝(不会写出两个同名分组) | `{ ok, reason, channelId, lineIds, groupId, groupIndex, groups, skipped }`;到组数 / 回数上限时 `ok: false` + `reason`,显式 `id` 重名同样 `ok: false` + `reason` |
331
330
  | 分组(整份重拆 / 合并 / 单条改派) | `splitChannelGroups(channelId, [{ id, lineIds, path? }…])` / `mergeChannelGroups(channelId, groupIds, targetGroupId)` / `moveChannelLine(channelId, lineId, { type: 'newGroup' } \| { type: 'joinGroup', groupId })` | 前两个整份换分组声明(第一个组沿用当前拐点);`moveChannelLine` 挪一条回线,也接受 `'newGroup'` 或直接给分组 id | 都把最终声明写回数据副本、记一条「通道分组」历史;`moveChannelLine` 返回 `{ ok, channelId, lineId, groupId, groupIndex, groups }` |
332
331
  | 分组(删一个:把一组并进相邻组) | `removeChannelGroup(channelId, groupId, options?)` | `channelId` / `groupId` 目标通道与要删的组;`options.targetGroupId` 指名并到哪一组(缺省前一组,第一组并后一组) | `{ ok, reason, channelId, groupId, targetGroupId, lineIds, groups }`;骨架 / 拐点沿用目标组,并完只剩一组时声明回到「整条通道一组」;单组通道 `ok: false`(删整条用 `removeChannel`) |
@@ -352,7 +351,7 @@ const added = view.addChannel({ from: 's-1', to: 's-2', path: [[116.7, 40.0]] },
352
351
  console.log(added.channelId, added.lineIds, added.groupId)
353
352
  // 多条通道一次建:每项与 addChannel 同一套写法,只重排一次、只记一步历史
354
353
  const many = view.addChannels([
355
- { from: 's-2', to: 's-3', lineItems: [{ id: 'line-c' }, { id: 'line-d' }] },
354
+ { from: 's-2', to: 's-3', lineData: [{ id: 'line-c' }, { id: 'line-d' }] },
356
355
  { from: 's-3', to: 's-4', name: '三号通道', lineData: [{ id: 'line-e' }] }
357
356
  ])
358
357
 
@@ -380,7 +379,7 @@ view.getParallelGroups()
380
379
  ```
381
380
 
382
381
  四条口径:
383
- - **新增时的线路 / 通道 `path` 口径**:`addLine` / `addChannel(..., kind: 'line')` 的 `routing: 'orthogonal'` 会自动补一个先横后纵的 90° 拐点;输入里的 `path` 一律按**中间拐点**解释,独立线路落地成 `[起点, ...中间拐点, 终点]` 的完整 `path`,新建通道 / 分组只把中间拐点写进骨架。`beginAddChannel` 草稿用同一份解析,预览与落地一致。
382
+ - **新增时的线路 / 通道 `path` 口径**:`addLine` / `addChannel` 的 `routing: 'orthogonal'` 会自动补一个先横后纵的 90° 拐点;输入里的 `path` 一律按**中间拐点**解释,独立线路落地成 `[起点, ...中间拐点, 终点]` 的完整 `path`,新建通道 / 分组只把中间拐点写进骨架。`beginAddChannel` / `beginAddLine` 草稿用同一份解析,预览与落地一致。
384
383
 
385
384
  - **返回里带下标**:`addPoint` / `addPoints` / `addLines` 的 `indexes` 是追加后在数组里的位置(老数据一个都不动),后续 `updatePoint` / `updateLine` 直接拿它当 id 用;`addChannel` 给的是 `lineIndex` / `channelIndex` / `groupId`。
386
385
  - **事件与历史**:新增发 `dataChange`(`addPoints` / `addLines` / `addLine` / `addChannel` / `addChannels` / `addChannelGroups`),分组改动另发 `channelGroups`(`onChannelGroupChange`,见「通道分组」);`addPoints` / `addLines` / `addChannels` / `addChannelGroups` / `addWaypoints` 的批量写法都只记一步历史、只发一条数据变更,`options.emit: false` 只落地不通知。开着历史时每一步都可撤销。
@@ -69,21 +69,41 @@ view.updateOptions({ cascadeHighlight: false }) // 关掉并收掉当前高亮
69
69
 
70
70
  ### action:一次操作的判读
71
71
 
72
- 指针事件、拐点、标签与选中集事件都带一份 `action`,回答三个问题:**这是什么操作**(`action.type`)、**点在了什么上面**(`action.target`)、**能拿到什么数据**(`action.data`):
72
+ 指针事件、拐点、标签与选中集事件都带一份 `action`,回答两个问题:**这是什么操作**(`action.type`)、**点在了什么上面**(`action.target`)。命中的数据不重复打包,直接在载荷顶层读:
73
73
 
74
74
  | 字段 | 取值 | 说明 |
75
75
  | --- | --- | --- |
76
76
  | `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` |
77
77
  | `action.target` | `point` / `line` / `channel` / `waypoint` / `label` / `selection` / `empty` | 点在了什么上面:通道回线的 `type` 也是 `line`,但要按通道处理,所以 `target` 单独给 `channel`;点空白是 `empty`;拐点与标签各有自己的 `waypoint` / `label` |
78
- | `action.data` | 对象 / `null` | 按 `target` 直接取到的那份数据:节点 / 线路是数据里那个对象(与 `getData()` 同一份引用)、通道回线是通道定义、选中集是这一批 `items`、拐点是 `{ lineIndex, pathIndex, coordinate, line }`、标签是 `{ label, parent }`、空白处是 `null` |
79
- | `action.button` | `left` / `middle` / `right` / `none` | 鼠标键名,与载荷里的 `button` 数字一一对应;悬停没有按键,固定是 `'none'` |
80
- | `action.modifiers` | `{ ctrl, meta, shift, alt }` | 修饰键,与原生事件一一对应 —— 「按住 Shift 是另一套菜单」这类判断不用再读 `originalEvent` |
81
- | `action.left` / `action.right` | 布尔 | 左键 / 右键的一眼判定(与 `action.button` 同一份:`left` 就是 `button === 'left'`),比比对字符串少写一点;中键两边都是 `false` |
78
+ | 命中数据 | 载荷顶层 | 点 / 线读 `item`(与数据里同一份对象);通道回线读 `channel` / `channelContext`;选中集变更读 `items`;拐点读 `lineIndex` / `pathIndex` / `coordinate` / `line`;标签读 `label` / `parent`;聚合读 `id` / `count` / `pointIds` / `bounds` |
79
+ | 原始输入 | `originalEvent` | 鼠标键(`button` / `buttons`)、修饰键(`ctrlKey` / `metaKey` / `shiftKey` / `altKey`)与 `clientX` / `clientY` 都从原始事件读;程序化 `hoverAt()` 没有这一份 |
82
80
  | `action.moved` | 布尔 | 这一次按下之后有没有真的拖动过:按下恒为 `false`,松开时说明是「拖」还是「点」,拐点拖动是 `start` 为 `false`、`move` / `end` 为 `true` |
83
81
  | `action.double` | 布尔 | 只在点击载荷里出现:`true` 说明这一下是双击里的第二下(单双击要做两件事的界面按它推迟一下) |
84
82
  | `action.press` | 动作名 / `null` | 只在松开 / 点击载荷里出现:**按下时的意图**(与那一刻 `onPointerDown` 的 `action.type` 同一份)——「按下想拖、松开成了点」这类对照看它;没有配对的按下事件时是 `null` |
85
83
  | `action.duration` | 毫秒 | 只在松开 / 点击载荷里出现:这一次按下按了多久(四舍五入),没有配对的按下事件时是 `0` |
86
- | `action.longPress` | 布尔 | 只在松开 / 点击载荷里出现:这一次算不算长按(超过 500 ms 且中间没拖动过 —— 触摸 / 触控笔按它出菜单,`action.button` 仍然是 `'left'`) |
84
+ | `action.longPress` | 布尔 | 只在松开 / 点击载荷里出现:这一次算不算长按(超过 500 ms 且中间没拖动过 —— 触摸 / 触控笔按它出菜单;鼠标键仍看 `originalEvent.button`) |
85
+
86
+ ### 载荷迁移:旧字段 → 新入口
87
+
88
+ 这一版把能从别处取得的字段从回调载荷里删掉了。旧代码按下表改一行即可;`selected` / `wasSelected` 是事件发生时的状态快照,保留:
89
+
90
+ | 旧字段 / 写法 | 现在从哪取 |
91
+ | --- | --- |
92
+ | `payload.selection` | `view.getSelectionInfo()`(`{ ids, count, points, lines, channels }`,结果按选中集引用缓存) |
93
+ | `action.data`(点 / 线) | `payload.item` |
94
+ | `action.data`(通道回线) | `payload.channel` / `payload.channelContext` |
95
+ | `action.data`(选中集) | `payload.items` |
96
+ | `action.data`(拐点) | `payload.lineIndex` / `pathIndex` / `coordinate` / `line` |
97
+ | `action.data`(标签) | `payload.label` / `payload.parent` |
98
+ | `action.data`(聚合) | 载荷顶层 `id` / `count` / `pointIndexes` / `pointIds` / `bounds` / `radius` |
99
+ | `action.button` / `action.modifiers` / `action.left` / `action.right` | `payload.originalEvent.button` / `buttons` / `ctrlKey` / `metaKey` / `shiftKey` / `altKey` |
100
+ | `payload.button` / `payload.buttons` | `payload.originalEvent.button` / `buttons` |
101
+ | `payload.clientX` / `payload.clientY` | `payload.originalEvent.clientX` / `clientY` |
102
+ | `payload.lineIndex` / `payload.lineId`(右键线路) | `payload.index` / `payload.item.id`;通道归属用 `view.getLineChannel(payload.index)` |
103
+ | 复制载荷 `payload.point` | `payload.item`;批量看 `payload.items[0]` |
104
+ | 复制载荷 `payload.coordinate` | `payload.item.x` / `payload.item.y`;批量看 `payload.items[0].x` / `y` |
105
+ | 复制载荷 `payload.setItem(patch)` | `payload.update(patch)` |
106
+ | 回调 `(payload, event)` 两个参数 | 回调只收 `(payload)`,DOM 事件在 `payload.originalEvent`;事件总线载荷也不再包成 `{ payload, event }` |
87
107
 
88
108
  ```js
89
109
  createGisView(container, {
@@ -91,19 +111,19 @@ createGisView(container, {
91
111
  // 一套分支处理全部指针操作:先看是什么操作,再看点在什么上面,最后直接取数据
92
112
  onPointerUp: payload => {
93
113
  if (payload.action.moved) return // 拖过的不当点击处理
94
- if (payload.action.type === 'click' && payload.action.target === 'point') openPoint(payload.action.data)
95
- if (payload.action.type === 'click' && payload.action.target === 'channel') openChannel(payload.action.data)
114
+ if (payload.action.type === 'click' && payload.action.target === 'point') openPoint(payload.item)
115
+ if (payload.action.type === 'click' && payload.action.target === 'channel') openChannel(payload.channel)
96
116
  if (payload.action.target === 'empty') closePanel()
97
117
  },
98
118
  onClick: payload => {
99
119
  if (!payload) return // 空白处的点击载荷是 null(选中已经清空)
100
120
  if (payload.action.double) return // 双击的第二下:单双击要做不同的事时按它推迟
101
- openDetail(payload.item, payload.action.type, payload.action.modifiers)
121
+ openDetail(payload.item, payload.action.type, payload.originalEvent)
102
122
  },
103
- onContextMenu: (payload, event) => {
104
- event.preventDefault()
123
+ onContextMenu: payload => {
124
+ payload.originalEvent.preventDefault()
105
125
  // 右键只有一条意思:action.type 恒为 contextMenu,action.target 说明点的是什么
106
- openMenu(payload.action.target, payload.action.data, payload.world)
126
+ openMenu(payload.action.target, payload, payload.world)
107
127
  }
108
128
  })
109
129
  ```
@@ -112,16 +132,16 @@ createGisView(container, {
112
132
  createGisView(container, {
113
133
  points, lines, channels,
114
134
  // 左键按下:按下那一刻光标下的要素
115
- onPointerDown: (payload, event) => {
116
- console.log(payload.button, payload.buttons) // 0 左键、1 中键、2 右键
135
+ onPointerDown: payload => {
136
+ console.log(payload.originalEvent.button, payload.originalEvent.buttons) // 0 左键、1 中键、2 右键
117
137
  console.log(payload.hit, payload.type, payload.item) // 空白处 hit 为 false、type 为 null
118
138
  console.log(payload.world, payload.x, payload.y) // 光标处的世界坐标与画布 CSS 像素
119
139
  },
120
140
  onPointerUp: payload => console.log('抬起', payload.type, payload.item),
121
141
  // 右键:点 / 线 / 空白都发,命中通道回线时载荷里还有 channelId / groupId / channelIndex / group / groups
122
- onContextMenu: (payload, event) => {
142
+ onContextMenu: payload => {
123
143
  if (!payload.hit) return // 空白处也可以在这里收掉自己的菜单
124
- event.preventDefault() // 想自己弹菜单就拦住浏览器默认菜单
144
+ payload.originalEvent.preventDefault() // 想自己弹菜单就拦住浏览器默认菜单
125
145
  openMenu(payload.item, payload.world, payload.type)
126
146
  },
127
147
  onHover: payload => console.log('悬停', payload?.item ?? '空白处')
@@ -133,12 +153,12 @@ createGisView(container, {
133
153
  - 配了 GeoJSON 背景时,以上载荷都多一个 `lngLat`:按光标的世界坐标(要素命中用 `coordinate`,悬停用最近一次光标位置)反算出来的真实经纬度,点 / 线 / 通道都一样;想自己换算就用 `worldToLngLat` / `screenToLngLat`,光标级别的屏幕坐标 + 世界坐标 + 经纬度看 `onPointer` 与 `getPointer()`。
134
154
  - `onPointerDown` / `onPointerUp` 不改变组件行为:选中、拖拽、框选、拐点编辑照旧。左键的一次「点」(没有拖动)仍然走 `onClick` / `onDblClick`,两者是并列的,不会互相吞掉 —— 载荷里的 `action.type` 各说各话:按下是**意图**、松开是**刚做完的那件事**(`action.moved` 说明是拖还是点)、点击是**真正发生的那一件**。这一下如果同时改了选中,顺序固定是 `onClick → onSelect → onSelectChange`;`selectTrigger: 'dblClick'` 的第二下再在最后补 `onDblClick`。
135
155
  - 点空白处照发:`onPointerDown` / `onPointerUp` 的 `action.target` 是 `empty`(开了平移时按下是 `pan` 的意图),`onClick` / `onDblClick` 的载荷是 `null`(选中在那一刻已经清空)——「点了空白」这件事也可以看 `onSelectChange` 的 `action.type: 'clearSelection'`。
136
- - **中键按住就是临时平移**(`pan` 开关开着时):`onPointerDown` 的 `action.type` 是 `pan`、`action.button` 是 `'middle'`,按住拖动平移画布、松开结束(`onPointerUp` 的 `action.type` 也是 `pan`);这一路**不经过** `onClick`,中键也不会改选中 —— 想自己接中键(中键菜单 / 快捷操作)就按 `action.button === 'middle'` 认它。长按(触摸 / 触控笔)与中键一样有明确的读数:看松开 / 点击载荷的 `action.longPress` 与 `action.press` / `action.duration`。
156
+ - **中键按住就是临时平移**(`pan` 开关开着时):`onPointerDown` 的 `action.type` 是 `pan`、`originalEvent.button === 1`,按住拖动平移画布、松开结束(`onPointerUp` 的 `action.type` 也是 `pan`);这一路**不经过** `onClick`,中键也不会改选中 —— 想自己接中键(中键菜单 / 快捷操作)就按 `originalEvent.button` 认它。长按(触摸 / 触控笔)与中键一样有明确的读数:看松开 / 点击载荷的 `action.longPress` 与 `action.press` / `action.duration`。
137
157
  - `onContextMenu` 每次都只发这一条;命中通道回线时,分组读数在同一份载荷的 `group` / `groups` 上,可执行动作挂在 `channelContext` 上(见「通道右键交互框」),不再额外发第二个回调。**右键缺省整个不接**(`contextMenu` 开关没开时系统菜单照弹、回调也不发);接住之后一律 `preventDefault()` 收掉系统菜单(点 / 线 / 空白 / 通道都一样),回调照常发。想自己弹菜单就写 `interactive: true` / `contextMenu: true` / `features: 'view'`,想让系统菜单自己弹出来就写 `preventContextMenu: false`。
138
158
  - 命中的层级是**点 → 线 → 通道**:右键落在节点上时载荷是 `type: 'point'`,没有 `channelContext` —— 节点压在通道回线上(端点最常见)不会被当成通道右键;点空白处同样没有 `channelContext`,可以直接用它收框。
139
159
  - 悬停是高频率回调:大数据量下建议只做节流的读数或轻量样式切换(demo 里的读数就是这么做的)。
140
160
 
141
- - 命中的要素**在不在选中集里**、以及整份选中集有多少,载荷里直接给:`selected`(这一刻在不在选中集里)、`wasSelected`(`onClick` 给的是「点之前」的那一份,双击同理;右键与按下 / 松开都是「当下」,此时与 `selected` 相同)、`selection`(整份选中集的读数 `{ ids, count, points, lines, channels }`,通道回线按通道算一个)。左键 / 右键要自己接一套操作(按命中分支、弹自己的面板、决定要不要保留多选)时,看这三项就不用再去比对 `getSelectionData().ids`:
161
+ - 命中的要素**在不在选中集里**用载荷里的 `selected`(这一刻)/ `wasSelected`(`onClick` 给的是「点之前」的那一份,双击同理;右键与按下 / 松开都是「当下」,此时与 `selected` 相同)。整份选中集有多少改用 `view.getSelectionInfo()`:`{ ids, count, points, lines, channels }`,通道回线按通道算一个。左键 / 右键要自己接一套操作(按命中分支、弹自己的面板、决定要不要保留多选)时,这一快照加一次读数就够:
142
162
 
143
163
  ```js
144
164
  createGisView(container, {
@@ -147,23 +167,24 @@ createGisView(container, {
147
167
  if (!payload) return // 空白处:选中已经清空
148
168
  // payload.selected:「点完之后」在不在选中集里;payload.wasSelected:「点之前」的那一份
149
169
  if (payload.selected && payload.wasSelected) openDetail(payload.item)
150
- console.log(payload.selection.count, payload.selection.channels)
170
+ const info = view.getSelectionInfo()
171
+ console.log(info.count, info.channels)
151
172
  },
152
- onContextMenu: (payload, event) => {
153
- event.preventDefault() // 自己弹菜单
173
+ onContextMenu: payload => {
174
+ payload.originalEvent.preventDefault() // 自己弹菜单
154
175
  if (payload.type === 'point' && !payload.wasSelected) {
155
176
  // 右键落在没选中的节点上:先把它选上,再按「选中集」弹面板(落在已选中的节点上就保留整份多选)
156
177
  view.selectFeatures(payload.item.id)
157
178
  }
158
- openMenu({ target: payload.item, selection: payload.selection, coordinate: payload.world })
179
+ openMenu({ target: payload.item, selection: view.getSelectionInfo(), coordinate: payload.world })
159
180
  }
160
181
  })
161
182
  ```
162
183
 
163
- - Ctrl + 点击(多选取反)与 Shift + 拖动(默认框选键,可用 `shortcuts.boxSelect` 改)**不经过** `onClick`:顺序是 `onSelect → onSelectChange`。取反的 `action.type` 是 `toggleSelect`(取反取没了也是它,此时 `action.target` 是 `empty`)、框选是 `boxSelect`(没框到东西也是它)、点空白清空是 `clearSelection`;载荷里的 `items` 是操作之后的选中集、`count` 是新的条数。想在这条路里知道「点下去的那一刻它是不是已选中的」,看 `onPointerDown` / `onPointerUp` 载荷的 `selected`,或者在回调里读一次 `getSelectionData()`。选中事件里通道回线的 `group` / `groups` 在单通道载荷顶层;多通道一起选中时看 `channelContexts`,`items[]` 里的回线不再逐条重复挂这两个字段。
184
+ - Ctrl + 点击(多选取反)与 Shift + 拖动(默认框选键,可用 `shortcuts.boxSelect` 改)**不经过** `onClick`:顺序是 `onSelect → onSelectChange`。取反的 `action.type` 是 `toggleSelect`(取反取没了也是它,此时 `action.target` 是 `empty`)、框选是 `boxSelect`(没框到东西也是它)、点空白清空是 `clearSelection`;载荷里的 `items` 是操作之后的选中集、`count` 是新的条数。想在这条路里知道「点下去的那一刻它是不是已选中的」,看 `onPointerDown` / `onPointerUp` 载荷的 `selected`,或者在回调里读一次 `getSelectionData()`。选中事件里通道回线的 `group` / `groups` 与本次选中的 `lineIndexes` / `lineIds` 看单通道载荷顶层;多通道一起选中时看 `channelContexts`。`items[]` 里的回线不重复挂任何通道字段,需要单条归属时用外层 `lineIndexes` / `lineIds` 映射或调 `getLineChannel(index)`。
164
185
  - 不订阅事件、只想知道「这儿是什么」时用 `pickAt(clientX, clientY)`:按鼠标事件里的客户端坐标拾取,返回与指针载荷同一份结果(另加 `target` 与 `lngLat`),空白处返回 `null`;只读 —— 不改选中、不动光标,自建浮层 / 自定义菜单 / 拖拽放下时用它。框内有什么(自建框选界面、框内统计)用 `getFeaturesInRect(rect)`、当前画面里有哪几条通道用 `getChannelsInView()`,三个方法都在「实例方法」里。
165
186
  - 悬停也可以**程序化驱动**:`hoverAt(clientX, clientY)` 让指针「停」到某个位置(悬停高亮、光标与 `onHover` 一起更新,返回与 `onHover` 同一份读数),`clearHover()` 撤掉并补发一条 `onHover(null)`,`getHover()` 随时读当前这一份 —— 外部列表 / 表格 hover 到某一行时联动高亮图上的要素用它,不必自己派发指针事件;不需要了就不用订阅 `onHover`。
166
- - 选中集整个拿走用 `getSelectionData()`,一份就够:读数(`ids` / `count` / `pointCount` / `lineCount` / `channelCount`)加**要素本身**(`points` / `lines` / `channels`(按通道去重))与 `items`(与 `getSelections()` 同一份)、`pointIndexes` / `lineIndexes`、`bounds`(世界包围盒,空选中时 `null`):
187
+ - 选中集整个拿走用 `getSelectionData()`,一份就够:读数(`ids` / `count` / `pointCount` / `lineCount` / `channelCount`)加**要素本身**(`points` / `lines` / `channels`(按通道去重))与 `items`(与 `getSelections()` 同一份,通道回线不带通道字段)、`pointIndexes` / `lineIndexes`、`bounds`(世界包围盒,空选中时 `null`):
167
188
 
168
189
  ```js
169
190
  const data = view.getSelectionData()
@@ -344,13 +365,13 @@ if (!copied.ok) console.warn(copied.reason)
344
365
 
345
366
  | phase | 什么时候 | 能做什么 |
346
367
  | --- | --- | --- |
347
- | `start` | 预览刚出现 | `payload.update({...})` / `setItem({...})` 改复制品,`payload.cancel()` 直接取消 |
368
+ | `start` | 预览刚出现 | `payload.update({...})` 改复制品,`payload.cancel()` 直接取消 |
348
369
  | `move` | 预览跟着鼠标动(`follow: true`) | 同 `start` |
349
370
  | `commit` | 落地之前(`commitPointCopy()` 里发) | `payload.cancel()` 可以拦住这一次复制,改数据也在这里生效 |
350
371
  | `end` | 已经落地 | 读 `payload.index` / `payload.item` 同步业务数据 |
351
372
  | `cancel` | 复制被取消 | 清理自建预览 |
352
373
  | `clipboard` | 复制到剪贴板(Ctrl+C) | `payload.cancel()` 表示不要这次剪贴板 |
353
- | `batch` | 批量复制 / 整组粘贴落地 | 读 `payload.sources`(来源快照)、`payload.items` / `indexes`(新节点)、`payload.lines` / `channels`(一起复制出来的内部线路 / 通道);要撤掉整批用 `payload.revert()` / `cancel()`,要改落地后的节点用 `view.updatePoint(payload.item.id, patch)`(批量载荷不提供预览期的 `update` / `setItem` 改写) |
374
+ | `batch` | 批量复制 / 整组粘贴落地 | 读 `payload.sources`(来源快照)、`payload.items` / `indexes`(新节点)、`payload.lines` / `channels`(一起复制出来的内部线路 / 通道);要撤掉整批用 `payload.revert()` / `cancel()`,要改落地后的节点用 `view.updatePoint(payload.item.id, patch)`(批量载荷不提供预览期的 `update` 改写) |
354
375
 
355
376
  ```js
356
377
  createGisView(container, {
@@ -592,13 +613,12 @@ onPointMerge: async payload => {
592
613
 
593
614
  接口调用不做确认,直接按规则合并:`view.mergePoints('a', 'b')`(来源、目标收 id、下标或 `{ id }` / `{ index }`)。合并的数据规则是:
594
615
 
595
- 这里的「合并样式」不是另一项样式配置,也不是新的 API;它指的是**合并后保留节点最终写进数据的 `size` 与 `symbol`**。Demo 的读数用它回答“合完会长什么样、用哪个图标”:尺寸取双方较大值、图标优先目标节点。它决定合并结果的外观,需要自定义时改 `merge.createItem(...)` 的返回值或 `payload.item` 即可。
596
-
597
- - 节点数据缺省按「被并入的一端在前、保留端在后」合并(保留端优先,另一端独有的字段带过来),坐标与 id 取保留端;拖动合并确认里缺省保留碰撞目标,`keep: 'source'` 时保留拖动的来源节点;
598
- - **图标大小取双方的最大值**:高电压往低电压合,原来的图标跟着变大(结果写成节点自己的 `size`,`sizeScale` 归 1);**图标类型优先目标节点**,目标没配符号才用来源的;
599
- - 想自己决定就用 `merge.createItem(source, target, context)`,`context` 里带双方的 `sourceStyle` / `targetStyle`(`{ index, size, symbol, zIndex }`,样式链定下来的那一份,不含状态样式与热力倍率);
600
- - 绑在被并入节点 id 上的线路(`from` / `to`)改绑到保留节点,端点 / 顶点坐标与被并入端重合的也一并改到保留端坐标;
601
- - 合并后两端落在同一个节点上的自环线路、缩成一个点的零长度线路,以及两端因此相同的通道(成员回线跟着一起)直接删掉;
616
+ - **缺省以保留节点为底**:名称、图标类型、颜色、业务属性等普通字段都取保留节点;拖动合并缺省保留碰撞目标,`keep: 'source'` 时保留拖动的来源节点。只有 `merge.maxKeys` 列出的字段取双方最高值:数组或逗号分隔字符串,缺省空表(一个都不取);每个键把双方能解析成有限数字的值收集起来取 `Math.max`,空串、`null`、非数字当没给,只有一方有效就用那一方,两边都无效时保持保留节点的原值。例如 `merge: { maxKeys: ['vn_kv', 'value'] }` 只把电压与 `value` 保留最高值,其余字段仍取保留端。
617
+ - **图标大小取双方解析后样式的最大值**:高电压往低电压合,图标跟着变大(结果写成节点自己的 `size`,`sizeScale` 归 1);**图标类型只用保留节点**,保留端没配图标不会回落到来源端的业务字段。
618
+ - 想自己决定业务字段就用 `merge.createItem(source, target, context)`,`context` 里带双方的 `sourceStyle` / `targetStyle`(`{ index, size, symbol, zIndex }`,样式链定下来的那一份,不含状态样式与热力倍率);最终 `id`、坐标与 `mergeInfo` 始终由组件按保留节点维护,`merge.createItem` / `options.item` 改不了这三样。
619
+ - 绑在被并入节点 id 上的线路(`from` / `to`)改绑到保留节点,端点 / 顶点坐标与被并入端重合的也一并改到保留端坐标;id 比较会把数字和同值字符串当成同一个(`1` 与 `'1'`)。
620
+ - **通道端点也跟着改**:通道的 `from` / `to` 指向被并入节点时改到保留节点;改完两端相同的通道整条删掉,成员回线跟着删除。
621
+ - 合并后两端落在同一个节点上的自环线路、缩成一个点的零长度线路一起删掉;
602
622
  - **两端因此撞成同一条的通道合成一条**:`merge.channelGroups` 决定回线怎么分组 —— `'keep'`(默认)各自保留自己的分组,`'merge'` 合成一个分组(回线取并集);
603
623
  - 结果里带 `linesChanged`、`removedLines`、`removedChannels`、`mergedChannels`、`channelsChanged` 五个读数;自己接管数据落地时用 `commitPointMerge()` / `revertPointMerge()` 收尾。
604
624
 
@@ -612,7 +632,7 @@ onPointMerge: async payload => {
612
632
  返回值就是收尾那条 `phase: 'mergeSelected'` 的载荷:`{ ok, reason, target, merged, sourcesMerged, skipped, linesChanged, removedLines, removedChannels, mergedChannels, channelsChanged }` ——
613
633
  `merged` 逐对列出(每项与 `mergePoints` 的返回同形),没选中 / 不够两个 / 都并不了时 `ok: false` 且 `reason` 说明原因(不抛异常)。
614
634
 
615
- **指定保留谁、改写最终节点**:`target` 就是最后留下的那个节点(坐标与 id 都按它保留,不指定才自动挑)。`options.item` 可以给一份最终节点补丁,或者给 `(context) => 补丁` 按每一对现算 —— `context` 里有 `item` / `merged`(缺省合并结果)、`source` / `target`、`sourceIndex` / `targetIndex`、`merge`(与 `merge.createItem` 同一份上下文)与 `view`;返回 `undefined` 表示沿用缺省结果。坐标与 id 不会被补丁改掉。
635
+ **指定保留谁、改写最终节点**:`target` 就是最后留下的那个节点(坐标、id 与 `mergeInfo` 都按它保留,不指定才自动挑)。`options.item` 可以给一份最终节点补丁,或者给 `(context) => 补丁` 按每一对现算 —— `context` 里有 `item` / `merged`(缺省合并结果)、`source` / `target`、`sourceIndex` / `targetIndex`、`merge`(与 `merge.createItem` 同一份上下文)与 `view`;返回 `undefined` 表示沿用缺省结果。坐标、id 与 `mergeInfo` 不会被补丁改掉。
616
636
 
617
637
  ```js
618
638
  view.mergeSelectedPoints({
@@ -627,25 +647,64 @@ view.resolvePointMerge(true) // 确认
627
647
  view.resolvePointMerge(false) // 取消:拖动的节点回原位,数据不动
628
648
  ```
629
649
 
650
+ ### 合并追溯(mergeInfo)
651
+
652
+ `mergePoints` / `mergeSelectedPoints` 落地时会给保留节点写一份可序列化的 `mergeInfo`(格式版本 `version: 1`),用来回答「这个节点并过谁、合并前长什么样」,也是 `splitPoint(source)` 自动解除合并的输入。完整字段是:
653
+
654
+ | 字段 | 说明 |
655
+ | --- | --- |
656
+ | `version` | 追溯格式版本,当前固定为 `1`;不认这个版本的同名字段不会当快照使用 |
657
+ | `targetId` | 保留节点的 id(通道上的同一字段表示合并到的目标节点) |
658
+ | `targetIndex` | 第一次合并时保留节点在原 `points` 里的下标,仅作恢复时没有 id 的兜底 |
659
+ | `targetPoint` | 保留节点第一次合并前的完整快照(不含上一份 `mergeInfo`) |
660
+ | `sourceIds` | 依次并进来的来源节点 id,按发生顺序追加 |
661
+ | `points` | 来源节点快照:每项 `{ index, id, item }`,`item` 是来源合并前的数据;恢复时按 `index` 顺序放回 |
662
+ | `lines` | 受影响线路第一次合并前的快照:每项 `{ index, id, item }`,用来恢复改绑、几何与删除 |
663
+ | `channels` | 受影响通道第一次合并前的快照:每项 `{ index, id, item }`,用来恢复端点、分组与回线归属 |
664
+
665
+ 同一个保留节点连续并多个来源时,`sourceIds` 与 `points` 继续累加,`targetPoint` 仍是第一次合并前的数据;`lines` / `channels` 只保留第一次遇到的那份快照,避免后面的快照覆盖真正的合并前状态。合并后仍然存在的受影响通道另写一份轻量 `mergeInfo`:`{ version, targetId, sourceIds, originalIds }`,`originalIds` 是参与这次合并、被改端点或被并掉的原始通道 id,便于后端按原通道对账;它不承担单独恢复节点的职责。
666
+
667
+ `mergeInfo` 会随 `getData()` / `exportData()` 的 `points` / `channels` 一起导出,JSON 序列化后可直接回灌。它是组件的保留字段,业务数据不要占用;合并结果里的 `id`、坐标与这个字段都由组件维护。
668
+
630
669
  删节点用 `view.removePoints('a')` / `view.removePoints({ index: 2 })` / 数组:绑在它上面的线路一并删掉,声明了它当端点的整条通道(含成员回线)跟着删。
631
670
 
632
671
  ## 节点拆分(splitPoint)
633
672
 
634
- `splitPoint` 是 `mergePoints` 的逆操作:把一个节点按业务需要拆成两份或更多,原来连在它身上的线路与通道两端按分配重新挂到新节点上。它不弹对话框,直接按规则落地;整次调用只记一条历史、只发一条 `splitPoint` 数据变更。
673
+ `splitPoint` 是 `mergePoints` 的逆操作,有两条路:`splitPoint(source)` 按 `mergeInfo` 自动恢复;传 `parts` 时则把一个节点按业务需要手工拆成两份或更多,原来连在它身上的线路与通道两端按分配重新挂到新节点上。它不弹对话框,直接按规则落地;整次调用只记一条历史、只发一条 `splitPoint` 数据变更。
674
+
675
+ **自动解除合并**:`splitPoint(source)` 省略 `parts`(或显式传 `null` / `[]`)时读取保留节点的 `mergeInfo`,恢复第一次合并前的保留节点与全部来源节点,再按快照恢复线路和通道。完整字段见上面「合并追溯(mergeInfo)」;不需要自己再写每个节点的坐标与线路归属。
676
+
677
+ ```js
678
+ const restored = view.splitPoint('hub') // 等价于 splitPoint('hub', null) / splitPoint('hub', [])
679
+ if (!restored.ok) console.warn(restored.reason)
680
+ console.log(restored.autoRestored, restored.mergeSourceIds) // true / ['a', 'b', ...]
681
+ console.log(restored.changes) // 可直接提交后端事务
682
+ // 默认不选中恢复结果;需要选中全部结果时:splitPoint('hub', null, { select: true })
683
+ ```
684
+
685
+ 恢复范围与边界:
686
+
687
+ - 保留节点在原下标恢复成 `targetPoint`,`mergeInfo` 一并移除;来源节点按快照追加到 `points` 末尾。
688
+ - 线路 / 通道先按 id 找当前位置并替换,合并时被删掉的按快照追加回来;合并之后用户新建、且不在这份快照里的节点 / 线路 / 通道不会被删掉。
689
+ - 来源节点 id 如果已经被后来手工新建的节点占用,整次调用返回 `ok: false`,`reason` 说明冲突 id,数据与历史都不动。
690
+ - 自动解除是一步历史:`view.undo()` 一步回到合并后的状态,`view.redo()` 一步恢复解除结果;返回 `autoRestored: true` 与 `mergeSourceIds`,手工拆分时 `autoRestored` 为 `false`、`mergeSourceIds` 为空数组。
691
+ - 没有 `mergeInfo` 或追溯信息不完整时不会猜测拆法,返回 `ok: false`;要手工拆就继续传两份以上 `parts`。
635
692
 
636
693
  ```js
637
694
  const split = view.splitPoint('hub', [
638
695
  { name: '枢纽(主)' }, // 第一份:沿用原下标与 id
639
696
  { x: 116.42, y: 39.91, name: '枢纽(东)', lines: ['line-east'] },
640
697
  { x: 116.38, y: 39.89, name: '枢纽(西)', lines: ['line-west'], channelTo: ['corridor-1'] }
641
- ], { label: '拆分枢纽' })
698
+ ], { autoLines: 'alternate', label: '解除合并' })
642
699
 
643
700
  if (split.ok) {
644
- console.log(split.pointIds, split.linesChanged, split.channelsChanged)
701
+ console.log(split.pointIds, split.autoAssignedLines, split.lineAssignments)
645
702
  api.post('/gis/points/split', split.changes) // 拆分后的节点、受影响的线路与通道端点,以及删除项
646
703
  }
647
704
  ```
648
705
 
706
+ `options.autoLines` 决定**没写进 `lines` 的线路**怎么分:缺省 `'first'` 全跟第一份(兼容旧行为);`'alternate'` 按「同一条通道的成员成一组、独立线路各算一条」为单位,轮流分给当前负载最少的一份。显式写进 `lines` 的线路不参与自动分配,但会计入负载;同一条通道的成员因此不会被拆到两份上。解除合并时推荐 `'alternate'`,可以让四回线的通道整体去 A、两条独立线路分别去 A / B,而不是把通道回线拆散。
707
+
649
708
  每份节点定义可以直接写节点字段(`id` / `x` / `y` / `name` / 样式 / 业务字段),也可以放进 `item`;另外三项是从节点字段里摘出来的分配指令,不会写进节点数据:
650
709
 
651
710
  | 字段 | 作用 |
@@ -658,14 +717,15 @@ if (split.ok) {
658
717
 
659
718
  - **第一份接在原下标上**,缺省沿用来源节点的 id;其余几份追加到 `points` 末尾。`options.keepSourceId: false` 时第一份也生成 `${来源 id}-split-1`。没写 id 的其余份依次生成 `${来源 id}-split-2` / `-3`…,撞上现有 id 时自动加序号;显式写了重复 id 会整次失败。
660
719
  - **节点字段从来源继承,再按这一份的字段覆盖**;坐标缺省继承来源。至少给两份,坐标必须是有效数字,否则 `ok: false` 且 `reason` 说明原因。
661
- - **线路默认跟第一份**:没写进任何一份 `lines`、但连在来源节点上的线路,全部改挂到第一份;同一条线路显式分给两份会整次失败。认不出 / 没连在来源上的引用进 `skipped.lines`,不影响其余条目。
720
+ - **线路默认跟第一份**:没写进任何一份 `lines`、但连在来源节点上的线路,`autoLines: 'first'`(缺省)时全部改挂到第一份;写 `autoLines: 'alternate'` 时按上面的「通道成组 / 独立线路单条」轮流分配。同一条线路显式分给两份会整次失败。认不出 / 没连在来源上的引用进 `skipped.lines`,不影响其余条目。
662
721
  - **通道端点默认跟第一条被分配过的成员回线**:例如通道里唯一一条回线分给了第二份,通道的 `from` 会自动改到第二份节点,而不是留在第一份;成员都没显式分配时才回落到第一份。显式写了 `channels` / `channelFrom` / `channelTo` 的按显式分配来。
663
722
  - **几何一起改**:线路的 `from` / `to` 改到对应新节点;没有 id 绑定、但 `start` / `end` / `path` 顶点与来源坐标重合的端点 / 顶点也改到新坐标。通道端点按新声明重新锚定,成员回线由通道骨架推导,不用逐条改。
664
723
  - **拆完清理退化数据**:两端落到同一份、变自环或零长度的线路删掉;两端因此相同的通道删掉;成员回线全被删空的通道也删掉。删除项分别进 `removedLineIds` / `removedLineIndexes` 与 `removedChannelIds`。
665
- - **返回的 `channelsChanged` 只数端点被改写的通道**;被删掉的通道单列在 `removedChannels` / `removedChannelIds`。`changes` 给 `{ removedPoint, points, lines, removedLines, channels, removedChannels }`:`points` 是拆分后的全部节点,`lines` / `channels` 是仍存在且端点被改写的线路 / 通道,删除项单列;可直接作为后端事务输入。`skipped` 说明哪些线路 / 通道引用没认出来。
724
+ - **结果默认不选中**:`options.select` 缺省 `false`,只把来源节点本身从当前选中集里摘掉,不选中恢复 / 拆分出来的节点,也不动其它无关的线路 / 通道选中;写 `select: true` 时改为选中全部结果节点(替换当前选中集)。自动解除与手工拆分共用这一条。
725
+ - **返回的 `channelsChanged` 只数端点被改写的通道**;被删掉的通道单列在 `removedChannels` / `removedChannelIds`。`autoLines` 是本次采用的口径,`autoAssignedLines` 只数自动分配(没在 `parts[].lines` 里显式写)的线路,`lineAssignments` 按份给出 `{ index, pointId, lineIds, lineCount }`,含显式与自动分配后的最终结果。手工拆分时 `autoRestored` 为 `false`、`mergeSourceIds` 是空数组;自动解除时反过来。`changes` 给 `{ removedPoint, points, lines, removedLines, channels, removedChannels }`:`points` 是拆分后的全部节点,`lines` / `channels` 是仍存在且端点被改写的线路 / 通道,删除项单列;可直接作为后端事务输入。`skipped` 说明哪些线路 / 通道引用没认出来。
666
726
  - **撤销**:不用逐条回滚,`view.undo()` 一步回到拆分前;重做一步恢复拆分结果。
667
727
 
668
- `CopyMergeDemo.vue` 的「拆分节点」一节可以直接点按钮看效果:选中一个节点,按两份拆开,读数会列出新节点 id、改绑的线路与通道端点,以及这一步的变更集。
728
+ `CopyMergeDemo.vue` 的「解除合并」一节可以直接点按钮看效果:优先调用 `splitPoint(source.id, null, { label: '解除合并(自动恢复)', select: splitSelect })`,`splitSelect` 缺省 `false`(不选中恢复结果,读数会写清),勾选后才传 `true`;读数还会列出 `autoRestored`、恢复的来源 id、每个节点恢复后的电压以及改线 / 改通道数。选中项没有 `mergeInfo` 时,Demo 自动退回 `splitPoint(source.id, [A, B], { autoLines: 'alternate', label: '解除合并(手工拆分)', select: splitSelect })`,继续演示新节点 id、自动分线、每份线路数与通道成组结果。演示页的合并读数还会直接显示保留节点的 `mergeInfo`(保留前名称 / 电压、来源、线路与通道快照条数)。
669
729
 
670
730
  ## 删除(remove)
671
731