目录

Class (MapComponentController)

Modules to Import

import { map, mapCommon } from '@kit.MapKit';

MapComponentController

Main entry class for map operations. It provides access for all map-related methods and provides event listening management functions.

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

Since: 4.1.0(11)

Example:

import { MapComponent, mapCommon, map } from '@kit.MapKit';
import { AsyncCallback } from '@kit.BasicServicesKit';

@Entry
@Component
struct HuaweiMapDemo {
  private TAG = "HuaweiMapDemo";
  private mapOptions?: mapCommon.MapOptions;
  private callback?: AsyncCallback<map.MapComponentController>;
  private mapController?: map.MapComponentController;
  private mapEventManager?: map.MapEventManager;

  aboutToAppear(): void {
    // Map initialization parameters used to set the coordinates of the map center point and zoom level.
    this.mapOptions = {
      position: {
        target: {
          latitude: 39.9,
          longitude: 116.4
        },
        zoom: 10
      }
    };

    // Map initialization callback.
    this.callback = async (err, mapController) => {
      if (!err) {
        // Obtain the controller class of the map to operate the map.
        this.mapController = mapController;
        // Return the event manager of the map component.
        this.mapEventManager = this.mapController.getEventManager();
        let callback = () => {
          console.info(this.TAG, `on-mapLoad`);
        };
        this.mapEventManager.on("mapLoad", callback);

        // Execute the customized method.
        this.customizedMethod();
      }
    };
  }

  // Customized method.
  private customizedMethod() {
    // ...
  }

  build() {
    Stack() {
      // Call the MapComponent component to initialize the map.
      MapComponent({ mapOptions: this.mapOptions, mapCallback: this.callback })
        .width('100%')
        .height('100%')
    }.height('100%')
  }
}

The methods in MapComponentController need to be executed in the map initialization callback or in customized method in the preceding example.

[h2]animateCamera

animateCamera(update: CameraUpdate, duration?: number): void

Updates the camera position in animation mode within a specified period of time.

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
update CameraUpdate Yes Camera position change. Invalid values are not processed.
duration number No Animation duration, in milliseconds. The value must be greater than 0. The default value is 250. The default value is used for invalid values.

Example:

let target: mapCommon.LatLng = {
  latitude: 39.9,
  longitude: 116.4
};
let cameraPosition: mapCommon.CameraPosition = {
  target: target,
  zoom: 10
};
// Create a CameraUpdate object.
let cameraUpdate: map.CameraUpdate = map.newCameraPosition(cameraPosition);
// Move the camera in animation mode within 1000 ms.
this.mapController.animateCamera(cameraUpdate, 1000);

[h2]animateCameraStatus

animateCameraStatus(update: CameraUpdate, duration?: number): Promise<AnimateResult>

Updates the camera position in animation mode within a specified period of time, and returns the animation result. This API uses a promise to return the result asynchronously.

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

Since: 5.0.0(12)

Parameters:

Name Type Mandatory Description
update CameraUpdate Yes Camera position change. For invalid values, error code 401 will be returned.
duration number No Animation duration, in milliseconds. The value must be greater than 0. The default value is 250. The default value is used for invalid values.

Returns:

Type Description
Promise<AnimateResult> Promise used to return AnimateResult.

Error codes:

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

ID Error Message
401 Invalid input parameter.

Example:

let target: mapCommon.LatLng = {
  latitude: 39.9,
  longitude: 116.4
};
let cameraPosition: mapCommon.CameraPosition = {
  target: target,
  zoom: 10
};
// Create a CameraUpdate object.
let cameraUpdate: map.CameraUpdate = map.newCameraPosition(cameraPosition);
// Move the camera in animation mode within 1000 ms.
let animateResult = await this.mapController.animateCameraStatus(cameraUpdate, 1000);

[h2]animateCameraWithMarker

animateCameraWithMarker(update: CameraUpdate, marker: Marker, duration: number): Promise<AnimateResult>

Updates the camera position in animation mode within a specified period of time, and updates a specified Marker. This API uses a promise to return the result asynchronously. If the camera movement is interrupted, the return value of the isCanceled parameter in AnimateResult will be true.

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

Since: 5.0.0(12)

Parameters:

Name Type Mandatory Description
update CameraUpdate Yes Camera position change. Invalid values are not processed.
marker Marker Yes Marker. Invalid values are not processed.
duration number Yes Animation duration, in milliseconds. The value must be greater than 0. The default value is 250. The default value is used for invalid values.

Returns:

Type Description
Promise<AnimateResult> Promise used to return AnimateResult.

Example:

let target: mapCommon.LatLng = {
  latitude: 39.9,
  longitude: 116.4
};
let cameraPosition: mapCommon.CameraPosition = {
  target: target,
  zoom: 10
};
// Create a CameraUpdate object.
let cameraUpdate: map.CameraUpdate = map.newCameraPosition(cameraPosition);
// Marker initialization parameters.
let markerOptions: mapCommon.MarkerOptions = {
  position: {
    latitude: 39.9,
    longitude: 116.4
  },
  title: "XXX",
  // The icon must be stored in the resources/rawfile directory.
  icon: 'icon/icon.png',
  clickable: true
};
// Create a Marker.
let marker = await this.mapController?.addMarker(markerOptions);
// Move the camera in animation mode within 1000 ms and update the specified Marker.
await this.mapController.animateCameraWithMarker(cameraUpdate, marker, 1000);

[h2]animateCameraWithMarkers

animateCameraWithMarkers(update: CameraUpdate, markers: Array<Marker>, duration: number): Promise<AnimateResult>

Updates the camera position in animation mode within a specified period of time, and updates a group of specified Markers. This API uses a promise to return the result asynchronously.

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

Since: 5.0.0(12)

Parameters:

Name Type Mandatory Description
update CameraUpdate Yes Camera position change. For invalid values, error code 401 will be returned.
markers Array<Marker> Yes

Group of Markers.

Note:

The positions of these Markers must be the same. Otherwise, error code 401 will be returned.
duration number Yes Animation duration, in milliseconds. The value must be greater than 0. The default value is 250. The default value is used for values less than or equal to 0 and for invalid values.

Returns:

Type Description
Promise<AnimateResult> Promise used to return AnimateResult.

Error codes:

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

ID Error Message
401 Invalid input parameter.

Example:

let target: mapCommon.LatLng = {
  latitude: 39.9,
  longitude: 116.4
};
let cameraPosition: mapCommon.CameraPosition = {
  target: target,
  zoom: 10
};
// Create a CameraUpdate object.
let cameraUpdate: map.CameraUpdate = map.newCameraPosition(cameraPosition);
// Initialization parameters of marker1.
let markerOptions1: mapCommon.MarkerOptions = {
  position: {
    latitude: 31.984410259206815,
    longitude: 118.76625379397866
  },
  title: "icon",
  // The icon must be stored in the resources/rawfile directory.
  icon: 'icon/icon.png',
  clickable: true
};
let markerOptions2: mapCommon.MarkerOptions = {
  position: {
    latitude: 31.984410259206815,
    longitude: 118.76625379397866
  },
  title: "avocado",
  // The icon must be stored in the resources/rawfile directory.
  icon: 'icon/avocado.png',
  clickable: true,
  anchorU: 0.5,
  anchorV: 1
};
let marker1 = await this.mapController?.addMarker(markerOptions1);
// Initialization parameters of marker2.
let marker2 = await this.mapController?.addMarker(markerOptions2);
// Move the camera in animation mode within 1000 ms and update the specified Marker.
await this.mapController.animateCameraWithMarkers(cameraUpdate, [marker1, marker2], 1000);

[h2]stopAnimation

stopAnimation(): void

Stops the current animation of the camera. When this method is called, the camera stops moving immediately and remains in that position.

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

Since: 4.1.0(11)

Example:

this.mapController.stopAnimation();

[h2]clear

clear(): void

Removes all MapCircles, Markers, MapPolylines, and other overlays from a map.

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

Since: 4.1.0(11)

Example:

this.mapController.clear();

[h2]moveCamera

moveCamera(update: CameraUpdate): void

Updates the camera position.

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
update CameraUpdate Yes Camera position change. Invalid values are not processed.

Example:

let target: mapCommon.LatLng = {
  latitude: 39.9,
  longitude: 116.4
};
let cameraPosition: mapCommon.CameraPosition = {
  target: target,
  zoom: 10
};
// Create a CameraUpdate object.
let cameraUpdate: map.CameraUpdate = map.newCameraPosition(cameraPosition);
// Move the camera.
this.mapController.moveCamera(cameraUpdate);

[h2]getCameraPosition

getCameraPosition(): mapCommon.CameraPosition

Obtains the current position of the camera.

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

Since: 4.1.0(11)

Returns:

Type Description
mapCommon.CameraPosition Current position of the camera.

Example:

let cameraPosition: mapCommon.CameraPosition = this.mapController.getCameraPosition();

[h2]setLatLngBounds

setLatLngBounds(bounds: mapCommon.LatLngBounds): void

Sets a mapCommon.LatLngBounds object to constrain the camera target so that the camera target does not move outside the bounds when a user scrolls the map. If new bounds are set, the new bounds will overwrite the existing ones.

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
bounds mapCommon.LatLngBounds Yes

Bounds for constraining the camera target. Invalid values are not processed.

Note:

This parameter does not take effect if the latitude of the southwest corner is greater than that of the northeast corner.

Example:

let bounds:mapCommon.LatLngBounds = {
  northeast: {
    latitude: 31,
    longitude: 118
  },
  southwest: {
    latitude: 30,
    longitude: 117
  }
};
this.mapController.setLatLngBounds(bounds);

[h2]setPointToCenter

setPointToCenter(point: mapCommon.MapPoint): void

Sets a pixel position on the screen as the center point of the map. Once applied, all zooming and rotating operations will pivot around the coordinates of this pixel position.

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
point mapCommon.MapPoint Yes Screen coordinates. Invalid values are not processed.

Example:

let point: mapCommon.MapPoint = {
  positionX: 1000,
  positionY: 1000
};
this.mapController.setPointToCenter(point);

[h2]setMaxZoom

setMaxZoom(maxZoom: number): void

Sets the maximum zoom level of the camera.

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
maxZoom number Yes

Maximum zoom level of the camera. The value range is [2, 20]. For values outside this range, the nearest boundary value will be used.

If the input value is less than the current minZoom value, both the maximum zoom level and minimum zoom level will be set to the input value. Invalid values are not processed.

Example:

this.mapController.setMaxZoom(10);

[h2]setMinZoom

setMinZoom(minZoom: number): void

Sets the minimum zoom level of the camera.

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
minZoom number Yes

Minimum zoom level of the camera. The value range is [2, 20]. For values outside this range, the nearest boundary value will be used.

If the input value is greater than the current maxZoom value, both the maximum zoom level and minimum zoom level will be set to the input value. Invalid values are not processed.

Example:

this.mapController.setMinZoom(3);

[h2]getMaxZoom

getMaxZoom(): number

Obtains the maximum zoom level of the camera.

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

Since: 4.1.0(11)

Returns:

Type Description
number Maximum zoom level of the camera.

Example:

let maxZoom: number = this.mapController.getMaxZoom();

[h2]getMinZoom

getMinZoom(): number

Obtains the minimum zoom level of the camera.

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

Since: 4.1.0(11)

Returns:

Type Description
number Minimum zoom level of the camera.

Example:

let minZoom: number = this.mapController.getMinZoom();

[h2]setTrafficEnabled

setTrafficEnabled(enabled: boolean): void

Sets whether to enable the traffic status layer.

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
enabled boolean Yes

Indicates whether to enable the traffic status layer. Invalid values are not processed.

- true: yes

- false: no

Example:

this.mapController.setTrafficEnabled(true);

[h2]isTrafficEnabled

isTrafficEnabled(): boolean

Checks whether the traffic status layer is enabled.

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

Since: 4.1.0(11)

