目录

sceneMap (Scenario-specific Control)

This module provides scenario-specific map controls, including the place details control, location selection control, and division selection control.

Since: 4.1.0(11)

Modules to Import

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

queryLocation

queryLocation(context: common.UIAbilityContext, options: LocationQueryOptions): Promise<void>

Starts up the place details control based on the provided parameters. This API uses a promise to return the result.

  • This API can be called only in the ArkUI page context.

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

Atomic service API: This API can be used in atomic services since version 4.1.0(11).

System capability: SystemCapability.Map.Core

Device behavior differences: This API is supported on phones, tablets, and PCs/2-in-1 devices. On other device types, it returns error code 801.

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
context common.UIAbilityContext Yes Context corresponding to UIAbility or UIExtensionAbility
options LocationQueryOptions Yes Parameters for querying place 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.
1002600001 System internal error.
1002600002 Failed to connect to the Map Kit server.
1002600003 App authentication failed.
1002600004 The Map permission is not enabled.
801

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

Applicable versions: 5.1.0(18)+

Example:

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

let queryLocationOptions: sceneMap.LocationQueryOptions = { siteId: "922207154068557824" };
sceneMap.queryLocation(this.getUIContext().getHostContext() as common.UIAbilityContext, queryLocationOptions)
  .then(() => {
    console.info("QueryLocation", "Succeeded in querying location.");
  })
  .catch((err: BusinessError) => {
    console.error("QueryLocation", `Failed to query Location, code: ${err.code}, message: ${err.message}`);
  });

chooseLocation

chooseLocation(context: common.UIAbilityContext, options: LocationChoosingOptions): Promise<LocationChoosingResult>

Starts up the location selection control based on the provided parameters. This API uses a promise to return the result.

  • This API can be called only in the ArkUI page context.

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

Atomic service API: This API can be used in atomic services since version 4.1.0(11).

System capability: SystemCapability.Map.Core

Device behavior differences: This API is supported on phones, tablets, and PCs/2-in-1 devices. On other device types, it returns error code 801.

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
context common.UIAbilityContext Yes Context corresponding to UIAbility or UIExtensionAbility
options LocationChoosingOptions Yes Parameters for location selection.

Returns:

Type Description
Promise<LocationChoosingResult> Promise object, which returns LocationChoosingResult.

Error codes:

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

ID Error Message
401 Invalid input parameter.
1002600001 System internal error.
1002600002 Failed to connect to the Map Kit server.
1002600003 App authentication failed.
1002600004 The Map permission is not enabled.
801

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

Applicable versions: 5.1.0(18)+

Example:

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

let locationChoosingOptions: sceneMap.LocationChoosingOptions = {
  location: { latitude: 39.92194051376904, longitude: 116.3971836796932 },
  searchEnabled: true,
  showNearbyPoi: true
};
sceneMap.chooseLocation(this.getUIContext().getHostContext() as common.UIAbilityContext, locationChoosingOptions)
  .then((data) => {
    console.info("ChooseLocation", "Succeeded in choosing location.");
  })
  .catch((err: BusinessError) => {
    console.error("ChooseLocation", `Failed to choose Location, code: ${err.code}, message: ${err.message}`);
  });

selectDistrict

selectDistrict(context: common.Context, options: DistrictSelectOptions): Promise<DistrictSelectResult>

Displays the division selection page based on the provided parameters. This API uses a promise to return the result.

  • This API can be called only in the ArkUI page context.

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

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.Map.Core

Device behavior differences: 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.0(12)

Parameters:

Name Type Mandatory Description
context common.Context Yes Context corresponding to UIAbility or UIExtensionAbility
options DistrictSelectOptions Yes Initial options on the division selection page.

Returns:

Type Description
Promise<DistrictSelectResult> Promise object, which returns DistrictSelectResult.

Error codes:

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

ID Error Message
401 Invalid input parameter.
1002600001 System internal error.
1002600002 Failed to connect to the Map Kit server.
1002600003 App authentication failed.
1002600004 The Map permission is not enabled.
1002600012 The country code is not supported.
801

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

Applicable versions: 5.1.0(18)+

Example:

import { BusinessError } from '@kit.BasicServicesKit';

let districtSelectOptions: sceneMap.DistrictSelectOptions = {
  countryCode: "CN"
};
sceneMap.selectDistrict(this.getUIContext().getHostContext(), districtSelectOptions).then((data) => {
  console.info("SelectDistrict", "Succeeded in selecting district.");
}).catch((err: BusinessError) => {
  console.error("SelectDistrict", `Failed to select district, code: ${err.code}, message: ${err.message}`);
});

LocationQueryOptions

Defines parameters for querying place details.

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

System capability: SystemCapability.Map.Core

Device behavior differences: This API is supported on phones, tablets, and PCs/2-in-1 devices. On other device types, it returns error code 801.

Since: 4.1.0(11)

Name Type Read-Only Optional Description
siteId string No Yes

Place ID on the place details page. Error code 401 will be returned for any invalid value.

You can obtain siteId through the on(type: 'poiClick', callback: Callback<mapCommon.Poi>) method of MapEventManager.

