Baidu Map HarmonyOS SDK 开发 Skill

使用场景

在以下情况必须优先使用本 Skill：

• 提到 HarmonyOS NEXT 百度地图 / 鸿蒙地图 SDK / HarmonyNEXT 地图 开发
• 在本项目中使用 @bdmap/base、@bdmap/map、@bdmap/search、@bdmap/util 等包或者直接完全使用 @bdmap/mapwalkridesearch等组合包
• 需要实现以下能力之一：

- 地图组件展示、手势和控件交互 - 标注点（Marker）、线、面、多边形、圆、文字、信息窗口等覆盖物 - 普通地图、卫星地图、个性化地图、自定义瓦片图等图层 - 驾车/步行/骑行/公交等路线规划以及步骑行导航 - POI/AOI/室内 POI/建筑物/行政区/天气 等检索 - 正逆地址解析、推荐上车点、坐标转换、调起百度地图等

以下情况不适合使用本 Skill，应转用其他平台/能力的 Skill：

• 仅涉及 Web 版百度地图 JavaScript API、Android/iOS 原生 SDK、或小程序地图能力
• 与地图无关的一般 HarmonyOS 应用开发（此时应优先使用空工程/通用 HarmonyOS Skill）

⚠️ 强制要求（必须严格遵守）

在使用本 Skill 进行开发时，必须严格遵守以下规范（仅列核心摘要，详细说明见引用文档）：

1. 日志 / 注释 / 模块化规范

- 必须使用统一的 Logger 工具类封装原生 console，第一个参数固定使用场景名 "SportHealthMap"，禁止直接使用 console.info/error/warn/debug。 - 关键业务方法必须补充中文注释说明用途、参数与返回值，通用工具类必须抽取为独立模块，禁止在页面内联定义通用类。 - 详细规则与示例见：[代码规范](references/guidelines/coding-standards.md)。

1. 图片资源使用规范（必须主动拷贝）

- 生成或修改示例代码时，优先使用本 Skill 资产中约定的图片名，并保持与 [assets](references/assets.md) 表格中的用途一致或相近。 - 必须提醒开发者：将对应图片主动拷贝到 HarmonyOS 工程的 resources/rawfile/ 目录后，再通过 rawfile://xxx.png 方式引用，否则覆盖物会因为找不到资源而不显示或报错。 - 详细说明见：[代码规范 / 图片资源使用规范](references/guidelines/coding-standards.md#4-图片资源使用规范)。

1. 地图功能开发（代码组织与规范）（强制要求）

- 示例与 API 使用：回答与实现时，应优先参考本目录下 references/reference.md 中给出的示例代码与调用方式，在此基础上按业务场景做适配，避免自创与 SDK 不一致的用法。 - 性能与覆盖物分层：高频 UI 更新场景（如气泡内容刷新、轨迹回放等）必须缓存复用 PopView/Label 等对象，所有覆盖物需显式设置 zIndex 并遵循统一分层，避免信息被遮挡；详细见：[地图性能与覆盖物分层规范](references/guidelines/performance-optimization.md)。 - 地图 & UI 交互反馈：地图初始化、检索、路线规划、定位、覆盖物增删、权限/网络异常等关键行为，必须通过 Toast/Dialog/页面状态文本等方式给出清晰的用户反馈，而不仅仅是日志；详细见：[地图 UI 交互与用户反馈规范](references/guidelines/ui-feedback.md)。 - 定位与地图协同：涉及 @bdmap/locsdk 的地图场景时，需同时遵守定位 SDK 的初始化顺序、权限与错误处理规范；完整说明见：[定位 SDK 开发指南](references/guidelines/location-sdk-guide.md)。 - 步骑行导航开发：涉及步行/骑行导航（@bdmap/mapwalkridesearch）时，需遵循导航引擎初始化时序、生命周期管理、模拟导航退出、默认 UI 手势穿透等规范；完整说明见：[步骑行导航 SDK 开发指南](references/guidelines/walkride-sdk-guide.md)。 - 地图样式与视觉规范：涉及 Marker 锚点、路线/区域颜色与线宽、不同缩放级别信息密度控制等样式问题时，需遵循统一规范；详见：[地图样式与视觉规范](references/guidelines/map-style-guide.md)。 - 类型与 ArkTSCheck：实现地图相关回调与方法时，必须显式声明参数与返回值类型，禁止使用 any 或隐式 undefined；当无法明确 .catch 回调参数类型时，优先使用 Error 或 object，确保通过 ArkTSCheck。

1. 包管理互斥规则（强制要求）

