Baidu Map HarmonyOS SDK 开发 Skill

使用场景

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

• 提到 HarmonyOS NEXT 百度地图 / 鸿蒙地图 SDK / HarmonyNEXT 地图 开发
• 在本项目中使用 @bdmap/base、@bdmap/map、@bdmap/search、@bdmap/util 等包或者直接完全使用 @bdmap/map_walkride_search等组合包
• 需要实现以下能力之一：
  • 地图组件展示、手势和控件交互
  • 标注点（Marker）、线、面、多边形、圆、文字、信息窗口等覆盖物
  • 普通地图、卫星地图、个性化地图、自定义瓦片图等图层
  • 驾车/步行/骑行/公交等路线规划以及步骑行导航
  • POI/AOI/室内 POI/建筑物/行政区/天气 等检索
  • 正逆地址解析、推荐上车点、坐标转换、调起百度地图等

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

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

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

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

1. 依赖安装前置（最高优先级，必须在编码之前执行）

   • 禁止在依赖包未安装到本地的情况下编写任何业务代码。 必须先确保 oh-package.json5 中声明了所需的 @bdmap/* 依赖，并在工程根目录成功执行 ohpm install，使 oh_modules/ 下存在对应包的声明文件（.d.ets）后，才能开始分析需求和编写代码。
   • 原因：百度地图 SDK 的类型导出位置、类/接口名、属性名等均以安装包内的声明文件（Index.d.ets 及其引用的 .d.ets）为准。仅凭文档示例或记忆推测 API 会导致导入路径错误。
   • 执行流程：
     1. 检查 entry/oh-package.json5（或工程根 oh-package.json5）中是否已声明所需的 @bdmap/* 依赖；若缺失则先补充声明。
     2. 在工程根目录执行 ohpm install，确认安装成功（无报错）。
     3. 确认 oh_modules/.ohpm/@bdmap+\x3C包名>@\x3C版本>/oh_modules/@bdmap/\x3C包名>/Index.d.ets 文件存在。
     4. 在编写 import 语句前，必须通过查阅安装包的 Index.d.ets �灵精附体确认目标类/接口/枚举的实际导出包名和导出名称。对于属性名、方法签名等细节，应跳转到具体的 .d.ets 定义文件确认。

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

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

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

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

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

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

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

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

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

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

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

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

1. 确认需求类型
   • 判断问题属于哪类场景：
     • 地图展示与交互
     • 覆盖物绘制（点/Marker/线/面/文字/圆）
     • 检索（POI/AOI/建筑物/行政区/天气等）
     • 路线规划（驾车/步行/骑行/公交）
     • 步骑行导航（导航引擎、默认导航 UI、导航状态监听、模拟导航等）
     • 定位能力（单点定位/持续定位/后台定位）
     • 工具类能力（距离/面积计算、坐标转换、点与图形位置关系等）
2. 检查依赖与安装方式（强制遵守包管理互斥规则）

• 必须先阅读 包管理规范，确认当前项目使用的是组合包还是独立包方案，严格遵守互斥规则。
• 根据模块索引建议：
  • 若只需要部分能力，建议按需安装独立包：
    • ohpm install @bdmap/base
    • ohpm install @bdmap/search
    • ohpm install @bdmap/util
    • ohpm install @bdmap/map
    • ohpm install @bdmap/locsdk
  • 若需要地图 + 步行/骑行 等组合能力，可直接使用组合包：
    • ohpm install @bdmap/map_walkride_search
  • 若需要导航 + 地图能力，可使用组合包：
    • ohpm install @bdmap/navi_map
• 组合包与独立包不允许混用，详见 包管理规范。
• 在回答中明确指出需要安装的包以及命令。
• ⚠️ 依赖安装后必须验证：在 oh-package.json5 中声明依赖后，必须在工程根目录执行 ohpm install 并确认安装成功。在依赖包未实际安装到 oh_modules/ 之前，禁止编写任何业务代码。安装成功后，必须通过查阅 oh_modules/.ohpm/@bdmap+\x3C包名>@\x3C版本>/oh_modules/@bdmap/\x3C包名>/Index.d.ets 确认所需类/接口/枚举的实际导出位置和名称，再开始编码。

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

• 参考在线文档的约束与限制，回答时需提醒：
  • 仅支持标准系统，设备为华为手机
  • HarmonyOS 版本：HarmonyOS NEXT Developer Preview1 及以上
  • DevEco Studio 版本：DevEco Studio NEXT Developer Preview1 及以上
  • HarmonyOS SDK 版本：HarmonyOS NEXT Developer Preview1 SDK 及以上

4. 配置权限
   • 如涉及网络访问、检索、路线规划等，需要在权限配置中加入至少：
     • "ohos.permission.GET_WIFI_INFO"
     • "ohos.permission.GET_NETWORK_INFO"
     • "ohos.permission.GET_BUNDLE_INFO"
     • "ohos.permission.INTERNET"
   • 提示在工程配置中正确声明这些权限。
5. 精确定位 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/reference（示例与用法）。如需更详细的 API 参数/枚举/接口明细，请查阅在线官方文档或安装包声明文件。

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

• 引导：
  • 从 references/reference 查找对应的地图组件、控制器相关示例与用法
  • 选择合适的地图类型：标准地图、个性化地图、卫星图、自定义瓦片图
  • 配置基本参数：中心点、缩放级别、旋转、倾斜、罗盘、比例尺、定位按钮等控件
• 回答中应覆盖：
  • 如何在鸿蒙页面中引入 MapComponent
  • 如何在 onReady 中拿到 MapController
  • 开启/关闭手势交互（缩放、平移、旋转、倾斜等）
  • 控件显隐与自定义样式的关键配置点（如在文档中有具体字段名，需引用）

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

• 关注以下覆盖物类型（优先在 references/reference 中查找具体接口名）：
  • Marker 点、点聚合、Marker 动画
  • 折线（Polyline）、弧线
  • 多边形/面
  • 圆
  • 文本注记
  • 地面覆盖物、棱柱、3D 建筑物/模型
  • 气泡/弹框/信息框/信息窗口
• 回答时的通用模式：
  • 指出需要通过 MapController 提供的方法添加/更新/删除对应覆盖物
  • 说明必要参数（经纬度、颜色、宽度、透明度、zIndex 等）
  • 如需复杂样式（自定义 icon），引导查阅在线文档中对应章节（地图覆盖物部分）。

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

• 根据需求分类：
  • POI 检索：普通地点搜索，支持关键字、城市、范围检索
  • AOI 检索：区域面信息
  • 室内 POI 检索：购物中心、写字楼内部 POI
  • 建筑物检索：楼宇信息
  • 行政区检索：省/市/区划边界数据
  • 天气检索：实况天气、预报等
• 回答时应：
  • 指出需安装 @bdmap/search 或组合包
  • 引导查看 references/reference 的对应接口说明
  • 说明同步/异步调用模式（根据文档）以及结果回调/Promise 的处理方式
  • 提醒注意配额限制、错误码处理，可引导查看在线文档「请求状态码说明」。

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

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

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

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

• 能力示例：
  • 距离和面积计算
  • 点与其他图形的位置关系判断（点是否在多边形内等）
  • 坐标转换（如与其他坐标系互转）
  • 调起百度地图客户端相关能力（如在线文档中有说明）
  • 位置短地址分享、地图收藏夹等
• 回答方式：
  • 根据具体需求，指明应使用 references/reference 或在线文档中「工具」「调起百度地图功能」「位置短地址分享」等章节
  • 简要讲清：
    • 输入参数含义
    • 返回值结构
    • 常见错误和注意事项（如坐标系要求）。

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

本节只给出关键要点，完整开发指南请见：定位 SDK 开发指南。

• 适用场景：前台连续定位、单次定位、后台持续定位、经纬度/地址/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/map_walkride_search 组合包）

本节只给出关键要点，完整开发指南请见：步骑行导航 SDK 开发指南。

• 适用场景：步行导航、骑行导航、路线规划结果展示、导航状态监听、默认导航 UI 渲染、模拟导航调试等。
• 依赖与安装：使用组合包 @bdmap/map_walkride_search（已包含 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 等能力）时，必须优先读取本地文档：
     • （例如）使用 read_file / grep 等工具打开并检索：
       • references/reference
   • ✅ 只有在本地文档无法覆盖、或发现明显版本差异/缺失时，才使用 web_search 查阅在线文档（如 https://lbsyun.baidu.com/faq/api?title=harmonynextsdk），并在回答中说明参考来源。
   • ✅ 回答中引用 API 名称、参数、枚举等时，应以「本地文档 + 官方在线文档」为准，禁止仅凭记忆或经验臆造 API。
   • ❌ 在未阅读本地 references/reference 前，禁止直接通过在线搜索结果给出具体 API 写法（例如 PopView 的构造参数、事件枚举名等）。
3. 回答结构尽量清晰，建议使用如下顺序：
   • 场景说明：先简要说明这是哪个模块/能力（地图展示、检索、路线规划等）。
   • 依赖与权限：列出需要安装的 ohpm 包和必需权限。
   • 关键步骤：用 3–6 个步骤说明从初始化到接口调用的流程。
   • 示例代码：给出尽量简洁的示例（注意不要与本 Skill 说明中的示意代码冲突，应参考项目实际 API 命名）。
   • 扩展阅读：给出应查看的本地文档文件（如 references/reference 对应章节）和在线文档章节（如「地图覆盖物」「路线规划」等）。
4. 构建与编码错误自检（强制要求）：
   • 每次完成与百度地图 HarmonyOS SDK 相关的代码改动后，需在工程根目录执行一次 ohpm install 与 hvigorw assembleHap --mode module -p product=default -p buildMode=debug --no-daemon 进行构建与 ArkTSCheck 自检。
   • 如构建报错，需根据错误信息回溯并修复本次改动引入的编码问题；若为环境/工具链问题，则在回答中明确区分并给出处理建议。详细流程见：构建与编码错误自检规范。

资源文件

• 图像资源：assets.md，生成代码中的图像，优先使用提供的图像资源

参考文档

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

• 本地文档（本项目）：
  • references/reference：HarmonyNEXT 地图 SDK 使用文档以及参考代码摘要
• 开发指南（本项目）：
  • references/guidelines/walkride-sdk-guide：步骑行导航 SDK 完整开发指南（引擎初始化、路线规划、导航控制、状态监听、默认 UI、模拟导航、TTS、资源释放）
  • references/guidelines/location-sdk-guide：定位 SDK 开发指南
  • references/guidelines/package-management：包管理互斥规范
  • references/guidelines/coding-standards：代码规范（日志、注释、模块化、图片资源）
  • references/guidelines/performance-optimization：性能与覆盖物分层规范
  • references/guidelines/ui-feedback：UI 交互与用户反馈规范
  • references/guidelines/map-style-guide：地图样式与视觉规范
  • references/guidelines/build-and-test：构建与编码错误自检规范
• 安装包声明文件：
  • 前置条件，检查entry/oh-package.json5中的引用是否已经安装，如果未安装，则需要通过ohpm install安装，记录下包名版本号
  • 查声明文件中的 class/接口名： 用 grep（或 IDE 全局搜索）搜："class MapOptions"，范围限制到 oh_modules/@bdmap/map/src/main/ets/。
  • 不确定具体路径时,统一推荐走 @bdmap/xxx/Index.d.ets → 目标 .d.ets 这条路径，不要直接在大量混淆文件里乱翻:
    • 首先检索当前工程的oh_modules/.ohpm/@bdmap+包名@版本号，找到目录
    • 然后，继续往下查找oh_modules/@bdmap/包名/Index.d.ets文件
    • 最后，从Index.d.ets文件中内部搜索类型名，查看定义
    • (举例)查找 {MapController} from '@bdmap/map'的MapController定义，定位到当前工程中的oh_modules/.ohpm/@[email protected]/oh_modules/@bdmap/map/Index.d.ets文件，查到MapController是Index.d.ets的相对路径./src/main/ets/lbsmapsdk/e/g，则通过oh_modules/.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

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