Returns:

Type Description
boolean

- true: The traffic status layer is enabled.

- false: The traffic status layer is disabled.

Example:

let isTrafficEnabled: boolean = this.mapController.isTrafficEnabled();

[h2]setBuildingEnabled

setBuildingEnabled(enabled: boolean): void

Sets whether to enable the BuildingOverlay.

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
enabled boolean Yes

Indicates whether to enable the BuildingOverlay. Invalid values are not processed.

- true: yes

- false: no

Note:

Once the BuildingOverlay is enabled, the 3D layer effect will be rendered at map zoom level 16 and above.

Example:

this.mapController.setBuildingEnabled(true);

[h2]isBuildingEnabled

isBuildingEnabled(): boolean

Checks whether the BuildingOverlay is enabled.

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

Since: 4.1.0(11)

Returns:

Type Description
boolean

- true: The BuildingOverlay is enabled.

- false: The BuildingOverlay is disabled.

Example:

let isBuildingEnabled: boolean = this.mapController.isBuildingEnabled();

[h2]setMyLocationEnabled

setMyLocationEnabled(myLocationEnabled: boolean): void

Sets whether to enable the my-location layer function. By default, the continuous location capability of the system is used to display user locations. After the function is enabled, the my-location icon is displayed in the lower right corner of the map by default. When a user taps the my-location icon, the user's current location will be displayed in the center of the screen as a blue dot. To customize the location icon style, call setMyLocationStyle.

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
myLocationEnabled boolean Yes

Indicates whether to enable the my-location layer function. Invalid values are not processed.

- true: yes

- false: no

Example:

this.mapController.setMyLocationEnabled(true);

[h2]setMyLocation

setMyLocation(location: geoLocationManager.Location): void

By default, Map Kit uses the continuous location capability of the system to display user locations. If you want to customize the display frequency or accuracy, you can call this API to set the coordinates of my-location.

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
location geoLocationManager.Location Yes

User location. Invalid values are not processed.

Note:

The value of the location parameter must be coordinates in the WGS84 coordinate system.

Example:

// Import the @kit.LocationKit module.
import { geoLocationManager } from '@kit.LocationKit';

let location = await geoLocationManager.getCurrentLocation();
this.mapController.setMyLocation(location);

[h2]setMyLocationStyle

setMyLocationStyle(style: mapCommon.MyLocationStyle): Promise<void>

Sets the user location style. This API uses a promise to return the result asynchronously.

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
style mapCommon.MyLocationStyle Yes User location style. Invalid values are not processed.

Returns:

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

Example:

let style: mapCommon.MyLocationStyle = {
  anchorU: 0.5,
  anchorV: 0.5,
  radiusFillColor: 0xffff0000,
  // Icons are custom resources stored in resources/rawfile. Set icon to what you need.
  icon: 'icon/avocado.png'
};
await this.mapController.setMyLocationStyle(style);

[h2]isMyLocationEnabled

isMyLocationEnabled(): boolean

Checks whether the my-location layer is enabled.

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

Since: 4.1.0(11)

Returns:

Type Description
boolean

Indicates whether the my-location layer is enabled.

- true: yes

- false: no

Example:

let isMyLocationEnabled: boolean = this.mapController.isMyLocationEnabled();

[h2]setZoomGesturesEnabled

setZoomGesturesEnabled(enabled: boolean): void

Sets whether to enable zoom gestures. By default, zoom gestures are enabled.

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
enabled boolean Yes

Indicates whether to enable zoom gestures. Invalid values are not processed.

- true: yes

- false: no

Example:

this.mapController.setZoomGesturesEnabled(true);

[h2]isZoomGesturesEnabled

isZoomGesturesEnabled(): boolean

Checks whether zoom gestures are enabled.

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

Since: 4.1.0(11)

Returns:

Type Description
boolean

Indicates whether zoom gestures are enabled.

- true: yes

- false: no

Example:

let isZoomGesturesEnabled: boolean = this.mapController.isZoomGesturesEnabled();

[h2]setScrollGesturesEnabled

setScrollGesturesEnabled(enabled: boolean): void

Sets whether to enable scroll gestures. By default, scroll gestures are enabled.

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
enabled boolean Yes

Indicates whether to enable scroll gestures. Invalid values are not processed.

- true: yes

- false: no

Example:

this.mapController.setScrollGesturesEnabled(true);

[h2]isScrollGesturesEnabled

isScrollGesturesEnabled(): boolean

Checks whether scroll gestures are enabled.

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

Since: 4.1.0(11)

Returns:

Type Description
boolean

Indicates whether scroll gestures are enabled.

- true: yes

- false: no

Example:

let isScrollGesturesEnabled: boolean = this.mapController.isScrollGesturesEnabled();

[h2]setRotateGesturesEnabled

setRotateGesturesEnabled(enabled: boolean): void

Sets whether to enable rotation gestures. By default, rotation gestures are enabled.

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
enabled boolean Yes

Indicates whether to enable rotation gestures. Invalid values are not processed.

- true: yes

- false: no

Example:

this.mapController.setRotateGesturesEnabled(true);

[h2]isRotateGesturesEnabled

isRotateGesturesEnabled(): boolean

Checks whether rotation gestures are enabled.

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

Since: 4.1.0(11)

Returns:

Type Description
boolean

Indicates whether rotation gestures are enabled.

- true: yes

- false: no

Example:

let isRotateGesturesEnabled: boolean = this.mapController.isRotateGesturesEnabled();

[h2]setTiltGesturesEnabled

setTiltGesturesEnabled(enabled: boolean): void

Sets whether to enable tilt gestures. By default, tilt gestures are enabled.

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
enabled boolean Yes

Indicates whether to enable tilt gestures. Invalid values are not processed.

- true: yes

- false: no

Example:

this.mapController.setTiltGesturesEnabled(true);

[h2]isTiltGesturesEnabled

isTiltGesturesEnabled(): boolean

Checks whether tilt gestures are enabled.

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

Since: 4.1.0(11)

Returns:

Type Description
boolean

Indicates whether tilt gestures are enabled.

- true: yes

- false: no

Example:

let isTiltGesturesEnabled: boolean = this.mapController.isTiltGesturesEnabled();

[h2]setZoomControlsEnabled

setZoomControlsEnabled(enabled: boolean): void

Sets whether to enable zoom controls. By default, zoom controls are enabled.

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
enabled boolean Yes

Indicates whether to enable zoom controls. Invalid values are not processed.

- true: yes

- false: no

Example:

this.mapController.setZoomControlsEnabled(true);

[h2]isZoomControlsEnabled

isZoomControlsEnabled(): boolean

Checks whether zoom controls are enabled.

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

Since: 4.1.0(11)

Returns:

Type Description
boolean

Indicates whether zoom controls are enabled.

- true: yes

- false: no

Example:

let isZoomControlsEnabled: boolean = this.mapController.isZoomControlsEnabled();

[h2]setMyLocationControlsEnabled

setMyLocationControlsEnabled(enabled: boolean): void

Sets whether to enable the my-location icon. If the my-location layer function is disabled, the system does not respond when the icon is tapped.

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
enabled boolean Yes

Indicates whether to enable the my-location icon. Invalid values are not processed.

- true: yes

- false: no

Example:

this.mapController.setMyLocationControlsEnabled(true);

[h2]isMyLocationControlsEnabled

isMyLocationControlsEnabled(): boolean

Checks whether the my-location icon is enabled.

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

Since: 4.1.0(11)

Returns:

Type Description
boolean

Indicates whether the my-location icon is enabled.

- true: yes

- false: no

Example:

let isMyLocationControlsEnabled: boolean = this.mapController.isMyLocationControlsEnabled();

[h2]setScaleControlsEnabled

setScaleControlsEnabled(enabled: boolean): void

Sets whether to enable the scale.

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
enabled boolean Yes

Indicates whether to enable the scale. Invalid values are not processed.

- true: yes

- false: no

Example:

this.mapController.setScaleControlsEnabled(true);

[h2]isScaleControlsEnabled

isScaleControlsEnabled(): boolean

Checks whether the scale is enabled.

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

Since: 4.1.0(11)

Returns:

Type Description
boolean

Indicates whether the scale is enabled.

- true: yes

- false: no

Example:

let isScaleControlsEnabled: boolean = this.mapController.isScaleControlsEnabled();

[h2]setCompassControlsEnabled

setCompassControlsEnabled(enabled: boolean): void

Sets whether to enable the compass.

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
enabled boolean Yes

Indicates whether to enable the compass. Invalid values are not processed.

- true: yes

- false: no

Example:

this.mapController.setCompassControlsEnabled(true);

[h2]isCompassControlsEnabled

isCompassControlsEnabled(): boolean

Checks whether the compass is enabled.

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

Since: 4.1.0(11)

Returns:

Type Description
boolean

Indicates whether the compass is enabled.

- true: yes

- false: no

Example:

let isCompassControlsEnabled: boolean = this.mapController.isCompassControlsEnabled();

[h2]setGestureScaleByMapCenter

setGestureScaleByMapCenter(enabled: boolean): void

Sets whether a fixed screen center can be passed for zooming. By default, this function is disabled.

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
enabled boolean Yes

Indicates whether a fixed screen center can be passed for zooming. Invalid values are not processed.

- true: yes. The map will be zoomed based on the passed fixed screen center.

- false: no. The map will be zoomed based on the tap point on the screen.

Example:

this.mapController.setGestureScaleByMapCenter(true);

[h2]isGestureScaleByMapCenter

isGestureScaleByMapCenter(): boolean

Checks whether a fixed screen center can be passed for zooming.

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

Since: 4.1.0(11)

Returns:

Type Description
boolean

Indicates whether a fixed screen center can be passed for zooming.

- true: yes

- false: no

Example:

let isGestureScaleByMapCenter: boolean = this.mapController.isGestureScaleByMapCenter();

[h2]setLogoAlignment

setLogoAlignment(alignment: mapCommon.LogoAlignment): void

Sets the map logo alignment mode.

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
alignment mapCommon.LogoAlignment Yes Map logo alignment mode. Invalid values are not processed.

Example:

this.mapController.setLogoAlignment(mapCommon.LogoAlignment.BOTTOM_START);

[h2]setLogoPadding

setLogoPadding(padding: mapCommon.Padding): void

Sets the padding between the logo and map edges. The logo dimensions are fixed and are not affected by map zooming. The logo is always displayed in pixels.

When setting the padding between the logo and map edges, do not hide or cover the logo.

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
padding mapCommon.Padding Yes Padding between the logo and map edges. Invalid values are not processed.

Example:

let padding: mapCommon.Padding = {
  left: 0,
  bottom: 50
};
this.mapController.setLogoPadding(padding);

[h2]getScalePerPixel

getScalePerPixel(): number

Obtains the length corresponding to one pixel point on the map at the current zoom level, in meters.

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

Since: 4.1.0(11)

Returns:

Type Description
number Length corresponding to one pixel point on the map at the current zoom level, in meters. If the map object does not exist or has been destroyed, 0 will be returned.

Example:

let scalePerPixel: number = this.mapController.getScalePerPixel();

[h2]addMarker

addMarker(options: mapCommon.MarkerOptions): Promise<Marker>

Adds a Marker to a map. This API uses a promise to return the result asynchronously.

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
options mapCommon.MarkerOptions Yes Marker attributes.

Returns:

Type Description
Promise<Marker> Promise used to return Marker.

Error codes:

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

ID Error Message
401 Invalid input parameter.
1002601001 The object to be operated does not exist.
1002601005

Failed to generate the icon of the customized component.

Applicable version: 6.0.0(20)+

Example:

// Marker initialization parameters.
let markerOptions: mapCommon.MarkerOptions = {
  position: {
    latitude: 39.9,
    longitude: 116.4
  },
  rotation: 0,
  visible: true,
  zIndex: 0,
  alpha: 1,
  anchorU: 0.5,
  anchorV: 1,
  clickable: true,
  draggable: true,
  flat: false,
  // The icon is stored in resources/rawfile.
  icon: 'test.png'
};
// Add a Marker to the map.
let marker: map.Marker = await this.mapController.addMarker(markerOptions);