- 组合包（@bdmap/mapwalkridesearch、@bdmap/navi_map）与独立包（@bdmap/base、@bdmap/map、@bdmap/search、@bdmap/util）不允许混用，否则会导致依赖冲突。 - 添加任何百度地图依赖前，必须先检查 oh-package.json5 中已有的包方案，并严格遵循同一方案。 - 自动切换：当项目已使用独立包、但新需求明确需要组合包能力时，Agent 必须自动执行切换（卸载独立包 → 安装组合包 → 批量替换 import → 构建验证），无需额外询问用户。 - @bdmap/locsdk 为独立定位包，不受上述互斥限制，可与任何方案搭配使用。 - 详细规则、自动切换流程与场景建议见：[包管理规范](references/guidelines/package-management.md)。

1. 运行检测（Auto Run 构建）

- 每次完成与百度地图 HarmonyOS SDK 相关的代码改动后，必须按照约定的 Auto Run 流程执行一次构建与 ArkTSCheck，自检是否存在编码错误。 - 核心命令为：ohpm install + hvigorw assembleHap --mode module -p product=default -p buildMode=debug --no-daemon。 - 详细流程与错误分类处理见：[构建与编码错误自检规范](references/guidelines/build-and-test.md)。

基本开发流程（通用步骤）

处理任何鸿蒙百度地图 SDK 相关问题时，遵循以下流程组织思路与回答：

1. 确认需求类型

- 判断问题属于哪类场景： - 地图展示与交互 - 覆盖物绘制（点/Marker/线/面/文字/圆） - 检索（POI/AOI/建筑物/行政区/天气等） - 路线规划（驾车/步行/骑行/公交） - 步骑行导航（导航引擎、默认导航 UI、导航状态监听、模拟导航等） - 定位能力（单点定位/持续定位/后台定位） - 工具类能力（距离/面积计算、坐标转换、点与图形位置关系等）

1. 检查依赖与安装方式（强制遵守包管理互斥规则）

- 必须先阅读 [包管理规范](references/guidelines/package-management.md)，确认当前项目使用的是组合包还是独立包方案，严格遵守互斥规则。 - 根据 references/api/modules.md（模块索引）建议： - 若只需要部分能力，建议按需安装独立包： - ohpm install @bdmap/base - ohpm install @bdmap/search - ohpm install @bdmap/util - ohpm install @bdmap/map - ohpm install @bdmap/locsdk - 若需要地图 + 步行/骑行 等组合能力，可直接使用组合包： - ohpm install @bdmap/mapwalkridesearch - 若需要导航 + 地图能力，可使用组合包： - ohpm install @bdmap/navi_map - 组合包与独立包不允许混用，详见 [包管理规范](references/guidelines/package-management.md)。 - 在回答中明确指出需要安装的包以及命令。

1. 确认系统与工具链约束

- 参考 references/api/modules.md（模块索引）与在线文档的约束与限制，回答时需提醒： - 仅支持标准系统，设备为华为手机 - HarmonyOS 版本：HarmonyOS NEXT Developer Preview1 及以上 - DevEco Studio 版本：DevEco Studio NEXT Developer Preview1 及以上 - HarmonyOS SDK 版本：HarmonyOS NEXT Developer Preview1 SDK 及以上

1. 配置权限

- 如涉及网络访问、检索、路线规划等，需要在权限配置中加入至少： - "ohos.permission.GETWIFIINFO" - "ohos.permission.GETNETWORKINFO" - "ohos.permission.GETBUNDLEINFO" - "ohos.permission.INTERNET" - 提示在工程配置中正确声明这些权限。

1. 精确定位 API 声明推荐流程

- 从业务代码出发：先看 import { MapOptions } from '@bdmap/map' 里的「包名 + 类型名」。 - 定位包根声明文件：在当前工程找到 oh_modules/@bdmap/map/Index.d.ets。 - 在 Index.d.ets 中查导出：搜索 MapOptions，找到类似 import MapOptions from "./src/main/ets/lbsmapsdk/e/p"; - 跳到具体定义文件：根据相对路径打开 src/main/ets/lbsmapsdk/e/p.d.ets，再在文件内搜索 class MapOptions 查看完整定义。

常见能力指引

在提需求时，优先按照下列能力分类，结合对应模块文档进行回答。

1. 能力索引（给开发工具全局搜索用）

使用建议：

