344 lines
19 KiB
Markdown
344 lines
19 KiB
Markdown
# 地图可视化配置平台（MapStudio）技术实现说明文档
|
||
|
||
## 1. 项目概述
|
||
|
||
本项目是一个基于 **Vue3** + **Ant Design Vue 4.0** + **OpenLayers (ol ^10.8.0)** 的独立地图配图功能模块。 **核心定位**：用于流域水电场景的地图配图工具，支持多类型底图切换、基础图层叠加、业务锚点管理（含样式编辑）。 **关键特性**：作为一个高内聚、低耦合的独立模块，支持整体复制迁移至其他 Vue3 项目。
|
||
|
||
## 2. 技术栈与环境
|
||
|
||
- **框架**：Vue 3 (Composition API)
|
||
- **UI 组件库**：Ant Design Vue 4.0 (`a-drawer`, `a-tabs`, `a-popover`, `a-modal` 等)
|
||
- **地图引擎**：OpenLayers (`ol@^10.8.0`)
|
||
- **状态管理**：Vue `reactive` + `provide`/`inject` 模式（`useMapStudioState.ts`）
|
||
- **辅助库**：`html2canvas`（配图截图预览，待接入）
|
||
- **图标资源**：`/src/assets/legend/*.svg`（Vite glob 批量导入）
|
||
|
||
## 3. 页面布局结构
|
||
|
||
整体采用 **“左侧固定工具栏 + 中央地图容器 + 右侧可收抽屉 + 左下悬浮图例”** 的布局方案。
|
||
|
||
| 区域 | 组件/实现 | 交互说明 |
|
||
| :--------------------- | :--------------------- | :------------------------------------------------------------------------------------------- |
|
||
| **工具栏** | `LeftToolbar.vue` | 垂直排列【放大】、【缩小】、【全屏】、【导入(占位)】、【保存配图】。独立于抽屉，抽屉收起时依然显示。目前按钮均为静态占位，无实际交互逻辑。 |
|
||
| **中央地图容器** | `index.vue` 内联 div | 承载 OL Map 实例，直接在 `index.vue` 中通过 `ref` 挂载地图，无独立 `MapContainer.vue` 组件。 |
|
||
| **右侧抽屉** | `RightDrawer.vue` | `a-drawer` 组件，支持收起/展开。内部嵌套 `a-tabs`，包含【基础底图】、【图例/标题管理】、【锚点样式】三个 Tab。 |
|
||
| **左下悬浮图例** | `Legend.vue` | 动态显示当前可见锚点分类的图标和标签，支持图例标题/子级样式配置，位置可通过配置调整（左上/左下/右上/右下）。 |
|
||
|
||
## 4. 功能模块详细说明
|
||
|
||
### 4.1 底图切换
|
||
|
||
- **支持类型**：【影像图】、【矢量图】、【地形图】、【等高线图】。通过替换 `ol/layer/Tile` 的 `source` 实现。
|
||
- 影像图：ArcGIS World Imagery
|
||
- 矢量图：内网 GeoServer WMTS（`qgc_qsj_arcgistiles_l13`）
|
||
- 地形图：天地图地形 `ter_w`
|
||
- 等高线图：Thunderforest Cycle
|
||
- **边界图层**：可通过 `a-checkbox` 控制显示/隐藏内网 GeoServer 提供的流域边界线。切换到矢量图时强制隐藏边界。
|
||
- **空间范围限定**：未实现（后续可扩展）。
|
||
|
||
### 4.2 叠加基础图层（显隐控制）
|
||
|
||
通过 `useOverlayLayers.ts` 管理，右侧抽屉"基础底图"Tab 中的 Checkbox 勾选控制图层显隐（取消勾选时仅 `setVisible(false)`，不删除图层）。
|
||
|
||
支持以下图层（部分为 WMTS/ArcGIS/GeoServer 服务）：
|
||
|
||
| 图层 | 类型 | 数据来源 |
|
||
| :----------- | :---------- | :------------------------------- |
|
||
| 行政标注 | TileLayer | 天地图矢量标注 `cia_w` |
|
||
| 区域服务 | ImageLayer | ArcGIS REST `ZH_QUYU` |
|
||
| 九段线 | ImageLayer | ArcGIS REST `九段线服务1` |
|
||
| 岛屿 | ImageLayer | GeoServer WMS `cite:dy` |
|
||
| 流域注记 | ImageLayer | ArcGIS REST `zh_LiuYu_annotation` |
|
||
| 流域线 | ImageLayer | ArcGIS REST `zh_LiuYu_line` |
|
||
| 轮渡 | ImageLayer | ArcGIS REST `jiaotong_ferry` |
|
||
| 铁路 | ImageLayer | ArcGIS REST `jiaotong_railway` |
|
||
| 地铁 | ImageLayer | ArcGIS REST `jiaotong_metro` |
|
||
| 行政区面状 | ImageLayer | ArcGIS REST `zh_XingZhengQu_Polygon` |
|
||
| 行政区 | ImageLayer | ArcGIS REST `ZH_XINGZHEGNQU` |
|
||
|
||
### 4.3 业务锚点系统
|
||
|
||
锚点类型（4 类）：电站、过鱼设施、鱼类增殖站、低温水减缓设施。页面初始化时即并行加载所有分类的接口数据，勾选子类型后渲染到地图上，同时图例自动显示。
|
||
|
||
#### 4.3.1 数据模型
|
||
|
||
锚点核心接口定义在 `useMapStudioState.ts` 中：
|
||
|
||
```typescript
|
||
interface AnchorCategory {
|
||
key: string; // 分类 key（powerStation / fishPassage / fishFarm / coldWater）
|
||
label: string; // 分类名称
|
||
icon: string; // 分类图标 key
|
||
children: AnchorItem[];
|
||
}
|
||
|
||
interface AnchorItem {
|
||
key: string; // 子类型 key（如 large_eng_built）
|
||
label: string; // 子类型名称
|
||
icon: string; // 子类型图标 key
|
||
checked: boolean; // 是否勾选
|
||
}
|
||
```
|
||
|
||
每个锚点 Feature 的 properties 包含：
|
||
|
||
- `_iconUrl` - 当前图标 URL
|
||
- `_label` - 显示文字
|
||
- `_stnm` - 站点名称
|
||
- `_lng`, `_lat` - 经纬度
|
||
- `_categoryKey`, `_subTypeKey` - 分类/子类型标识
|
||
- `_iconSource` - 图标来源（inherit / custom）
|
||
- `_customIconUrl` - 自定义图标 URL
|
||
- `_customTypeLabel` - 自定义类型名称（更换图标时可自定义）
|
||
- `_ov_*` - 样式覆盖字段（字体、字号、颜色、加粗、图标大小、描边、文字位置/边距、显示文字）
|
||
|
||
#### 4.3.2 样式继承与优先级
|
||
|
||
- **全局样式**：存储在 `anchorGlobalStyle` ref 中，修改时全局锚点刷新。
|
||
- **单个覆盖**：存储在 feature properties 的 `_ov_*` 字段中。`null` 表示继承全局。
|
||
- **渲染合并**：在 `createStyleFunction()` 中执行：`getOv(feature, key, globalValue)` - 有覆盖用覆盖值，否则回退到全局。
|
||
- **恢复默认**：将所有 `_ov_*` 置为 `null`。
|
||
|
||
#### 4.3.3 锚点交互
|
||
|
||
- **勾选显示**：右侧抽屉"基础底图"Tab 提供四类锚点的 Checkbox 组，勾选子类型后地图渲染对应锚点，图例自动更新。
|
||
- **选中与编辑**：
|
||
- **点击地图锚点**：触发选中事件，右侧抽屉自动切换到"锚点样式"Tab 并展开该锚点的详情编辑区域。
|
||
- **右侧面板编辑**：可编辑当前选中锚点的：
|
||
- **经纬度**（支持直接修改并更新地图位置）
|
||
- **显示文字**（修改锚点显示的文本）
|
||
- **更换图标**（上传自定义图标，支持两个选项）
|
||
- **样式覆盖**（每个样式字段独立覆盖全局，支持一键恢复继承）
|
||
- **无气泡 popover**：目前不弹出地图气泡。
|
||
|
||
- **更换图标**：
|
||
- **选项 A - 应用于此锚点**：仅替换当前选中锚点的图标。可选择"添加到图例"，输入父级名称和当前名称，若图例中不存在则自动添加。
|
||
- **选项 B - 应用于所有同类型**：替换当前分类下所有锚点的图标，同时图例中该分类的图标也会更新。
|
||
|
||
- **碰撞检测**：不做碰撞检测与抽稀（`declutterMode: 'none'`）。
|
||
|
||
#### 4.3.4 锚点导入（暂为占位）
|
||
|
||
左侧工具栏【导入】按钮为静态占位，无实际交互逻辑。
|
||
|
||
#### 4.3.5 图标资源映射
|
||
|
||
图标 SVG 文件存放于 `/src/assets/legend/`，通过 `ICON_SVG_MAP`（`useMapStudioState.ts`）建立 icon key 到文件名（不含扩展名）的映射，Vite glob 批量导入获取 URL。
|
||
|
||
### 4.4 图例/标题管理
|
||
|
||
右侧抽屉"图例/标题管理"Tab：
|
||
|
||
#### 4.4.1 图例配置
|
||
|
||
- **显示控制**：`a-checkbox` 控制图例和标题的显隐
|
||
- **图例属性**：位置（左上/左下/右上/右下）、宽度、高度、左边距/右边距、上边距/下边距
|
||
- **图例标题**：对齐方式（左/中/右）、字体、字号、颜色、加粗
|
||
- **子级样式**：字体、字号、颜色、加粗、图标大小
|
||
|
||
#### 4.4.2 标题配置
|
||
|
||
- 标题内容、X/Y 位置、宽度、高度（通过 `BasicControlOptions[1].checked` 控制显隐）
|
||
|
||
### 4.5 锚点全局样式管理
|
||
|
||
右侧抽屉"锚点样式"Tab，在无选中锚点时仅显示"全局样式"配置区：
|
||
|
||
- 字体、字号、颜色、加粗
|
||
- 图标大小
|
||
- 文字描边宽度、描边颜色
|
||
- 文字位置（上/下/左/右）、水平边距、垂直边距
|
||
- 是否显示文字标注
|
||
- **恢复默认**：一键重置为 `DEFAULT_ANCHOR_STYLE`
|
||
|
||
有选中锚点时，顶部显示"当前选中"区域，包含：
|
||
|
||
- 分类标签（含自定义类型名称）
|
||
- 站点名称
|
||
- 经纬度编辑
|
||
- 显示文字编辑
|
||
- 当前图标预览 + 更换图标按钮
|
||
- **样式覆盖**区：每个样式字段独立可调，带"恢复为继承"按钮（×）
|
||
- **恢复默认**：一键清空所有覆盖
|
||
|
||
### 4.6 自定义图形绘制（未实现）
|
||
|
||
预留功能，尚未开发。
|
||
|
||
### 4.7 自定义图片叠加（未实现）
|
||
|
||
预留功能，尚未开发。
|
||
|
||
### 4.8 配图方案管理（未实现）
|
||
|
||
预留功能，尚未开发。
|
||
|
||
## 5. 目录结构与实际代码
|
||
|
||
```
|
||
src/modules/MapStudio/
|
||
├── index.vue # 主入口组件
|
||
├── api/
|
||
│ └── index.ts # 4 类锚点 API 接口
|
||
├── components/
|
||
│ ├── LeftToolbar.vue # 左侧工具栏
|
||
│ ├── RightDrawer.vue # 右侧抽屉
|
||
│ └── Legend.vue # 左下悬浮图例
|
||
├── composables/
|
||
│ ├── useMapStudioState.ts # 共享状态创建/注入
|
||
│ ├── useMapInit.ts # 地图初始化与底图切换
|
||
│ ├── useOverlayLayers.ts # 基础图层叠加管理
|
||
│ └── useAnchorLayers.ts # 锚点图层管理
|
||
└── styles/
|
||
└── index.scss # 模块样式
|
||
```
|
||
|
||
## 6. 核心数据流
|
||
|
||
- **状态管理**：`useMapStudioState.ts` 通过 `createMapStudioState()` 创建所有响应式状态，`provideMapStudioState()` 注入，子组件通过 `injectMapStudioState()` 获取。
|
||
- **锚点图层**：`useAnchorLayers.ts` 管理 4 类锚点的 API 数据加载、OL 图层创建/显隐、样式函数、地图点击选中、样式覆盖同步。
|
||
- **基础图层**：`useOverlayLayers.ts` 管理基础底图的叠加，通过 `LAYER_MAP` 定义各图层的创建工厂，响应式同步勾选状态。
|
||
- **API 层**：`api/index.ts` 定义 4 类锚点的请求参数和接口函数，使用项目通用 `request` 工具（基于 axios）。
|
||
|
||
## 7. 开发注意事项与难点规避
|
||
|
||
- **性能优化**：锚点数量较多（>500）时，务必开启 VectorSource 的 `renderMode: 'vector'`，并批量添加 Features（`source.addFeatures()`）。
|
||
- **样式刷新**：覆盖字段写入 feature 后，必须重新 `setStyle(styleFn)` 触发重绘。
|
||
- **交互冲突**：左侧工具栏按钮需阻止点击事件冒泡，避免触发地图的 `singleclick` 事件。
|
||
- **底图切换**：切换时将新底图 `insertAt(0)` 插入最底层，避免覆盖上层叠加图层。
|
||
- **边界图层**：切换到底图"矢量图"时强制移除边界图层（因矢量图 WMTS 已包含边界信息）。
|
||
- **图标覆盖**：选项 B 替换图标时，通过 `categoryIconOverrides` 存储覆盖 URL，图例组件会读取该字段更新显示。
|
||
|
||
## 8. 未实现功能列表与推荐优先级
|
||
|
||
### 功能完成度概览
|
||
|
||
| 功能模块 | 状态 | 说明 |
|
||
| :--------------------- | :----------- | :------------------------------------------- |
|
||
| 底图切换 | ✅ 已完成 | 4 种底图，边界图层显隐控制 |
|
||
| 基础图层叠加 | ✅ 已完成 | 11 个子图层，分组 Checkbox 勾选控制 |
|
||
| 锚点数据加载与展示 | ✅ 已完成 | 4 类接口初始化加载，勾选渲染，图例自动更新 |
|
||
| 锚点全局样式控制 | ✅ 已完成 | 字体/字号/颜色/加粗/图标大小/描边/位置/边距 |
|
||
| 锚点选中与编辑 | ✅ 已完成 | 点击选中，右侧面板编辑经纬度/文字/样式 |
|
||
| 更换图标（单锚点） | ✅ 已完成 | 上传+添加到图例，自定义类型名称 |
|
||
| 更换图标（同分类） | ✅ 已完成 | 替换全部分类图标，更新图例 |
|
||
| 图例/标题配置 | ✅ 已完成 | 位置/尺寸/对齐/字体/颜色/加粗 |
|
||
| 配图方案管理 | ❌ 未实现 | 保存/加载/历史配图 |
|
||
| 工具栏按钮功能 | ❌ 未实现 | 放大/缩小/全屏/导入/保存按钮均为静态占位 |
|
||
| 自定义图形绘制 | ❌ 未实现 | 线条/箭头/矩形/圆圈 |
|
||
| 自定义图片叠加 | ❌ 未实现 | PNG 上传叠加，调整位置/大小 |
|
||
| 空间范围限定 | ❌ 未实现 | 选择区域并裁切地图 |
|
||
| 锚点拖拽 | ❌ 未实现 | Translate 交互拖动锚点位置 |
|
||
| 选中锚点 popover 气泡 | ❌ 未实现 | 点击锚点在地图弹出小气泡 |
|
||
| 锚点导入功能 | ❌ 未实现 | Excel/CSV 批量导入 |
|
||
|
||
### 推荐开发优先级
|
||
|
||
**P0 - 核心功能（建议优先完成）**
|
||
|
||
1. **配图方案管理** - 这是配图工具的核心闭环功能。左侧【保存】按钮应弹出命名输入框，保存当前所有状态（底图类型、图层显隐、锚点数据与样式覆盖、图例配置、标题配置）为JSON配图方案，并支持历史记录查看、加载、删除。
|
||
- 涉及文件：`LeftToolbar.vue`（接入保存/导入按钮逻辑）、`RightDrawer.vue`（新增加载方案界面）、新建 `useSerializer.ts`（序列化/反序列化）
|
||
- 依赖：需要后端存储接口或本地 localStorage
|
||
|
||
2. **工具栏按钮功能** - 放大/缩小/全屏/导入/保存按钮目前均为静态。放大缩小应绑定 `map.getView().zoom`，全屏应调用 `FullScreen` API，导入按钮应弹出功能弹框。
|
||
- 涉及文件：`LeftToolbar.vue`（接入 mapInstance）
|
||
|
||
**P1 - 重要功能（配图方案之后）**
|
||
|
||
3. **自定义图形绘制** - 利用 `ol/interaction/Draw` 实现线条、矩形、圆圈，以及箭头（起点终点+终点三角头）。图形存入独立 `VectorSource`，支持选中删除。保存配图时需包含图形坐标数据。
|
||
- 涉及文件：新建 `useDrawTools.ts`、`RightDrawer.vue`（新增绘制Tab或面板）
|
||
|
||
4. **自定义图片叠加** - 上传 PNG 图片以绝对定位 div 覆盖在地图上，支持鼠标拖拽移动位置。保存配图时记录 CSS 位置数据。
|
||
- 涉及文件：新建 `CustomImageOverlay.vue`、`RightDrawer.vue`（新增图片管理面板）
|
||
|
||
**P2 - 增强功能（基础功能稳定后）**
|
||
|
||
5. **空间范围限定** - 下拉选择水电基地/流域/省份，地图 fit 至对应边界，并可调用 `clippingPolygons` 实现区域外变灰的裁切效果。
|
||
- 涉及文件：`useMapInit.ts`（扩展）、`RightDrawer.vue`（新增下拉选择）
|
||
|
||
6. **选中锚点气泡 popover** - 点击锚点时在地图弹出轻量 `a-popover` 气泡，显示站点名称和"删除"按钮。
|
||
- 涉及文件：`useAnchorLayers.ts`（点击事件扩展）
|
||
|
||
7. **锚点拖拽** - 启用 `ol/interaction/Translate` 允许拖动锚点改变地理位置，拖拽结束自动更新选中面板的经纬度。
|
||
- 涉及文件：`useAnchorLayers.ts`（添加 Translate 交互）
|
||
|
||
8. **锚点导入** - 左侧【导入】按钮弹出 a-modal 弹框，支持 Excel/CSV 批量导入经纬度数据。
|
||
- 涉及文件：`LeftToolbar.vue`（接入导入弹框）、新建导入逻辑 composable
|
||
|
||
**P3 - 工程优化（可逐步完善）**
|
||
|
||
9. **迁移为 Pinia 状态管理** - 当前使用 `provide`/`inject`，迁移到 Pinia 可更好地支持 Vue Devtools 调试和模块隔离。
|
||
- 涉及文件：新建 `store/mapStudioStore.ts`，调整 `useMapStudioState.ts`
|
||
|
||
10. **目录结构调整** - 将类型定义迁移到 `types/index.ts`，新建 `MapContainer.vue` 独立组件，对外暴露 `index.ts`（app.use 安装）。
|
||
|
||
## 9. 与现有底层地图的集成方案（接入指南）
|
||
|
||
### 9.1 核心原则（禁止叠放）
|
||
|
||
在集成至已有地图项目时，**严禁**使用 `z-index` 将本模块地图叠放于底层地图之上。
|
||
|
||
**原因**：
|
||
|
||
1. **事件冲突**：鼠标滚轮缩放、点击拖拽等事件会同时触发两层地图，导致画面闪烁、缩放倍数混乱。
|
||
2. **性能浪费**：被遮盖的底层地图仍在持续进行瓦片请求和渲染，消耗 CPU/GPU 与网络资源。
|
||
|
||
**正确策略**：必须将底层地图**隐藏/销毁**后，再加载本模块地图。
|
||
|
||
### 9.2 推荐集成方案（二选一）
|
||
|
||
#### 方案 A：隐藏底层容器（推荐，保留底层状态）
|
||
|
||
适用于底层地图涉及复杂的业务交互状态（如选中的点位、高亮区域），退出模块后需无缝恢复。
|
||
|
||
- **进入模块时**：设置底层地图容器的 CSS 样式为 `display: none` 或 `visibility: hidden`。
|
||
- **模块内部**：在底层地图容器同级位置，新建一个绝对定位的 `div` 作为本模块地图的挂载点，初始化 `ol.Map`。
|
||
- **退出模块时**：
|
||
1. 调用本模块地图实例的 `map.dispose()` 销毁地图。
|
||
2. 移除新建的挂载 `div` 元素。
|
||
3. 恢复底层地图容器的显示样式。
|
||
|
||
#### 方案 B：销毁底层地图（更彻底）
|
||
|
||
适用于底层地图仅作展示、无复杂临时状态的场景。
|
||
|
||
- **进入模块时**：直接获取底层地图容器，销毁原有 `ol.Map` 实例（`targetElement.innerHTML = ''`），并复用该容器作为本模块地图的挂载点。
|
||
- **退出模块时**：销毁本模块地图实例，根据业务需求决定是否重新初始化底层地图。
|
||
|
||
### 9.3 解耦约定（确保模块可迁移）
|
||
|
||
由于本模块设计为**独立可迁移**，模块内部代码**严禁**直接操作父级项目的 DOM 元素或地图实例。
|
||
|
||
**正确的通信方式**：本模块 `MapStudio/index.vue` 通过暴露生命周期事件，由父级项目自行控制底层地图的显隐与销毁。
|
||
|
||
```vue
|
||
<!-- 父级项目使用示例 -->
|
||
<template>
|
||
<div id="app">
|
||
<!-- 原有底层地图容器 -->
|
||
<div id="old-map-container" v-show="!showMapStudio"></div>
|
||
|
||
<!-- MapStudio 模块 -->
|
||
<MapStudio
|
||
v-if="showMapStudio"
|
||
@before-mount="handleBeforeMount" <!-- 进入模块时触发 -->
|
||
@after-destroy="handleAfterDestroy" <!-- 退出模块时触发 -->
|
||
/>
|
||
</div>
|
||
</template>
|
||
|
||
<script setup>
|
||
const showMapStudio = ref(false);
|
||
|
||
const handleBeforeMount = () => {
|
||
// 父级在此处执行：隐藏底层地图或销毁其实例
|
||
// 例如：document.getElementById('old-map-container').style.display = 'none';
|
||
};
|
||
|
||
const handleAfterDestroy = () => {
|
||
// 父级在此处执行：恢复底层地图显示或重新初始化
|
||
// 例如：document.getElementById('old-map-container').style.display = 'block';
|
||
};
|
||
</script>
|
||
```
|