[h2]addCircle

addCircle(options: mapCommon.MapCircleOptions): Promise<MapCircle>

Adds a MapCircle to a map. The longitude and latitude of the center and the radius are specified for the MapCircle to indicate the surrounding area of a location. This API uses a promise to return the result asynchronously.

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
options mapCommon.MapCircleOptions Yes MapCircle attributes.

Returns:

Type Description
Promise<MapCircle> Promise used to return MapCircle.

Error codes:

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

ID Error Message
401 Invalid input parameter.
1002601001 The object to be operated does not exist.

Example:

// MapCircle initialization parameters.
let mapCircleOptions: mapCommon.MapCircleOptions = {
  center: {
    latitude: 39.9,
    longitude: 116.4
  },
  patterns: [{
    type: 0,
    length: 100
  }, {
    type: 1,
    length: 100
  }, {
    type: 2,
    length: 100
  }],
  radius: 700,
  fillColor: 0XFF00FFFF,
  strokeColor: 0xFFFF0000,
  strokeWidth: 10,
  zIndex: 15
};
// Add a MapCircle to the map.
let mapCircle: map.MapCircle = await this.mapController.addCircle(mapCircleOptions);

[h2]addPolyline

addPolyline(options: mapCommon.MapPolylineOptions): Promise<MapPolyline>

Adds a MapPolyline to a map. This API uses a promise to return the result asynchronously.

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
options mapCommon.MapPolylineOptions Yes MapPolyline attributes.

Returns:

Type Description
Promise<MapPolyline> Promise used to return MapPolyline.

Error codes:

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

ID Error Message
401 Invalid input parameter.
1002601001 The object to be operated does not exist.

Example:

// Initialize parameters.
let polylineOption: mapCommon.MapPolylineOptions = {
  // MapPolyline coordinates, which are mandatory.
  points: [{
    latitude: 31.984410,
    longitude: 118.7662537
  }, {
    latitude: 31.084410,
    longitude: 118.0662537
  }],
  clickable: true,
  color: 0xff000000,
  startCap: mapCommon.CapStyle.BUTT,
  endCap: mapCommon.CapStyle.BUTT,
  geodesic: false,
  jointType: mapCommon.JointType.DEFAULT,
  visible: true,
  width: 10,
  zIndex: 0,
  gradient: false
};
// Add a MapPolyline to a map.
let mapPolyline: map.MapPolyline = await this.mapController.addPolyline(polylineOption);

[h2]addPolygon

addPolygon(options: mapCommon.MapPolygonOptions): Promise<MapPolygon>

Adds a MapPolygon to a map. This API uses a promise to return the result asynchronously.

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
options mapCommon.MapPolygonOptions Yes MapPolygon attributes.

Returns:

Type Description
Promise<MapPolygon> Promise used to return MapPolygon.

Error codes:

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

ID Error Message
401 Invalid input parameter.
1002601001 The object to be operated does not exist.

Example:

// Initialize parameters.
let polygonOptions: mapCommon.MapPolygonOptions = {
  // MapPolygon coordinates, which are mandatory.
  points: [{
    latitude: 31.98441,
    longitude: 118.066253
  }, {
    latitude: 31.98441,
    longitude: 118.766253
  }, {
    latitude: 32.98441,
    longitude: 118.766253
  }, {
    latitude: 32.98441,
    longitude: 118.066253
  }],
  clickable: true,
  fillColor: 0xff00DE00,
  geodesic: false,
  strokeColor: 0xff000000,
  jointType: mapCommon.JointType.DEFAULT,
  strokeWidth: 10,
  visible: true,
  zIndex: 10
};
// Add a MapPolygon to a map.
let mapPolygon: map.MapPolygon = await this.mapController.addPolygon(polygonOptions);

[h2]addPointAnnotation

addPointAnnotation(params: mapCommon.PointAnnotationParams): Promise<PointAnnotation>

Adds a PointAnnotation to a map. This API uses a promise to return the result asynchronously.

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
params mapCommon.PointAnnotationParams Yes PointAnnotation attributes.

Returns:

Type Description
Promise<PointAnnotation> Promise used to return PointAnnotation.

Error codes:

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

ID Error Message
401 Invalid input parameter.
1002601001 The object to be operated does not exist.

Example:

let pointAnnotationOptions: mapCommon.PointAnnotationParams = {
  // Define the anchor for the icon of a PointAnnotation.
  position: {
    latitude: 39.918,
    longitude: 116.397
  },
  // Define whether to support deduplication when the PointAnnotation name is the same as a map POI name.
  repeatable: true,
  // Define the collision rule of the PointAnnotation.
  collisionRule: mapCommon.CollisionRule.NAME,
  // Define PointAnnotation titles. The minimum length of the array is 1 and the maximum length is 3.
  titles: [{
    // Define the title content.
    content: "Title1",
    // Define the title text color.
    color: 0xFF000000,
    // Define the title text font size.
    fontSize: 15,
    // Define the title stroke color.
    strokeColor: 0xFFFFFFFF,
    // Define the title stroke width.
    strokeWidth: 2,
    // Define the title text font style.
    fontStyle: mapCommon.FontStyle.ITALIC
  }],
  // Set an icon for the PointAnnotation. The icon is stored in resources/rawfile.
  icon: "icon/avocado.png",
  // Define whether to display the icon for the PointAnnotation.
  showIcon: true,
  // Define the horizontal position of the anchor of the PointAnnotation.
  anchorU: 0.5,
  // Define the vertical position of the anchor of the PointAnnotation.
  anchorV: 1,
  // Set the display attribute of the PointAnnotation. If it is set to true, the PointAnnotation remains visible after collision.
  forceVisible: false,
  // Define the collision priority. A larger value indicates a lower priority.
  priority: 3,
  // Define the minimum zoom level for PointAnnotation display.
  minZoom: 2,
  // Define the maximum zoom level for PointAnnotation display.
  maxZoom: 20,
  // Define whether the PointAnnotation is visible.
  visible: true,
  // Define the overlay level attribute of the PointAnnotation.
  zIndex: 10
};
let pointAnnotation: map.PointAnnotation = await this.mapController.addPointAnnotation(pointAnnotationOptions);

[h2]addBubble

addBubble(params: mapCommon.BubbleParams): Promise<Bubble>

Adds a Bubble to a map. This API uses a promise to return the result asynchronously.

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
params mapCommon.BubbleParams Yes Bubble attributes.

Returns:

Type Description
Promise<Bubble> Promise used to return Bubble.

Error codes:

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

ID Error Message
401 Invalid input parameter.
1002601001 The object to be operated does not exist.

Example:

let bubbleOptions: mapCommon.BubbleParams = {
  // Bubble position.
  positions: [[{ latitude: 31, longitude: 118 }]],
  // Bubble icons. Icons in four directions need to be passed. The icons are stored in resources/rawfile.
  icons: [
    'icon.png',
    'icon.png',
    'icon.png',
    'icon.png'
  ],
  // Set the display attribute of the Bubble. If it is set to true, the Bubble remains visible after collision.
  forceVisible: true,
  // Define the Bubble collision priority. A larger value indicates a lower priority.
  priority: 3,
  // Define the minimum zoom level for Bubble display.
  minZoom: 2,
  // Define the maximum zoom level for Bubble display.
  maxZoom: 20,
  // Define whether the Bubble is visible.
  visible: true,
  // Define the overlay level attribute of the Bubble.
  zIndex: 1
};
let bubble: map.Bubble = await this.mapController.addBubble(bubbleOptions);

[h2]setPadding

setPadding(padding?: mapCommon.Padding): void

Sets the padding between the map and its edges to define the visible region of a map. Map layer elements will adapt to the padding. For example, zoom controls and compass will be moved to adapt to the visible region, and the camera will move in relative to the center of the visible region.

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
padding mapCommon.Padding No Padding between the map and its edges. Invalid values are not processed.

Example:

// Initialization parameters. The left padding is 0 px and the bottom padding is 50 px.
let padding: mapCommon.Padding = {
  left: 0,
  bottom: 50
};
this.mapController.setPadding(padding);

[h2]getProjection

getProjection(): Projection

Obtains a Projection object that can be used to convert between the screen coordinates and the longitude/latitude coordinates.

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

Since: 4.1.0(11)

Returns:

Type Description
Projection Projection object.

Example:

let projection: map.Projection = this.mapController.getProjection();

[h2]setCustomMapStyle

setCustomMapStyle(customMapStyleOptions: mapCommon.CustomMapStyleOptions): Promise<void>

Sets the map style to a custom style. This API uses a promise to return the result asynchronously.

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

Since: 5.0.0(12)

Parameters:

Name Type Mandatory Description
customMapStyleOptions mapCommon.CustomMapStyleOptions Yes Custom style parameters. Invalid values are not processed.

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
1002601002 The custom map style file does not exist.
1002601004 The style content format is incorrect.

Example:

// Replace the value of styleId with your own style ID. The style ID can be created on the Petal Maps Studio platform.
let param: mapCommon.CustomMapStyleOptions = {
  styleId: "xxxxxxx"
};
await this.mapController.setCustomMapStyle(param);

[h2]getDayNightMode

getDayNightMode(): mapCommon.DayNightMode

Obtains the day/night mode of a map.

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

Since: 5.0.0(12)

Returns:

Type Description
mapCommon.DayNightMode

Day/Night mode.

- DayNightMode.DAY: day mode

- DayNightMode.NIGHT: night mode

- DayNightMode.AUTO: automatic mode. If the system's dark mode is enabled, the night mode is used; otherwise, the day mode is used.

If the map object does not exist or has been destroyed, mapCommon.DayNightMode.DAY will be used.

Example:

let mode = this.mapController.getDayNightMode();

[h2]setDayNightMode

setDayNightMode(mode: mapCommon.DayNightMode): void

Sets the day/night mode of a map.

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

Since: 5.0.0(12)

Parameters:

Name Type Mandatory Description
mode mapCommon.DayNightMode Yes Day/Night mode. Invalid values are not processed.

Example:

this.mapController.setDayNightMode(mapCommon.DayNightMode.AUTO);

[h2]getMapType

getMapType(): mapCommon.MapType

Obtains the map type.

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

Since: 5.0.0(12)

Returns:

Type Description
mapCommon.MapType Map type. If the map object does not exist or has been destroyed, mapCommon.MapType.STANDARD will be returned.

Example:

let mapType = this.mapController.getMapType();

[h2]setMapType

setMapType(mapType: mapCommon.MapType): void

Sets the map type.

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

Since: 5.0.0(12)

Parameters:

Name Type Mandatory Description
mapType mapCommon.MapType Yes Map type. Invalid values are not processed.

Example:

this.mapController.setMapType(mapCommon.MapType.TERRAIN);

[h2]setScalePosition

setScalePosition(point: mapCommon.MapPoint): void

Sets the position of the scale control.

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

Since: 5.0.0(12)

Parameters:

Name Type Mandatory Description
point mapCommon.MapPoint Yes

Scale location. Invalid values are not processed.

Note:

On wearables, the scale control is horizontally centered by default, and the passed positionX does not take effect.

Example:

let point: mapCommon.MapPoint = {
  // Use the upper left corner of the current map component as the origin and move 1000 pixels rightwards.
  positionX: 1000,
  // Use the upper left corner of the current map component as the origin and move 1000 pixels downwards.
  positionY: 1000
};
this.mapController.setScalePosition(point);

[h2]getScaleLevel

getScaleLevel(): number

Obtains the scale at the current zoom level.

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

Since: 5.0.0(12)

Returns:

Type Description
number Text number on the scale, in meters. If the map object does not exist or has been destroyed, 0 will be returned.

