目录

petalMaps (Starting the Map App)

This module provides the function of starting the map app.

Since: 5.0.3(15)

Modules to Import

import { petalMaps } from '@kit.MapKit';

openMapHomePage

openMapHomePage(context: common.Context): Promise<void>

Opens the home screen of the map app. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Map.Core

Device behavior differences: For version 5.1.1(19) or earlier, this API is supported on phones and tablets. On other device types, it returns error code 801. For version 6.0.0(20) or later, this API is supported on phones, tablets, and PCs/2-in-1 devices. On other device types, it returns error code 801.

Since: 5.0.3(15)

Parameters:

Name Type Mandatory Description
context common.Context Yes Context.

Returns:

Type Description
Promise<void> Promise that returns no value.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
401 Invalid input parameter.
1002600014 Failed to start the map app.
801

Capability not supported. Failed to call the API due to limited device capabilities.

Applicable versions: 5.1.0(18)+

Example:

await petalMaps.openMapHomePage(this.getUIContext().getHostContext());

openMapPoiDetail

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

Opens the POI details screen of the map app. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Map.Core

Device behavior differences: For version 5.1.1(19) or earlier, this API is supported on phones and tablets. On other device types, it returns error code 801. For version 6.0.0(20) or later, this API is supported on phones, tablets, and PCs/2-in-1 devices. On other device types, it returns error code 801.

Since: 5.0.3(15)

Parameters:

Name Type Mandatory Description
context common.Context Yes Context.
poiDetailParams PoiDetailParams Yes Parameters for POI details.

Returns:

Type Description
Promise<void> Promise that returns no value.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
401 Invalid input parameter.
1002600014 Failed to start the map app.
801

Capability not supported. Failed to call the API due to limited device capabilities.

Applicable versions: 5.1.0(18)+

Example:

let params: petalMaps.PoiDetailParams = {
  destinationPosition: {
    latitude: 30.983015468224288,
    longitude: 118.78058590757131
  }
};
await petalMaps.openMapPoiDetail(this.getUIContext().getHostContext(), params);

openMapTextSearch

openMapTextSearch(context: common.Context, textSearchParams: TextSearchParams): Promise<void>

Opens the text search screen of the map app. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Map.Core

Device behavior differences: For version 5.1.1(19) or earlier, this API is supported on phones and tablets. On other device types, it returns error code 801. For version 6.0.0(20) or later, this API is supported on phones, tablets, and PCs/2-in-1 devices. On other device types, it returns error code 801.

Since: 5.0.3(15)

Parameters:

Name Type Mandatory Description
context common.Context Yes Context.
textSearchParams TextSearchParams Yes Parameters for text search.

Returns:

Type Description
Promise<void> Promise that returns no value.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
401 Invalid input parameter.
1002600014 Failed to start the map app.
801

Capability not supported. Failed to call the API due to limited device capabilities.

Applicable versions: 5.1.0(18)+

Example:

let params: petalMaps.TextSearchParams = {
  destinationName: 'Cloud Park'
};
await petalMaps.openMapTextSearch(this.getUIContext().getHostContext(), params);

openMapRoutePlan

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

Opens the route planning screen of the map app. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Map.Core

Device behavior differences: For version 5.1.1(19) or earlier, this API is supported on phones and tablets. On other device types, it returns error code 801. For version 6.0.0(20) or later, this API is supported on phones, tablets, and PCs/2-in-1 devices. On other device types, it returns error code 801.

Since: 5.0.3(15)

Parameters:

Name Type Mandatory Description
context common.Context Yes Context.
routePlanParams RoutePlanParams Yes Parameters for route planning.

Returns:

Type Description
Promise<void> Promise that returns no value.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
401 Invalid input parameter.
1002600014 Failed to start the map app.
801

Capability not supported. Failed to call the API due to limited device capabilities.

Applicable versions: 5.1.0(18)+

Example:

let params: petalMaps.RoutePlanParams = {
  destinationPosition: {
    latitude: 31.983015468224288,
    longitude: 118.78058590757131
  }
};
await petalMaps.openMapRoutePlan(this.getUIContext().getHostContext(), params);

openMapNavi

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

Opens the navigation screen of the map app. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Map.Core

Device behavior differences: For version 5.1.1(19) or earlier, this API is supported on phones and tablets. On other device types, it returns error code 801. For version 6.0.0(20) or later, this API is supported on phones, tablets, and PCs/2-in-1 devices. On other device types, it returns error code 801.

Since: 5.0.3(15)

Parameters:

Name Type Mandatory Description
context common.Context Yes Context.
naviParams NaviParams Yes Parameters for navigation.

Returns:

Type Description
Promise<void> Promise that returns no value.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
401 Invalid input parameter.
1002600014 Failed to start the map app.
801

Capability not supported. Failed to call the API due to limited device capabilities.

