WholeProcessPlatform/frontend/docs/地图模块-OpenLayers抽吸与碰撞分析.md

# 地图模块-OpenLayers抽吸与碰撞分析

## 1. 背景

当前地图 2D 主引擎已经切换为 OpenLayers，项目依赖版本为 `ol@^10.8.0`。  
本次关注的问题有两个：

- 点位“抽吸”逻辑不符合业务预期；
- 文字碰撞时把整个点位一起隐藏，而不是仅隐藏文字。

典型场景是两个相邻电站，例如“积石峡”和“公伯峡”：

- 可用代号 `1`、`2` 表示两个相邻点；
- 默认缩放下只展示 `1`；
- 放大到某个层级后，`1` 隐藏，`2` 展示；
- 再继续放大后，`1` 和 `2` 都展示，但 `2` 需要“抽吸/拉开”显示，避免与 `1` 重叠；
- 如果只是文字发生碰撞，希望点图标保留，仅文字隐藏或延后显示。

本文件先整理当前代码现状和问题成因，不直接修改实现。  
如果需要查看**当前已经落地的抽吸规则、默认参数和调参入口**，请同时参考：

- `docs/地图模块-抽吸规则与参数说明.md`

## 2. 当前代码结构

当前前端 GIS 运行链路如下：

1. `src/components/gis/GisView.vue`
2. `src/modules/map/application/map-orchestrator.ts`
3. `src/components/gis/map.class.ts`
4. `src/components/gis/map.ol.ts`
5. `src/components/gis/ol/point-layer-manager.ts`
6. `src/components/gis/ol/popup-manager.ts`

各层职责简述：

- `GisView.vue`
  - 地图入口组件；
  - 挂载地图容器、图例、筛选器、控制器；
  - 通过 `mapOrchestrator.mountView()` 初始化地图；
  - 菜单切换时通过 `handlePageChange()` 触发页面地图重载。

- `map.class.ts`
  - 地图门面类；
  - 当前 2D 实现实际绑定的是 `MapOl`；
  - 3D 实现才会切到 `MapCesium`。

- `map.ol.ts`
  - OpenLayers 主实现；
  - 负责地图初始化、底图加载、点位样式、Popup、区域裁切、量算等；
  - 当前“点位渲染规则”和“碰撞相关逻辑”主要集中在这个文件。

- `point-layer-manager.ts`
  - 负责点图层创建、Feature 灌入、按图层控制显隐；
  - 点位图层统一使用 `VectorLayer + VectorSource`。

- `popup-manager.ts`
  - 管理 hover popup 和高缩放下的批量 popup；
  - 内部额外做了一套基于边界框的碰撞判断。

## 3. 当前点位渲染链路

### 3.1 点图层创建

`point-layer-manager.ts` 中的 `ensureLayer()` 会统一创建点图层：

- 图层类型为 `VectorLayer<VectorSource>`；
- 图层上开启了 `declutter: true`；
- 样式函数统一走 `map.ol.ts` 中的 `createPointStyle()`。

也就是说，当前所有点位的“是否显示”和“图标/文字如何避让”，都收敛到 OpenLayers 的 declutter 机制和样式函数里。

### 3.2 点样式生成

`map.ol.ts` 的 `createPointStyle()` 当前做了这些事：

- 读取 `_iconUrl` 和 `_labelText`；
- 如果图例不可见、区域不可见，则直接返回 `null`；
- 如果 `distance` 不满足当前缩放级别要求，也直接返回 `null`；
- 图标使用 `Icon`；
- 文字使用 `Text`；
- 图标和文字都设置了 `declutterMode: 'declutter'`；
- 最终把图标和文字一起放进同一个 `Style` 返回。

这意味着：

- 点图标和文字不是两个独立的渲染对象；
- 它们在当前实现中属于同一个样式结果；
- 只要这组样式参与碰撞判定，图标和文字的命运就是绑定的。

### 3.3 当前已有的“抽稀”逻辑

当前项目中确实有一层“缩放越小，显示越少”的处理，但它不是精细的“抽吸”。

`map.ol.ts` 的 `shouldRenderFeatureByDistance()` 逻辑是：

- 小缩放下要求 `distance` 更大才允许显示；
- 缩放越大，允许显示的点逐渐增多；
- 本质上是基于后端数据字段 `distance` 做全局抽稀。

这个逻辑的特点是：

- 是全局阈值，不是成对点位或同组点位的专属规则；
- 只能决定“这个点显示还是不显示”；
- 不能表达“1 和 2 是近邻关系，并且在不同缩放阶段按业务优先级切换显示”。

### 3.4 当前批量 Popup 的碰撞检测

