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，直接复用花瓣地图的成熟体验
- 功能完整：导航、路线规划、打车等专业功能由花瓣地图承载
- 持续更新：花瓣地图独立升级，应用侧无需跟进地图功能迭代
支持的功能列表
| 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}from'@kit.MapKit';import{common}from'@kit.AbilityKit';三、核心 API 详解
3.1 openMapNavi — 实时导航
拉起花瓣地图的实时导航界面，支持设置终点和出行方式。
方法签名：
functionopenMapNavi(context:common.Context,params:NaviParams):Promise<void>NaviParams 参数说明：
| 属性名 | 类型 | 必填 | 说明 |
|---|---|---|---|
destinationPosition | Coordinate2D | 是 | 目的地坐标{ latitude, longitude } |
vehicleType | number | 否 | 出行方式：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):Promise<void>RoutePlanParams 参数说明：
| 属性名 | 类型 | 必填 | 说明 |
|---|---|---|---|
destinationPosition | Coordinate2D | 是 | 目的地坐标 |
注意：
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 参数说明：
| 属性名 | 类型 | 必填 | 说明 |
|---|---|---|---|
destinationPosition | Coordinate2D | 否 | POI 坐标（与destinationPoiId二选一） |
destinationPoiId | string | 否 | 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 V2）
petalMaps 的所有 API 都需要传入common.Context参数，在 V1 和 V2 中获取方式不同：
| 方式 | 代码 | 适用场景 |
|---|---|---|
| V1 方式 | getContext(this) | @Component（V1 组件） |
| V2 方式 | this.getUIContext().getHostContext() | @ComponentV2（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处理。
| 错误码 | 含义 | 排查方向 |
|---|---|---|
1002101 | 参数错误 | 检查坐标值是否在有效范围内 |
1002102 | 网络错误 | 检查设备网络连接 |
1002103 | 花瓣地图未安装 | 确认设备已安装花瓣地图应用 |
60001 | 地图服务未开通 | 前往 AGC 开通地图服务并重新签名 |
60002 | 签名校验失败 | 检查签名证书和 Profile 文件是否正确 |
// 推荐的错误处理模式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 应用中实现导航、路线规划的推荐方案。关键开发步骤：
- 确保设备已安装花瓣地图
- 开通地图服务并配置签名
- 通过
this.getUIContext().getHostContext()获取 Context（V2 方式） - 构造对应的 Params 对象
- 使用
await+try-catch调用 petalMaps API
参考文档
- petalMaps API 官方参考
- 开通地图服务配置指南
- HarmonyOS 状态管理 V2 开发指南
Context（V2 方式）
- 构造对应的 Params 对象
- 使用
await+try-catch调用 petalMaps API
参考文档
- petalMaps API 官方参考
- 开通地图服务配置指南
- HarmonyOS 状态管理 V2 开发指南
