离线地图与 PMTiles 配置

本文引用的文件

readme.md
offlineMap.ts
MapLocalSettingModal.vue
behavior-spacetime-style.json
StationMapModal.vue
behaviorSpacetime/index.vue
BaseStationQueryMap.vue
authorization/index.vue

简介

本说明聚焦前端离线地图与 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`	负责设备绑定、机器码获取、离线授权文件和授权校验流程

graph TB
    User["用户"] --> AuthorizationPage["授权入口页<br/>authorization/index.vue"]
    AuthorizationPage --> System["后端服务"]
    AuthorizationPage --> BusinessPages["业务页面<br/>behaviorSpacetime/index.vue、StationMapModal.vue 等"]
    BusinessPages --> OfflineMapUtils["离线地图工具<br/>offlineMap.ts"]
    OfflineMapUtils --> LocalDisk["本机磁盘<br/>china.pmtiles、style.json"]
    OfflineMapUtils --> StaticResource["内置静态资源<br/>public/resource/map"]
    OfflineMapUtils --> ElectronIPC["Electron IPC<br/>读二进制范围、读文本文件"]
    BusinessPages --> MapLibre["MapLibre GL + PMTiles"]

图表来源

offlineMap.ts:1-228
MapLocalSettingModal.vue:1-153
behaviorSpacetime/index.vue:2500-2700
StationMapModal.vue:180-340
authorization/index.vue:340-650

章节来源

offlineMap.ts:1-228
MapLocalSettingModal.vue:1-153
behavior-spacetime-style.json:1-200
readme.md:1-76

核心组件总览

offlineMap.ts：离线地图工具模块

offlineMap.ts 是离线地图的前端核心工具模块，主要职责包括：

定义离线地图目录键和事件名
- 本地存储键：OFFLINE_MAP_DIR__
- 目录变更事件：offline-map-dir-changed
计算内置 PMTiles 地址
- getBuiltinPmtilesUrl() 返回 public/resource/map/china.pmtiles 对应的 Web URL。
- 当没有配置本机离线地图目录时，地图会回退到该内置地址。
构造本机离线地图路径
- getOfflineMapFilePath(fileName) 根据当前配置的离线地图目录拼接文件名。
- getOfflineMapPmtilesPath() 固定取 china.pmtiles。
- getOfflineMapStylePath() 固定取 behavior-spacetime-style.json。
实现两种 PMTiles Source
- ElectronPmtilesSource：用于本机绝对路径，通过 IPC readBinaryFileRange 分块读取 .pmtiles 文件。
- HttpPmtilesSource：用于 Web 静态资源 URL，通过 HTTP Range 请求加载瓦片。
选择 Source 类型
- isLocalFilePath() 判断目标是否为本机绝对路径（Windows 盘符、UNC 路径或 POSIX 路径）。
- createPmtilesSource(target) 按路径类型创建对应 Source。
注册离线 PMTiles 源
- resolveOfflinePmtilesSources() 优先使用本机目录中的 china.pmtiles，否则使用内置静态资源。
读取自定义样式文本
- readOfflineMapStyleText() 通过 IPC readTextFile 读取本机目录下的 behavior-spacetime-style.json。
- 失败时返回空字符串，调用方应回退到内置样式。
管理离线地图目录缓存
- getOfflineMapDir() / setOfflineMapDir(path) / clearOfflineMapDir() 操作 localStorage。
- 写入成功后派发 offline-map-dir-changed 事件，已打开的地图组件监听该事件后重新加载。
路径规范化与 URL 转换
- isValidOfflineMapPath() 校验路径格式。
- buildFileUrl() / toLocalMapUrl() 把本机路径转换为内部协议或 file:// URL，供样式源使用。

章节来源

offlineMap.ts:1-228

MapLocalSettingModal.vue：地图本地设置弹窗

该弹窗负责管理“离线地图瓦片目录”，但不直接读写服务端配置：

提示用户在本机目录下放置 china.pmtiles，可选放置 behavior-spacetime-style.json。
提供输入框和“选择目录”按钮。
非桌面客户端下禁用操作，并给出提示。
打开弹窗时调用 getLocalMapDir() 读取本机配置。
保存时调用 saveLocalMapDir(next)，成功后调用 setOfflineMapDir(saved) 更新前端缓存。

保存成功后派发 offline-map-dir-changed 事件，使已打开的地图组件重新登记瓦片源并刷新。

flowchart TD
Open["打开地图设置弹窗"] --> Load["读取本机地图目录"]
Load --> Pick["用户选择目录或手动输入"]
Pick --> Save["调用 saveLocalMapDir 保存到本机"]
Save --> Cache["setOfflineMapDir 更新前端缓存"]
Cache --> Event["派发 offline-map-dir-changed 事件"]
Event --> Refresh["地图组件重新加载离线地图"]

图表来源

MapLocalSettingModal.vue:1-153
offlineMap.ts:170-228

章节来源

MapLocalSettingModal.vue:1-153

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
readme.md:1-76

架构概览

下图展示从用户访问系统到加载离线地图的关键流程：

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
behaviorSpacetime/index.vue:2500-2700
StationMapModal.vue:180-340
offlineMap.ts:110-170

详细组件分析

离线地图瓦片源构建流程

offlineMap.ts 提供了两套 PMTiles Source 实现，并根据目标路径自动选择：

场景	路径形式	Source 类型	数据来源
本机离线地图	Windows 盘符、UNC、POSIX 绝对路径	`ElectronPmtilesSource`	IPC `readBinaryFileRange` 从磁盘分块读取
内置静态资源	`http(s)://` 或相对 URL	`HttpPmtilesSource`	HTTP `Range` 请求 `public/resource/map/china.pmtiles`

