baidu-maps/harmony-sdk-skills/baidu-map-harmonyos-sdk

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. 日志 / 注释 / 模块化规范

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

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

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

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

• 示例与 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。

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

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

1. 运行检测（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、导航状态监听、模拟导航等）
• 定位能力（单点定位/持续定位/后台定位）
• 工具类能力（距离/面积计算、坐标转换、点与图形位置关系等）

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/map_walkride_search
• 若需要导航 + 地图能力，可使用组合包：
• ohpm install @bdmap/navi_map
• 组合包与独立包不允许混用，详见 包管理规范。
• 在回答中明确指出需要安装的包以及命令。

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.GET_WIFI_INFO"
• "ohos.permission.GET_NETWORK_INFO"
• "ohos.permission.GET_BUNDLE_INFO"
• "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/api/modules/*.md（API 参数/枚举/接口明细）。