帮助在 HarmonyOS NEXT 上使用百度地图鸿蒙 SDK 进行开发。支持独立包(@bdmap/base、@bdmap/map、@bdmap/search、@bdmap/util)和组合包(@bdmap/map_walkride_search、@bdmap/navi_map),以及定位 SDK(@bdmap...
在以下情况必须优先使用本 Skill:
@bdmap/base、@bdmap/map、@bdmap/search、@bdmap/util 等包或者直接完全使用 @bdmap/map_walkride_search等组合包以下情况不适合使用本 Skill,应转用其他平台/能力的 Skill:
在使用本 Skill 进行开发时,必须严格遵守以下规范(仅列核心摘要,详细说明见引用文档):
依赖安装前置(最高优先级,必须在编码之前执行)
oh-package.json5 中声明了所需的 @bdmap/* 依赖,并在工程根目录成功执行 ohpm install,使 oh_modules/ 下存在对应包的声明文件(.d.ets)后,才能开始分析需求和编写代码。Index.d.ets 及其引用的 .d.ets)为准。仅凭文档示例或记忆推测 API 会导致导入路径错误。entry/oh-package.json5(或工程根 oh-package.json5)中是否已声明所需的 @bdmap/* 依赖;若缺失则先补充声明。ohpm install,确认安装成功(无报错)。oh_modules/.ohpm/@bdmap+<包名>@<版本>/oh_modules/@bdmap/<包名>/Index.d.ets 文件存在。Index.d.ets �灵精附体确认目标类/接口/枚举的实际导出包名和导出名称。对于属性名、方法签名等细节,应跳转到具体的 .d.ets 定义文件确认。日志 / 注释 / 模块化规范
Logger 工具类封装原生 console,第一个参数固定使用场景名 "SportHealthMap",禁止直接使用 console.info/error/warn/debug。图片资源使用规范(必须主动拷贝)
resources/rawfile/ 目录后,再通过 rawfile://xxx.png 方式引用,否则覆盖物会因为找不到资源而不显示或报错。地图功能开发(代码组织与规范)(强制要求)
references/reference.md 中给出的示例代码与调用方式,在此基础上按业务场景做适配,避免自创与 SDK 不一致的用法。zIndex 并遵循统一分层,避免信息被遮挡;详细见:地图性能与覆盖物分层规范。@bdmap/locsdk 的地图场景时,需同时遵守定位 SDK 的初始化顺序、权限与错误处理规范;完整说明见:定位 SDK 开发指南。@bdmap/map_walkride_search)时,需遵循导航引擎初始化时序、生命周期管理、模拟导航退出、默认 UI 手势穿透等规范;完整说明见:步骑行导航 SDK 开发指南。any 或隐式 undefined;当无法明确 .catch 回调参数类型时,优先使用 Error 或 object,确保通过 ArkTSCheck。包管理互斥规则(强制要求)
@bdmap/map_walkride_search、@bdmap/navi_map)与独立包(@bdmap/base、@bdmap/map、@bdmap/search、@bdmap/util)不允许混用,否则会导致依赖冲突。oh-package.json5 中已有的包方案,并严格遵循同一方案。@bdmap/locsdk 为独立定位包,不受上述互斥限制,可与任何方案搭配使用。运行检测(Auto Run 构建)
ohpm install + hvigorw assembleHap --mode module -p product=default -p buildMode=debug --no-daemon。处理任何鸿蒙百度地图 SDK 相关问题时,遵循以下流程组织思路与回答:
ohpm install @bdmap/baseohpm install @bdmap/searchohpm install @bdmap/utilohpm install @bdmap/mapohpm install @bdmap/locsdkohpm install @bdmap/map_walkride_searchohpm install @bdmap/navi_mapoh-package.json5 中声明依赖后,必须在工程根目录执行 ohpm install 并确认安装成功。在依赖包未实际安装到 oh_modules/ 之前,禁止编写任何业务代码。安装成功后,必须通过查阅 oh_modules/.ohpm/@bdmap+<包名>@<版本>/oh_modules/@bdmap/<包名>/Index.d.ets 确认所需类/接口/枚举的实际导出位置和名称,再开始编码。"ohos.permission.GET_WIFI_INFO""ohos.permission.GET_NETWORK_INFO""ohos.permission.GET_BUNDLE_INFO""ohos.permission.INTERNET"在提需求时,优先按照下列能力分类,结合对应模块文档进行回答。
使用建议:
references/reference.md 小节查看示例与用法。关键词(用户问题) → references/reference(示例与用法)。如需更详细的 API 参数/枚举/接口明细,请查阅在线官方文档或安装包声明文件。| 场景(按功能归类) | 推荐搜索词 | references/reference 定位 |
|---|---|---|
| 地图初始化/展示 | MapComponent、MapController、onReady、MapOptions、MapStatus、显示地图 | references/reference / references/reference |
| 地图类型/底图 | setMapType、普通图、卫星图、空白地图、POI显隐、交通流 | references/reference / references/reference |
| 个性化地图 | CustomStyle、setCustomStyleById、initCustomStyle、sty | references/reference |
| 室内图 | indoorMap、INDOORSTATUSCHANGE、switchIndoorFloor、getIndoorInfo | references/reference |
| 离线地图 | LocalMapManager、getHotCities、start、pause、resume、delete | references/reference |
| 手势/交互 | gestures、zoomGesturesEnabled、moveGesturesEnabled、rotateGesturesEnabled、MapEvent.PINCH | references/reference |
| 控件/图层 | CompassLayer、LocationLayer、比例尺、缩放控件、定位控件、getLayerByTag | references/reference / references/reference |
| 地图事件 | MAPSTATUSCHANGE、CLICK、DOUBLECLICK、PINCHSTART、ROTATIONUPDATE | references/reference |
| 地图生命周期/销毁 | onWillDisappear、MapController.onWillDisappear、Navigation、Router | references/reference |
| 英文地图 | MapLanguage、setMapLanguage、getMapLanguage | references/reference |
| 粒子效果 | ParticleEffectType、showParticleEffectByType、customParticleEffectByType | references/reference |
| 覆盖物:Marker | Marker、ImageEntity、addOverlay、removeOverlay、OverlayEvent.CLICK | references/reference |
| 覆盖物:气泡(弹框、信息窗) | PopView、LabelUI、HorizontalLayout | references/reference / references/reference |
| 覆盖物:点聚合 | ClusterGroup、ClusterTemplate、addMarker | references/reference |
| 覆盖物:折线/轨迹 | Polyline、textures、dottedline、TrackAnimation、Track | references/reference / references/reference / references/reference |
| 覆盖物:面/圆 | Polygon、Circle、Stroke、fillcolor、alpha | references/reference / references/reference |
| 覆盖物:3D | Prism、Building、Bd_3DModel、GLTF、OBJ | references/reference / references/reference / references/reference |
| 图层:瓦片/热力 | UrlTileProvider、ImageTileLayer、HeatMapBuilder、HexagonMapBuilder | references/reference / references/reference / references/reference / references/reference |
| 检索:POI | PoiSearch、searchInCity、searchNearby、searchInBound、PoiDetail | references/reference |
| 检索:地理编码 | GeoCoder、geocode、reverseGeoCode、GeoCodeOption | references/reference |
| 检索:AOI | AoiSearch、requestAoi、polygon | references/reference |
| 检索:Sug | SuggestionSearch、requestSuggestion | references/reference |
| 检索:公交线路 | BusLineSearch、searchBusLine、BUS_LINE、SUBWAY_LINE | references/reference |
| 检索:天气 | WeatherSearch、WeatherResult、districtID | references/reference |
| 检索:推荐上车点 | requestRecommendStop、RecommendStopResult | references/reference |
| 检索:行政区 | DistrictSearch、searchDistrict、边界、polylines | references/reference |
| 检索:建筑物 | BuildingSearch、requestBuilding、3D楼块 | references/reference |
| 路线:驾车 | RoutePlanSearch、drivingSearch、DrivingRouteResult | references/reference |
| 路线:步行 | walkingSearch、WalkingRouteResult | references/reference |
| 路线:骑行 | bikingSearch、BikingRouteResult | references/reference |
| 路线:公交 | transitSearch、masstransitSearch、TransitRouteResult | references/reference |
| 导航:步骑行引擎 | BDNaviService、NaviType、NaviMode、initializer、init、unInit | 步骑行导航 SDK 开发指南 |
| 导航:路线规划 | RoutePlanOption、RouteNodeInfo、IRoutePlanListener、RoutePlanError、displayRoutePlanResult | 步骑行导航 SDK 开发指南 |
| 导航:导航控制 | start、stop、pause、resume、isStart、cancelRoutePlanDisplay、isMultiNaviCreated | 步骑行导航 SDK 开发指南 |
| 导航:状态监听 | IGuideSubStatusListener、IGuideInfoListener、onRouteFarAway、onArriveDest、onFinalEnd | 步骑行导航 SDK 开发指南 |
| 导航:默认 UI | walkRideDefaultUIPage、walkRideUIPageOption、headerGuideShow、naviETAShow、hitTestBehavior | 步骑行导航 SDK 开发指南 |
| 导航:模拟导航 | MockLocationPlugin、setLocationPlugin、resetLocationPlugin、reloadTrack | 步骑行导航 SDK 开发指南 |
| 导航:语音播报 | ITTSPlugin、playTTSText、setTTsPlugin | 步骑行导航 SDK 开发指南 |
| 工具:距离/面积 | DistanceUtil、AreaUtil、calculateArea、getDistance | references/reference |
| 工具:空间关系 | SpatialRelationUtil、isPolygonContainsPoint、getNearestPointFromLine | references/reference |
| 工具:坐标转换 | NativeMethods、wgsll2bdll、gcjll2bdll、mc2ll | references/reference |
| 其他:收藏/分享 | FavoriteManager、ShareUrlSearch、requestRouteShareUrl | references/reference / references/reference |
MapComponentonReady 中拿到 MapControllerMapController 提供的方法添加/更新/删除对应覆盖物@bdmap/search 或组合包@bdmap/search 以及必要的步行/骑行/公交相关模块或组合包,例如 @bdmap/map_walkride_search步骑行导航场景:若需求不仅是路线规划,还涉及实时导航引导(导航启停、偏航重算、默认导航 UI、语音播报、模拟导航等),请直接参考第 8 节「步骑行导航能力」和 步骑行导航 SDK 开发指南。
本节只给出关键要点,完整开发指南请见:定位 SDK 开发指南。
@bdmap/locsdk 版本,按指南配置线上/线下依赖并执行 ohpm install + 构建自检。LocationClient.setAgreePrivacy(true)、LocationClient.checkAuthKey(...),并正确声明 module.json5 中的定位相关权限与 backgroundModes。LocationClient → 注册监听 → 配置 LocationClientOption → 启动定位」的顺序,页面/业务结束时必须停止定位并注销监听。isLocSuccess、坐标非 (0,0)、精度半径合理,并通过 Logger + Toast/状态文本反馈错误原因与解决建议。本节只给出关键要点,完整开发指南请见:步骑行导航 SDK 开发指南。
@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() 释放引擎。walkRideDefaultUIPage 渲染导航界面时,必须设置 .hitTestBehavior(HitTestMode.None) 防止拦截底图手势。CoordTrans.wgsToBaidu() / CoordTrans.gcjToBaidu() 转换。RoutePlanError 提供 20+ 种错误码,必须封装用户友好的错误提示,不可仅输出日志。在基于本 Skill 回答问题时:
@bdmap/map 覆盖物、信息框/PopView 等能力)时,必须优先读取本地文档:
read_file / grep 等工具打开并检索:
web_search 查阅在线文档(如 https://lbsyun.baidu.com/faq/api?title=harmonynextsdk),并在回答中说明参考来源。ohpm install 与 hvigorw assembleHap --mode module -p product=default -p buildMode=debug --no-daemon 进行构建与 ArkTSCheck 自检。使用本 Skill 时,始终优先结合本地文档、安装包声明文件和在线官方文档:
entry/oh-package.json5中的引用是否已经安装,如果未安装,则需要通过ohpm install安装,记录下包名版本号oh_modules/.ohpm/@bdmap+包名@版本号,找到目录oh_modules/@bdmap/包名/Index.d.ets文件Index.d.ets文件中内部搜索类型名,查看定义{MapController} from '@bdmap/map'的MapController定义,定位到当前工程中的oh_modules/.ohpm/@bdmap+map@2.0.3/oh_modules/@bdmap/map/Index.d.ets文件,查到MapController是Index.d.ets的相对路径./src/main/ets/lbsmapsdk/e/g,则通过oh_modules/.ohpm/@bdmap+map@2.0.3/oh_modules/@bdmap/map/src/main/ets/lbsmapsdk/e/g.d.ets文件,即可找到MapController的定义;https://lbsyun.baidu.com/faq/api?title=harmonynextsdk当本地文档与在线文档存在差异时,以在线官方文档为准,但要在回答中说明参考了哪一类文档。
ZIP package — ready to use