# 离线地图与 PMTiles 配置 **本文引用的文件** - [readme.md](file://readme.md) - [offlineMap.ts](file://ai-electron/frontend/src/core/utils/map/offlineMap.ts) - [MapLocalSettingModal.vue](file://ai-electron/frontend/src/core/layouts/default/setting/components/MapLocalSettingModal.vue) - [behavior-spacetime-style.json](file://ai-electron/frontend/public/resource/map/behavior-spacetime-style.json) - [StationMapModal.vue](file://ai-electron/frontend/src/case/views/dm/components/StationMapModal.vue) - [behaviorSpacetime/index.vue](file://ai-electron/frontend/src/trans/views/behaviorSpacetime/index.vue) - [BaseStationQueryMap.vue](file://ai-electron/frontend/src/trans/views/aiBaseStation/components/BaseStationQueryMap.vue) - [authorization/index.vue](file://ai-electron/frontend/src/plat/views/authorization/index.vue) ## 目录 1. [简介](#简介) 2. [项目结构与资源位置](#项目结构与资源位置) 3. [核心组件总览](#核心组件总览) 4. [架构概览](#架构概览) 5. [详细组件分析](#详细组件分析) 6. [许可证校验与地图加载的关系](#许可证校验与地图加载的关系) 7. [依赖关系分析](#依赖关系分析) 8. [使用与扩展指南](#使用与扩展指南) 9. [性能与初始化时机](#性能与初始化时机) 10. [故障排查](#故障排查) 11. [结论](#结论) ## 简介 本说明聚焦前端离线地图与 PMTiles 的配置方式,重点解释以下内容: - 前端如何使用 MapLibre GL 的 PMTiles 协议加载本地 `china.pmtiles`。 - `offlineMap.ts` 如何构建瓦片源、选择本机文件或内置静态资源、读取自定义样式 JSON。 - `MapLocalSettingModal.vue` 如何管理“离线地图瓦片目录”,以及保存后如何通知地图重新加载。 - `readme.md` 中栅格地图模板、PMTiles 转换命令和 `regInfo.exe` 激活说明的含义。 - 许可证有效性与地图加载之间的关系:系统入口会先校验授权状态;只有授权有效时,用户才能继续登录并进入包含地图的业务页面。 - 资源目录 `public/resource/map` 的结构、如何替换 PMTiles 文件或样式,以及如何新增图层或更换离线地图源。 该文档既面向开发者,也面向需要调整离线地图数据或样式的业务维护人员。 ## 项目结构与资源位置 与离线地图直接相关的代码和资源分布如下: | 类别 | 路径 | 作用 | |---|---|---| | 离线地图工具模块 | `ai-electron/frontend/src/core/utils/map/offlineMap.ts` | 提供本机离线地图路径、PMTiles Source 实现、样式读取、目录缓存等能力 | | 地图设置弹窗 | `ai-electron/frontend/src/core/layouts/default/setting/components/MapLocalSettingModal.vue` | 让用户设置本机离线地图目录 | | 行为时空地图页面 | `ai-electron/frontend/src/trans/views/behaviorSpacetime/index.vue` | 使用 PMTiles 加载离线地图,并处理样式解析 | | 案件站点地图弹窗 | `ai-electron/frontend/src/case/views/dm/components/StationMapModal.vue` | 在案件场景中复用离线地图能力 | | 基站查询地图组件 | `ai-electron/frontend/src/trans/views/aiBaseStation/components/BaseStationQueryMap.vue` | 另一个复用离线地图能力的地图组件 | | 默认矢量样式 | `ai-electron/frontend/public/resource/map/behavior-spacetime-style.json` | 内置矢量样式,引用 `pmtiles://resource/map/china.pmtiles` | | 栅格地图示例 | `readme.md` | 提供栅格地图模板、PMTiles 转换命令和 `regInfo.exe` 使用说明 | | 授权入口页 | `ai-electron/frontend/src/plat/views/authorization/index.vue` | 负责设备绑定、机器码获取、离线授权文件和授权校验流程 | ```mermaid graph TB User["用户"] --> AuthorizationPage["授权入口页
authorization/index.vue"] AuthorizationPage --> System["后端服务"] AuthorizationPage --> BusinessPages["业务页面
behaviorSpacetime/index.vue、StationMapModal.vue 等"] BusinessPages --> OfflineMapUtils["离线地图工具
offlineMap.ts"] OfflineMapUtils --> LocalDisk["本机磁盘
china.pmtiles、style.json"] OfflineMapUtils --> StaticResource["内置静态资源
public/resource/map"] OfflineMapUtils --> ElectronIPC["Electron IPC
读二进制范围、读文本文件"] BusinessPages --> MapLibre["MapLibre GL + PMTiles"] ``` **图表来源** - [offlineMap.ts:1-228](file://ai-electron/frontend/src/core/utils/map/offlineMap.ts#L1-L228) - [MapLocalSettingModal.vue:1-153](file://ai-electron/frontend/src/core/layouts/default/setting/components/MapLocalSettingModal.vue#L1-L153) - [behaviorSpacetime/index.vue:2500-2700](file://ai-electron/frontend/src/trans/views/behaviorSpacetime/index.vue#L2500-L2700) - [StationMapModal.vue:180-340](file://ai-electron/frontend/src/case/views/dm/components/StationMapModal.vue#L180-L340) - [authorization/index.vue:340-650](file://ai-electron/frontend/src/plat/views/authorization/index.vue#L340-L650) **章节来源** - [offlineMap.ts:1-228](file://ai-electron/frontend/src/core/utils/map/offlineMap.ts#L1-L228) - [MapLocalSettingModal.vue:1-153](file://ai-electron/frontend/src/core/layouts/default/setting/components/MapLocalSettingModal.vue#L1-L153) - [behavior-spacetime-style.json:1-200](file://ai-electron/frontend/public/resource/map/behavior-spacetime-style.json#L1-L200) - [readme.md:1-76](file://readme.md#L1-L76) ## 核心组件总览 ### offlineMap.ts:离线地图工具模块 `offlineMap.ts` 是离线地图的前端核心工具模块,主要职责包括: 1. **定义离线地图目录键和事件名** - 本地存储键:`OFFLINE_MAP_DIR__` - 目录变更事件:`offline-map-dir-changed` 2. **计算内置 PMTiles 地址** - `getBuiltinPmtilesUrl()` 返回 `public/resource/map/china.pmtiles` 对应的 Web URL。 - 当没有配置本机离线地图目录时,地图会回退到该内置地址。 3. **构造本机离线地图路径** - `getOfflineMapFilePath(fileName)` 根据当前配置的离线地图目录拼接文件名。 - `getOfflineMapPmtilesPath()` 固定取 `china.pmtiles`。 - `getOfflineMapStylePath()` 固定取 `behavior-spacetime-style.json`。 4. **实现两种 PMTiles Source** - `ElectronPmtilesSource`:用于本机绝对路径,通过 IPC `readBinaryFileRange` 分块读取 `.pmtiles` 文件。 - `HttpPmtilesSource`:用于 Web 静态资源 URL,通过 HTTP `Range` 请求加载瓦片。 5. **选择 Source 类型** - `isLocalFilePath()` 判断目标是否为本机绝对路径(Windows 盘符、UNC 路径或 POSIX 路径)。 - `createPmtilesSource(target)` 按路径类型创建对应 Source。 6. **注册离线 PMTiles 源** - `resolveOfflinePmtilesSources()` 优先使用本机目录中的 `china.pmtiles`,否则使用内置静态资源。 7. **读取自定义样式文本** - `readOfflineMapStyleText()` 通过 IPC `readTextFile` 读取本机目录下的 `behavior-spacetime-style.json`。 - 失败时返回空字符串,调用方应回退到内置样式。 8. **管理离线地图目录缓存** - `getOfflineMapDir()` / `setOfflineMapDir(path)` / `clearOfflineMapDir()` 操作 `localStorage`。 - 写入成功后派发 `offline-map-dir-changed` 事件,已打开的地图组件监听该事件后重新加载。 9. **路径规范化与 URL 转换** - `isValidOfflineMapPath()` 校验路径格式。 - `buildFileUrl()` / `toLocalMapUrl()` 把本机路径转换为内部协议或 `file://` URL,供样式源使用。 **章节来源** - [offlineMap.ts:1-228](file://ai-electron/frontend/src/core/utils/map/offlineMap.ts#L1-L228) ### MapLocalSettingModal.vue:地图本地设置弹窗 该弹窗负责管理“离线地图瓦片目录”,但不直接读写服务端配置: - 提示用户在本机目录下放置 `china.pmtiles`,可选放置 `behavior-spacetime-style.json`。 - 提供输入框和“选择目录”按钮。 - 非桌面客户端下禁用操作,并给出提示。 - 打开弹窗时调用 `getLocalMapDir()` 读取本机配置。 - 保存时调用 `saveLocalMapDir(next)`,成功后调用 `setOfflineMapDir(saved)` 更新前端缓存。 - 保存成功后派发 `offline-map-dir-changed` 事件,使已打开的地图组件重新登记瓦片源并刷新。 ```mermaid flowchart TD Open["打开地图设置弹窗"] --> Load["读取本机地图目录"] Load --> Pick["用户选择目录或手动输入"] Pick --> Save["调用 saveLocalMapDir 保存到本机"] Save --> Cache["setOfflineMapDir 更新前端缓存"] Cache --> Event["派发 offline-map-dir-changed 事件"] Event --> Refresh["地图组件重新加载离线地图"] ``` **图表来源** - [MapLocalSettingModal.vue:1-153](file://ai-electron/frontend/src/core/layouts/default/setting/components/MapLocalSettingModal.vue#L1-L153) - [offlineMap.ts:170-228](file://ai-electron/frontend/src/core/utils/map/offlineMap.ts#L170-L228) **章节来源** - [MapLocalSettingModal.vue:1-153](file://ai-electron/frontend/src/core/layouts/default/setting/components/MapLocalSettingModal.vue#L1-L153) ### behavior-spacetime-style.json:默认矢量样式 该样式文件位于 `public/resource/map/behavior-spacetime-style.json`,是一个符合 MapLibre Style Spec v8 的样式: - 名称为 `behavior-spacetime-offline-template`。 - 主数据源名为 `behavior-basemap`,类型为矢量源。 - 瓦片地址为 `pmtiles://resource/map/china.pmtiles`。 - 定义了多个图层,例如地形覆盖、土地利用、公园、水域、水系、边界、道路、地名标注等。 - 样式中使用的 `source-layer` 必须与 `china.pmtiles` 中矢量层一致。 注意:仓库根目录 `readme.md` 中还包含一个“栅格地图配置”示例,其 `sources.behavior-basemap.type` 是 `raster`,这与实际默认样式中的 `vector` 不同。实际项目中应以 `public/resource/map/behavior-spacetime-style.json` 为准;`readme.md` 更适合作为生成 PMTiles 时的参考模板。 **章节来源** - [behavior-spacetime-style.json:1-200](file://ai-electron/frontend/public/resource/map/behavior-spacetime-style.json#L1-L200) - [readme.md:1-76](file://readme.md#L1-L76) ## 架构概览 下图展示从用户访问系统到加载离线地图的关键流程: ```mermaid sequenceDiagram participant User as "用户" participant Auth as "授权入口页" participant Server as "后端服务" participant Page as "地图业务页面" participant Utils as "offlineMap.ts" participant Disk as "本机磁盘或静态资源" participant Map as "MapLibre GL + PMTiles" User->>Auth: 打开应用 Auth->>Server: 检查授权状态 Server-->>Auth: 返回授权结果 alt 授权无效或未授权 Auth-->>User: 显示授权卡片 else 授权有效 Auth->>Page: 进入业务页面 Page->>Utils: 获取离线地图目录和 PMTiles 路径 Utils->>Disk: 读取 china.pmtiles 或 style.json Page->>Map: 注册 PMTiles Source 并加载样式 Map-->>User: 渲染离线地图 end ``` **图表来源** - [authorization/index.vue:340-650](file://ai-electron/frontend/src/plat/views/authorization/index.vue#L340-L650) - [behaviorSpacetime/index.vue:2500-2700](file://ai-electron/frontend/src/trans/views/behaviorSpacetime/index.vue#L2500-L2700) - [StationMapModal.vue:180-340](file://ai-electron/frontend/src/case/views/dm/components/StationMapModal.vue#L180-L340) - [offlineMap.ts:110-170](file://ai-electron/frontend/src/core/utils/map/offlineMap.ts#L110-L170) ## 详细组件分析 ### 离线地图瓦片源构建流程 `offlineMap.ts` 提供了两套 PMTiles Source 实现,并根据目标路径自动选择: | 场景 | 路径形式 | Source 类型 | 数据来源 | |---|---|---|---| | 本机离线地图 | Windows 盘符、UNC、POSIX 绝对路径 | `ElectronPmtilesSource` | IPC `readBinaryFileRange` 从磁盘分块读取 | | 内置静态资源 | `http(s)://` 或相对 URL | `HttpPmtilesSource` | HTTP `Range` 请求 `public/resource/map/china.pmtiles` | `resolveOfflinePmtilesSources()` 的优先级如下: 1. 如果 `getOfflineMapDir()` 有值且能拼出 `china.pmtiles` 路径,则注册本机 PMTiles 源。 2. 始终注册内置 `public/resource/map/china.pmtiles` 作为兜底源。 这样做的意义是:未配置本机目录时,仍可加载内置离线地图;配置了本机目录后,优先使用用户指定的本地 PMTiles 文件。 ```mermaid flowchart TD Start["开始构建离线 PMTiles 源"] --> CheckDir["检查 getOfflineMapDir()"] CheckDir --> HasDir{"是否配置本机目录?"} HasDir -->|是| AddLocal["添加本机 china.pmtiles 源"] HasDir -->|否| SkipLocal["跳过本机源"] AddLocal --> AddBuiltIn["添加内置 resource/map/china.pmtiles 源"] SkipLocal --> AddBuiltIn AddBuiltIn --> End["返回 PMTiles 源列表"] ``` **图表来源** - [offlineMap.ts:110-130](file://ai-electron/frontend/src/core/utils/map/offlineMap.ts#L110-L130) **章节来源** - [offlineMap.ts:1-228](file://ai-electron/frontend/src/core/utils/map/offlineMap.ts#L1-L228) ### 样式加载与回退策略 地图页面在 `resolveStyle()` 中采用以下顺序选择样式: 1. **优先尝试本机自定义样式** - 如果存在离线地图目录、`china.pmtiles` 路径和样式路径,则调用 `readOfflineMapStyleText()` 读取 `behavior-spacetime-style.json`。 - 成功解析后使用该样式。 2. **回退到外部模板样式** - 如果本机样式为空,则构造一个内嵌的“外部地图样式”,其数据源指向本机 `china.pmtiles`。 3. **再回退到脚本注入或静态样式 URL** - 支持通过全局变量或样式 URL 注入自定义样式对象。 - 最后尝试从 `public/resource/map/behavior-spacetime-style.json` 拉取默认样式。 4. **最终回退到最小背景样式** - 所有样式解析失败时,返回只含背景层的 fallback 样式。 这种设计确保即使离线样式不可用,地图也不会完全崩溃,而是至少显示一个空白背景。 ```mermaid flowchart TD Start["解析地图样式"] --> TryOfflineStyle["尝试读取本机 behavior-spacetime-style.json"] TryOfflineStyle --> OfflineOk{"解析成功?"} OfflineOk -->|是| UseOffline["使用本机样式"] OfflineOk -->|否| BuildExternal["构造外部地图样式"] BuildExternal --> ExternalOk{"是否有本机 PMTiles?"} ExternalOk -->|是| UseExternal["使用外部模板样式"] ExternalOk -->|否| TryCustom["尝试脚本注入或静态样式 URL"] TryCustom --> CustomOk{"可获取样式?"} CustomOk -->|是| UseCustom["使用自定义样式"] CustomOk -->|否| Fallback["返回最小背景样式"] ``` **图表来源** - [behaviorSpacetime/index.vue:2601-2700](file://ai-electron/frontend/src/trans/views/behaviorSpacetime/index.vue#L2601-L2700) - [StationMapModal.vue:292-340](file://ai-electron/frontend/src/case/views/dm/components/StationMapModal.vue#L292-L340) **章节来源** - [behaviorSpacetime/index.vue:2500-2700](file://ai-electron/frontend/src/trans/views/behaviorSpacetime/index.vue#L2500-L2700) - [StationMapModal.vue:180-340](file://ai-electron/frontend/src/case/views/dm/components/StationMapModal.vue#L180-L340) ### PMTiles 协议与路径映射 样式中的 PMTiles 地址通常形如: ``` pmtiles://resource/map/china.pmtiles ``` `normalizePmtilesSources()` 会将样式中的 `pmtiles://` 地址转换为: - 如果配置了本机离线地图目录,则使用本机绝对路径。 - 否则使用内置静态资源 URL。 关键规则: - 样式中的 `source.url` 必须以 `pmtiles://` 开头才会被替换。 - 替换后的 key 必须与 `resolveOfflinePmtilesSources()` 注册的 source key 一致。 - 本机路径会被包装成内部协议或 `file://` URL,再由 `ElectronPmtilesSource` 或 `HttpPmtilesSource` 消费。 ```mermaid flowchart TD Style["样式中的 pmtiles:// 地址"] --> Normalize["normalizePmtilesSources 处理"] Normalize --> PathType{"是否配置本机目录?"} PathType -->|是| LocalKey["使用本机绝对路径作为 key"] PathType -->|否| StaticKey["使用内置静态资源 URL 作为 key"] LocalKey --> Register["注册 ElectronPmtilesSource"] StaticKey --> Register Register --> MapLoad["MapLibre 加载瓦片"] ``` **图表来源** - [behaviorSpacetime/index.vue:2643-2690](file://ai-electron/frontend/src/trans/views/behaviorSpacetime/index.vue#L2643-L2690) - [StationMapModal.vue:180-210](file://ai-electron/frontend/src/case/views/dm/components/StationMapModal.vue#L180-L210) - [offlineMap.ts:100-130](file://ai-electron/frontend/src/core/utils/map/offlineMap.ts#L100-L130) **章节来源** - [behaviorSpacetime/index.vue:2643-2690](file://ai-electron/frontend/src/trans/views/behaviorSpacetime/index.vue#L2643-L2690) - [StationMapModal.vue:180-210](file://ai-electron/frontend/src/case/views/dm/components/StationMapModal.vue#L180-L210) - [offlineMap.ts:100-130](file://ai-electron/frontend/src/core/utils/map/offlineMap.ts#L100-L130) ## 许可证校验与地图加载的关系 ### readme.md 中的许可证说明 `readme.md` 中包含三类内容: 1. **栅格地图配置示例** 提供一个栅格地图模板,其中 `sources.behavior-basemap.type` 为 `raster`,瓦片地址为 `pmtiles://resource/map/china.pmtiles`。这是生成 PMTiles 时的参考模板,不是本项目默认样式。 2. **metadata.json 示例** 描述 MBTiles 元数据字段,如名称、版本、格式、最小缩放级别、最大缩放级别。 3. **PMTiles 转换命令** 使用 `pmtiles.exe convert light.mbtiles china.pmtiles` 将 MBTiles 转为 PMTiles,并用 `pmtiles.exe show china.pmtiles` 查看内容。 4. **regInfo.exe 激活说明** 提供机器码查询、许可证读取、字段查看和有效性验证命令,并列出常见错误码: - `0`:许可证有效。 - `10001`:许可证文件无效。 - `10002`:许可证过期。 - `10004`:机器码不匹配。 ### 前端授权流程 前端授权入口页 `authorization/index.vue` 的流程如下: 1. 首次启动时判断是否需要绑定后端服务地址。 2. 调用 `checkAuthApi()` 检查设备授权状态。 3. 如果授权无效或过期,进入“离线授权”模式。 4. 用户选择 `.xlts` 授权文件后调用 `offlineAuthorizationApi` 提交离线授权。 5. 授权成功后刷新授权摘要,并根据登录态决定进入业务页面或登录页。 因此,“许可证有效”是进入业务页面的前置条件。虽然离线地图加载本身由 `offlineMap.ts` 控制,但**用户只有在授权通过后才能到达使用离线地图的业务页面**。 ```mermaid flowchart TD Start["应用启动"] --> BindServer["绑定后端服务地址"] BindServer --> CheckAuth["调用 checkAuthApi 检查授权"] CheckAuth --> Authorized{"授权有效?"} Authorized -->|否| ShowLicenseCard["显示离线授权卡片"] ShowLicenseCard --> UploadLicense["上传 .xlts 授权文件"] UploadLicense --> OfflineAuth["调用 offlineAuthorizationApi"] OfflineAuth --> Recheck["刷新授权摘要"] Recheck --> LoginOrBusiness["无 token 进入登录页
有 token 进入业务页"] Authorized -->|是| TokenCheck{"已有登录令牌?"} TokenCheck -->|是| Business["进入业务页面"] TokenCheck -->|否| Login["进入登录页"] ``` **图表来源** - [authorization/index.vue:340-650](file://ai-electron/frontend/src/plat/views/authorization/index.vue#L340-L650) **章节来源** - [readme.md:1-76](file://readme.md#L1-L76) - [authorization/index.vue:340-650](file://ai-electron/frontend/src/plat/views/authorization/index.vue#L340-L650) ## 依赖关系分析 ### 组件依赖图 ```mermaid graph LR OfflineMap["offlineMap.ts"] --> Ipc["Electron IPC"] OfflineMap --> LocalStorage["localStorage"] MapLocalSetting["MapLocalSettingModal.vue"] --> OfflineMap BehaviorSpacetime["behaviorSpacetime/index.vue"] --> OfflineMap StationMap["StationMapModal.vue"] --> OfflineMap BaseStation["BaseStationQueryMap.vue"] --> OfflineMap Authorization["authorization/index.vue"] --> Business["业务页面"] Business --> OfflineMap ``` **图表来源** - [offlineMap.ts:1-228](file://ai-electron/frontend/src/core/utils/map/offlineMap.ts#L1-L228) - [MapLocalSettingModal.vue:1-153](file://ai-electron/frontend/src/core/layouts/default/setting/components/MapLocalSettingModal.vue#L1-L153) - [behaviorSpacetime/index.vue:2500-2700](file://ai-electron/frontend/src/trans/views/behaviorSpacetime/index.vue#L2500-L2700) - [StationMapModal.vue:180-340](file://ai-electron/frontend/src/case/views/dm/components/StationMapModal.vue#L180-L340) - [BaseStationQueryMap.vue:1-250](file://ai-electron/frontend/src/trans/views/aiBaseStation/components/BaseStationQueryMap.vue#L1-L250) - [authorization/index.vue:340-650](file://ai-electron/frontend/src/plat/views/authorization/index.vue#L340-L650) ### 耦合性说明 - `offlineMap.ts` 是低层工具模块,被多个地图组件复用。 - `MapLocalSettingModal.vue` 只负责持久化本机目录,不关心地图具体渲染逻辑。 - 地图页面通过 `offline-map-dir-changed` 事件解耦目录变更与地图刷新。 - 授权流程与地图加载属于两条链路:授权控制能否进入业务页面,地图加载控制是否能渲染离线瓦片。 **章节来源** - [offlineMap.ts:1-228](file://ai-electron/frontend/src/core/utils/map/offlineMap.ts#L1-L228) - [MapLocalSettingModal.vue:1-153](file://ai-electron/frontend/src/core/layouts/default/setting/components/MapLocalSettingModal.vue#L1-L153) - [behaviorSpacetime/index.vue:2500-2700](file://ai-electron/frontend/src/trans/views/behaviorSpacetime/index.vue#L2500-L2700) ## 使用与扩展指南 ### 资源目录 public/resource/map 结构 建议保持以下结构: | 路径 | 用途 | |---|---| | `public/resource/map/china.pmtiles` | 内置离线 PMTiles 数据文件 | | `public/resource/map/behavior-spacetime-style.json` | 内置矢量样式文件 | 如果需要在运行时使用本机离线地图,则在用户选择的目录中放置: | 文件 | 必需性 | |---|---| | `china.pmtiles` | 启用本机离线地图时必须存在 | | `behavior-spacetime-style.json` | 可选,用于覆盖默认样式 | ### 替换 china.pmtiles 步骤: 1. 准备新的 PMTiles 文件。 2. 如果使用内置资源,替换 `public/resource/map/china.pmtiles`。 3. 如果使用本机目录,将新文件放入用户配置的离线地图目录。 4. 确保样式中的 `source.url` 指向该 PMTiles 文件。 5. 如果是矢量 PMTiles,确认样式中的 `source-layer` 与新数据中的图层名称一致。 注意:`readme.md` 提供的栅格地图模板是 `type: raster`,而默认样式是 `type: vector`。替换矢量 PMTiles 时应以矢量样式为准;替换栅格 PMTiles 时需要改用栅格样式模板。 ### 更换离线地图源 如果需要让某个地图页面加载不同的 PMTiles 源,可以在样式中修改对应 source 的 `url`,并在 `normalizePmtilesSources()` 处理时确保 key 与注册源一致。典型做法: - 在样式中使用 `pmtiles://...` 引用瓦片。 - 通过 `resolveOfflinePmtilesSources()` 注册该 key 对应的 Source。 - 如果希望强制覆盖某个样式中的 PMTiles 地址,可在 `normalizePmtilesSources()` 的 `overridePmtilesUrl` 参数中传入新地址。 ### 新增地图图层 新增图层时需要注意: 1. 图层必须引用已有的 source,通常是 `behavior-basemap`。 2. 矢量图层必须指定正确的 `source-layer`。 3. 样式表达式中的字段名必须与 PMTiles 数据字段一致。 4. 如果是新增 PMTiles 数据,需同步更新样式、Source 注册和可能的颜色/透明度配置。 示例思路: - 在样式 `layers` 数组中添加新图层。 - 若新增独立 PMTiles,新增一个 source,并为其注册 `ElectronPmtilesSource` 或 `HttpPmtilesSource`。 - 在地图初始化后按需开启或关闭图层可见性。 ### 调试地图加载失败的步骤 推荐按以下顺序排查: 1. 确认是否已完成授权并通过登录进入业务页面。 2. 确认是否配置了本机离线地图目录,或是否存在内置 `china.pmtiles`。 3. 检查样式是否成功解析。 4. 检查 PMTiles 源是否已注册。 5. 检查浏览器控制台和网络面板中的 Range 请求或 IPC 调用。 6. 检查样式 JSON 是否合法。 7. 检查 PMTiles 文件的 `source-layer` 是否与样式一致。 **章节来源** - [behavior-spacetime-style.json:1-200](file://ai-electron/frontend/public/resource/map/behavior-spacetime-style.json#L1-L200) - [offlineMap.ts:1-228](file://ai-electron/frontend/src/core/utils/map/offlineMap.ts#L1-L228) - [readme.md:1-76](file://readme.md#L1-L76) ## 性能与初始化时机 ### 初始化时机 离线地图相关初始化通常发生在地图页面或地图组件挂载时: 1. 页面或组件创建 MapLibre map 实例。 2. 调用 `ensureOfflinePmtilesArchive()` 或类似逻辑,将 `resolveOfflinePmtilesSources()` 返回的源注册到 PMTiles 协议管理器。 3. 调用 `resolveStyle()` 解析样式。 4. 将样式和源应用到 map。 5. 如需动态切换目录,监听 `offline-map-dir-changed` 事件后重新执行上述步骤。 ### 性能特性 - 本机 PMTiles 通过 `ElectronPmtilesSource` 使用 `readBinaryFileRange` 分块读取,避免一次性加载整个 `.pmtiles` 文件。 - 内置 PMTiles 通过 `HttpPmtilesSource` 使用 HTTP `Range` 请求,适合部署环境下的静态资源访问。 - 样式读取失败时不会中断地图初始化,而是回退到外层样式或最小背景样式。 - 目录变更通过事件触发局部刷新,而不是强制重启整个应用。 **章节来源** - [behaviorSpacetime/index.vue:2500-2520](file://ai-electron/frontend/src/trans/views/behaviorSpacetime/index.vue#L2500-L2520) - [offlineMap.ts:40-100](file://ai-electron/frontend/src/core/utils/map/offlineMap.ts#L40-L100) ## 故障排查 ### china.pmtiles 无法加载 可能原因: - 本机目录中没有 `china.pmtiles`。 - 内置 `public/resource/map/china.pmtiles` 缺失。 - 本机路径未被正确识别为本地路径。 - PMTiles 文件格式损坏。 - 样式中 source key 与实际注册 key 不一致。 排查建议: 1. 检查 `getOfflineMapDir()` 是否返回有效路径。 2. 检查 `getOfflineMapPmtilesPath()` 是否指向真实文件。 3. 检查控制台是否出现 IPC 读取失败。 4. 使用 `pmtiles.exe show china.pmtiles` 验证 PMTiles 文件可读。 5. 确认样式中 source 的 key 与 `resolveOfflinePmtilesSources()` 返回的 key 一致。 **章节来源** - [offlineMap.ts:9-25](file://ai-electron/frontend/src/core/utils/map/offlineMap.ts#L9-L25) - [offlineMap.ts:40-130](file://ai-electron/frontend/src/core/utils/map/offlineMap.ts#L40-L130) - [readme.md:1-76](file://readme.md#L1-L76) ### 样式 JSON 报错 可能原因: - 本机 `behavior-spacetime-style.json` 语法非法。 - 样式引用了不存在的 `source-layer`。 - 样式中的 PMTiles 地址无法解析。 - 样式文件编码异常。 排查建议: 1. 先清空本机样式目录,确认内置样式是否正常。 2. 将本机样式复制一份,逐步删除图层定位问题。 3. 检查 `JSON.parse` 是否抛出异常。 4. 检查样式中的 `source-layer` 是否与 PMTiles 实际图层一致。 **章节来源** - [behaviorSpacetime/index.vue:2601-2700](file://ai-electron/frontend/src/trans/views/behaviorSpacetime/index.vue#L2601-L2700) - [StationMapModal.vue:292-340](file://ai-electron/frontend/src/case/views/dm/components/StationMapModal.vue#L292-L340) - [behavior-spacetime-style.json:1-200](file://ai-electron/frontend/public/resource/map/behavior-spacetime-style.json#L1-L200) ### 地图空白 可能原因: - 地图处于 fallback 模式。 - PMTiles 源未注册。 - 样式解析失败。 - 授权未通过,导致未能进入业务页面。 - 本机目录配置为空,且内置资源不可用。 排查建议: 1. 检查是否已成功授权并进入业务页面。 2. 检查 `resolveStyle()` 是否返回 fallback 样式。 3. 检查 PMTiles 源是否已注册。 4. 检查浏览器控制台网络请求。 5. 确认样式中的 background 颜色是否过于透明或与屏幕背景相近。 **章节来源** - [authorization/index.vue:340-650](file://ai-electron/frontend/src/plat/views/authorization/index.vue#L340-L650) - [behaviorSpacetime/index.vue:2601-2700](file://ai-electron/frontend/src/trans/views/behaviorSpacetime/index.vue#L2601-L2700) ### 许可证无效导致地图禁用 这里的“禁用”应理解为:**用户停留在授权入口页,无法进入包含地图的业务页面**。 可能原因: - 未绑定后端服务地址。 - `checkAuthApi()` 返回非 200。 - 授权文件过期。 - 机器码不匹配。 - 选择了无效的 `.xlts` 授权文件。 排查建议: 1. 检查是否显示“离线授权”卡片。 2. 检查 `checkAuthApi()` 响应。 3. 使用 `regInfo.exe -f licensefile -verify` 验证许可证。 4. 确认授权文件后缀为 `.xlts`。 5. 确认机器码与授权文件匹配。 **章节来源** - [readme.md:1-76](file://readme.md#L1-L76) - [authorization/index.vue:340-650](file://ai-electron/frontend/src/plat/views/authorization/index.vue#L340-L650) ### PMTiles 路径错误 可能原因: - 本机路径格式不被 `isLocalFilePath()` 识别。 - 路径末尾多或少反斜杠。 - 样式中的 `pmtiles://` 地址没有被正确替换。 - 使用了远程 URL,却期望走本机 IPC 读取。 排查建议: 1. 检查 `getOfflineMapDir()` 返回值。 2. 检查 `getOfflineMapPmtilesPath()` 返回值。 3. 检查 `isLocalFilePath()` 判定结果。 4. 检查样式中 source url 是否以 `pmtiles://` 开头。 5. 检查 `normalizePmtilesSources()` 是否正确重写地址。 **章节来源** - [offlineMap.ts:100-130](file://ai-electron/frontend/src/core/utils/map/offlineMap.ts#L100-L130) - [behaviorSpacetime/index.vue:2643-2690](file://ai-electron/frontend/src/trans/views/behaviorSpacetime/index.vue#L2643-L2690) ## 结论 离线地图功能由三个层次组成: 1. **授权层**:通过 `authorization/index.vue` 完成设备绑定、机器码获取和离线授权校验。只有授权有效,用户才能进入业务页面。 2. **配置层**:通过 `MapLocalSettingModal.vue` 和本地存储保存本机离线地图目录;`offlineMap.ts` 负责路径规范化、Source 选择和样式读取。 3. **渲染层**:地图页面使用 MapLibre GL 和 PMTiles,优先加载本机 PMTiles 和样式,否则回退到内置静态资源。 要扩展或替换离线地图,核心原则是: - 保持 PMTiles 文件与样式中的 `source-layer` 一致。 - 保持样式中的 PMTiles key 与 `resolveOfflinePmtilesSources()` 注册的 key 一致。 - 本机路径必须能被 `isLocalFilePath()` 识别。 - 授权必须先通过,否则用户无法进入使用离线地图的业务页面。