Applicable versions: 5.1.0(18)+

Example:

let params: petalMaps.NaviParams = {
  destinationPosition: {
    latitude: 31.983015468224288,
    longitude: 118.78058590757131
  }
};
await petalMaps.openMapNavi(this.getUIContext().getHostContext(), params);

openMapTaxi

openMapTaxi(context: common.Context, taxiParams: TaxiParams): Promise<void>

Opens the ride hailing screen of the map app. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Map.Core

Device behavior differences: For version 6.0.1(21) or later, this API is supported on phones and tablets. On other device types, it returns error code 801.

Since: 6.0.1(21)

Parameters:

Name Type Mandatory Description
context common.Context Yes Context.
taxiParams TaxiParams Yes Parameters for ride hailing.

Returns:

Type Description
Promise<void> Promise that returns no value.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
1002600014 Failed to start the map app.
801 Capability not supported. Failed to call the API due to limited device capabilities.

Example:

let params: petalMaps.TaxiParams = {
  destinationPosition: {
    latitude: 31.983015468224288,
    longitude: 118.78058590757131
  }
};
await petalMaps.openMapTaxi(this.getUIContext().getHostContext(), params);

openMapOfflineDataManagement

openMapOfflineDataManagement(context: common.Context, offlineDataParams: OfflineDataParams): Promise<void>

Opens the offline map management screen of the map app. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Map.Core

Device behavior differences: For version 6.1.1(24) or later, this API is supported on phones, tablets, and PCs/2-in-1 devices. On other device types, it returns error code 801.

Since: 6.1.1(24)

Parameters:

Name Type Mandatory Description
context common.Context Yes Context.
offlineDataParams OfflineDataParams Yes Parameters for offline map management.

Returns:

Type Description
Promise<void> Promise that returns no value.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
1002600014 Failed to start the map app.
801 Capability not supported. Failed to call the API due to limited device capabilities.

Example:

let params: petalMaps.OfflineDataParams = {
  scenarios: 'PHONE'
};
await petalMaps.openMapOfflineDataManagement(this.getUIContext().getHostContext(), params);

PoiDetailParams

Defines parameters for POI details.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Map.Core

Device behavior differences: For version 5.1.1(19) or earlier, this API is supported on phones and tablets. On other device types, it returns error code 801. For version 6.0.0(20) or later, this API is supported on phones, tablets, and PCs/2-in-1 devices. On other device types, it returns error code 801.

Since: 5.0.3(15)

Name Type Read-Only Optional Description
destinationPosition mapCommon.LatLng No No

POI coordinates.

The value ranges from -180 to 180 (excluded) for the longitude and from -85.2 to 85.2 for the latitude. Error code 401 will be returned for any invalid value.
destinationName string No Yes POI name. If the name exceeds the display limit, the overflowing part will be replaced with an ellipsis (...).
destinationPoiId string No Yes

POI ID.

When both the POI ID and coordinates are passed in, the POI ID will be used preferentially.
zoom number No Yes

Zoom level of the map. The value ranges from 3 to 20. The default value is 17. If an invalid value is passed, the default value will be used.

Note:

When destinationPoiId is set, the map zoom level cannot be customized.

Since: 6.0.1(21)
coordinateType mapCommon.CoordinateType No Yes

Coordinate system of the map. The default value is mapCommon.CoordinateType.GCJ02. If an invalid value is passed, the default value will be used.

Since: 6.0.1(21)
destinationAddress string No Yes

POI description. For the default value and invalid values, the corresponding description will be obtained through reverse geocoding.

Since: 6.1.1(24)

Example:

let params: petalMaps.PoiDetailParams = {
  destinationPosition: {
    latitude: 31.968789,
    longitude: 118.798537
  },
  destinationName: 'Marker',
  zoom: 17,
  coordinateType: mapCommon.CoordinateType.GCJ02,
  destinationAddress: 'This is the demo address.'
};

TextSearchParams

Defines parameters for text search.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Map.Core

Device behavior differences: For version 5.1.1(19) or earlier, this API is supported on phones and tablets. On other device types, it returns error code 801. For version 6.0.0(20) or later, this API is supported on phones, tablets, and PCs/2-in-1 devices. On other device types, it returns error code 801.

Since: 5.0.3(15)

Name Type Read-Only Optional Description
destinationName string No Yes Destination name. If the name exceeds the display limit, the overflowing part will be replaced with an ellipsis (...).

Example:

let params: petalMaps.TextSearchParams = {
  destinationName: 'Cloud Park'
};

RoutePlanParams

Defines parameters for route planning.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Map.Core

Device behavior differences: For version 5.1.1(19) or earlier, this API is supported on phones and tablets. On other device types, it returns error code 801. For version 6.0.0(20) or later, this API is supported on phones, tablets, and PCs/2-in-1 devices. On other device types, it returns error code 801.