`popup-manager.ts` 在高缩放批量 popup 模式下，又额外做了一层碰撞判断：

- 先估算图标和文字合并后的锚点边界框；
- 如果边界框碰撞，则当前要素直接不参与 popup 渲染；
- 随后再判断 popup 矩形之间是否碰撞。

这说明当前“图标 + 文字”被视为一个整体，不仅体现在 OpenLayers 的 declutter 里，也体现在 popup 的辅助判断里。

## 4. 当前仓库里“抽吸”相关代码现状

仓库中确实存在历史上的“抽吸”实现，但不在当前 OpenLayers 主链路里。

相关文件：

- `src/utils/leaflet/leaflet.inflatable-markers-group.js`
- `src/components/gis/map.leaflet.ts`

现状判断：

- `leaflet.inflatable-markers-group.js` 是旧 Leaflet 时代的抽吸插件；
- 它内部有 `inflateAsManyAsPossible()`、`_zoomend()` 等典型抽吸逻辑；
- 但当前 `map.class.ts` 实际实例化的是 `new MapOl()`；
- `map.leaflet.ts` 已经不在主运行路径上。

结论是：

- 当前页面上看到的点位行为，不是 Leaflet 抽吸插件在工作；
- 现在的显示结果主要来自 OpenLayers 的 `declutter`、当前样式函数和 `distance` 抽稀逻辑；
- 因此“已经有抽吸但是不太对”，更准确地说是“历史上有抽吸代码，但现在主链路没有真正使用那套机制”。

## 5. 问题分析

### 5.1 为什么当前实现做不到你要的分阶段抽吸

你描述的目标并不是简单“避让”，而是一个明确的分阶段显示策略：

1. 默认只显示 `1`；
2. 缩放到阶段 A 时，隐藏 `1`，改为显示 `2`；
3. 缩放到阶段 B 时，`1` 和 `2` 都显示；
4. 阶段 B 下，`2` 还要相对 `1` 做抽吸/偏移，避免完全重叠。

而当前代码缺少以下能力：

- 没有“近邻点关系”配置
  - 代码里没有看到类似 `groupId`、`neighborIds`、`priority`、`displayLevel` 这样的结构；
  - 系统不知道“积石峡”和“公伯峡”是一组特殊近邻点。

- 没有“分阶段显示规则”配置
  - 当前只有全局的 `distance` 阈值判断；
  - 没有按缩放阶段表达“谁替代谁显示、谁先隐藏、谁后展示”。

- 没有“抽吸偏移”计算
  - 当前点要素坐标就是原始经纬度转换结果；
  - 没有根据缩放级别和邻近关系生成偏移坐标；
  - 也没有“展开后沿圆周/沿固定方向偏移”的逻辑。

- 当前 declutter 是被动避让，不是主动编排
  - declutter 只会尽量避免重叠；
  - 它不会理解业务上的“1 是主点、2 是附点”；
  - 也不会自动实现“先 1，后 2，再两个都展示且 2 偏移”的规则。

所以当前看到的结果不稳定，本质原因不是某一个参数不对，而是“现有机制和目标能力不是一类问题”。

### 5.2 为什么文字碰撞会把整个点隐藏

这是当前实现里最关键的原因：

- 点图标和文字是在同一个 `Style` 里返回的；
- 图层开启了 `declutter: true`；
- 图标和文字又都设置了 `declutterMode: 'declutter'`。

在这种组织方式下，当前要素的碰撞判定是按“一个整体渲染单元”处理的，而不是“图标一套规则，文字一套规则”。

因此会出现下面的现象：

- 图标本身其实不冲突；
- 但文字边界框发生碰撞；
- 最终被隐藏的是整条样式结果；
- 用户视觉上就会觉得“明明只是字挤了，为什么点也没了”。

这和你现在观察到的问题是一致的。

### 5.3 为什么当前逻辑还会进一步放大这个问题

除了 OpenLayers 自身的 declutter 组织方式，代码里还有两层因素会继续放大问题：

- `shouldRenderFeatureByDistance()` 会先根据 `distance` 直接过滤点位；
- `popup-manager.ts` 在批量 popup 模式下，也把“图标 + 文字”当作合并边界框做碰撞模拟。

也就是说，当前系统对近邻点位的处理是：

- 先用全局 `distance` 规则筛掉一部分；
- 再用 OpenLayers declutter 继续过滤；
- 高缩放时 popup 层再做一轮碰撞跳过。

这三层叠加后，显示行为更偏向“谁先撞谁消失”，而不是“按业务规则分阶段展开”。

## 6. 结合你的案例做具体映射

