HarmonyOS petalMaps 拉起地图应用使用指南导航、路线规划与 POI 详情状态管理V2版本文详细介绍 HarmonyOSkit.MapKit中petalMaps命名空间的全部 API包括导航、路线规划、POI 详情、文本搜索等功能并提供状态管理 V2ComponentV2完整实战案例帮助开发者在应用中无缝拉起花瓣地图。效果一、什么是 petalMaps拉起地图应用petalMaps是 HarmonyOS Map Kit 提供的应用间调用能力通过 Intent 机制拉起设备上已安装的花瓣地图Petal Maps应用实现导航、路线规划、POI 详情查看、文本搜索、打车等功能。与集成地图 SDK 相比petalMaps 的优势在于零 UI 开发成本无需在应用中实现地图交互 UI直接复用花瓣地图的成熟体验功能完整导航、路线规划、打车等专业功能由花瓣地图承载持续更新花瓣地图独立升级应用侧无需跟进地图功能迭代支持的功能列表API 方法功能说明openMapNavi打开实时导航界面openMapRoutePlan打开路线规划界面openMapPoiDetail查看 POI兴趣点详情openMapTextSearch按关键词搜索地点openMapHomePage打开花瓣地图首页openMapTaxi打开打车界面二、前置条件2.1 设备要求设备需预装花瓣地图应用HarmonyOS 系统设备通常预装真机运行ARM/x86 模拟器不支持 petalMaps 功能必须使用真机调试2.2 开通地图服务登录 AppGallery Connect在项目中开启地图服务并重新申请 Profile 签名文件。2.3 声明网络权限在module.json5中声明{ module: { requestPermissions: [ { name: ohos.permission.INTERNET } ] } }2.4 导入模块import{petalMaps}fromkit.MapKit;import{common}fromkit.AbilityKit;三、核心 API 详解3.1 openMapNavi — 实时导航拉起花瓣地图的实时导航界面支持设置终点和出行方式。方法签名functionopenMapNavi(context:common.Context,params:NaviParams):PromisevoidNaviParams 参数说明属性名类型必填说明destinationPositionCoordinate2D是目的地坐标{ latitude, longitude }vehicleTypenumber否出行方式0驾车1步行2骑行注意NaviParams不支持sourcePosition属性起点由花瓣地图自动使用用户当前位置。// 示例导航到海珠湿地公园驾车模式constparams:petalMaps.NaviParams{destinationPosition:{latitude:23.0590,longitude:113.3370},vehicleType:0// 驾车};awaitpetalMaps.openMapNavi(context,params);3.2 openMapRoutePlan — 路线规划拉起花瓣地图的路线规划界面展示多种出行方式的路线方案。方法签名functionopenMapRoutePlan(context:common.Context,params:RoutePlanParams):PromisevoidRoutePlanParams 参数说明属性名类型必填说明destinationPositionCoordinate2D是目的地坐标注意RoutePlanParams不支持sourcePosition属性起点由花瓣地图自动使用用户当前位置。// 示例规划到海珠湿地公园的路线constparams:petalMaps.RoutePlanParams{destinationPosition:{latitude:23.0590,longitude:113.3370}};awaitpetalMaps.openMapRoutePlan(context,params);3.3 openMapPoiDetail — POI 详情拉起花瓣地图查看某个 POI兴趣点的详细信息包括地址、电话、评分、评论等。方法签名functionopenMapPoiDetail(context:common.Context,params:PoiDetailParams):PromisevoidPoiDetailParams 参数说明属性名类型必填说明destinationPositionCoordinate2D否POI 坐标与destinationPoiId二选一destinationPoiIdstring否POI 唯一 ID优先使用 ID 定位// 方式一通过坐标查看 POI 详情constparams:petalMaps.PoiDetailParams{destinationPosition:{latitude:23.0590,longitude:113.3370}};awaitpetalMaps.openMapPoiDetail(context,params);// 方式二通过 POI ID 查看详情更精准constparamsById:petalMaps.PoiDetailParams{destinationPosition:{latitude:23.0590,longitude:113.3370},destinationPoiId:1234567890};awaitpetalMaps.openMapPoiDetail(context,paramsById);3.4 openMapTextSearch — 文本搜索拉起花瓣地图并按关键词搜索地点。constparams:petalMaps.TextSearchParams{text:海珠湿地公园};awaitpetalMaps.openMapTextSearch(context,params);3.5 openMapHomePage — 打开地图首页最简单的方式直接打开花瓣地图应用首页。awaitpetalMaps.openMapHomePage(context);3.6 openMapTaxi — 打车拉起花瓣地图的打车界面设置目的地。constparams:petalMaps.TaxiParams{destinationPosition:{latitude:23.0590,longitude:113.3370},destinationName:海珠湿地公园};awaitpetalMaps.openMapTaxi(context,params);四、Context 获取方式V1 vs V2petalMaps 的所有 API 都需要传入common.Context参数在 V1 和 V2 中获取方式不同方式代码适用场景V1 方式getContext(this)ComponentV1 组件V2 方式this.getUIContext().getHostContext()ComponentV2V2 组件V2 方式详解// 在 ComponentV2 组件中获取 ContextprivategetCommonContext():common.Context{consthostContext:common.Context|undefinedthis.getUIContext().getHostContext();if(hostContextundefined){thrownewError(无法获取 Context);}returnhostContext;}注意getHostContext()可能返回undefined需要做空值判断后再使用。五、状态管理 V2 实战案例以下是一个完整的导航操作面板组件提供导航、路线规划、POI 详情三种操作按钮。5.1 导航按钮组件import{petalMaps}fromkit.MapKit;import{common}fromkit.AbilityKit;import{BusinessError}fromkit.BasicServicesKit;// 导航操作面板组件// 使用 ComponentV2 Param Local 构建响应式导航操作面板ComponentV2exportstruct MapActionPanel{ParamdestLatitude:number23.0590;// 目标纬度ParamdestLongitude:number113.3370;// 目标经度ParamsrcLatitude:number23.0742;// 起点纬度ParamsrcLongitude:number113.3236;// 起点经度LocalstatusMessage:string;// 操作状态反馈privategetContext():common.Context{constctx:common.Context|undefinedthis.getUIContext().getHostContext();if(ctxundefined){thrownewError(Context 获取失败);}returnctx;}// 导航按钮点击处理privateasynchandleNavi():Promisevoid{try{constctx:common.Contextthis.getContext();constparams:petalMaps.NaviParams{destinationPosition:{latitude:this.destLatitude,longitude:this.destLongitude},vehicleType:0};awaitpetalMaps.openMapNavi(ctx,params);this.statusMessage导航已启动;}catch(error){consterr:BusinessErrorerrorasBusinessError;this.statusMessage导航失败(${err.code}):${err.message};}}// 路线规划按钮点击处理privateasynchandleRoutePlan():Promisevoid{try{constctx:common.Contextthis.getContext();constparams:petalMaps.RoutePlanParams{destinationPosition:{latitude:this.destLatitude,longitude:this.destLongitude}};awaitpetalMaps.openMapRoutePlan(ctx,params);this.statusMessage路线规划已打开;}catch(error){consterr:BusinessErrorerrorasBusinessError;this.statusMessage路线规划失败(${err.code}):${err.message};}}// POI 详情按钮点击处理privateasynchandlePoiDetail():Promisevoid{try{constctx:common.Contextthis.getContext();constparams:petalMaps.PoiDetailParams{destinationPosition:{latitude:this.destLatitude,longitude:this.destLongitude}};awaitpetalMaps.openMapPoiDetail(ctx,params);this.statusMessagePOI 详情已打开;}catch(error){consterr:BusinessErrorerrorasBusinessError;this.statusMessagePOI 详情失败(${err.code}):${err.message};}}build(){Column({space:12}){Button(开始导航).width(100%).height(44).backgroundColor(#007DFF).fontColor(Color.White).onClick(async(){awaitthis.handleNavi();})Button(路线规划).width(100%).height(44).backgroundColor(#FFFFFF).fontColor(#007DFF).borderWidth(1).borderColor(#007DFF).onClick(async(){awaitthis.handleRoutePlan();})Button(查看详情).width(100%).height(44).backgroundColor(#FFFFFF).fontColor(#182431).borderWidth(1).borderColor(#E0E0E0).onClick(async(){awaitthis.handlePoiDetail();})if(this.statusMessage.length0){Text(this.statusMessage).fontSize(12).fontColor(#999999)}}.width(100%).padding(16)}}5.2 父组件调用方式import{MapActionPanel}from../components/MapActionPanel;EntryComponentV2struct NavigationPage{build(){Column(){Text(海珠湿地公园).fontSize(22).fontWeight(FontWeight.Bold)MapActionPanel({destLatitude:23.0590,destLongitude:113.3370,srcLatitude:23.0742,srcLongitude:113.3236})}.padding(16)}}六、错误处理与常见错误码所有 petalMaps API 均返回Promisevoid调用失败时会抛出BusinessError需使用try-catch处理。错误码含义排查方向1002101参数错误检查坐标值是否在有效范围内1002102网络错误检查设备网络连接1002103花瓣地图未安装确认设备已安装花瓣地图应用60001地图服务未开通前往 AGC 开通地图服务并重新签名60002签名校验失败检查签名证书和 Profile 文件是否正确// 推荐的错误处理模式try{awaitpetalMaps.openMapNavi(context,params);}catch(error){consterr:BusinessErrorerrorasBusinessError;if(err.code1002103){// 提示用户安装花瓣地图console.warn(请先安装花瓣地图应用);}else{console.error(操作失败:${err.code}-${err.message});}}七、注意事项7.1 异步调用所有 petalMaps API 均为异步操作调用后花瓣地图应用启动需要一定时间建议使用await等待完成。7.2 坐标系一致性传入的坐标必须与地图服务配置的坐标系一致。中国大陆使用GCJ02火星坐标系海外使用WGS84。7.3 vehicleType 出行方式openMapNavi的vehicleType支持三种出行方式0驾车导航默认1步行导航2骑行导航7.4 POI ID 优先级openMapPoiDetail中如果同时传入了destinationPoiId和destinationPosition优先使用 POI ID定位坐标作为兜底。7.5 模拟器限制petalMaps 命名空间下的所有 API在模拟器上不可用包括 ARM 和 x86 模拟器必须使用 HarmonyOS 真机进行调试。八、总结petalMaps提供了应用间拉起花瓣地图的完整能力是 HarmonyOS 应用中实现导航、路线规划的推荐方案。关键开发步骤确保设备已安装花瓣地图开通地图服务并配置签名通过this.getUIContext().getHostContext()获取 ContextV2 方式构造对应的 Params 对象使用awaittry-catch调用 petalMaps API参考文档petalMaps API 官方参考开通地图服务配置指南HarmonyOS 状态管理 V2 开发指南ContextV2 方式构造对应的 Params 对象使用awaittry-catch调用 petalMaps API参考文档petalMaps API 官方参考开通地图服务配置指南HarmonyOS 状态管理 V2 开发指南