Example:

let level = this.mapController.getScaleLevel();

[h2]setCompassPosition

setCompassPosition(point: mapCommon.MapPoint): void

Sets the compass position.

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

Since: 5.0.0(12)

Parameters:

Name Type Mandatory Description
point mapCommon.MapPoint Yes Compass position, which is the offset of the upper left corner of the compass relative to the upper left corner of the map component, in pixels. Invalid values are not processed.

Example:

let point: mapCommon.MapPoint = {
  positionX: 10,
  positionY: 10
};
this.mapController.setCompassPosition(point);

[h2]setAllGesturesEnabled

setAllGesturesEnabled(enabled: boolean): void

Sets whether to enable all gestures.

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

Since: 5.0.0(12)

Parameters:

Name Type Mandatory Description
enabled boolean Yes

Indicates whether to enable all gestures. Invalid values are not processed.

- true: yes

- false: no

Example:

this.mapController.setAllGesturesEnabled(true);

[h2]getScaleControlsHeight

getScaleControlsHeight(): number

Obtains the height of the scale control.

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

Since: 5.0.0(12)

Returns:

Type Description
number Height of the scale control, in vp.

Example:

let height = this.mapController.getScaleControlsHeight();

[h2]getScaleControlsWidth

getScaleControlsWidth(): number

Obtains the width of the scale control.

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

Since: 5.0.0(12)

Returns:

Type Description
number Width of the scale control, in vp.

Example:

let width = this.mapController.getScaleControlsWidth();

[h2]setAlwaysShowScaleEnabled

setAlwaysShowScaleEnabled(enabled: boolean): void

Sets whether to always display the scale. Before using this API, call setScaleControlsEnabled to enable the scale control first.

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

Since: 5.0.0(12)

Parameters:

Name Type Mandatory Description
enabled boolean Yes

Indicates whether to always display the scale. Invalid values are not processed.

- true: yes

- false: no. The scale is displayed for 2 seconds and then disappear.

Example:

this.mapController.setAlwaysShowScaleEnabled(true);

[h2]isAlwaysShowScaleEnabled

isAlwaysShowScaleEnabled(): boolean

Checks whether the scale is always displayed.

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

Since: 5.0.0(12)

Returns:

Type Description
boolean

- true: yes

- false: no

Example:

let scaleEnabled: boolean = this.mapController.isAlwaysShowScaleEnabled();

[h2]addClusterOverlay

addClusterOverlay(params: mapCommon.ClusterOverlayParams): Promise<ClusterOverlay>

Adds a ClusterOverlay. This API uses a promise to return the result asynchronously.

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

Since: 5.0.0(12)

Parameters:

Name Type Mandatory Description
params mapCommon.ClusterOverlayParams Yes ClusterOverlay parameters.

Returns:

Type Description
Promise<ClusterOverlay> Promise used to return ClusterOverlay.

Error codes:

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

ID Error Message
401 Invalid input parameter.
1002601001 The object to be operated does not exist.

Example:

let clusterItem1: mapCommon.ClusterItem = {
  position: {
    latitude: 31.98,
    longitude: 118.766
  }
};
let clusterItem2: mapCommon.ClusterItem = {
  position: {
    latitude: 31.68,
    longitude: 118.366
  }
};
let array: Array<mapCommon.ClusterItem> = [
  clusterItem1,
  clusterItem2
];
let clusterOverlayParams: mapCommon.ClusterOverlayParams = { distance: 40, clusterItems: array };
let clusterOverlay: map.ClusterOverlay = await this.mapController.addClusterOverlay(clusterOverlayParams);

[h2]addImageOverlay

addImageOverlay(params: mapCommon.ImageOverlayParams): Promise<ImageOverlay>

Adds an ImageOverlay. This API uses a promise to return the result asynchronously.

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

Since: 5.0.0(12)

Parameters:

Name Type Mandatory Description
params mapCommon.ImageOverlayParams Yes ImageOverlay parameters.

Returns:

Type Description
Promise<ImageOverlay> Promise used to return ImageOverlay.

Error codes:

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

ID Error Message
401 Invalid input parameter.
1002601001 The object to be operated does not exist.

Example:

let imageOverlayParams: mapCommon.ImageOverlayParams = {
  bounds: {
    southwest: { latitude: 32, longitude: 118 },
    northeast: { latitude: 32.4, longitude: 118.4 }
  },
  // The icon must be stored in the resources/rawfile directory.
  image: 'icon/icon.png',
  transparency: 0.3,
  zIndex: 101,
  anchorU: 0.5,
  anchorV: 0.5,
  clickable: true,
  visible: true,
  bearing: 0
};
let imageOverlay = await this.mapController?.addImageOverlay(imageOverlayParams);

[h2]snapshot

snapshot(): Promise<image.PixelMap>

Generates a map snapshot. This API uses a promise to return the result. You are advised to implement a 3-second timeout protection when calling it.

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

Since: 5.0.0(12)

Returns:

Type Description
Promise<image.PixelMap> Promise used to return image.PixelMap.

Example:

import { image } from '@kit.ImageKit';

let image: image.PixelMap = await this.mapController.snapshot();

[h2]addBuildingOverlay

addBuildingOverlay(params: mapCommon.BuildingOverlayParams): Promise<BuildingOverlay>

Adds a BuildingOverlay. This API uses a promise to return the result asynchronously.

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

Since: 5.0.0(12)

Parameters:

Name Type Mandatory Description
params mapCommon.BuildingOverlayParams Yes BuildingOverlay attributes.

Returns:

Type Description
Promise<BuildingOverlay> Promise used to return BuildingOverlay.

Error codes:

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

ID Error Message
401 Invalid input parameter.
1002601001 The object to be operated does not exist.

Example:

let points: Array<mapCommon.LatLng> = [
  {
    latitude: 31.984794,
    longitude: 118.765865
  },
  {
    latitude: 31.98468,
    longitude: 118.766076
  },
  {
    latitude: 31.98472,
    longitude: 118.766116
  },
  {
    latitude: 31.98463,
    longitude: 118.766292
  },
  {
    latitude: 31.984586,
    longitude: 118.766251
  },
  {
    latitude: 31.984536,
    longitude: 118.766344
  },
  {
    latitude: 31.984633,
    longitude: 118.766446
  },
  {
    latitude: 31.9848,
    longitude: 118.766285
  },
  {
    latitude: 31.984925,
    longitude: 118.766312
  },
  {
    latitude: 31.985282,
    longitude: 118.766661
  },
  {
    latitude: 31.985438,
    longitude: 118.766419
  },
  {
    latitude: 31.985801,
    longitude: 118.766755
  },
  {
    latitude: 31.985856,
    longitude: 118.766504
  },
  {
    latitude: 31.985785,
    longitude: 118.766434
  },
  {
    latitude: 31.985821,
    longitude: 118.766278
  },
  {
    latitude: 31.985897,
    longitude: 118.766311
  },
  {
    latitude: 31.985944,
    longitude: 118.766095
  },
  {
    latitude: 31.985909,
    longitude: 118.766069
  },
  {
    latitude: 31.985794,
    longitude: 118.765989
  },
  {
    latitude: 31.9857,
    longitude: 118.766029
  },
  {
    latitude: 31.985658,
    longitude: 118.766164
  },
  {
    latitude: 31.985647,
    longitude: 118.766271
  },
  {
    latitude: 31.985574,
    longitude: 118.766297
  },
  {
    latitude: 31.985458,
    longitude: 118.766285
  },
  {
    latitude: 31.985271,
    longitude: 118.766002
  },
  {
    latitude: 31.985219,
    longitude: 118.766002
  },
  {
    latitude: 31.985135,
    longitude: 118.766029
  },
  {
    latitude: 31.985093,
    longitude: 118.766083
  },
  {
    latitude: 31.985019,
    longitude: 118.766109
  },
  {
    latitude: 31.984978,
    longitude: 118.766083
  },
  {
    latitude: 31.984794,
    longitude: 118.765865
  }
];
points.reverse();
// BuildingOverlay parameters.
let buildingOverlayOptions: mapCommon.BuildingOverlayParams =
  {
    // Scope parameter of the BuildingOverlay (points are drawn in clockwise order).
    points: points,
    // Height of the BuildingOverlay.
    totalHeight: 51,
    // Height of the selected floor in the BuildingOverlay.
    floorBottomHeight: 33,
    // Top color of the BuildingOverlay.
    topFaceColor: 0xffa4b8f7,
    // Side color of the BuildingOverlay.
    sideFaceColor: 0x44a4b8f7,
    // Color of the selected floor in the BuildingOverlay.
    floorColor: 0xff000000,
    // Display level of the BuildingOverlay.
    showLevel: 14,
    // Animation duration for the selected floor in the BuildingOverlay rising from the bottom.
    animationDuration: 5000,
    // Side texture of the BuildingOverlay.
    sideTexture: { image: $r("app.media.side_tex"), height: 3, width: 3 },
    // Texture of the selected floor in the BuildingOverlay.
    floorTexture: { image: $r("app.media.floor_tex"), height: 3, width: 3 }
  };
let cameraUpdate = map.newCameraPosition({
  target: {
    latitude: 31.984794,
    longitude: 118.765865
  },
  zoom: 18,
  tilt: 70
});
// Move the map camera to the BuildingOverlay area.
this.mapController?.moveCamera(cameraUpdate);
// Create a BuildingOverlay.
let buildingOverlay: map.BuildingOverlay = await this.mapController?.addBuildingOverlay(buildingOverlayOptions);

[h2]addTraceOverlay

addTraceOverlay(params: mapCommon.TraceOverlayParams, markers?: Array<Marker>): Promise<TraceOverlay>

Draws a TraceOverlay. A group of markers can be passed, which will move along with the trajectory. This API uses a promise to return the result asynchronously.

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

Since: 5.0.0(12)

Parameters:

Name Type Mandatory Description
params mapCommon.TraceOverlayParams Yes TraceOverlay parameters.
markers Array<Marker> No

Image array of the TraceOverlay. Invalid values are not processed.

Note:

The positions of the passed Markers must be the same.

Returns:

Type Description
Promise<TraceOverlay> Promise used to return TraceOverlay.

Error codes:

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

ID Error Message
401 Invalid input parameter.
1002601001 The object to be operated does not exist.

Example:

// Parameters of marker 1.
let markerOptions1: mapCommon.MarkerOptions = {
  position: {
    latitude: 31.99227173519985,
    longitude: 118.7622219990476
  },
  // The icon must be stored in the resources/base/media directory.
  icon: $r("app.media.track_setting_sport_map_marker_22"),
  anchorU: 0.5,
  anchorV: 1,
  visible: true
};
// Add marker 1.
let markerBoy1 = await this.mapController.addMarker(markerOptions1);
let boyImages1: map.PlayImageAnimation = new map.PlayImageAnimation();
boyImages1.setDuration(1000);
let resourceArray: Array<Resource> = new Array();
resourceArray.push($r("app.media.side_0"));
resourceArray.push($r("app.media.side_1"));
resourceArray.push($r("app.media.side_2"));
resourceArray.push($r("app.media.side_3"));
resourceArray.push($r("app.media.side_4"));
resourceArray.push($r("app.media.side_5"));
resourceArray.push($r("app.media.side_6"));
resourceArray.push($r("app.media.side_7"));
resourceArray.push($r("app.media.side_8"));
resourceArray.push($r("app.media.side_9"));
resourceArray.push($r("app.media.side_10"));
resourceArray.push($r("app.media.side_11"));
resourceArray.push($r("app.media.side_12"));
resourceArray.push($r("app.media.side_13"));
resourceArray.push($r("app.media.side_14"));
resourceArray.push($r("app.media.side_15"));
resourceArray.push($r("app.media.side_16"));
resourceArray.push($r("app.media.side_17"));
resourceArray.push($r("app.media.side_18"));
resourceArray.push($r("app.media.side_19"));
resourceArray.push($r("app.media.side_20"));
await boyImages1.addImages(resourceArray);
boyImages1.setRepeatCount(-1);