resolveOfflinePmtilesSources() 的优先级如下：

如果 getOfflineMapDir() 有值且能拼出 china.pmtiles 路径，则注册本机 PMTiles 源。
始终注册内置 public/resource/map/china.pmtiles 作为兜底源。

这样做的意义是：未配置本机目录时，仍可加载内置离线地图；配置了本机目录后，优先使用用户指定的本地 PMTiles 文件。

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

章节来源

offlineMap.ts:1-228

样式加载与回退策略

地图页面在 resolveStyle() 中采用以下顺序选择样式：

优先尝试本机自定义样式
- 如果存在离线地图目录、china.pmtiles 路径和样式路径，则调用 readOfflineMapStyleText() 读取 behavior-spacetime-style.json。
- 成功解析后使用该样式。
回退到外部模板样式
- 如果本机样式为空，则构造一个内嵌的“外部地图样式”，其数据源指向本机 china.pmtiles。
再回退到脚本注入或静态样式 URL
- 支持通过全局变量或样式 URL 注入自定义样式对象。
- 最后尝试从 public/resource/map/behavior-spacetime-style.json 拉取默认样式。
最终回退到最小背景样式
- 所有样式解析失败时，返回只含背景层的 fallback 样式。

这种设计确保即使离线样式不可用，地图也不会完全崩溃，而是至少显示一个空白背景。

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
StationMapModal.vue:292-340

章节来源

behaviorSpacetime/index.vue:2500-2700
StationMapModal.vue:180-340

PMTiles 协议与路径映射

样式中的 PMTiles 地址通常形如：

pmtiles://resource/map/china.pmtiles

normalizePmtilesSources() 会将样式中的 pmtiles:// 地址转换为：

如果配置了本机离线地图目录，则使用本机绝对路径。
否则使用内置静态资源 URL。

关键规则：

样式中的 source.url 必须以 pmtiles:// 开头才会被替换。
替换后的 key 必须与 resolveOfflinePmtilesSources() 注册的 source key 一致。

本机路径会被包装成内部协议或 file:// URL，再由 ElectronPmtilesSource 或 HttpPmtilesSource 消费。

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
StationMapModal.vue:180-210
offlineMap.ts:100-130

章节来源

behaviorSpacetime/index.vue:2643-2690
StationMapModal.vue:180-210
offlineMap.ts:100-130

许可证校验与地图加载的关系

readme.md 中的许可证说明