Since: 5.0.3(15)

Name Type Read-Only Optional Description
originPosition mapCommon.LatLng No Yes

Coordinates of the departure place. The default value is the user's current coordinates.

The value ranges from -180 to 180 (excluded) for the longitude and from -85.2 to 85.2 for the latitude. Error code 401 will be returned for any invalid value.
originName string No Yes Departure place name. If the name exceeds the display limit, the overflowing part will be replaced with an ellipsis (...).
originPoiId string No Yes

POI ID of the departure place.

When both the POI ID and coordinates are passed in, the POI ID will be used preferentially.
destinationPosition mapCommon.LatLng No No

Coordinates of the destination.

The value ranges from -180 to 180 (excluded) for the longitude and from -85.2 to 85.2 for the latitude. Error code 401 will be returned for any invalid value.
destinationName string No Yes Destination name. If the name exceeds the display limit, the overflowing part will be replaced with an ellipsis (...).
destinationPoiId string No Yes

POI ID of the destination.

When both the POI ID and coordinates are passed in, the POI ID will be used preferentially.
vehicleType VehicleType No Yes

Mode of transportation.

The default value is VehicleType.DRIVING. If an invalid value is passed, the default value will be used.
coordinateType mapCommon.CoordinateType No Yes

Coordinate system of the map. The default value is mapCommon.CoordinateType.GCJ02. If an invalid value is passed, the default value will be used.

Since: 6.0.1(21)

Example:

let params: petalMaps.RoutePlanParams = {
  destinationPosition: {
    latitude: 31.983015468224288,
    longitude: 118.78058590757131
  }
};

OfflineDataParams

Describes parameters for offline map management.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Map.Core

Device behavior differences: For version 6.1.1(24) or later, this API is supported on phones, tablets, and PCs/2-in-1 devices. On other device types, it returns error code 801.

Since: 6.1.1(24)

Name Type Read-Only Optional Description
scenarios string No No

Scenario description.

Note:

Currently, only WATCH, PHONE, TABLET, PC, and VOICE are supported, and the values are case-insensitive.

WATCH: opens the offline map management screen on the watch for offline map management.

PHONE: opens the map resource management screen for local offline map management.

TABLET: opens the map resource management screen for local offline map management.

PC: opens the map resource management screen for local offline map management.

VOICE: opens the navigation voice screen for local offline navigation voice management.
recommendedRegionIds string[] No Yes Set of recommended regions for offline map download. The maximum length is 20. If an invalid value is passed, error code 401 is returned.

Example:

let params: petalMaps.OfflineDataParams = {
  scenarios: 'PHONE'
};

VehicleType

Mode of transportation. Currently, the map app supports only driving, walking, cycling, and public transit.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Map.Core

Device behavior differences: For version 5.1.1(19) or earlier, this API is supported on phones and tablets. On other device types, it returns error code 801. For version 6.0.0(20) or later, this API is supported on phones, tablets, and PCs/2-in-1 devices. On other device types, it returns error code 801.

Since: 5.0.3(15)

Name Value Description
DRIVING 0 Driving.
WALKING 1 Walking.
CYCLING 2 Cycling.
TRANSIT 3

Public transit.

Since: 6.0.1(21)

TaxiParams

Defines parameters for ride hailing.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Map.Core

Device behavior differences: For version 6.0.1(21) or later, this API is supported on phones and tablets. On other device types, it returns error code 801.

Since: 6.0.1(21)

Name Type Read-Only Optional Description
destinationPosition mapCommon.LatLng No No

Coordinates of the destination.

The value ranges from -180 to 180 (excluded) for the longitude and from -85.2 to 85.2 for the latitude. Error code 401 will be returned for any invalid value.
destinationName string No Yes Destination name. If the name exceeds the display limit, the overflowing part will be replaced with an ellipsis (...).
destinationPoiId string No Yes

POI ID of the destination.

When both the POI ID and coordinates are passed in, the POI ID will be used preferentially.
originPosition mapCommon.LatLng No Yes

Coordinates of the departure place. The default value is the user's current coordinates.

The value ranges from -180 to 180 (excluded) for the longitude and from -85.2 to 85.2 for the latitude. Error code 401 will be returned for any invalid value.
originName string No Yes Departure place name. If the name exceeds the display limit, the overflowing part will be replaced with an ellipsis (...).
originPoiId string No Yes

POI ID of the departure place.

When both the POI ID and coordinates are passed in, the POI ID will be used preferentially.
coordinateType mapCommon.CoordinateType No Yes Coordinate system of the map. The default value is mapCommon.CoordinateType.GCJ02. If an invalid value is passed, the default value will be used.

Example:

let params: petalMaps.TaxiParams = {
  destinationPosition: {
    latitude: 31.983015468224288,
    longitude: 118.78058590757131
  }
};