// Add an animation for marker 1.
markerBoy1.setAnimation(boyImages1);
markerBoy1.startAnimation();

// Parameters of marker 2.
let markerOptions2: mapCommon.MarkerOptions = {
  position: {
    latitude: 31.99227173519985,
    longitude: 118.7622219990476
  },
  // The icon must be stored in the resources/base/media directory.
  icon: $r("app.media.track_setting_sport_map_marker_22"),
  anchorU: 0.5,
  anchorV: 1,
  visible: false
};
// Add marker 2.
let markerBoy2 = await this.mapController.addMarker(markerOptions2);
let boyImages2: map.PlayImageAnimation = new map.PlayImageAnimation();
boyImages2.setDuration(1000);
let resourceArray2: Array<Resource> = new Array();
resourceArray2.push($r("app.media.behavior_front_cycling_boy_000"));
resourceArray2.push($r("app.media.behavior_front_cycling_boy_001"));
resourceArray2.push($r("app.media.behavior_front_cycling_boy_002"));
resourceArray2.push($r("app.media.behavior_front_cycling_boy_003"));
resourceArray2.push($r("app.media.behavior_front_cycling_boy_004"));
resourceArray2.push($r("app.media.behavior_front_cycling_boy_005"));
resourceArray2.push($r("app.media.behavior_front_cycling_boy_006"));
resourceArray2.push($r("app.media.behavior_front_cycling_boy_007"));
resourceArray2.push($r("app.media.behavior_front_cycling_boy_008"));
resourceArray2.push($r("app.media.behavior_front_cycling_boy_009"));
resourceArray2.push($r("app.media.behavior_front_cycling_boy_010"));
resourceArray2.push($r("app.media.behavior_front_cycling_boy_011"));
resourceArray2.push($r("app.media.behavior_front_cycling_boy_012"));
resourceArray2.push($r("app.media.behavior_front_cycling_boy_013"));
resourceArray2.push($r("app.media.behavior_front_cycling_boy_014"));
resourceArray2.push($r("app.media.behavior_front_cycling_boy_015"));
resourceArray2.push($r("app.media.behavior_front_cycling_boy_016"));
resourceArray2.push($r("app.media.behavior_front_cycling_boy_017"));
resourceArray2.push($r("app.media.behavior_front_cycling_boy_018"));
await boyImages2.addImages(resourceArray2);
boyImages2.setRepeatCount(-1);
// Add an animation for marker 2.
markerBoy2.setAnimation(boyImages2);
markerBoy2.startAnimation();

let points: Array<mapCommon.LatLng> = new Array();
points.push({ latitude: 31.99685233070878, longitude: 118.75846023442728 });
points.push({ latitude: 31.99671325810786, longitude: 118.75846738985165 });
points.push({ latitude: 31.99659191076709, longitude: 118.7585347621686 });
points.push({ latitude: 31.99648202537233, longitude: 118.7586266510386 });
points.push({ latitude: 31.99637707201552, longitude: 118.75872004590596 });
points.push({ latitude: 31.996278207010903, longitude: 118.75880449946251 });
points.push({ latitude: 31.996187481969695, longitude: 118.7588781960278 });
points.push({ latitude: 31.996092248919354, longitude: 118.75895330554488 });
points.push({ latitude: 31.995962740450565, longitude: 118.75904721407304 });
points.push({ latitude: 31.995792921394, longitude: 118.75916904998051 });
points.push({ latitude: 31.995601885713416, longitude: 118.7593235241019 });
points.push({ latitude: 31.995398221178277, longitude: 118.75949998588176 });
points.push({ latitude: 31.995185902197715, longitude: 118.7596871082939 });
points.push({ latitude: 31.994983473052656, longitude: 118.75987334062296 });
points.push({ latitude: 31.99482433699269, longitude: 118.76002095184032 });
points.push({ latitude: 31.994709073721708, longitude: 118.76012902920532 });
points.push({ latitude: 31.99460732100702, longitude: 118.76023892576234 });
points.push({ latitude: 31.99449284962087, longitude: 118.7603694232856 });
points.push({ latitude: 31.99435358179254, longitude: 118.76053622438056 });
points.push({ latitude: 31.99420771148339, longitude: 118.76072790126692 });
points.push({ latitude: 31.994075194901523, longitude: 118.7609100960977 });
points.push({ latitude: 31.993952686158877, longitude: 118.7610741329013 });
points.push({ latitude: 31.993840180644217, longitude: 118.7612193418965 });
points.push({ latitude: 31.993733787150244, longitude: 118.76135383115654 });
points.push({ latitude: 31.993617206525155, longitude: 118.76150529647698 });

// Input parameters of the TraceOverlay.
let traceOptions: mapCommon.TraceOverlayParams = {
  // Trajectory points.
  points: points,
  // Animation duration of the trajectory.
  animationDuration: 5000,
  // Whether the camera moves with the animation.
  isMapMoving: true,
  // Color of the trajectory.
  color: 0xAAFFAA00,
  // Width of the trajectory.
  width: 20,
  // Animation callback of the trajectory (it returns the trajectory point index).
  animationCallback: (pointIndex) => {
    // Change to cycling.
    if (pointIndex === 10) {
      markerBoy1.setVisible(false);
      markerBoy2.setVisible(true);
    }
  }
};
let markers: Array<map.Marker> = new Array();
markers.push(markerBoy1, markerBoy2);
// Add a trajectory point animation.
let traceOverlay: map.TraceOverlay = await this.mapController.addTraceOverlay(traceOptions, markers);

[h2]addArc

addArc(params: mapCommon.MapArcParams): MapArc

Adds a MapArc to a map.

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

Since: 5.0.0(12)

Parameters:

Name Type Mandatory Description
params mapCommon.MapArcParams Yes MapArc attributes.

Returns:

Type Description
MapArc MapArc.

Error codes:

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

ID Error Message
401 Invalid input parameter.
1002601001 The object to be operated does not exist.

Example:

// Set MapArc parameters.
let mapArcParams: mapCommon.MapArcParams = {
  // Coordinates of the MapArc start point.
  startPoint: {
    latitude: 39.913138,
    longitude: 116.415112
  },
  // Coordinates of the MapArc end point.
  endPoint: {
    latitude: 28.239473,
    longitude: 112.954094
  },
  // Coordinates of the MapArc midpoint.
  centerPoint: {
    latitude: 33.86970399048567,
    longitude: 112.08633528544145
  },
  width: 10,
  color: 0xffff0000,
  visible: true,
  zIndex: 100
};
// Add a MapArc.
this.mapController.addArc(mapArcParams);

[h2]show

show(): void

Switches the map to the foreground. You can call this API in onPageShow, which is a function in the page lifecycle.

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

Since: 5.0.0(12)

Example:

// This is called each time the page is displayed, for example, during page redirection or when the app is switched to the foreground. It works only for the custom components decorated using @Entry.
onPageShow(): void {
  // Switch the map to the foreground.
  if (this.mapController) {
    this.mapController.show();
  }
}

[h2]hide

hide(): void

Switches the map to the background. You can call this API in onPageHide, which is a function in the page lifecycle.

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

Since: 5.0.0(12)

Example:

// This is called each time the page is hidden, for example, during page redirection or when the app is switched to the background. It works only for the custom components decorated using **@Entry**.
onPageHide(): void {
  // Switch the map to the background.
  if (this.mapController) {
    this.mapController.hide();
  }
}

[h2]getEventManager

getEventManager(): MapEventManager

Returns the map listening event manager.

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

Since: 5.0.0(12)

Returns:

Type Description
MapEventManager Map listening event manager.

Example:

let mapEventManager: map.MapEventManager = this.mapController.getEventManager();

[h2]setDisplayOrder

setDisplayOrder(types: Array<mapCommon.MapElementType>): void

Sets the display order of map elements in ascending order. Subsequently added overlays will be rendered on top of preceding ones.

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

Since: 5.0.0(12)

Parameters:

Name Type Mandatory Description
types Array<mapCommon.MapElementType> Yes

Overlay order of the map elements. The default order is [1, 2, 3, 4].

The parameter value length must be 4. Each element in the parameter value must be an enumerated value defined in mapCommon.MapElementType. Otherwise, error code 401 is returned.

Error codes:

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

ID Error Message
401 Invalid input parameter.

Example:

let mapElementTypeArr: Array<mapCommon.MapElementType> = [
  mapCommon.MapElementType.OVERLAY,
  mapCommon.MapElementType.POI,
  mapCommon.MapElementType.CUSTOM_POI,
  mapCommon.MapElementType.MARKER];
this.mapController.setDisplayOrder(mapElementTypeArr);

[h2]setLogoScale

setLogoScale(logoScale: number): void

Modifies the logo scaling ratio.

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.3(15).

System capability: SystemCapability.Map.Core

Since: 5.0.3(15)

Parameters:

Name Type Mandatory Description
logoScale number Yes Logo scaling ratio. The value range is [0.8, 1]. Error code 401 will be returned for any invalid value.

Error codes:

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

ID Error Message
401 Invalid input parameter.

Example:

this.mapController.setLogoScale(0.9);

[h2]getLogoScale

getLogoScale(): number

Obtains the logo scaling ratio. The value range is [0.8, 1].

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.3(15).

System capability: SystemCapability.Map.Core

Since: 5.0.3(15)

Returns:

Type Description
number Logo scaling ratio.

Example:

let logoScale: number = this.mapController.getLogoScale();

[h2]isSphereEnabled

isSphereEnabled(): boolean

Checks whether the 3D globe view is enabled.

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.3(15).

System capability: SystemCapability.Map.Core

Since: 5.0.3(15)

Returns:

Type Description
boolean

- true: The 3D globe view is enabled.

- false: The 3D globe view is disabled.

Example:

let result: boolean = this.mapController.isSphereEnabled();

[h2]setSphereEnabled

setSphereEnabled(enabled: boolean): void

Switches between the 2D and 3D globe views in animation mode. The 3D globe refers to a technology that displays Earth's surface information in a three-dimensional format on digital devices.

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.3(15).

System capability: SystemCapability.Map.Core

Since: 5.0.3(15)

Parameters:

Name Type Mandatory Description
enabled boolean Yes

Switches between the 2D and 3D maps in animation mode. Invalid values are not processed. The options are as follows:

- true: Switches to the 3D map.

- false: Switches to the 2D map.

Example:

this.mapController.setSphereEnabled(true);

[h2]setSphereEnabled

setSphereEnabled(enabled: boolean, animateDuration: number): void

Switches between the 2D and 3D globe views in animation mode. The 3D globe refers to a technology that displays Earth's surface information in a three-dimensional format on digital devices.

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 6.0.0(20).

System capability: SystemCapability.Map.Core

Since: 6.0.0(20)

Parameters:

Name Type Mandatory Description
enabled boolean Yes

Switches between the 2D and 3D maps in animation mode. Invalid values are not processed. The options are as follows:

- true: Switches to the 3D map.

- false: Switches to the 2D map.
animateDuration number Yes Animation duration, in milliseconds. The value must be greater than 0. Invalid values are not processed.

Example:

this.mapController.setSphereEnabled(true, 1000);

[h2]setSphereEnabled

setSphereEnabled(enabled: boolean, animateDuration: number, cityLight: boolean): void

Switches between the 2D and 3D globe views in animation mode. The 3D globe refers to a technology that displays Earth's surface information in a three-dimensional format on digital devices.

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 6.1.0(23).

System capability: SystemCapability.Map.Core

Since: 6.1.0(23)

Parameters:

Name Type Mandatory Description
enabled boolean Yes

Switches between the 2D and 3D maps in animation mode. Invalid values are not processed. The options are as follows:

- true: Switches to the 3D map.

