《商家地址路线导航》二、拉起地图应用指南

HarmonyOS petalMaps 拉起地图应用使用指南：导航、路线规划与 POI 详情（状态管理V2版）

本文详细介绍 HarmonyOS@kit.MapKit中petalMaps命名空间的全部 API，包括导航、路线规划、POI 详情、文本搜索等功能，并提供状态管理 V2（@ComponentV2）完整实战案例，帮助开发者在应用中无缝拉起花瓣地图。

效果

一、什么是 petalMaps（拉起地图应用）

petalMaps是 HarmonyOS Map Kit 提供的应用间调用能力，通过 Intent 机制拉起设备上已安装的花瓣地图（Petal Maps）应用，实现导航、路线规划、POI 详情查看、文本搜索、打车等功能。

与集成地图 SDK 相比，petalMaps 的优势在于：

• 零 UI 开发成本：无需在应用中实现地图交互 UI，直接复用花瓣地图的成熟体验
• 功能完整：导航、路线规划、打车等专业功能由花瓣地图承载
• 持续更新：花瓣地图独立升级，应用侧无需跟进地图功能迭代

支持的功能列表

二、前置条件

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}from'@kit.MapKit';import{common}from'@kit.AbilityKit';

三、核心 API 详解

3.1 openMapNavi — 实时导航

拉起花瓣地图的实时导航界面，支持设置终点和出行方式。

方法签名：

functionopenMapNavi(context:common.Context,params:NaviParams):Promise<void>

NaviParams 参数说明：

注意：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):Promise<void>

RoutePlanParams 参数说明：

注意：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):Promise<void>

PoiDetailParams 参数说明：

// 方式一：通过坐标查看 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 V2）

petalMaps 的所有 API 都需要传入common.Context参数，在 V1 和 V2 中获取方式不同：

V2 方式详解：

// 在 @ComponentV2 组件中获取 ContextprivategetCommonContext():common.Context{consthostContext:common.Context|undefined=this.getUIContext().getHostContext();if(hostContext===undefined){thrownewError('无法获取 Context');}returnhostContext;}

注意：getHostContext()可能返回undefined，需要做空值判断后再使用。

五、状态管理 V2 实战案例

以下是一个完整的导航操作面板组件，提供导航、路线规划、POI 详情三种操作按钮。

5.1 导航按钮组件

import{petalMaps}from'@kit.MapKit';import{common}from'@kit.AbilityKit';import{BusinessError}from'@kit.BasicServicesKit';// 导航操作面板组件// 使用 @ComponentV2 + @Param + @Local 构建响应式导航操作面板@ComponentV2exportstruct MapActionPanel{@ParamdestLatitude:number=23.0590;// 目标纬度@ParamdestLongitude:number=113.3370;// 目标经度@ParamsrcLatitude:number=23.0742;// 起点纬度@ParamsrcLongitude:number=113.3236;// 起点经度@LocalstatusMessage:string='';// 操作状态反馈privategetContext():common.Context{constctx:common.Context|undefined=this.getUIContext().getHostContext();if(ctx===undefined){thrownewError('Context 获取失败');}returnctx;}// 导航按钮点击处理privateasynchandleNavi():Promise<void>{try{constctx:common.Context=this.getContext();constparams:petalMaps.NaviParams={destinationPosition:{latitude:this.destLatitude,longitude:this.destLongitude},vehicleType:0};awaitpetalMaps.openMapNavi(ctx,params);this.statusMessage='导航已启动';}catch(error){consterr:BusinessError=errorasBusinessError;this.statusMessage=`导航失败(${err.code}):${err.message}`;}}// 路线规划按钮点击处理privateasynchandleRoutePlan():Promise<void>{try{constctx:common.Context=this.getContext();constparams:petalMaps.RoutePlanParams={destinationPosition:{latitude:this.destLatitude,longitude:this.destLongitude}};awaitpetalMaps.openMapRoutePlan(ctx,params);this.statusMessage='路线规划已打开';}catch(error){consterr:BusinessError=errorasBusinessError;this.statusMessage=`路线规划失败(${err.code}):${err.message}`;}}// POI 详情按钮点击处理privateasynchandlePoiDetail():Promise<void>{try{constctx:common.Context=this.getContext();constparams:petalMaps.PoiDetailParams={destinationPosition:{latitude:this.destLatitude,longitude:this.destLongitude}};awaitpetalMaps.openMapPoiDetail(ctx,params);this.statusMessage='POI 详情已打开';}catch(error){consterr:BusinessError=errorasBusinessError;this.statusMessage=`POI 详情失败(${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.length>0){Text(this.statusMessage).fontSize(12).fontColor('#999999')}}.width('100%').padding(16)}}

5.2 父组件调用方式

import{MapActionPanel}from'../components/MapActionPanel';@Entry@ComponentV2struct 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 均返回Promise<void>，调用失败时会抛出BusinessError，需使用try-catch处理。

// 推荐的错误处理模式try{awaitpetalMaps.openMapNavi(context,params);}catch(error){consterr:BusinessError=errorasBusinessError;if(err.code===1002103){// 提示用户安装花瓣地图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 应用中实现导航、路线规划的推荐方案。关键开发步骤：

1. 确保设备已安装花瓣地图
2. 开通地图服务并配置签名
3. 通过this.getUIContext().getHostContext()获取 Context（V2 方式）
4. 构造对应的 Params 对象
5. 使用await+try-catch调用 petalMaps API

参考文档

• petalMaps API 官方参考
• 开通地图服务配置指南
• HarmonyOS 状态管理 V2 开发指南
  Context（V2 方式）

4. 构造对应的 Params 对象
5. 使用await+try-catch调用 petalMaps API

参考文档

• petalMaps API 官方参考
• 开通地图服务配置指南
• HarmonyOS 状态管理 V2 开发指南