readme.md 中包含三类内容：

栅格地图配置示例
提供一个栅格地图模板，其中 sources.behavior-basemap.type 为 raster，瓦片地址为 pmtiles://resource/map/china.pmtiles。这是生成 PMTiles 时的参考模板，不是本项目默认样式。
metadata.json 示例
描述 MBTiles 元数据字段，如名称、版本、格式、最小缩放级别、最大缩放级别。
PMTiles 转换命令
使用 pmtiles.exe convert light.mbtiles china.pmtiles 将 MBTiles 转为 PMTiles，并用 pmtiles.exe show china.pmtiles 查看内容。
regInfo.exe 激活说明
提供机器码查询、许可证读取、字段查看和有效性验证命令，并列出常见错误码：
- 0：许可证有效。
- 10001：许可证文件无效。
- 10002：许可证过期。
- 10004：机器码不匹配。

前端授权流程

前端授权入口页 authorization/index.vue 的流程如下：

首次启动时判断是否需要绑定后端服务地址。
调用 checkAuthApi() 检查设备授权状态。
如果授权无效或过期，进入“离线授权”模式。
用户选择 .xlts 授权文件后调用 offlineAuthorizationApi 提交离线授权。
授权成功后刷新授权摘要，并根据登录态决定进入业务页面或登录页。

因此，“许可证有效”是进入业务页面的前置条件。虽然离线地图加载本身由 offlineMap.ts 控制，但用户只有在授权通过后才能到达使用离线地图的业务页面。

flowchart TD
    Start["应用启动"] --> BindServer["绑定后端服务地址"]
    BindServer --> CheckAuth["调用 checkAuthApi 检查授权"]
    CheckAuth --> Authorized{"授权有效？"}
    Authorized -->|否| ShowLicenseCard["显示离线授权卡片"]
    ShowLicenseCard --> UploadLicense["上传 .xlts 授权文件"]
    UploadLicense --> OfflineAuth["调用 offlineAuthorizationApi"]
    OfflineAuth --> Recheck["刷新授权摘要"]
    Recheck --> LoginOrBusiness["无 token 进入登录页<br/>有 token 进入业务页"]
    Authorized -->|是| TokenCheck{"已有登录令牌？"}
    TokenCheck -->|是| Business["进入业务页面"]
    TokenCheck -->|否| Login["进入登录页"]

图表来源

authorization/index.vue:340-650

章节来源

readme.md:1-76
authorization/index.vue:340-650

依赖关系分析

组件依赖图

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
MapLocalSettingModal.vue:1-153
behaviorSpacetime/index.vue:2500-2700
StationMapModal.vue:180-340
BaseStationQueryMap.vue:1-250
authorization/index.vue:340-650

耦合性说明

offlineMap.ts 是低层工具模块，被多个地图组件复用。
MapLocalSettingModal.vue 只负责持久化本机目录，不关心地图具体渲染逻辑。
地图页面通过 offline-map-dir-changed 事件解耦目录变更与地图刷新。
授权流程与地图加载属于两条链路：授权控制能否进入业务页面，地图加载控制是否能渲染离线瓦片。

章节来源

offlineMap.ts:1-228
MapLocalSettingModal.vue:1-153
behaviorSpacetime/index.vue:2500-2700

使用与扩展指南

资源目录 public/resource/map 结构

建议保持以下结构：

路径	用途
`public/resource/map/china.pmtiles`	内置离线 PMTiles 数据文件
`public/resource/map/behavior-spacetime-style.json`	内置矢量样式文件

如果需要在运行时使用本机离线地图，则在用户选择的目录中放置：

文件	必需性
`china.pmtiles`	启用本机离线地图时必须存在
`behavior-spacetime-style.json`	可选，用于覆盖默认样式

替换 china.pmtiles

步骤：

准备新的 PMTiles 文件。
如果使用内置资源，替换 public/resource/map/china.pmtiles。
如果使用本机目录，将新文件放入用户配置的离线地图目录。
确保样式中的 source.url 指向该 PMTiles 文件。
如果是矢量 PMTiles，确认样式中的 source-layer 与新数据中的图层名称一致。