- false: Switches to the 2D map.
animateDuration number Yes Animation duration, in milliseconds. The value must be greater than 0. Invalid values are not processed.
cityLight boolean Yes

Indicates whether to enable city lighting. To use city lighting, you need to enable the 3D globe view. Invalid values are not processed.

- true: Enable city lighting.

- false: Disable city lighting.

Example:

this.mapController.setSphereEnabled(true, 1000, true);

[h2]setSphereMapEnabled

setSphereMapEnabled(enabled: boolean, params?: mapCommon.SphereParams): Promise<void>

Sets the 3D map switch.

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

Atomic service API: This API can be used in atomic services since API version 26.0.0.

System capability: SystemCapability.Map.Core

Since: 26.0.0

Parameters:

Name Type Mandatory Description
enabled boolean Yes

Switches between the 2D and 3D maps in animation mode. Invalid values are not processed. The options are as follows:

- true: Switches to the 3D map.

- false: Switches to the 2D map.
params mapCommon.SphereParams No Sphere attributes.

Returns:

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

Example:

let mSphereOptions: mapCommon.SphereParams =
  {
    // Enable the sunlight effect for the sphere.
    sunLightEnabled: true,
    // Enable the city light effect for the sphere.
    cityLightEnabled: true,
    // Set the animation duration to 1000 ms.
    animateDuration: 1000,
    // The images must be stored in the resources/base/media directory.
    backgroundImage: $r('app.media.bg_compress'),
    coverageImage: $r('app.media.coverage_icon')
  };
await this.mapController.setSphereMapEnabled(true, mSphereOptions);

[h2]addHeatmap

addHeatmap(params: mapCommon.HeatmapParams): Promise<Heatmap>

Adds a heatmap. This API uses a promise to return the result. Heatmaps are well suited for visualizing data density in large-scale scenarios, such as pedestrian flow distribution and hotspot areas.

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 6.0.0(20).

System capability: SystemCapability.Map.Core

Since: 6.0.0(20)

Parameters:

Name Type Mandatory Description
params mapCommon.HeatmapParams Yes Parameters for adding a heatmap.

Returns:

Type Description
Promise<Heatmap> Promise used to return Heatmap.

Error codes:

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

ID Error Message
1002601001 The object to be operated does not exist.
1002600015 The heatmap ID already exists.

Example:

let data: mapCommon.WeightedLatLng[] = [];
// Generate 500 random coordinate points for the heatmap data.
for (let i = 0; i < 500; i++) {
  data.push({
    point: {
      longitude: 118.000000 + Math.random() * 1 - 0.25,
      latitude: 31.000000 + Math.random() * 1 - 0.25
    },
    intensity: 1
  });
}
let heatMapOptions: mapCommon.HeatmapParams = {
  id: 'heatmap0001',
  data: data,
  radius: 20,
  intensity: {
    2: 1,
    5: 5,
    8: 10
  },
}
await this.mapController?.addHeatmap(heatMapOptions)

[h2]addMvtOverlay

addMvtOverlay(params: mapCommon.MvtOverlayParams): MvtOverlay

Adds an MvtOverlay.

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 6.0.0(20).

System capability: SystemCapability.Map.Core.EnhancedOverlay

Since: 6.0.0(20)

Parameters:

Name Type Mandatory Description
params mapCommon.MvtOverlayParams Yes

MvtOverlay parameters.

Note:

To add an MvtOverlay using an online resource (via the tileUrl method specified in the mapCommon.MvtSource parameter of mapCommon.MvtOverlayParams), you must apply for the network access permission ohos.permission.INTERNET.

Returns:

Type Description
MvtOverlay MvtOverlay object.

Error codes:

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

ID Error Message
1022100001 The operation object does not exist. 
let params: mapCommon.MvtOverlayParams = {
  source: {
    // Set the URL of the MvtOverlay, which must start with http or https and contain placeholders {x}, {y}, and {z}.
    tileUrl: 'http://xxx/tiles/{z}/{x}/{y}.pbf',
    minZoom: 2,
    maxZoom: 15
  },
  layers: [{
    id: 'layer-map',
    type: mapCommon.MvtLayerType.FILL,
    // MvtOverlay name.
    sourceLayer: 'XX',
    paint: {
      fillColor: {
        operator: mapCommon.Operator.GET,
        args: 'fill'
      },
      fillOpacity: {
        operator: mapCommon.Operator.GET,
        args: 'fill-opacity'
      }
    }
  }]
};
let mvtOverlay = this.mapController?.addMvtOverlay(params);

[h2]setFramePerSecond

setFramePerSecond(fps: number): void

Sets the number of frames per second.

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 6.0.0(20).

System capability: SystemCapability.Map.Core

Since: 6.0.0(20)

Parameters:

Name Type Mandatory Description
fps number Yes Expected number of frames per second. The value ranges from 1 to 60. Error code 401 will be returned for any invalid value.

Example:

this.mapController?.setFramePerSecond(60);

[h2]addFlowFieldOverlay

addFlowFieldOverlay(params: mapCommon.FlowFieldOverlayParams): Promise<FlowFieldOverlay>

Adds a FlowFieldOverlay, which is applicable to wind field and ocean current scenarios. This API uses a promise to return the result asynchronously.

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 6.0.0(20).

System capability: SystemCapability.Map.Core.EnhancedOverlay

Since: 6.0.0(20)

Parameters:

Name Type Mandatory Description
params mapCommon.FlowFieldOverlayParams Yes FlowFieldOverlay parameters.

Returns:

Type Description
Promise<FlowFieldOverlay> Promise used to return the FlowFieldOverlay object.

Error codes:

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

ID Error Message
1022100001 The operation object does not exist.

Example:

let params: mapCommon.FlowFieldOverlayParams = {
  // The value of data must be in JSON format that complies with the GRIB2 specification. Set data by referring to the flow field data format reference.
  data: 'xxx'
};
let fieldOverlay = await this.mapController.addFlowFieldOverlay(params);

[h2]addMassPointOverlay

addMassPointOverlay(params: mapCommon.MassPointOverlayParams): Promise<MassPointOverlay>

Adds a MassPointOverlay. This API uses a promise to return the result asynchronously.

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 6.0.0(20).

System capability: SystemCapability.Map.Core

Since: 6.0.0(20)

Parameters:

Name Type Mandatory Description
params mapCommon.MassPointOverlayParams Yes MassPointOverlay parameters.

Returns:

Type Description
Promise<MassPointOverlay> Promise used to return the MassPointOverlay object.

Error codes:

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

ID Error Message
1002601001 The object to be operated does not exist.

Example:

let items: mapCommon.MassPointItem[] = [];
for (let i = 0; i < 1000; i++) {
  // Save massive points to items.
  items.push({
    itemId: 'test' + i,
    position: {
      longitude: 118.11111 + Math.random() * 1 - 0.5,
      latitude: 32.11111 + Math.random() * 1 - 0.5,
    },
    snippet: 'test' + i,
    title: 'test' + i
  })
}
let params: mapCommon.MassPointOverlayParams = {
  id: 'test',
  items: items,
  // The icon is stored in resources/rawfile. Set icon to the relative path of the icon file within the rawfile folder.
  icon: 'icon/maps_blue_dot.png',
}
let massPointOverlay = await this.mapController?.addMassPointOverlay(params);

[h2]setLanguage

setLanguage(language: string): void

Sets the language of the map component.

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 6.0.0(20).

System capability: SystemCapability.Map.Core

Since: 6.0.0(20)

Parameters:

Name Type Mandatory Description
language string Yes Map language. Invalid values are not processed. For details about the language values, please refer to Languages Supported by the Map Component.

Example:

this.mapController?.setLanguage('ja');

[h2]getLanguage

getLanguage(): string

Obtains the language of the map component.

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 6.0.0(20).

System capability: SystemCapability.Map.Core

Since: 6.0.0(20)

Returns:

Type Description
string Map language. For details about the language values, please refer to Languages Supported by the Map Component.

Example:

let language = this.mapController?.getLanguage();

[h2]changeMyLocationLayerOrder

changeMyLocationLayerOrder(isBelow: boolean): void

Changes the stacking order of the my-location layer relative to overlays.

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 6.0.1(21).

System capability: SystemCapability.Map.Core

Since: 6.0.1(21)

Parameters:

Name Type Mandatory Description
isBelow boolean Yes

Indicates whether the my-location layer is below overlays. Invalid values are not processed.

- true: yes

- false: no

Note:

This API takes effect for the Marker, MapPolyline, MapPolygon, MapCircle, PointAnnotation, Bubble, ImageOverlay, MapArc, TraceOverlay, and base map POI.

Example:

this.mapController?.changeMyLocationLayerOrder(true);

[h2]addTileOverlay

addTileOverlay(params: mapCommon.TileOverlayParams | mapCommon.TileOverlayOptions): TileOverlay

Adds a TileOverlay.

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.3(15).

System capability: SystemCapability.Map.Core

Since: 5.0.3(15)

Parameters:

Name Type Mandatory Description
params mapCommon.TileOverlayParams | mapCommon.TileOverlayOptions Yes

TileOverlay parameters.

Note:

The params parameter supports the mapCommon.TileOverlayOptions type since version 6.0.0(20).

Returns:

Type Description
TileOverlay TileOverlay.

Error codes:

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

ID Error Message
1002601001 The object to be operated does not exist.

Example:

let params: mapCommon.TileOverlayOptions = {
  // Set the URL of the TileOverlay, which must start with http or https and contain placeholders {x}, {y}, and {z}.
  // Replace it with your own URL.
  tileUrl: "https://xxx/xxx?x={x}&y={y}&z={z}",
  // Set the transparency.
  transparency: 0.5,
  // Enable the TileOverlay fade-in effect.
  fadeIn: true,
  // Enable disk caching.
  diskCacheEnabled: true,
  // Disk cache size, in KB. The default value is 20480.
  diskCacheSize: 20480,
  // Sandbox path for storing disk cache.
  diskCachePath: this.getUIContext().getHostContext()?.databaseDir
};
let tileOverlay: map.TileOverlay = this.mapController?.addTileOverlay(params);

[h2]on('cameraChange')

on(type: 'cameraChange', callback: Callback<mapCommon.LatLng>): void

Listens for map camera status changes. This API returns the result asynchronously through a callback. The callback is not triggered during animation. Instead, it is triggered when the animation ends.

You are advised to use MapEventManager.on(type: 'cameraChange').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'cameraChange': map camera status change event.
callback Callback<mapCommon.LatLng> Yes Callback function, which returns mapCommon.LatLng. This callback listens for map camera status changes. The callback is not triggered during animation. Instead, it is triggered when the animation ends.

Example:

this.mapController.on("cameraChange", (position) => {
  console.info("cameraChange", `on-cameraChange position = ${position.longitude}`);
});

[h2]off('cameraChange')

off(type: 'cameraChange', callback: Callback<void>): void

Cancels listening for map camera status changes. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.off(type: 'cameraChange').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'cameraChange': map camera status change event.
callback Callback<void> Yes Callback that returns no value.

Example:

this.mapController.off("cameraChange", (position) => {
  console.info("cameraChange", `off-cameraChange`);
});

[h2]on('cameraIdle')

on(type: 'cameraIdle', callback: Callback<void>): void

Listens for camera movement end events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.on(type: 'cameraIdle').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'cameraIdle': camera movement end event.
callback Callback<void> Yes Callback that returns no value.

Example:

this.mapController.on("cameraIdle", () => {
  console.info("cameraIdle", `on-cameraIdle`);
});

[h2]off('cameraIdle')

off(type: 'cameraIdle', callback: Callback<void>): void

Cancels listening for camera movement end events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.off(type: 'cameraIdle').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'cameraIdle': camera movement end event.
callback Callback<void> Yes Callback that returns no value.

Example:

this.mapController.off("cameraIdle", () => {
  console.info("cameraIdle", `off-cameraIdle`);
});

[h2]on('cameraMoveCancel')