Atomic service API: This API can be used in atomic services since version 4.1.0(11).
language string No Yes

Language. For details, please refer to Languages Supported by Map Picker. If this parameter is not set, the system language will be used by default. If an invalid value is passed, the default value will be used.

Atomic service API: This API can be used in atomic services since version 4.1.0(11).
location mapCommon.LatLng No Yes

Coordinates of the map center point. If siteId is not available, use the location parameter to query place details.

Atomic service API: This API can be used in atomic services since version 4.1.0(11).
name string No Yes

Name of a place. If siteId is not available, use name as the name of location.

Atomic service API: This API can be used in atomic services since version 4.1.0(11).
address string No Yes

Address of a place. If siteId is not available, use address as the address of location.

Atomic service API: This API can be used in atomic services since version 4.1.0(11).
showBusiness boolean No Yes

Indicates whether to display business information (such as taxi hailing). The default value is true.

- true: yes

- false: no

Atomic service API: This API can be used in atomic services since version 4.1.0(11).

Note:

This parameter was reserved in API versions 4.1.0(11) through 5.1.1(19) and has been in use since API version 6.0.0(20).
themeColor CustomColors No Yes

Custom theme color object. The default value is brand (brand color).

Since: 5.0.3(15)

Atomic service API: This API can be used in atomic services since version 5.0.3(15).
cancelCallback Callback<void> No Yes

Callback that returns no value. Callback for the place details control closing events.

Since: 5.0.3(15)

Atomic service API: This API can be used in atomic services since version 5.0.3(15).
transitionDuration number No Yes

Transition animation duration, in milliseconds. The value must be greater than 0. The default value is -1. If an invalid value is passed, the default value -1 is used, maintaining interpolatingSpring(0.5, 1, 328, 36) (initial velocity: 0.5; mass: 1; stiffness: 328; damping: 36). This parameter does not take effect on PCs/2-in-1 devices as they do not support transition animation currently.

Since: 6.0.2(22)

Atomic service API: This API can be used in atomic services since version 6.0.2(22).

At least one of the following groups of parameters must be passed. If all parameters are passed, use siteId.

  • siteId

  • location, name

Example:

let queryLocationOptions: sceneMap.LocationQueryOptions = { siteId: "922207154068557824" };

LocationChoosingOptions

Parameters for location selection.

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

System capability: SystemCapability.Map.Core

Device behavior differences: This API is supported on phones, tablets, and PCs/2-in-1 devices. On other device types, it returns error code 801.

Since: 4.1.0(11)

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

Coordinates of the map center point.

If this parameter is not set, the current location of the device is used as the center point. If the current location of the device fails to be obtained, the Palace Museum is used as the center point by default.

Atomic service API: This API can be used in atomic services since version 4.1.0(11).
language string No Yes

Language. For details, please refer to Languages Supported by Map Picker. If this parameter is not set, the system language will be used by default. If an invalid value is passed, the default value will be used.

Atomic service API: This API can be used in atomic services since version 4.1.0(11).
poiTypes Array<string> No Yes

POI types to be displayed. For details about the available options, please refer to HwLocationType.

Atomic service API: This API can be used in atomic services since version 4.1.0(11).
searchEnabled boolean No Yes

Indicates whether to display the search control. The default value is false. If an invalid value is passed, the default value will be used.

- true: yes

- false: no

Atomic service API: This API can be used in atomic services since version 4.1.0(11).
showNearbyPoi boolean No Yes

Indicates whether to display nearby POIs. The default value is false. If an invalid value is passed, the default value will be used.

- true: yes

- false: no

Atomic service API: This API can be used in atomic services since version 4.1.0(11).
snapshotEnabled boolean No Yes

Indicates whether to return mapped snapshots. The default value is false.

- true: yes

- false: no

Since: 5.0.0(12)

Atomic service API: This API can be used in atomic services since version 5.0.0(12).
themeColor CustomColors No Yes

Custom theme color object. The default value is brand (brand color).

Since: 5.0.3(15)

Atomic service API: This API can be used in atomic services since version 5.0.3(15).
cancelCallback Callback<void> No Yes

Callback that returns no value. Callback for the location selection control closing events.

Since: 5.0.3(15)

Atomic service API: This API can be used in atomic services since version 5.0.3(15).
transitionDuration number No Yes

Transition animation duration, in milliseconds. The value must be greater than 0. The default value is -1. If an invalid value is passed, the default value -1 is used, maintaining interpolatingSpring(0.5, 1, 328, 36) (initial velocity: 0.5; mass: 1; stiffness: 328; damping: 36). This parameter does not take effect on PCs/2-in-1 devices as they do not support transition animation currently.

Since: 6.0.2(22)

Atomic service API: This API can be used in atomic services since version 6.0.2(22).

Example:

let locationChoosingOptions: sceneMap.LocationChoosingOptions = {
  location: { latitude: 39.9, longitude: 116.4 }
};

LocationChoosingResult

Result of location selection.

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

System capability: SystemCapability.Map.Core