• 先搜关键词，再跳转：优先用下表“推荐搜索词”（包含类名/方法名/中文别名）做全局搜索；命中后再打开对应 references/reference.md 小节，最后按需下钻到 references/api/ API 文档。
• 三段式定位：关键词（用户问题） → [references/reference](references/reference.md)（示例与用法） → references/api/modules/*.md（API 参数/枚举/接口明细）。

2. 地图展示与交互（模块：map）

• 引导：

- 从 [references/api/modules/map](references/api/modules/map.md) 查找对应的地图组件、控制器 API - 选择合适的地图类型：标准地图、个性化地图、卫星图、自定义瓦片图 - 配置基本参数：中心点、缩放级别、旋转、倾斜、罗盘、比例尺、定位按钮等控件

• 回答中应覆盖：

- 如何在鸿蒙页面中引入 MapComponent - 如何在 onReady 中拿到 MapController - 开启/关闭手势交互（缩放、平移、旋转、倾斜等） - 控件显隐与自定义样式的关键配置点（如在文档中有具体字段名，需引用）

3. 覆盖物绘制（模块：map）

• 关注以下覆盖物类型（优先在 [references/api/modules/map](references/api/modules/map.md) 中查找具体接口名）：

- Marker 点、点聚合、Marker 动画 - 折线（Polyline）、弧线 - 多边形/面 - 圆 - 文本注记 - 地面覆盖物、棱柱、3D 建筑物/模型 - 气泡/弹框/信息框/信息窗口

• 回答时的通用模式：

- 指出需要通过 MapController 提供的方法添加/更新/删除对应覆盖物 - 说明必要参数（经纬度、颜色、宽度、透明度、zIndex 等） - 如需复杂样式（自定义 icon），引导查阅在线文档中对应章节（地图覆盖物部分）。

4. 检索能力（模块：search）

• 根据需求分类：

- POI 检索：普通地点搜索，支持关键字、城市、范围检索 - AOI 检索：区域面信息 - 室内 POI 检索：购物中心、写字楼内部 POI - 建筑物检索：楼宇信息 - 行政区检索：省/市/区划边界数据 - 天气检索：实况天气、预报等

• 回答时应：

- 指出需安装 @bdmap/search 或组合包 - 引导查看 [references/api/modules/search](references/api/modules/search.md)的对应接口说明 - 说明同步/异步调用模式（根据文档）以及结果回调/Promise 的处理方式 - 提醒注意配额限制、错误码处理，可引导查看在线文档「请求状态码说明」。

5. 路线规划（模块：@bdmap/mapwalkridesearch组合包）

• 支持：

- 驾车路线规划 - 步行路线规划 - 骑行路线规划 - 公交路线规划 - 跨城公交路线规划

• 回答步骤建议：

- 明确需要的出行方式（驾车/步行/骑行/公交） - 提示安装 @bdmap/search 以及必要的步行/骑行/公交相关模块或组合包，例如 @bdmap/mapwalkridesearch - 在 [references/api/modules/search](references/api/modules/search.md)、[references/api/modules/walkridecommon](references/api/modules/walkridecommon.md) 查找对应 API： - 典型参数：起终点坐标 / 关键字、策略（最短时间、最短距离、避堵等）、途经点等 - 在回答中给出： - 如何构造请求参数对象 - 如何发起路线规划调用 - 如何从返回结果中解析路线、路段、坐标点，并在地图上绘制（配合地图覆盖物功能）。

步骑行导航场景：若需求不仅是路线规划，还涉及实时导航引导（导航启停、偏航重算、默认导航 UI、语音播报、模拟导航等），请直接参考第 8 节「步骑行导航能力」和 [步骑行导航 SDK 开发指南](references/guidelines/walkride-sdk-guide.md)。

6. 工具类能力与其他（模块：util / map / search）

• 能力示例：

- 距离和面积计算 - 点与其他图形的位置关系判断（点是否在多边形内等） - 坐标转换（如与其他坐标系互转） - 调起百度地图客户端相关能力（如在线文档中有说明） - 位置短地址分享、地图收藏夹等

• 回答方式：

- 根据具体需求，指明应使用 [references/api/modules/util](references/api/modules/util.md) 或在线文档中「工具」「调起百度地图功能」「位置短地址分享」等章节 - 简要讲清： - 输入参数含义 - 返回值结构 - 常见错误和注意事项（如坐标系要求）。

7. 定位能力（模块：locsdk / @bdmap/locsdk）

本节只给出关键要点，完整开发指南请见：[定位 SDK 开发指南](references/guidelines/location-sdk-guide.md)。

- 适用场景：前台连续定位、单次定位、后台持续定位、经纬度/地址/POI 获取等。 - 依赖与安装：统一使用项目约定的 @bdmap/locsdk 版本，按指南配置线上/线下依赖并执行 ohpm install + 构建自检。 - 隐私与权限（强制）：先获取用户隐私同意和运行时定位权限，再调用 LocationClient.setAgreePrivacy(true)、LocationClient.checkAuthKey(...)，并正确声明 module.json5 中的定位相关权限与 backgroundModes。 - 初始化与使用顺序：遵循「隐私合规 → AK 鉴权 → 权限申请 → 创建 LocationClient → 注册监听 → 配置 LocationClientOption → 启动定位」的顺序，页面/业务结束时必须停止定位并注销监听。 - 模式与能力：根据业务选择连续定位、单次定位、后台定位，并合理设置坐标系、时间/距离间隔、是否返回地址/位置描述/POI 等参数。 - 结果校验与错误处理：使用前需检查 isLocSuccess、坐标非 (0,0)、精度半径合理，并通过 Logger + Toast/状态文本反馈错误原因与解决建议。 - 性能与合规：对连续/后台定位设置合理频率和结束条件，敏感数据通过 HTTPS 传输并避免在日志中输出精确坐标。

8. 步骑行导航能力（模块：@bdmap/mapwalkridesearch 组合包）

本节只给出关键要点，完整开发指南请见：[步骑行导航 SDK 开发指南](references/guidelines/walkride-sdk-guide.md)。

- 适用场景：步行导航、骑行导航、路线规划结果展示、导航状态监听、默认导航 UI 渲染、模拟导航调试等。 - 依赖与安装：使用组合包 @bdmap/mapwalkridesearch（已包含 base + map + search + util），与独立包不可混用。 - 核心类与接口： - BDNaviService：导航服务主入口，通过 NaviType.WALK / NaviType.RIDE 创建 - RoutePlanOption + IRoutePlanListener：路线规划参数与回调 - IGuideSubStatusListener：导航状态监听（偏航、接近/到达目的地等） - IGuideInfoListener：诱导信息、剩余距离/时间、速度等实时数据 - ITTSPlugin：语音播报接口 - walkRideDefaultUIPage：内置导航 UI 组件 - MockLocationPlugin：模拟定位插件（调试用） - 初始化时序：aboutToAppear 注册 TTS 插件 → MapComponent.onReady 获取 MapController → service.initializer().init(context, mapController)。 - 导航控制：路线规划成功 → cancelRoutePlanDisplay() 清除路线展示 → lifecycle().start() 启动导航 → 到达终点后 lifecycle().stop() 停止 → 页面销毁时 initializer().unInit() 释放引擎。 - 默认 UI：使用 walkRideDefaultUIPage 渲染导航界面时，必须设置 .hitTestBehavior(HitTestMode.None) 防止拦截底图手势。 - 坐标转换：SDK 使用百度坐标系（BD09ll），外部 WGS84/GCJ-02 数据须通过 CoordTrans.wgsToBaidu() / CoordTrans.gcjToBaidu() 转换。 - 错误处理：RoutePlanError 提供 20+ 种错误码，必须封装用户友好的错误提示，不可仅输出日志。

回答风格与输出格式要求

在基于本 Skill 回答问题时：

1. 优先使用中文回答，除非明确要求英文。
2. 文档检索与工具调用顺序（强制要求）：

- ✅ 当涉及百度地图 HarmonyOS SDK（例如 @bdmap/map 覆盖物、信息框/PopView 等能力）时，必须优先读取本地文档： - （例如）使用 readfile / grep 等工具打开并检索： - [references/reference](references/reference.md) - [references/api/modules](references/api/modules.md) - [references/api/modules/map](references/api/modules/map.md)（信息框/PopView 等相关章节） - ✅ 只有在本地文档无法覆盖、或发现明显版本差异/缺失时，才使用 websearch 查阅在线文档（如 https://lbsyun.baidu.com/faq/api?title=harmonynextsdk），并在回答中说明参考来源。 - ✅ 回答中引用 API 名称、参数、枚举等时，应以「本地文档 + 官方在线文档」为准，禁止仅凭记忆或经验臆造 API。 - ❌ 在未阅读本地 [references/reference](references/reference.md) / references/api/modules/*.md 前，禁止直接通过在线搜索结果给出具体 API 写法（例如 PopView 的构造参数、事件枚举名等）。

1. 回答结构尽量清晰，建议使用如下顺序：

- 场景说明：先简要说明这是哪个模块/能力（地图展示、检索、路线规划等）。 - 依赖与权限：列出需要安装的 ohpm 包和必需权限。 - 关键步骤：用 3–6 个步骤说明从初始化到接口调用的流程。 - 示例代码：给出尽量简洁的示例（注意不要与本 Skill 说明中的示意代码冲突，应参考项目实际 API 命名）。 - 扩展阅读：给出应查看的本地文档文件（如 [references/reference](references/api/modules/map.md) 对应章节）和在线文档章节（如「地图覆盖物」「路线规划」等）。

1. 构建与编码错误自检（强制要求）：

- 每次完成与百度地图 HarmonyOS SDK 相关的代码改动后，需在工程根目录执行一次 ohpm install 与 hvigorw assembleHap --mode module -p product=default -p buildMode=debug --no-daemon 进行构建与 ArkTSCheck 自检。 - 如构建报错，需根据错误信息回溯并修复本次改动引入的编码问题；若为环境/工具链问题，则在回答中明确区分并给出处理建议。详细流程见：[构建与编码错误自检规范](references/guidelines/build-and-test.md)。

资源文件

• 图像资源：[assets.md](references/assets.md)，生成代码中的图像，优先使用提供的图像资源

参考文档

使用本 Skill 时，始终优先结合本地文档、安装包声明文件和在线官方文档：

• 本地文档（本项目）：

- [references/reference](references/reference.md)：HarmonyNEXT 地图 SDK 使用文档以及参考代码摘要 - [references/api/modules](references/api/modules.md)：模块总览入口 - [references/api/modules/base](references/api/modules/base.md)：基础能力接口（坐标类型、权限验证）（按需阅读） - [references/api/modules/map](references/api/modules/map.md)：地图组件、地图控制器、地图样式与交互（按需阅读） - [references/api/modules/search](references/api/modules/search.md)：检索相关接口（POI/AOI/建筑物/行政区/天气等）（按需阅读） - [references/api/modules/util](references/api/modules/util.md)：工具与通用能力（按需阅读） - [references/api/modules/walkridecommon](references/api/modules/walkridecommon.md)：步行、骑行、公交等路线规划基础（按需阅读）

• 开发指南（本项目）：

- [references/guidelines/walkride-sdk-guide](references/guidelines/walkride-sdk-guide.md)：步骑行导航 SDK 完整开发指南（引擎初始化、路线规划、导航控制、状态监听、默认 UI、模拟导航、TTS、资源释放） - [references/guidelines/location-sdk-guide](references/guidelines/location-sdk-guide.md)：定位 SDK 开发指南 - [references/guidelines/package-management](references/guidelines/package-management.md)：包管理互斥规范 - [references/guidelines/coding-standards](references/guidelines/coding-standards.md)：代码规范（日志、注释、模块化、图片资源） - [references/guidelines/performance-optimization](references/guidelines/performance-optimization.md)：性能与覆盖物分层规范 - [references/guidelines/ui-feedback](references/guidelines/ui-feedback.md)：UI 交互与用户反馈规范 - [references/guidelines/map-style-guide](references/guidelines/map-style-guide.md)：地图样式与视觉规范 - [references/guidelines/build-and-test](references/guidelines/build-and-test.md)：构建与编码错误自检规范

• 安装包声明文件：

- 前置条件，检查entry/oh-package.json5中的引用是否已经安装，如果未安装，则需要通过ohpm install安装，记录下包名版本号 - 查声明文件中的 class/接口名： 用 grep（或 IDE 全局搜索）搜："class MapOptions"，范围限制到 ohmodules/@bdmap/map/src/main/ets/。 - 不确定具体路径时,统一推荐走 @bdmap/xxx/Index.d.ets → 目标 .d.ets 这条路径，不要直接在大量混淆文件里乱翻: - 首先检索当前工程的ohmodules/.ohpm/@bdmap+包名@版本号，找到目录 - 然后，继续往下查找ohmodules/@bdmap/包名/Index.d.ets文件 - 最后，从Index.d.ets文件中内部搜索类型名，查看定义 - (举例)查找 {MapController} from '@bdmap/map'的MapController定义，定位到当前工程中的ohmodules/.ohpm/@[email protected]/ohmodules/@bdmap/map/Index.d.ets文件，查到MapController是Index.d.ets的相对路径./src/main/ets/lbsmapsdk/e/g，则通过ohmodules/.ohpm/@[email protected]/oh_modules/@bdmap/map/src/main/ets/lbsmapsdk/e/g.d.ets文件，即可找到MapController的定义;

• 在线官方文档（需要更详细 API、枚举、参数说明时查阅）：

- HarmonyNEXT 地图 SDK 概述与开发指南：https://lbsyun.baidu.com/faq/api?title=harmonynextsdk

当本地文档与在线文档存在差异时，以在线官方文档为准，但要在回答中说明参考了哪一类文档。