on(type: 'cameraMoveCancel', callback: Callback<void>): void

Listens for camera movement cancellation events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.on(type: 'cameraMoveCancel').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'cameraMoveCancel': camera movement cancellation event.
callback Callback<void> Yes Callback that returns no value.

Example:

this.mapController.on("cameraMoveCancel", () => {
  console.info("cameraMoveCancel", `on-cameraMoveCancel`);
});

[h2]off('cameraMoveCancel')

off(type: 'cameraMoveCancel', callback: Callback<void>): void

Cancels listening for camera movement cancellation events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.off(type: 'cameraMoveCancel').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'cameraMoveCancel': camera movement cancellation event.
callback Callback<void> Yes Callback that returns no value.

Example:

this.mapController.off("cameraMoveCancel", () => {
  console.info("cameraMoveCancel", `off-cameraMoveCancel`);
});

[h2]on('cameraMove')

on(type: 'cameraMove', callback: Callback<void>): void

Listens for camera movement events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.on(type: 'cameraMove').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'cameraMove': camera movement event.
callback Callback<void> Yes Callback that returns no value.

Example:

this.mapController.on("cameraMove", () => {
  console.info("cameraMove", `on-cameraMove`);
});

[h2]off('cameraMove')

off(type: 'cameraMove', callback: Callback<void>): void

Cancels listening for camera movement events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.off(type: 'cameraMove').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'cameraMove': camera movement event.
callback Callback<void> Yes Callback that returns no value.

Example:

this.mapController.off("cameraMove", () => {
  console.info("cameraMove", `off-cameraMove`);
});

[h2]on('cameraMoveStart')

on(type: 'cameraMoveStart', callback: Callback<number>): void

Listens for camera movement start events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.on(type: 'cameraMoveStart').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'cameraMoveStart': camera movement start event.
callback Callback<number> Yes

Callback function, which returns number.

number indicates the reason why the camera moves.

1: A user makes a gesture on the map.

2: The default animation is triggered by user interaction.

3: You start an animation.

Example:

this.mapController.on("cameraMoveStart", (reason) => {
  console.info("cameraMoveStart", `on-cameraMoveStart reason = ${reason}`);
});

[h2]off('cameraMoveStart')

off(type: 'cameraMoveStart', callback: Callback<void>): void

Cancels listening for camera movement start events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.off(type: 'cameraMoveStart').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'cameraMoveStart': camera movement start event.
callback Callback<void> Yes Callback that returns no value.

Example:

this.mapController.off("cameraMoveStart", () => {
  console.info("cameraMoveStart", `off-cameraMoveStart`);
});

[h2]on('mapClick')

on(type: 'mapClick', callback: Callback<mapCommon.LatLng>): void

Listens for map tap events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.on(type: 'mapClick').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'mapClick': map tap event.
callback Callback<mapCommon.LatLng> Yes Callback used to return mapCommon.LatLng.

Example:

this.mapController.on("mapClick", (position) => {
  console.info("mapClick", `on-mapClick position = ${position.longitude}`);
});

[h2]off('mapClick')

off(type: 'mapClick', callback: Callback<void>): void

Cancels listening for map tap events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.off(type: 'mapClick').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'mapClick': map tap event.
callback Callback<void> Yes Callback that returns no value.

Example:

this.mapController.off("mapClick", () => {
  console.info("mapClick", `off-mapClick`);
});

[h2]on('mapLoad')

on(type: 'mapLoad', callback: Callback<void>): void

Listens for map load events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.on(type: 'mapLoad').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'mapLoad': map load event.
callback Callback<void> Yes Callback that returns no value.

Example:

this.mapController.on("mapLoad", () => {
  console.info("mapLoad", `on-mapLoad`);
});

[h2]off('mapLoad')

off(type: 'mapLoad', callback: Callback<void>): void

Cancels listening for map load events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.off(type: 'mapLoad').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'mapLoad': map load event.
callback Callback<void> Yes Callback that returns no value.

Example:

this.mapController.off("mapLoad", () => {
  console.info("mapLoad", `off-mapLoad`);
});

[h2]on('mapLongClick')

on(type: 'mapLongClick', callback: Callback<mapCommon.LatLng>): void

Listens for map long-press events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.on(type: 'mapLongClick').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'mapLongClick': map long-press event.
callback Callback<mapCommon.LatLng> Yes Callback used to return mapCommon.LatLng.

Example:

this.mapController.on("mapLongClick", () => {
  console.info("mapLongClick", `on-mapLongClick`);
});

[h2]off('mapLongClick')

off(type: 'mapLongClick', callback: Callback<void>): void

Cancels listening for map long-press events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.off(type: 'mapLongClick').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'mapLongClick': map long-press event.
callback Callback<void> Yes Callback that returns no value.

Example:

this.mapController.off("mapLongClick", () => {
  console.info("mapLongClick", `off-mapLongClick`);
});

[h2]on('myLocationButtonClick')

on(type: 'myLocationButtonClick', callback: Callback<void>): void

Listens for my-location icon tap events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.on(type: 'myLocationButtonClick').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'myLocationButtonClick': my-location icon tap event.
callback Callback<void> Yes Callback that returns no value.

Example:

this.mapController.on("myLocationButtonClick", () => {
  console.info("myLocationButtonClick", `on-myLocationButtonClick`);
});

[h2]off('myLocationButtonClick')

off(type: 'myLocationButtonClick', callback: Callback<void>): void

Cancels listening for my-location icon tap events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.off(type: 'myLocationButtonClick').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'myLocationButtonClick': my-location icon tap event.
callback Callback<void> Yes Callback that returns no value.

Example:

this.mapController.off("myLocationButtonClick", () => {
  console.info("myLocationButtonClick", `off-myLocationButtonClick`);
});

[h2]on('myLocationClick')

on(type: 'myLocationClick', callback: Callback<mapCommon.LatLng>): void

Listens for my location tap events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.on(type: 'myLocationClick').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'myLocationClick': my location tap event.
callback Callback<mapCommon.LatLng> Yes Callback used to return mapCommon.LatLng.

Example:

this.mapController.on("myLocationClick", (position) => {
  console.info("myLocationClick", `on-myLocationClick position = ${position.longitude}`);
});

[h2]off('myLocationClick')

off(type: 'myLocationClick', callback: Callback<void>): void

Cancels listening for my location tap events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.off(type: 'myLocationClick').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'myLocationClick': my location tap event.
callback Callback<void> Yes Callback that returns no value.

Example:

this.mapController.off("myLocationClick", () => {
  console.info("myLocationClick", `off-myLocationClick`);
});

[h2]on('poiClick')

on(type: 'poiClick', callback: Callback<mapCommon.Poi>): void

Listens for POI tap events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.on(type: 'poiClick').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'poiClick': POI tap event.
callback Callback<mapCommon.Poi> Yes Callback function, which returns mapCommon.Poi.

Example:

this.mapController.on("poiClick", (poi) => {
  console.info("poiClick", `on-poiClick poi = ${poi.id}`);
});

[h2]off('poiClick')

off(type: 'poiClick', callback: Callback<void>): void

Cancels listening for POI tap events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.off(type: 'poiClick').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'poiClick': POI tap event.
callback Callback<void> Yes Callback that returns no value.

Example:

this.mapController.off("poiClick", () => {
 console.info("poiClick", `off-poiClick`);
});

[h2]on('markerClick')

on(type: 'markerClick', callback: Callback<Marker>): void

Listens for Marker tap events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.on(type: 'markerClick').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'markerClick': Marker tap event.
callback Callback<Marker> Yes Callback used to return Marker.

Example:

this.mapController.on("markerClick", (marker) => {
 console.info("markerClick", `on-markerClick position = ${marker.getId()}`);
});

[h2]off('markerClick')

off(type: 'markerClick', callback: Callback<void>): void

Cancels listening for Marker tap events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.off(type: 'markerClick').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'markerClick': Marker tap event.
callback Callback<void> Yes Callback that returns no value.

Example:

this.mapController.off("markerClick", () => {
 console.info("markerClick", `off-markerClick`);
});

[h2]on('markerDragStart')

on(type: 'markerDragStart', callback: Callback<Marker>): void

Listens for Marker drag start events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.on(type: 'markerDragStart').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'markerDragStart': Marker drag start event.
callback Callback<Marker> Yes Callback used to return Marker.

Example:

this.mapController.on("markerDragStart", (marker) => {
 console.info("markerDragStart", `on-markerDragStart position = ${marker.getId()}`);
});

[h2]off('markerDragStart')

off(type: 'markerDragStart', callback: Callback<void>): void

Cancels listening for Marker drag start events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.off(type: 'markerDragStart').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'markerDragStart': Marker drag start event.
callback Callback<void> Yes Callback that returns no value.

Example:

this.mapController.off("markerDragStart", () => {
 console.info("markerDragStart", `off-markerDragStart`);
});

[h2]on('markerDrag')

on(type: 'markerDrag', callback: Callback<Marker>): void

Listens for Marker drag events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.on(type: 'markerDrag').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'markerDrag': Marker drag event.
callback Callback<Marker> Yes Callback used to return Marker.

Example:

this.mapController.on("markerDrag", (marker) => {
 console.info("markerDrag", `on-markerDrag position = ${marker.getId()}`);
});

[h2]off('markerDrag')

off(type: 'markerDrag', callback: Callback<void>): void

Cancels listening for Marker drag events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.off(type: 'markerDrag').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'markerDrag': Marker drag event.
callback Callback<void> Yes Callback that returns no value.

Example:

this.mapController.off("markerDrag", () => {
 console.info("markerDrag", `off-markerDrag`);
});

[h2]on('markerDragEnd')

on(type: 'markerDragEnd', callback: Callback<Marker>): void

Listens for Marker drag end events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.on(type: 'markerDragEnd').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'markerDragEnd': Marker drag end event.
callback Callback<Marker> Yes Callback used to return Marker.

Example:

this.mapController.on("markerDragEnd", (marker) => {
 console.info("markerDragEnd", `on-markerDragEnd position = ${marker.getId()}`);
});

[h2]off('markerDragEnd')

off(type: 'markerDragEnd', callback: Callback<void>): void

Cancels listening for Marker drag end events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.off(type: 'markerDragEnd').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'markerDragEnd': Marker drag end event.
callback Callback<void> Yes Callback that returns no value.

Example:

this.mapController.off("markerDragEnd", () => {
 console.info("markerDragEnd", `off-markerDragEnd`);
});

[h2]on('circleClick')

on(type: 'circleClick', callback: Callback<MapCircle>): void

Listens for MapCircle tap events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.on(type: 'circleClick').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'circleClick': MapCircle tap event.
callback Callback<MapCircle> Yes Callback used to return MapCircle.

Example:

this.mapController.on("circleClick", (position) => {
 console.info("circleClick", `on-circleClick position = ${position.getCenter().longitude}`);
});

[h2]off('circleClick')

off(type: 'circleClick', callback: Callback<void>): void

Cancels listening for MapCircle tap events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.off(type: 'circleClick').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'circleClick': MapCircle tap event.
callback Callback<void> Yes Callback that returns no value.

Example:

this.mapController.off("circleClick", () => {
 console.info("circleClick", `off-circleClick`);
});

[h2]on('polylineClick')

on(type: 'polylineClick', callback: Callback<MapPolyline>): void

Listens for MapPolyline tap events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.on(type: 'polylineClick').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'polylineClick': MapPolyline tap event.
callback Callback<MapPolyline> Yes Callback used to return MapPolyline.

Example:

this.mapController.on("polylineClick", (polyline) => {
  console.info("polylineClick", `on-polylineClick position = ${polyline.getId()}`);
});

[h2]off('polylineClick')

off(type: 'polylineClick', callback: Callback<void>): void

Cancels listening for MapPolyline tap events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.off(type: 'polylineClick').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'polylineClick': MapPolyline tap event.
callback Callback<void> Yes Callback that returns no value.