如果以近邻点 `1`、`2` 为例，当前代码里实际上缺的是下面这些业务语义：

- `1` 和 `2` 属于同一近邻组；
- 组内有主次优先级；
- 在不同 zoom 区间内有不同展示策略；
- 在最大放大阶段需要给 `2` 一个偏移位；
- 偏移后图标和文字还要分别控制碰撞策略。

当前实现只能表达：

- 某个点在当前 zoom 下是否允许渲染；
- 某个点图例是否可见；
- 某个点是否被区域裁切隐藏；
- 某个点的图标和文字整体是否参与 declutter。

它并不能表达：

- “1 替代 2 展示”；
- “2 替代 1 展示”；
- “1 和 2 一起展示，但 2 抽吸展开”；
- “只隐藏文字，不隐藏图标”。

所以你现在遇到的问题是结构性问题，不是简单调一个 `declutter` 参数就能彻底解决。

## 7. 后续修改时建议优先动的层

如果下一步要真正改这块，建议优先从下面几层入手：

### 7.1 先补“近邻点显示规则”

建议不要直接把业务规则写死在样式函数里，而是先增加一层近邻点编排规则，例如：

- `groupId`
- `priority`
- `showZoomMin`
- `showZoomMax`
- `replaceAtZoom`
- `expandAtZoom`
- `expandOffset`

这样才能表达：

- 默认只显示主点；
- 中间层级切换成副点；
- 更大层级两个都显示；
- 副点在展示时做偏移。

### 7.2 抽吸不要依赖 declutter 自动完成

抽吸本质上是“主动布局”问题，不是“被动避让”问题。

建议后续把近邻点抽吸拆成单独逻辑：

- 先根据原始点数据识别近邻组；
- 再根据当前 zoom 产出“本次真正参与渲染的点集合”；
- 对需要展开的点，生成偏移后的渲染坐标；
- 最后再交给图层渲染。

这样会比直接指望 OpenLayers 的 declutter 更可控。

### 7.3 图标层和文字层要分开控制

要实现“文字碰撞时只隐藏文字，不隐藏点图标”，后续最重要的一点是把图标和文字的渲染职责拆开。

至少要做到下面二选一：

- 图标层和文字层拆成两个独立图层；
- 或者把图标与文字拆成可独立决策的渲染单元。

目标是：

- 图标优先保留；
- 文字单独避让；
- 文本碰撞时只压文字，不压图标。

如果仍然维持“同一个样式对象里同时放 image 和 text”的组织方式，这个问题大概率还会持续存在。

### 7.4 Popup 碰撞策略也要和新规则同步

后续如果点位抽吸和文字单独避让改了，`popup-manager.ts` 里的边界框逻辑也要一起调整。

否则会出现：

- 图标已经正常显示；
- 文字也按新规则显示了；
- 但 popup 层仍然沿用旧的合并边界框；
- 最终又在 popup 阶段把结果打回去。

## 8. 建议的改造顺序

为了降低风险，建议后续改造按以下顺序推进：

1. 先梳理近邻点数据结构
   - 确定近邻点如何分组；
   - 确定主次优先级和缩放阈值从哪里来。

2. 再实现“显示决策层”
   - 在真正生成 Style 之前，先决定哪些点应该显示；
   - 哪些点应该隐藏；
   - 哪些点需要偏移展开。

3. 然后拆分图标和文字碰撞
   - 先保证点图标稳定显示；
   - 再单独做文字避让。

4. 最后调整 popup 逻辑
   - 保证 popup 的碰撞判定和最终可见点保持一致。

## 9. 涉及文件清单

本次分析重点涉及以下文件：

- `src/components/gis/GisView.vue`
- `src/components/gis/map.class.ts`
- `src/components/gis/map.ol.ts`
- `src/components/gis/ol/point-layer-manager.ts`
- `src/components/gis/ol/popup-manager.ts`
- `src/utils/leaflet/leaflet.inflatable-markers-group.js`
- `src/components/gis/map.leaflet.ts`
- `package.json`

## 10. 当前结论

当前地图问题可以归纳为两点：

1. 现在的 OpenLayers 主链路并没有真正使用旧 Leaflet 的抽吸机制；
2. 当前点图标和文字被作为一个整体参与 declutter，所以文字碰撞时会连点一起隐藏。

所以后续如果要改，方向不应该只是“调避让参数”，而应该是：

- 增加近邻点分阶段显示规则；
- 增加主动抽吸/偏移布局；
- 把图标和文字拆成可独立控制的渲染单元；
- 同步修正 popup 的碰撞判断。

在这个基础上，再进入代码修改会更稳。