注意：readme.md 提供的栅格地图模板是 type: raster，而默认样式是 type: vector。替换矢量 PMTiles 时应以矢量样式为准；替换栅格 PMTiles 时需要改用栅格样式模板。

更换离线地图源

如果需要让某个地图页面加载不同的 PMTiles 源，可以在样式中修改对应 source 的 url，并在 normalizePmtilesSources() 处理时确保 key 与注册源一致。典型做法：

在样式中使用 pmtiles://... 引用瓦片。
通过 resolveOfflinePmtilesSources() 注册该 key 对应的 Source。
如果希望强制覆盖某个样式中的 PMTiles 地址，可在 normalizePmtilesSources() 的 overridePmtilesUrl 参数中传入新地址。

新增地图图层

新增图层时需要注意：

图层必须引用已有的 source，通常是 behavior-basemap。
矢量图层必须指定正确的 source-layer。
样式表达式中的字段名必须与 PMTiles 数据字段一致。
如果是新增 PMTiles 数据，需同步更新样式、Source 注册和可能的颜色/透明度配置。

示例思路：

在样式 layers 数组中添加新图层。
若新增独立 PMTiles，新增一个 source，并为其注册 ElectronPmtilesSource 或 HttpPmtilesSource。
在地图初始化后按需开启或关闭图层可见性。

调试地图加载失败的步骤

推荐按以下顺序排查：

确认是否已完成授权并通过登录进入业务页面。
确认是否配置了本机离线地图目录，或是否存在内置 china.pmtiles。
检查样式是否成功解析。
检查 PMTiles 源是否已注册。
检查浏览器控制台和网络面板中的 Range 请求或 IPC 调用。
检查样式 JSON 是否合法。
检查 PMTiles 文件的 source-layer 是否与样式一致。

章节来源

behavior-spacetime-style.json:1-200
offlineMap.ts:1-228
readme.md:1-76

性能与初始化时机

初始化时机

离线地图相关初始化通常发生在地图页面或地图组件挂载时：

页面或组件创建 MapLibre map 实例。
调用 ensureOfflinePmtilesArchive() 或类似逻辑，将 resolveOfflinePmtilesSources() 返回的源注册到 PMTiles 协议管理器。
调用 resolveStyle() 解析样式。
将样式和源应用到 map。
如需动态切换目录，监听 offline-map-dir-changed 事件后重新执行上述步骤。

性能特性

本机 PMTiles 通过 ElectronPmtilesSource 使用 readBinaryFileRange 分块读取，避免一次性加载整个 .pmtiles 文件。
内置 PMTiles 通过 HttpPmtilesSource 使用 HTTP Range 请求，适合部署环境下的静态资源访问。
样式读取失败时不会中断地图初始化，而是回退到外层样式或最小背景样式。
目录变更通过事件触发局部刷新，而不是强制重启整个应用。

章节来源

behaviorSpacetime/index.vue:2500-2520
offlineMap.ts:40-100

故障排查

china.pmtiles 无法加载

可能原因：

本机目录中没有 china.pmtiles。
内置 public/resource/map/china.pmtiles 缺失。
本机路径未被正确识别为本地路径。
PMTiles 文件格式损坏。
样式中 source key 与实际注册 key 不一致。

排查建议：

检查 getOfflineMapDir() 是否返回有效路径。
检查 getOfflineMapPmtilesPath() 是否指向真实文件。
检查控制台是否出现 IPC 读取失败。
使用 pmtiles.exe show china.pmtiles 验证 PMTiles 文件可读。
确认样式中 source 的 key 与 resolveOfflinePmtilesSources() 返回的 key 一致。

章节来源

offlineMap.ts:9-25
offlineMap.ts:40-130
readme.md:1-76

样式 JSON 报错

可能原因：

本机 behavior-spacetime-style.json 语法非法。
样式引用了不存在的 source-layer。
样式中的 PMTiles 地址无法解析。
样式文件编码异常。

排查建议：