Device behavior differences: This API is supported on phones, tablets, and PCs/2-in-1 devices. On other device types, it returns error code 801.

Since: 4.1.0(11)

Name Type Read-Only Optional Description
siteId string No Yes

ID of the selected location. If the selected location is not a POI, no value is returned.

Atomic service API: This API can be used in atomic services since version 4.1.0(11).
location mapCommon.LatLng No No

Coordinates of the selected location.

Atomic service API: This API can be used in atomic services since version 4.1.0(11).
name string No Yes

POI name of the selected location. If the selected location is not a POI, the corresponding marker is returned.

Atomic service API: This API can be used in atomic services since version 4.1.0(11).
address string No No

Address of the selected location.

Atomic service API: This API can be used in atomic services since version 4.1.0(11).
addressComponent site.AddressComponent No Yes

Detailed information of the selected location.

Since: 5.0.0(12)

Atomic service API: This API can be used in atomic services since version 5.0.0(12).
zoom number No No

Zoom level of the selected location. The value range is [2, 20]. For a value out of the range, the nearest boundary value is used.

Since: 5.0.0(12)

Atomic service API: This API can be used in atomic services since version 5.0.0(12).
snapshot image.PixelMap No Yes

Map snapshot.

Since: 5.0.0(12)

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

DistrictSelectOptions

Initial options on the division selection page.

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

System capability: SystemCapability.Map.Core

Device behavior differences: 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.0(12)

Name Type Read-Only Optional Description
countryCode string No Yes

Country/Region code of an administrative division, which must comply with ISO 3166-1 alpha-2.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).
language string No Yes

Page language. For details, please refer to Languages Supported by Map Picker. If this parameter is not set, the system language will be used by default. If an invalid value is passed, the default value will be used.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).
address string No Yes

Address specified for searching.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).
themeColor CustomColors No Yes

Custom theme color object. The default value is brand (brand color).

Since: 5.0.3(15)

Atomic service API: This API can be used in atomic services since version 5.0.3(15).
subWindowEnabled boolean No Yes

Indicates whether to show the division selection in the subwindow. The default value is false.

- true: yes

- false: no

Since: 5.0.3(15)

Atomic service API: This API can be used in atomic services since version 5.0.3(15).
cancelCallback Callback<void> No Yes

Callback that returns no value. Callback for the division selection control closing events.

Since: 5.0.3(15)

Atomic service API: This API can be used in atomic services since version 5.0.3(15).
transitionDuration number No Yes

Transition animation duration, in milliseconds. The value must be greater than 0. The default value is -1. If an invalid value is passed, the default value -1 is used, maintaining interpolatingSpring(0.5, 1, 328, 36) (initial velocity: 0.5; mass: 1; stiffness: 328; damping: 36). This parameter does not take effect if subWindowEnabled is set to true.

Since: 6.0.2(22)

Atomic service API: This API can be used in atomic services since version 6.0.2(22).
maxAdminLevel number No Yes

Maximum display level of the division selection control. The value must be an integer in the range of [1, 6]. Decimals are floored. The default value is 6. If an invalid value is passed, the default value will be used.

Since: 6.1.1(24)

Atomic service API: This API can be used in atomic services since version 6.1.1(24).

Note:

If both address and maxAdminLevel are passed:

If the address query returns a unique result (no duplicate names), the result from the address query takes precedence. For example, if address is Yuhuatai District (display level 4) and maxAdminLevel is set to 2, the division selection control will use display level 4.

- If the address query returns multiple results due to duplicate regional names (for example, Datong exists as both Datong City in Shanxi and Datong District in Daqing, Heilongjiang), maxAdminLevel will take priority to resolve the ambiguity.

Example:

let districtSelectOptions: sceneMap.DistrictSelectOptions = {
  countryCode: "CN",
  language:"zh",
  address: "Henan",
  maxAdminLevel: 3
};

DistrictSelectResult

Defines the division selection result.

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

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.Map.Core

Device behavior differences: 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.0(12)

Name Type Read-Only Optional Description
districts Array<District> No No Level information about selected administrative divisions.
addressDescription string No Yes Address information about the selected administrative divisions.

District

Defines administrative division information.

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

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.Map.Core

Device behavior differences: 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.0(12)

Name Type Read-Only Optional Description
siteId string No Yes ID of a division.
name string No Yes Name of a division.
location mapCommon.LatLng No Yes Coordinates of a division.
adminLevel string No Yes

Division level, including country, province, city, district/county, and street.

Note:

Country: COUNTRY

Province: ADMINISTRATIVE_AREA_LEVEL_1

City: ADMINISTRATIVE_AREA_LEVEL_2

District/County: ADMINISTRATIVE_AREA_LEVEL_3

Street: ADMINISTRATIVE_AREA_LEVEL_4
adminCode string No Yes

Administrative division code.

Note:

The administrative division codes returned by the API cover all provinces, cities, districts/counties, and towns/streets in the Chinese mainland, Hong Kong (China), and Macao (China). The document appendix includes administrative division codes of certain cities only.
cityCode string No Yes City code.
countryCode string No Yes Country/Region code.