baidu-map-harmonyos-sdk

name baidu-map-harmonyos-sdk description 帮助在 HarmonyOS NEXT 上使用百度地图鸿蒙 SDK 进行开发。支持独立包（@bdmap/base、@bdmap/map、@bdmap/search、@bdmap/util）和组合包（@bdmap/map_walkride_search、@bdmap/navi_map），以及定位 SDK（@bdmap/locsdk）。涵盖地图展示与交互、覆盖物绘制、POI/AOI 检索、路线规划、导航、前台/后台定位、地址/POI 获取等场景。适用于提到鸿蒙地图、百度地图 HarmonyNEXT 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 进行开发时， 必须严格遵守 以下规范（仅列核心摘要，详细说明见引用文档）： 日志 / 注释 / 模块化规范 必须使用统一的 Logger 工具类封装原生 console ，第一个参数固定使用场景名 "SportHealthMap" ，禁止直接使用 console.info/error/warn/debug 。 关键业务方法必须补充中文注释说明用途、参数与返回值，通用工具类必须抽取为独立模块，禁止在页面内联定义通用类。 详细规则与示例见： 代码规范 。 图片资源使用规范（必须主动拷贝） 生成或修改示例代码时，优先使用本 Skill 资产中约定的图片名，并保持与 assets 表格中的用途一致或相近。 必须提醒开发者：将对应图片主动拷贝到 HarmonyOS 工程的 resources/rawfile/ 目录后，再通过 rawfile://xxx.png 方式引用，否则覆盖物会因为找不到资源而不显示或报错。 详细说明见： 代码规范 / 图片资源使用规范 。 地图功能开发（代码组织与规范）（强制要求） 示例与 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。 包管理互斥规则（强制要求） 组合包（ @bdmap/map_walkride_search 、 @bdmap/navi_map ）与独立包（ @bdmap/base 、 @bdmap/map 、 @bdmap/search 、 @bdmap/util ） 不允许混用 ，否则会导致依赖冲突。 添加任何百度地图依赖前，必须先检查 oh-package.json5 中已有的包方案，并严格遵循同一方案。 自动切换 ：当项目已使用独立包、但新需求明确需要组合包能力时，Agent 必须 自动执行切换 （卸载独立包 → 安装组合包 → 批量替换 import → 构建验证），无需额外询问用户。 @bdmap/locsdk 为独立定位包，不受上述互斥限制，可与任何方案搭配使用。 详细规则、自动切换流程与场景建议见： 包管理规范 。 运行检测（Auto Run 构建） 每次完成与百度地图 HarmonyOS SDK 相关的代码改动后，必须按照约定的 Auto Run 流程执行一次构建与 ArkTSCheck，自检是否存在编码错误。 核心命令为： ohpm install + hvigorw assembleHap --mode module -p product=default -p buildMode=debug --no-daemon 。 详细流程与错误分类处理见： 构建与编码错误自检规范 。 基本开发流程（通用步骤） 处理任何鸿蒙百度地图 SDK 相关问题时，遵循以下流程组织思路与回答： 确认需求类型 判断问题属于哪类场景： 地图展示与交互 覆盖物绘制（点/Marker/线/面/文字/圆） 检索（POI/AOI/建筑物/行政区/天气等） 路线规划（驾车/步行/骑行/公交） 步骑行导航（导航引擎、默认导航 UI、导航状态监听、模拟导航等） 定位能力（单点定位/持续定位/后台定位） 工具类能力（距离/面积计算、坐标转换、点与图形位置关系等） 检查依赖与安装方式（强制遵守包管理互斥规则） 必须先阅读 包管理规范 ，确认当前项目使用的是组合包还是独立包方案，严格遵守互斥规则。 根据 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 组合包与独立包不允许混用 ，详见 包管理规范 。 在回答中明确指出需要安装的包以及命令。 确认系统与工具链约束 参考 references/api/modules.md （模块索引）与在线文档的约束与限制，回答时需提醒： 仅支持标准系统，设备为华为手机 HarmonyOS 版本：HarmonyOS NEXT Developer Preview1 及以上 DevEco Studio 版本：DevEco Studio NEXT Developer Preview1 及以上 HarmonyOS SDK 版本：HarmonyOS NEXT Developer Preview1 SDK 及以上 配置权限 如涉及网络访问、检索、路线规划等，需要在权限配置中加入至少： "ohos.permission.GET_WIFI_INFO" "ohos.permission.GET_NETWORK_INFO" "ohos.permission.GET_BUNDLE_INFO" "ohos.permission.INTERNET" 提示在工程配置中正确声明这些权限。 精确定位 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 参数/枚举/接口明细） 。 场景（按功能归类） 推荐搜索词 references/reference 定位 references/api/ API 文档入口 地图初始化/展示 MapComponent、MapController、onReady、MapOptions、MapStatus、显示地图 references/reference / references/reference references/api/modules/map 地图类型/底图 setMapType、普通图、卫星图、空白地图、POI显隐、交通流 references/reference / references/reference references/reference 个性化地图 CustomStyle、setCustomStyleById、initCustomStyle、sty references/reference references/reference 室内图 indoorMap、INDOORSTATUSCHANGE、switchIndoorFloor、getIndoorInfo references/reference references/reference 离线地图 LocalMapManager、getHotCities、start、pause、resume、delete references/reference references/api/modules/map 手势/交互 gestures、zoomGesturesEnabled、moveGesturesEnabled、rotateGesturesEnabled、MapEvent.PINCH references/reference references/api/modules/map 控件/图层 CompassLayer、LocationLayer、比例尺、缩放控件、定位控件、getLayerByTag references/reference / references/reference references/api/modules/map 地图事件 MAPSTATUSCHANGE、CLICK、DOUBLECLICK、PINCHSTART、ROTATIONUPDATE references/reference references/api/modules/map 地图生命周期/销毁 onWillDisappear、MapController.onWillDisappear、Navigation、Router references/reference references/api/modules/map 英文地图 MapLanguage、setMapLanguage、getMapLanguage references/reference references/api/modules/map 粒子效果 ParticleEffectType、showParticleEffectByType、customParticleEffectByType references/reference references/api/modules/map 覆盖物：Marker Marker、ImageEntity、addOverlay、removeOverlay、OverlayEvent.CLICK references/reference references/api/modules/map 覆盖物：气泡（弹框、信息窗） PopView、LabelUI、HorizontalLayout references/reference / references/reference references/api/modules/map 覆盖物：点聚合 ClusterGroup、ClusterTemplate、addMarker references/reference references/api/modules/map 覆盖物：折线/轨迹 Polyline、textures、dottedline、TrackAnimation、Track references/reference / references/reference / references/reference references/api/modules/map 覆盖物：面/圆 Polygon、Circle、Stroke、fillcolor、alpha references/reference / references/reference references/api/modules/map 覆盖物：3D Prism、Building、Bd_3DModel、GLTF、OBJ references/reference / references/reference / references/reference references/api/modules/map 图层：瓦片/热力 UrlTileProvider、ImageTileLayer、HeatMapBuilder、HexagonMapBuilder references/reference / references/reference / references/reference / references/reference references/api/modules/map 检索：POI PoiSearch、searchInCity、searchNearby、searchInBound、PoiDetail references/reference references/api/modules/search 检索：地理编码 GeoCoder、geocode、reverseGeoCode、GeoCodeOption references/reference references/api/modules/search 检索：AOI AoiSearch、requestAoi、polygon references/reference references/api/modules/search 检索：Sug SuggestionSearch、requestSuggestion references/reference references/api/modules/search 检索：公交线路 BusLineSearch、searchBusLine、BUS_LINE、SUBWAY_LINE references/reference references/api/modules/search 检索：天气 WeatherSearch、WeatherResult、districtID references/reference references/api/modules/search 检索：推荐上车点 requestRecommendStop、RecommendStopResult references/reference references/api/modules/search 检索：行政区 DistrictSearch、searchDistrict、边界、polylines references/reference references/api/modules/search 检索：建筑物 BuildingSearch、requestBuilding、3D楼块 references/reference references/api/modules/search 路线：驾车 RoutePlanSearch、drivingSearch、DrivingRouteResult references/reference references/api/modules/search / references/api/modules/walkridecommon 路线：步行 walkingSearch、WalkingRouteResult references/reference references/api/modules/search / references/api/modules/walkridecommon 路线：骑行 bikingSearch、BikingRouteResult references/reference references/api/modules/search / references/api/modules/walkridecommon 路线：公交 transitSearch、masstransitSearch、TransitRouteResult references/reference references/api/modules/search / references/api/modules/walkridecommon 导航：步骑行引擎 BDNaviService、NaviType、NaviMode、initializer、init、unInit 步骑行导航 SDK 开发指南 references/api/modules/walkridecommon 导航：路线规划 RoutePlanOption、RouteNodeInfo、IRoutePlanListener、RoutePlanError、displayRoutePlanResult 步骑行导航 SDK 开发指南 references/api/modules/walkridecommon 导航：导航控制 start、stop、pause、resume、isStart、cancelRoutePlanDisplay、isMultiNaviCreated 步骑行导航 SDK 开发指南 references/api/modules/walkridecommon 导航：状态监听 IGuideSubStatusListener、IGuideInfoListener、onRouteFarAway、onArriveDest、onFinalEnd 步骑行导航 SDK 开发指南 references/api/modules/walkridecommon 导航：默认 UI walkRideDefaultUIPage、walkRideUIPageOption、headerGuideShow、naviETAShow、hitTestBehavior 步骑行导航 SDK 开发指南 references/api/modules/walkridecommon 导航：模拟导航 MockLocationPlugin、setLocationPlugin、resetLocationPlugin、reloadTrack 步骑行导航 SDK 开发指南 references/api/modules/walkridecommon 导航：语音播报 ITTSPlugin、playTTSText、setTTsPlugin 步骑行导航 SDK 开发指南 references/api/modules/walkridecommon 工具：距离/面积 DistanceUtil、AreaUtil、calculateArea、getDistance references/reference references/api/modules/util 工具：空间关系 SpatialRelationUtil、isPolygonContainsPoint、getNearestPointFromLine references/reference references/api/modules/util 工具：坐标转换 NativeMethods、wgsll2bdll、gcjll2bdll、mc2ll references/reference references/api/modules/base / references/api/modules/util