先清空本机样式目录，确认内置样式是否正常。
将本机样式复制一份，逐步删除图层定位问题。
检查 JSON.parse 是否抛出异常。
检查样式中的 source-layer 是否与 PMTiles 实际图层一致。

章节来源

behaviorSpacetime/index.vue:2601-2700
StationMapModal.vue:292-340
behavior-spacetime-style.json:1-200

地图空白

可能原因：

地图处于 fallback 模式。
PMTiles 源未注册。
样式解析失败。
授权未通过，导致未能进入业务页面。
本机目录配置为空，且内置资源不可用。

排查建议：

检查是否已成功授权并进入业务页面。
检查 resolveStyle() 是否返回 fallback 样式。
检查 PMTiles 源是否已注册。
检查浏览器控制台网络请求。
确认样式中的 background 颜色是否过于透明或与屏幕背景相近。

章节来源

authorization/index.vue:340-650
behaviorSpacetime/index.vue:2601-2700

许可证无效导致地图禁用

这里的“禁用”应理解为：用户停留在授权入口页，无法进入包含地图的业务页面。

可能原因：

未绑定后端服务地址。
checkAuthApi() 返回非 200。
授权文件过期。
机器码不匹配。
选择了无效的 .xlts 授权文件。

排查建议：

检查是否显示“离线授权”卡片。
检查 checkAuthApi() 响应。
使用 regInfo.exe -f licensefile -verify 验证许可证。
确认授权文件后缀为 .xlts。
确认机器码与授权文件匹配。

章节来源

readme.md:1-76
authorization/index.vue:340-650

PMTiles 路径错误

可能原因：

本机路径格式不被 isLocalFilePath() 识别。
路径末尾多或少反斜杠。
样式中的 pmtiles:// 地址没有被正确替换。
使用了远程 URL，却期望走本机 IPC 读取。

排查建议：

检查 getOfflineMapDir() 返回值。
检查 getOfflineMapPmtilesPath() 返回值。
检查 isLocalFilePath() 判定结果。
检查样式中 source url 是否以 pmtiles:// 开头。
检查 normalizePmtilesSources() 是否正确重写地址。

章节来源

offlineMap.ts:100-130
behaviorSpacetime/index.vue:2643-2690

结论

离线地图功能由三个层次组成：

授权层：通过 authorization/index.vue 完成设备绑定、机器码获取和离线授权校验。只有授权有效，用户才能进入业务页面。
配置层：通过 MapLocalSettingModal.vue 和本地存储保存本机离线地图目录；offlineMap.ts 负责路径规范化、Source 选择和样式读取。
渲染层：地图页面使用 MapLibre GL 和 PMTiles，优先加载本机 PMTiles 和样式，否则回退到内置静态资源。

要扩展或替换离线地图，核心原则是：

保持 PMTiles 文件与样式中的 source-layer 一致。
保持样式中的 PMTiles key 与 resolveOfflinePmtilesSources() 注册的 key 一致。
本机路径必须能被 isLocalFilePath() 识别。
授权必须先通过，否则用户无法进入使用离线地图的业务页面。

离线地图与 PMTiles 配置.md 31 KB История Исходник

离线地图与 PMTiles 配置

目录

简介

项目结构与资源位置

核心组件总览

offlineMap.ts：离线地图工具模块

MapLocalSettingModal.vue：地图本地设置弹窗

behavior-spacetime-style.json：默认矢量样式

架构概览

详细组件分析

离线地图瓦片源构建流程

样式加载与回退策略

PMTiles 协议与路径映射

许可证校验与地图加载的关系

readme.md 中的许可证说明

前端授权流程

依赖关系分析

组件依赖图

耦合性说明

使用与扩展指南

资源目录 public/resource/map 结构

替换 china.pmtiles

更换离线地图源

新增地图图层

调试地图加载失败的步骤

性能与初始化时机

初始化时机

性能特性

故障排查

china.pmtiles 无法加载

样式 JSON 报错

地图空白

许可证无效导致地图禁用

PMTiles 路径错误

结论

离线地图与 PMTiles 配置.md 31 KB

История Исходник