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

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 — 实时导航

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

方法签名：

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

NaviParams 参数说明：

注意：NaviParams 不支持 sourcePosition 属性，起点由花瓣地图自动使用用户当前位置。

// 示例：导航到海珠湿地公园（驾车模式）
const params: petalMaps.NaviParams = {
  destinationPosition: { latitude: 23.0590, longitude: 113.3370 },
  vehicleType: 0 // 驾车
};
await petalMaps.openMapNavi(context, params);

3.2 openMapRoutePlan — 路线规划

拉起花瓣地图的路线规划界面，展示多种出行方式的路线方案。

方法签名：

function openMapRoutePlan(context: common.Context, params: RoutePlanParams): Promise<void>

RoutePlanParams 参数说明：

注意：RoutePlanParams 不支持 sourcePosition 属性，起点由花瓣地图自动使用用户当前位置。

// 示例：规划到海珠湿地公园的路线
const params: petalMaps.RoutePlanParams = {
  destinationPosition: { latitude: 23.0590, longitude: 113.3370 }
};
await petalMaps.openMapRoutePlan(context, params);

3.3 openMapPoiDetail — POI 详情

拉起花瓣地图查看某个 POI（兴趣点）的详细信息，包括地址、电话、评分、评论等。

方法签名：

function openMapPoiDetail(context: common.Context, params: PoiDetailParams): Promise<void>

PoiDetailParams 参数说明：

// 方式一：通过坐标查看 POI 详情
const params: petalMaps.PoiDetailParams = {
  destinationPosition: { latitude: 23.0590, longitude: 113.3370 }
};
await petalMaps.openMapPoiDetail(context, params);

// 方式二：通过 POI ID 查看详情（更精准）
const paramsById: petalMaps.PoiDetailParams = {
  destinationPosition: { latitude: 23.0590, longitude: 113.3370 },
  destinationPoiId: '1234567890'
};
await petalMaps.openMapPoiDetail(context, paramsById);

3.4 openMapTextSearch — 文本搜索

拉起花瓣地图并按关键词搜索地点。

const params: petalMaps.TextSearchParams = {
  text: '海珠湿地公园'
};
await petalMaps.openMapTextSearch(context, params);

3.5 openMapHomePage — 打开地图首页

最简单的方式，直接打开花瓣地图应用首页。

await petalMaps.openMapHomePage(context);

3.6 openMapTaxi — 打车

拉起花瓣地图的打车界面，设置目的地。

const params: petalMaps.TaxiParams = {
  destinationPosition: { latitude: 23.0590, longitude: 113.3370 },
  destinationName: '海珠湿地公园'
};
await petalMaps.openMapTaxi(context, params);

四、Context 获取方式（V1 vs V2）

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

V2 方式详解：

// 在 @ComponentV2 组件中获取 Context
private getCommonContext(): common.Context {
  const hostContext: common.Context | undefined = this.getUIContext().getHostContext();
  if (hostContext === undefined) {
    throw new Error('无法获取 Context');
  }
  return hostContext;
}

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

五、状态管理 V2 实战案例

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

5.1 导航按钮组件

import { petalMaps } from '@kit.MapKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

// 导航操作面板组件
// 使用 @ComponentV2 + @Param + @Local 构建响应式导航操作面板
@ComponentV2
export struct MapActionPanel {
  @Param destLatitude: number = 23.0590;   // 目标纬度
  @Param destLongitude: number = 113.3370; // 目标经度
  @Param srcLatitude: number = 23.0742;    // 起点纬度
  @Param srcLongitude: number = 113.3236;  // 起点经度
  @Local statusMessage: string = '';       // 操作状态反馈

  private getContext(): common.Context {
    const ctx: common.Context | undefined = this.getUIContext().getHostContext();
    if (ctx === undefined) {
      throw new Error('Context 获取失败');
    }
    return ctx;
  }

  // 导航按钮点击处理
  private async handleNavi(): Promise<void> {
    try {
      const ctx: common.Context = this.getContext();
      const params: petalMaps.NaviParams = {
        destinationPosition: {
          latitude: this.destLatitude,
          longitude: this.destLongitude
        },
        vehicleType: 0
      };
      await petalMaps.openMapNavi(ctx, params);
      this.statusMessage = '导航已启动';
    } catch (error) {
      const err: BusinessError = error as BusinessError;
      this.statusMessage = `导航失败(${err.code}): ${err.message}`;
    }
  }

  // 路线规划按钮点击处理
  private async handleRoutePlan(): Promise<void> {
    try {
      const ctx: common.Context = this.getContext();
      const params: petalMaps.RoutePlanParams = {
        destinationPosition: {
          latitude: this.destLatitude,
          longitude: this.destLongitude
        }
      };
      await petalMaps.openMapRoutePlan(ctx, params);
      this.statusMessage = '路线规划已打开';
    } catch (error) {
      const err: BusinessError = error as BusinessError;
      this.statusMessage = `路线规划失败(${err.code}): ${err.message}`;
    }
  }

  // POI 详情按钮点击处理
  private async handlePoiDetail(): Promise<void> {
    try {
      const ctx: common.Context = this.getContext();
      const params: petalMaps.PoiDetailParams = {
        destinationPosition: {
          latitude: this.destLatitude,
          longitude: this.destLongitude
        }
      };
      await petalMaps.openMapPoiDetail(ctx, params);
      this.statusMessage = 'POI 详情已打开';
    } catch (error) {
      const err: BusinessError = error as BusinessError;
      this.statusMessage = `POI 详情失败(${err.code}): ${err.message}`;
    }
  }

  build() {
    Column({ space: 12 }) {
      Button('开始导航')
        .width('100%').height(44)
        .backgroundColor('#007DFF').fontColor(Color.White)
        .onClick(async () => { await this.handleNavi(); })

      Button('路线规划')
        .width('100%').height(44)
        .backgroundColor('#FFFFFF').fontColor('#007DFF')
        .borderWidth(1).borderColor('#007DFF')
        .onClick(async () => { await this.handleRoutePlan(); })

      Button('查看详情')
        .width('100%').height(44)
        .backgroundColor('#FFFFFF').fontColor('#182431')
        .borderWidth(1).borderColor('#E0E0E0')
        .onClick(async () => { await this.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
@ComponentV2
struct 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 {
  await petalMaps.openMapNavi(context, params);
} catch (error) {
  const err: BusinessError = error as BusinessError;
  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 开发指南