目录

Interface (Marker)

Modules to Import

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

Marker

Marker. This API inherits from BaseOverlay. An instance of this type will be returned when the addMarker method in the map.MapComponentController class is called.

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:

let markerOptions: mapCommon.MarkerOptions = {
  position: {
    latitude: 39.9,
    longitude: 116.4
  }
};
let marker: map.Marker = await this.mapController.addMarker(markerOptions);

[h2]getTitle

getTitle(): string

Obtains the title of an information window.

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
string Title of an information window.

Example:

let title: string = marker.getTitle();

[h2]getSnippet

getSnippet(): string

Obtains the subtitle of an information window.

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
string Subtitle of an information window.

Example:

let snippet: string = marker.getSnippet();

[h2]getAlpha

getAlpha(): number

Obtains the opacity of a Marker.

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 Opacity of a Marker. The value ranges from 0 to 1.

Example:

let alpha: number = marker.getAlpha();

[h2]getPosition

getPosition(): mapCommon.LatLng

Obtains the position of a Marker.

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.LatLng Position of a Marker.

Example:

let position: mapCommon.LatLng = marker.getPosition();

[h2]getRotation

getRotation(): number

Obtains the rotation angle of a Marker.

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 Rotation angle of a Marker, in degrees.

Example:

let rotation: number = marker.getRotation();

[h2]isClickable

isClickable(): boolean

Checks whether a Marker is tappable.

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 Marker is tappable.

- true: yes

- false: no

Example:

let isClickable: boolean = marker.isClickable();

[h2]isDraggable

isDraggable(): boolean

Checks whether users can long press a Marker to drag 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 4.1.0(11).

System capability: SystemCapability.Map.Core

Since: 4.1.0(11)

Returns:

Type Description
boolean

Indicates whether users can long press a Marker to drag it.

- true: yes

- false: no

Example:

let isDraggable: boolean = marker.isDraggable();

[h2]isFlat

isFlat(): boolean

Checks whether a Marker is flatly attached to 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 version 4.1.0(11).

System capability: SystemCapability.Map.Core

Since: 4.1.0(11)

Returns:

Type Description
boolean

Indicates whether a Marker is flatly attached to the map.

- true: The Marker is flatly attached to the map.

- false: The Marker directly faces the camera.

Example:

let isFlat: boolean = marker.isFlat();

[h2]setAlpha

setAlpha(alpha: number): void

Sets the opacity of a Marker.

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
alpha number Yes

Opacity of a Marker. The value ranges from 0 to 1. Invalid values are not processed.

0: completely transparent

1: completely opaque

Example:

marker.setAlpha(0.5);

[h2]setClickable

setClickable(clickable: boolean): void

Sets whether a Marker is tappable.

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
clickable boolean Yes

Indicates whether a Marker is tappable. Abnormal values are not processed.

- true: yes

- false: no

Example:

marker.setClickable(true);

[h2]setDraggable

setDraggable(draggable: boolean): void

Sets whether users can long press a Marker to drag 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 4.1.0(11).

System capability: SystemCapability.Map.Core

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
draggable boolean Yes

Indicates whether users can long press a Marker to drag it. Abnormal values are not processed.

- true: yes

- false: no

Example:

marker.setDraggable(true);

[h2]setFlat

setFlat(flat: boolean): void

Sets whether to flatly attach a Marker to the map. If the Marker is flatly attached to the map, it will stay on the map when the camera rotates or tilts, and remain the same size when the camera zooms in or out. If the marker faces the camera, it will always be drawn facing the camera and rotates or tilts with 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
flat boolean Yes

Indicates whether to flatly attach a Marker to the map. Invalid values are not processed.

- true: Flatly attach the Marker to the map.

- false: The Marker directly faces the camera.

Example:

marker.setFlat(true);

[h2]setIcon

setIcon(icon: string | image.PixelMap | Resource): Promise<void>

Sets the icon of a Marker. 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 version 4.1.0(11).

System capability: SystemCapability.Map.Core

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
icon string | image.PixelMap | Resource Yes

Marker icon. Invalid values are not processed.

- Images in JPG, JPEG, PNG, GIF (only the first frame will be displayed), WEBP, and SVG formats are supported.

- This input parameter of the string type supports the following formats:

- Relative resource path: The icon is stored in resources/rawfile. Set icon to the relative path of the icon file in the rawfile folder.

- toDataURL format: For example, set icon to image/png;base64,<Base64-encoded byte value of the icon file>.

Note:

Since version 5.0.0(12), icon supports the Resource and image.PixelMap types.

Returns:

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

Example:

// The icon must be stored in the resources/rawfile directory.
await marker.setIcon('icon/test.png');

[h2]setMarkerAnchor

setMarkerAnchor(anchorU: number, anchorV: number): void

Sets the anchor position of a Marker. The anchor is used to anchor a Marker icon to the map. The coordinates (0, 0), (1, 0), (0, 1), and (1, 1) respectively indicate the top-left, top-right, bottom-left, and bottom-right corners of the Marker icon. The following figure shows a Marker's anchor X whose coordinates are (0.5, 0.3).

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
anchorU number Yes Horizontal coordinate of an anchor, expressed in a proportion of the image width. The value ranges from 0 to 1. Invalid values are not processed.
anchorV number Yes Vertical coordinate of an anchor, expressed in a proportion of the image height. The value ranges from 0 to 1. Invalid values are not processed.

Example:

marker.setMarkerAnchor(1.0, 1.0);

[h2]setPosition

setPosition(latLng: mapCommon.LatLng): void

Sets the position coordinates of a Marker.

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
latLng mapCommon.LatLng Yes Position coordinates of a Marker. Invalid values are not processed.

Example:

let position: mapCommon.LatLng = {
  latitude: 39.9,
  longitude: 116.4
};
marker.setPosition(position);

[h2]setRotation

setRotation(rotation: number): void

Sets the rotation angle of a Marker, that is, the angle in which the Marker rotates around the anchor clockwise. The rotation axis is perpendicular to the Marker. By default, the Marker is north aligned, and the rotation angle is 0 degrees.

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
rotation number Yes

Rotation angle of a Marker, in degrees.

0 degrees is due north, and angles increase clockwise. The value range is [0, 360). Values that fall outside the valid range will be adjusted to values within the range. For instance, the value 361 would be converted to 1, and the value -1 would be converted to 359. Values null and undefined are not processed.

Example:

marker.setRotation(30);

[h2]setTitle

setTitle(title: string): void

Sets the title of an information window.

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
title string Yes Title of an information window. The maximum width of an information window is 136 vp. If a title exceeds the display limit, the overflowing part will be replaced with an ellipsis (...). Invalid values are not processed.

Example:

marker.setTitle("title");

[h2]setSnippet

setSnippet(snippet: string): void

Sets the subtitle of an information window.

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
snippet string Yes Subtitle of an information window. The maximum width of an information window is 136 vp. If a title exceeds the display limit, the overflowing part will be replaced with an ellipsis (...). Invalid values are not processed.

Example:

marker.setSnippet("su");

[h2]setInfoWindowAnchor

setInfoWindowAnchor(anchorU: number, anchorV: number): void

Sets the anchor position of an information window.

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
anchorU number Yes Horizontal coordinate of an anchor. The value ranges from 0 to 1. Invalid values are not processed.
anchorV number Yes Vertical coordinate of an anchor. The value ranges from 0 to 1. Invalid values are not processed.

Example:

marker.setInfoWindowAnchor(0.5, 0.5);

[h2]setInfoWindowVisible

setInfoWindowVisible(visible: boolean): void

Sets whether an information window is visible.

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
visible boolean Yes

Indicates whether an information window is visible. Invalid values are not processed.

- true: yes

- false: no

Example:

marker.setInfoWindowVisible(true);

[h2]isInfoWindowVisible

isInfoWindowVisible(): boolean

Checks whether an information window is visible.

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 an information window is visible.

- true: yes

- false: no

Example:

let visible: boolean = marker.isInfoWindowVisible();

[h2]setAnimation

setAnimation(animation: Animation): void

Sets the animation of a Marker. FontSizeAnimation is not supported.

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
animation Animation Yes Animation. Invalid values are not processed.

Example:

let animation: map.AlphaAnimation = new map.AlphaAnimation(0.2, 1);
animation.setDuration(3000);
let callbackStart = () => {
  console.info("animationStart", `callback`);
};
let callbackEnd = () => {
  console.info("animationEnd", `callback`);
};
animation.on("animationStart", callbackStart);
animation.on("animationEnd", callbackEnd);
animation.setFillMode(map.AnimationFillMode.BACKWARDS);
animation.setRepeatMode(map.AnimationRepeatMode.RESTART);
animation.setRepeatCount(100);

marker.setAnimation(animation);

[h2]startAnimation

startAnimation(): void

Starts the animation of a Marker.

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:

let animation: map.AlphaAnimation = new map.AlphaAnimation(0.2, 1);
animation.setDuration(3000);
let callbackStart = () => {
  console.info("animationStart", `callback`);
};
let callbackEnd = () => {
  console.info("animationEnd", `callback`);
};
animation.on("animationStart", callbackStart);
animation.on("animationEnd", callbackEnd);
animation.setFillMode(map.AnimationFillMode.BACKWARDS);
animation.setRepeatMode(map.AnimationRepeatMode.RESTART);
animation.setRepeatCount(100);

marker.setAnimation(animation);
marker.startAnimation();

[h2]clearAnimation

clearAnimation(): void

Clears the animation of a Marker.

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:

marker.clearAnimation();

[h2]getAltitude

getAltitude(): number

Obtains the height relative to the ground.

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 relative to the ground, in meters.

Example:

let altitude: number = marker.getAltitude();

[h2]setAltitude

setAltitude(altitude: number): void

Sets the height relative to the ground.

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
altitude number Yes Height relative to the ground, in meters. Abnormal values are not processed.

Example:

marker.setAltitude(500);

[h2]setAnnotationVisible

setAnnotationVisible(visible: boolean): void

Sets whether to display text for a Marker.

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

Since: 5.1.1(19)

Parameters:

Name Type Mandatory Description
visible boolean Yes

Indicates whether to display text for a Marker. Invalid values are not processed.

- true: yes

- false: no

Example:

marker.setAnnotationVisible(true);

[h2]isAnnotationVisible

isAnnotationVisible(): boolean

Checks whether the Marker text is visible.

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

Since: 5.1.1(19)

Returns:

Type Description
boolean

Indicates whether the Marker text is visible.

- true: yes

- false: no

Example:

let isVisible = marker.isAnnotationVisible();

[h2]setPriority

setPriority(priority: number): void

Sets the collision priority of a Marker.

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
priority number Yes Collision priority of a Marker. A larger value indicates a lower priority. When two Markers collide, the Marker with a lower priority will be hidden. The value must be an integer between 0 and 65535. Out-of-range or invalid values will not be processed.

Example:

marker.setPriority(50);

[h2]getPriority

getPriority(): number

Obtains the collision priority of a Marker.

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
number Collision priority of a Marker. A larger value indicates a lower priority. When two Markers collide, the Marker with a lower priority will be hidden.

Example:

let priority: number = marker.getPriority();

[h2]setIconBuilder

setIconBuilder(iconBuilder: CustomBuilder): Promise<void>

Sets a custom component for generating a Marker icon. 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 version 6.0.0(20).

System capability: SystemCapability.Map.Core

Since: 6.0.0(20)

Parameters:

Name Type Mandatory Description
iconBuilder CustomBuilder Yes Custom component. 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
1002601005 Failed to generate the icon of the custom component.

Example:

@Builder
renderBuilder() {
  Stack({ alignContent: Alignment.Center }) {
    Text('Test Icon Builder')
  }
  .height(50)
  .width(200)
}
// Set the custom component.
try {
  await this.marker?.setIconBuilder(() => {
    this.renderBuilder();
  })
} catch (error) {
  let err = error as BusinessError;
  console.error('Marker icon builder test error code' + err.code + 'message:' + err.message);
}

[h2]setOffset

setOffset(x: number, y: number): void

Sets the offset of a Marker icon.

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.2(22).

System capability: SystemCapability.Map.Core

Since: 6.0.2(22)

Parameters:

Name Type Mandatory Description
x number Yes Offset along the X axis, in px. The origin is the center point of the icon. Values null, undefined, and NaN are not processed.
y number Yes Offset along the Y axis, in px. The origin is the center point of the icon. Values null, undefined, and NaN are not processed.

Example:

marker.setOffset(20, 20);

[h2]getOffsetX

getOffsetX(): number

Obtains the offset of a Marker icon along the X axis.

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.2(22).

System capability: SystemCapability.Map.Core

Since: 6.0.2(22)

Returns:

Type Description
number Offset of the Marker icon along the X axis, in px. The origin is the center point of the icon.

Example:

let X: number = marker.getOffsetX();

[h2]getOffsetY

getOffsetY(): number

Obtains the offset of a Marker icon along the Y axis.

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.2(22).

System capability: SystemCapability.Map.Core

Since: 6.0.2(22)

Returns:

Type Description
number Offset of the Marker icon along the Y axis, in px. The origin is the center point of the icon.

Example:

let Y: number = marker.getOffsetY();