Example:

this.mapController.off("polylineClick", () => {
  console.info("polylineClick", "off-polylineClick");
});

[h2]on('polygonClick')

on(type: 'polygonClick', callback: Callback<MapPolygon>): void

Listens for MapPolygon tap events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.on(type: 'polygonClick').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'polygonClick': MapPolygon tap event.
callback Callback<MapPolygon> Yes Callback used to return MapPolygon.

Example:

this.mapController.on("polygonClick", (polygon) => {
  console.info("polygonClick", `on-polygonClick position = ${polygon.getId()}`);
});

[h2]off('polygonClick')

off(type: 'polygonClick', callback: Callback<void>): void

Cancels listening for MapPolygon tap events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.off(type: 'polygonClick').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'polygonClick': MapPolygon tap event.
callback Callback<void> Yes Callback that returns no value.

Example:

this.mapController.off("polygonClick", () => {
  console.info("polygonClick", "off-polygonClick");
});

[h2]on('infoWindowClick')

on(type: 'infoWindowClick', callback: Callback<Marker>): void

Listens for information window tap events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.on(type: 'infoWindowClick').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'infoWindowClick': information window tap event.
callback Callback<Marker> Yes Callback used to return Marker.

Example:

this.mapController.on("infoWindowClick", (infoWindow) => {
 console.info("infoWindowClick", `on-infoWindowClick infoWindow = ${infoWindow.getId()}`);
});

[h2]off('infoWindowClick')

off(type: 'infoWindowClick', callback: Callback<void>): void

Cancels listening for information window tap events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.off(type: 'infoWindowClick').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'infoWindowClick': information window tap event.
callback Callback<void> Yes Callback that returns no value.

Example:

this.mapController.off("infoWindowClick", () => {
 console.info("infoWindowClick", `off-infoWindowClick`);
});

[h2]on('infoWindowClose')

on(type: 'infoWindowClose', callback: Callback<Marker>): void

Listens for information window close events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.on(type: 'infoWindowClose').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'infoWindowClose': information window close event.
callback Callback<Marker> Yes Callback used to return Marker.

Example:

this.mapController.on("infoWindowClose", (infoWindowClose) => {
 console.info("infoWindowClose", `on-infoWindowClose infoWindowClose = ${infoWindowClose.getId()}`);
});

[h2]off('infoWindowClose')

off(type: 'infoWindowClose', callback: Callback<void>): void

Cancels listening for information window close events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.off(type: 'infoWindowClose').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'infoWindowClose': information window close event.
callback Callback<void> Yes Callback that returns no value.

Example:

this.mapController.off("infoWindowClose", () => {
 console.info("infoWindowClose", `off-infoWindowClose`);
});

[h2]on('pointAnnotationClick')

on(type: 'pointAnnotationClick', callback: Callback<PointAnnotation>): void

Listens for PointAnnotation tap events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.on(type: 'pointAnnotationClick').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'pointAnnotationClick': PointAnnotation tap event.
callback Callback<PointAnnotation> Yes Callback used to return PointAnnotation.

Example:

this.mapController.on("pointAnnotationClick", (pointAnnotation) => {
 console.info("pointAnnotationClick", `on-PointAnnotationClick pointAnnotation = ${pointAnnotation.getId()}`);
});

[h2]off('pointAnnotationClick')

off(type: 'pointAnnotationClick', callback: Callback<void>): void

Cancels listening for PointAnnotation tap events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.off(type: 'pointAnnotationClick').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'pointAnnotationClick': PointAnnotation tap event.
callback Callback<void> Yes Callback that returns no value.

Example:

this.mapController.off("pointAnnotationClick", () => {
 console.info("pointAnnotationClick", `off-PointAnnotationClick`);
});

[h2]on('bubbleClick')

on(type: 'bubbleClick', callback: Callback<Bubble>): void

Listens for Bubble tap events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.on(type: 'bubbleClick').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'bubbleClick': Bubble tap event.
callback Callback<Bubble> Yes Callback used to return Bubble.

Example:

this.mapController.on("bubbleClick", (bubble) => {
 console.info("bubbleClick", `on-BubbleClick bubble = ${bubble.getId()}`);
});

[h2]off('bubbleClick')

off(type: 'bubbleClick', callback: Callback<void>): void

Cancels listening for Bubble tap events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.off(type: 'bubbleClick').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'bubbleClick': Bubble tap event.
callback Callback<void> Yes Callback that returns no value.

Example:

this.mapController.off("bubbleClick", () => {
 console.info("bubbleClick", `off-BubbleClick`);
});

[h2]on('imageOverlayClick')

on(type: 'imageOverlayClick', callback: Callback<ImageOverlay>): void

Listens for ImageOverlay tap events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.on(type: 'imageOverlayClick').

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

Since: 5.0.0(12)

Parameters:

Name Type Mandatory Description
type string Yes 'imageOverlayClick': ImageOverlay tap event.
callback Callback<ImageOverlay> Yes Callback used to return ImageOverlay.

Example:

// Callback for listening for ImageOverlay tap events.
let imageOverlayCallback: Callback<map.ImageOverlay> = (imageOverlay:map.ImageOverlay) => {
  console.info("imageOverlay:" + imageOverlay?.getId());
};
this.mapController.on("imageOverlayClick", imageOverlayCallback)

[h2]off('imageOverlayClick')

off(type: 'imageOverlayClick', callback?: Callback<ImageOverlay>): void

Cancels listening for ImageOverlay tap events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.off(type: 'imageOverlayClick').

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

Since: 5.0.0(12)

Parameters:

Name Type Mandatory Description
type string Yes 'imageOverlayClick': ImageOverlay tap event.
callback Callback<ImageOverlay> No Callback used to return ImageOverlay. If no callback is specified, all listening callbacks are cleared.

Example:

let imageOverlayCallback: Callback<map.ImageOverlay> = (imageOverlay:map.ImageOverlay) => {
  console.info("imageOverlay:" + imageOverlay?.getId());
};
this.mapController.off("imageOverlayClick", imageOverlayCallback);

[h2]on('error')

on(type: 'error', callback: ErrorCallback): void

Listens for error events.

You are advised to use MapEventManager.on(type: 'error').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'error': error event.
callback ErrorCallback Yes Callback function used to listen for error events.

Example:

this.mapController.on("error", (error) => {
  console.error("error", `on-error: Code: ${error.code}, message: ${error.message}`);
});

[h2]off('error')

off(type: 'error', callback: Callback<void>): void

Cancels listening for error events. This API returns the result asynchronously through a callback.

You are advised to use MapEventManager.off(type: 'error').

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

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
type string Yes 'error': error event.
callback Callback<void> Yes Callback that returns no value.

Example:

this.mapController.off("error", () => {
  console.error("error", `off-error`);
});

[h2]setIndoorMapEnabled

setIndoorMapEnabled(enabled: boolean): void

Sets whether to enable the indoor map. The indoor map and floor selector control are only visible at zoom level 17 and higher.

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.1.1(19).

System capability: SystemCapability.Map.Core

Device behavior differences: For version 5.1.1(19) 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.1.1(19)

Parameters:

Name Type Mandatory Description
enabled boolean Yes

Indicates whether to enable the indoor map. Invalid values are not processed. The options are as follows:

- true: yes

- false: no

Error codes:

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

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

Example:

// Enable the indoor map.
this.mapController.setIndoorMapEnabled(true);

[h2]isIndoorMapEnabled

isIndoorMapEnabled(): boolean

Checks whether the indoor map is enabled.

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.1.1(19).

System capability: SystemCapability.Map.Core

Device behavior differences: For version 5.1.1(19) 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.1.1(19)

Returns:

Type Description
boolean

- true: yes

- false: no

Error codes:

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

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

Example:

let isIndoorMapEnabled = this.mapController.isIndoorMapEnabled();

[h2]switchIndoorMapFloor

switchIndoorMapFloor(buildingId: string, floorName: string): void

Switches to a specified indoor building floor.

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.1.1(19).

System capability: SystemCapability.Map.Core

Device behavior differences: For version 5.1.1(19) 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.1.1(19)

Parameters:

Name Type Mandatory Description
buildingId string Yes Building ID. The value is obtained from the callback function of the on('indoorMapEnter') method. Invalid values are not processed.
floorName string Yes Building floor name (example: 3F). Invalid values are not processed.

Error codes:

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

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

Example:

this.mapController?.switchIndoorMapFloor('822588304363886720', '3F');

[h2]setFloorControlsPosition

setFloorControlsPosition(point: mapCommon.MapPoint): void

Sets the position of the floor selector control. You need to call the setIndoorMapEnabled method to enable the indoor map function. The indoor map and floor selector control are only visible at zoom level 17 and higher.

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 6.0.0(20).

System capability: SystemCapability.Map.Core

Device behavior differences: 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: 6.0.0(20)

Parameters:

Name Type Mandatory Description
point mapCommon.MapPoint Yes Position of the floor selector control, in pixels. Invalid values are not processed.

Error codes:

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

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

Example:

this.mapController?.setFloorControlsPosition({
  positionX: 500,
  positionY: 500
});

[h2]isApproveNumberEnabled

isApproveNumberEnabled(): boolean

Checks whether the map approval number is displayed.

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 6.1.0(23).

System capability: SystemCapability.Map.Core

Since: 6.1.0(23)

Returns:

Type Description
boolean

- true: yes

- false: no

Example:

let isApproveNumberEnabled = this.mapController?.isApproveNumberEnabled();

[h2]setApproveNumberEnabled

setApproveNumberEnabled(enabled: boolean): void

Sets whether to display the map approval number.

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 6.1.0(23).

System capability: SystemCapability.Map.Core

Since: 6.1.0(23)

Parameters:

Name Type Mandatory Description
enabled boolean Yes

Indicates whether to display the map approval number. The map approval number can be displayed only when the routing location is in China. Invalid values are not processed.

- true: yes

- false: no

Example:

this.mapController?.setApproveNumberEnabled(true);

[h2]addSignalLine

addSignalLine(signalParams: mapCommon.MapSignalParams): Promise<MapSignalLine>

Adds a signal line to a map. This API uses a promise to return the 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 API version 26.0.0.

System capability: SystemCapability.Map.Core

Since: 26.0.0

Parameters:

Name Type Mandatory Description
signalParams mapCommon.MapSignalParams Yes Signal line management object.

Returns:

Type Description
Promise<MapSignalLine> Promise object used to return the signal line management object.

Error codes:

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

ID Error Message
1002600001 System internal error.
1002600017 The app lacks permission for the map signal prediction capability.
1002600018 signalId in the signal route already exists.
1002600019 The route length exceeds the maximum limit of 200 km.
1002600020 Invalid carrier.
1002600021 The route signal is unpredictable.

Example:

let mapSignalParams: mapCommon.MapSignalParams = {
  signalId: 'signalId1'
};
mapSignalParams.points =
  [{ longitude: 118.553695, latitude: 32.050789 },
    { longitude: 118.553738, latitude: 32.050884 },
    { longitude: 118.548506, latitude: 32.048543 },
    { longitude: 118.548413, latitude: 32.048374 },
    { longitude: 118.547185, latitude: 32.048252 },
    { longitude: 118.546939, latitude: 32.048296 }]
// Add a signal line.
let mapSignalLine1 = await mapController.addSignalLine(mapSignalParams);

[h2]removeSignalLineCache

removeSignalLineCache(signalLineId?: string): void

Removes the cached signal line data of the map.

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

Atomic service API: This API can be used in atomic services since API version 26.0.0.

System capability: SystemCapability.Map.Core

Since: 26.0.0

Parameters:

Name Type Mandatory Description
signalLineId string No

Signal line ID.

If this parameter is null or undefined, all cached signal line data of the maps is cleared.

Example:

// Remove the cached data of the signal line with ID signalId1.
this.mapController?.removeSignalLineCache('signalId1');