目录

mapCommon (Map Attribute Model)

This module provides APIs for setting map component attributes.

Since: 4.1.0(11)

Modules to Import

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

MapOptions

Sets initialization attributes of a map component.

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

System capability: SystemCapability.Map.Core

Since: 4.1.0(11)

Name Type Read-Only Optional Description
mapType MapType No Yes

Map type. The default value is MapType.STANDARD. If an invalid value is passed, the default value will be used.

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

Position of the map camera.

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

Map display bounds. By default, there is no bound. If an invalid value is passed, the default value will be used.

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

Note:

The latitude of the southwest corner cannot be greater than that of the northeast corner.
minZoom number No Yes

Minimum map zoom level. The value ranges from 2 to 20. The default value is 2. If an invalid value is passed, the default value will be used.

If the specified minimum zoom level is less than 2, the value 2 will be used. If the specified minimum zoom level is greater than 20, the value 20 will be used.

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

Maximum map zoom level. The value ranges from 2 to 20. The default value is 20. If an invalid value is passed, the default value will be used.

If the specified maximum zoom level is less than 2, the value 2 will be used. If the specified maximum zoom level is greater than 20, the value 20 will be used.

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

Indicates whether to support rotate gestures. The default value is true. If an invalid value is passed, the default value will be used.

- true: yes

- false: no

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

Indicates whether to support swipe gestures. The default value is true. If an invalid value is passed, the default value will be used.

- true: yes

- false: no

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

Indicates whether to support zoom gestures. The default value is true. If an invalid value is passed, the default value will be used.

- true: yes

- false: no

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

Indicates whether to support tilt gestures. The default value is true. If an invalid value is passed, the default value will be used.

- true: yes

- false: no

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

Indicates whether to display the zoom controls. The default value is true. If an invalid value is passed, the default value will be used.

- true: yes

- false: no

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

Indicates whether to display the my-location icon. The default value is false. If an invalid value is passed, the default value will be used.

- true: yes

- false: no

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

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

- true: yes

- false: no

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

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

- true: yes

- false: no

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

Padding between the map and its edges. The default value is { left: 0 , top: 0 , right: 0 , bottom: 0 }.

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

Custom style ID. If the ID is invalid, the system style is used. For details, please refer to Displaying a Custom Map.

Since: 5.0.0(12)

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

Day/Night mode. The default value is DayNightMode.DAY (day mode).

Since: 5.0.0(12)

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

Indicates whether to always display the scale. This parameter takes effect only when the scale is enabled. The scale can be enabled by setting the scaleControlsEnabled attribute to true during map initialization or by calling the setScaleControlsEnabled method.

- true: yes

- false: no

The default value is false.

Since: 5.0.0(12)

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

Logo scale ratio. The value range is [0.8, 1]. The default value is 1. If the value is abnormal, the default value is used.

Since: 5.0.3(15)

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

Indicates whether to enable the 3D globe view. The default value is false.

- true: yes

- false: no

Since: 5.0.3(15)

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

Indicates whether to enable the indoor map. The default value is false.

- true: yes

- false: no

Since: 5.1.1(19)

Atomic service API: This API can be used in atomic services since version 5.1.1(19).
scaleUnit ScaleUnit No Yes

Map scale unit. The default value is ScaleUnit.METRIC_UNIT (metric unit).

Since: 5.1.1(19)

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

Map language. For details about the language values, please refer to Languages Supported by the Map Component. The current system language is used by default.

Since: 6.0.0(20)

Atomic service API: This API can be used in atomic services since version 6.0.0(20).
approveNumberEnabled boolean No Yes

Indicates whether to display the map approval number and logo. The map approval number and logo can be displayed only when the routing location is in China.

- true: yes

- false: no

Since: 6.1.0(23)

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

Example:

// Map initialization parameters.
let mapOptions: mapCommon.MapOptions = {
  mapType: mapCommon.MapType.STANDARD,
  position: {
    target: {
      latitude: 39.9,
      longitude: 116.4
    },
    zoom: 10
  },
  bounds: {
    northeast: {
      latitude: 41.5,
      longitude: 125.5
    },
    southwest: {
      latitude: 37.5,
      longitude: 108.5
    }
  },
  maxZoom: 20,
  minZoom: 2,
  rotateGesturesEnabled: true,
  scrollGesturesEnabled: true,
  zoomGesturesEnabled: true,
  zoomControlsEnabled: true,
  myLocationControlsEnabled: false,
  dayNightMode: mapCommon.DayNightMode.NIGHT,
  scaleControlsEnabled: true,
  alwaysShowScaleEnabled: true,
  scaleUnit: mapCommon.ScaleUnit.METRIC_UNIT,
  language: 'zh-Hans',
  approveNumberEnabled: true
};

LatLng

Longitude-latitude object.

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)

Name Type Read-Only Optional Description
latitude number No No Latitude, in degrees. The value range is [-90, 90].
longitude number No No Longitude, in degrees. The value range is [-180, 180).

Example:

let position: mapCommon.LatLng = {
  latitude: 39.9,
  longitude: 116.4
};

CameraPosition

Defines the camera status, including the position, tilt angle, and 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 4.1.0(11).

System capability: SystemCapability.Map.Core

Since: 4.1.0(11)

Name Type Read-Only Optional Description
target LatLng No No Longitude and latitude of the map center.
zoom number No No Zoom level near the center of the screen. The value ranges from 2 to 20. The default value is 2.
tilt number No Yes Angle between the camera and the line perpendicular to the Earth's surface. The value ranges from 0 to 75. The default value is 0.
bearing number No Yes

Map rotation angle, in degrees.

0 degrees is due north, and angles increase clockwise. The value range is [0, 360). The default value is 0. 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.

Example:

let cameraPosition: mapCommon.CameraPosition = {
  target: {
    latitude: 39.9,
    longitude: 116.4
  },
  zoom: 10,
  tilt: 45,
  bearing: 90
};

LatLngBounds

Defines a rectangular region using longitudes and latitudes.

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)

Name Type Read-Only Optional Description
northeast LatLng No No Longitude and latitude of the northeast corner.
southwest LatLng No No Longitude and latitude of the southwest corner.

Example:

let bounds: mapCommon.LatLngBounds = {
  northeast: {
    latitude: 41.5,
    longitude: 125.5
  },
  southwest: {
    latitude: 37.5,
    longitude: 108.5
  }
};

PatternItem

Defines the stroke pattern of a MapPolyline or the outline of a MapPolygon or MapCircle.

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)

Name Type Read-Only Optional Description
type PatternItemType No No Stroke pattern.
length number No Yes Stroke length when the stroke pattern is DASH or GAP, in pixels. The value must be greater than or equal to 0. The default value is 1.

Example:

let patternItem: mapCommon.PatternItem = {
  type: mapCommon.PatternItemType.DASH,
  length: 10
};

MyLocationStyle

Defines the custom style of the my-location icon.

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

System capability: SystemCapability.Map.Core

Since: 4.1.0(11)

Name Type Read-Only Optional Description
anchorU number No Yes

Horizontal offset of the anchor. The value ranges from 0 to 1. The default value is 0.5.

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

Vertical offset of the anchor. The value ranges from 0 to 1. The default value is 0.5.

Atomic service API: This API can be used in atomic services since version 4.1.0(11).
icon string | image.PixelMap | Resource No Yes

My-location icon.

- 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 image.PixelMap and Resource types.

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

Fill color of the my-location icon. The default value is 0x8F7570FF (purple). The color value is in ARGB format.

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

Display style of the my-location icon. The default value is MyLocationDisplayType.DEFAULT.

Since: 5.0.0(12)

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

Example:

let style: mapCommon.MyLocationStyle = {
  anchorU: 0.5,
  anchorV: 1,
  radiusFillColor: 0xffff0000,
  // The icon must be stored in the resources/rawfile directory.
  icon: 'test.png',
  displayType: mapCommon.MyLocationDisplayType.FOLLOW
};

Poi

Defines a POI object on 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)

Name Type Read-Only Optional Description
id string No No ID of a POI.
name string No No Name of a POI.
position LatLng No No Longitude and latitude of a POI.

Example:

let poi: mapCommon.Poi = {
  id: "1001",
  name: "Chengdong Barbecue Store",
  position: {
    latitude: 39.6,
    longitude: 116.4
  }
};

BaseOverlayOptions

Defines the basic attributes of an overlay. MarkerOptions, MapCircleOptions, MapPolygonOptions, MapPolylineOptions, MapArcParams, ImageOverlayParams, and BasePriorityOverlayParams inherit from this base class.

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)

Name Type Read-Only Optional Description
visible boolean No Yes

Indicates whether an overlay is visible. The default value is true. If an invalid value is passed, the default value will be used.

- true: yes

- false: no
zIndex number No Yes

Overlay order of an overlay. An overlay with a larger z-index covers that with a smaller z-index. Overlays with the same z-index cover each other by the order in which they are added. If the z-index is not set during overlay initialization, the default value 0 will be used. If an invalid value is passed, the default value will be used.

Note:

The value of zIndex of BasePriorityOverlayParams is rounded down to an integer.

MarkerOptions

Describes the attributes of a Marker. This API inherits from BaseOverlayOptions.

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

System capability: SystemCapability.Map.Core

Since: 4.1.0(11)

Name Type Read-Only Optional Description
position LatLng No No

Position coordinates of a Marker.

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

Rotation angle of a Marker, in degrees.

0 degrees is due north, and angles increase clockwise. The value range is [0, 360). The default value is 0. 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.

Atomic service API: This API can be used in atomic services since version 4.1.0(11).
icon string | image.PixelMap | Resource No Yes

Icon. If this parameter is not passed, the default icon is displayed.

- 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>.

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

Note:

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

Transparency. The value ranges from 0 to 1, where 0 indicates completely transparent, and 1 indicates completely opaque. The default value is 1. If an invalid value is passed, the default value will be used.

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

Horizontal coordinate of the anchor of a Marker, expressed in a proportion of the Marker image width. The recommended value ranges from 0 to 1. The default value is 0.5. If an invalid value is passed, the default value will be used.

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

Vertical coordinate of the anchor of a Marker, expressed in a proportion of the Marker image height. The recommended value ranges from 0 to 1. The default value is 1. If an invalid value is passed, the default value will be used.

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

Indicates whether a Marker is tappable. The default value is false. If an invalid value is passed, the default value will be used.

- true: yes

- false: no

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

Indicates whether a Marker can be dragged by long pressing. The default value is false. If an invalid value is passed, the default value will be used.

- true: yes

- false: no

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

Indicates whether a Marker is flat on the map. The default value is false. If an invalid value is passed, the default value will be used.

- true: yes

- false: no

Note:

When the 3D globe is enabled and the zoom level is between 2 and 5, the Marker cannot be flat on the map.

Atomic service API: This API can be used in atomic services since version 4.1.0(11).
title string No 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 portion will be replaced with an ellipsis (...).

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

Subtitle of an information window. The maximum width of an information window is 136 vp. If a subtitle exceeds the display limit, the overflowing portion will be replaced with an ellipsis (...).

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

Position of the anchor of an information window in the horizontal direction. The value ranges from 0 to 1. The default value is 0.5. If an invalid value is passed, the default value will be used.

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

Position of the anchor of an information window in the vertical direction. The value ranges from 0 to 1. The default value is 0. If an invalid value is passed, the default value will be used.

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

Height relative to the ground, in meters. The default value is 0. If an invalid value is passed, the default value will be used.

Since: 5.0.0(12)

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

Rule for handling conflicts between a Marker and a map POI. The default value is CollisionRule.NONE. If an invalid value is passed, the default value will be used.

Note:

Since version 5.0.3(15), collisionRule supports CollisionRule.NONE and CollisionRule.ALL. Since 6.1.0(23), collisionRule adds support for CollisionRule.NAME and CollisionRule.ICON_CASCADE.

Since: 5.0.3(15)

Atomic service API: This API can be used in atomic services since version 5.0.3(15).
annotations Text[] No Yes

Annotations of a Marker. The maximum length is 3 and the minimum length is 1.

Since: 5.0.3(15)

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

Indicates whether to display the Marker icon. The default value is true. Invalid values are processed based on the displayed icon.

- true: yes

- false: no

Since: 5.0.3(15)

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

Annotation position relative to the icon. The default value is TextPosition.DEFAULT.

Since: 5.0.3(15)

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

Custom component used to generate a Marker icon. The priority of the custom component is higher than that of an icon.

Since: 6.0.0(20)

Atomic service API: This API can be used in atomic services since version 6.0.0(20).
offsetX number No Yes

Offset of the Marker icon along the X axis, in pixels. The positive direction of the X axis is to the right, and the origin is at the center point of the icon. If only offsetX is passed, offsetY is set to 0 by default. Invalid values are not processed. If offsetX is set, the offset is determined by offsetX. If offsetX is not set, the offset is determined by anchorU.

Since: 6.0.2(22)

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

Offset of the Marker icon along the Y axis, in pixels. The positive direction of the Y axis is downward, and the origin is at the center point of the icon. If only offsetY is passed, offsetX is set to 0 by default. Invalid values are not processed. If offsetY is set, the offset is determined by offsetY. If offsetY is not set, the offset is determined by anchorV.

Since: 6.0.2(22)

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

Indicates whether a Marker is displayed forcibly after collision. The default value is false. If an invalid value is passed, the default value will be used.

- true: yes

- false: no

Since: 6.1.0(23)

Atomic service API: This API can be used in atomic services since version 6.1.0(23).
priority number No Yes

Collision priority. 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 within the range [0, 65535].

Values below the minimum or above the maximum will be clamped to 0 and 65535, respectively.

If this parameter is not set or is set to null or undefined, the default value 2147483647 is used, indicating the lowest collision priority.

Since: 6.1.0(23)

Atomic service API: This API can be used in atomic services since version 6.1.0(23).
minZoom number No Yes

Minimum map zoom level. The default value is 2. The minimum zoom level cannot be greater than the maximum zoom level and cannot be less than 2. If an invalid value is passed, the default value will be used. If this parameter is set to a value less than 2, the value 2 will be used instead.

Since: 6.1.0(23)

Atomic service API: This API can be used in atomic services since version 6.1.0(23).
maxZoom number No Yes

Maximum map zoom level. The default value is 20. The maximum zoom level cannot be greater than 20 and cannot be less than the minimum zoom level. If an invalid value is passed, the default value will be used. If this parameter is set to a value greater than 20, the value 20 will be used instead.

Since: 6.1.0(23)

Atomic service API: This API can be used in atomic services since version 6.1.0(23).
annotationBackgroundColor number No Yes

Annotation background color, in ARGB format. By default, there is no background color. If an invalid value is passed, the default value will be used.

Since: 6.1.1(24)

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

Example:

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 must be stored in the resources/rawfile directory.
  icon: 'test.png',
  altitude: 100,
  collisionRule: mapCommon.CollisionRule.ALL,
  offsetX: 20,
  offsetY: 20,
  forceVisible: true,
  priority: 5,
  minZoom: 5,
  maxZoom: 19,
  annotationBackgroundColor: 0XFF00FFFF
};

MapCircleOptions

Describes the attributes of a MapCircle. This API inherits from BaseOverlayOptions.

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)

Name Type Read-Only Optional Description
center LatLng No No Center of a MapCircle, which cannot be empty or null. A MapCircle can be drawn only when the latitude of its center is within the range from -85.051119 to 85.051119. If the latitude of the circle center is -85.051119 or 85.051119, a MapCircle with a radius of 1 meter can be drawn exactly. Invalid values are not processed.
radius number No No Radius of a MapCircle, in meters. The value must be greater than or equal to 0. The default value is 0. If an invalid value is passed, the default value will be used.
clickable boolean No Yes

Indicates whether a MapCircle is tappable. The default value is false. If an invalid value is passed, the default value will be used.

- true: yes

- false: no
fillColor number No Yes Fill color of a MapCircle, in ARGB format. The default value is 0x00000000 (transparent). If an invalid value is passed, the default value will be used.
strokeColor number No Yes Stroke color of a MapCircle's outline, in ARGB format. The default value is 0xff000000 (black). If an invalid value is passed, the default value will be used.
patterns Array<PatternItem> No Yes Pattern of a MapCircle's outline, which is an empty array by default. If an invalid value is passed, the default value will be used.
strokeWidth number No Yes Stroke width of a MapCircle's outline, in pixels. The value must be greater than or equal to 0. The default value is 10. If an invalid value is passed, the default value will be used.

Example:

let mapCircleOptions: mapCommon.MapCircleOptions = {
  center: {
    latitude: 39.9,
    longitude: 116.4
  },
  radius: 5000,
  clickable: true,
  fillColor: 0XFF00FFFF,
  strokeColor: 0xFFFF0000,
  strokeWidth: 10,
  visible: true,
  zIndex: 15
};

MapPolygonOptions

Describes the attributes of a MapPolygon. This API inherits from BaseOverlayOptions.

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)

Name Type Read-Only Optional Description
points Array<LatLng> No No Array of vertices of a MapPolygon. The value range of the vertex latitude is [-85.2, 85.2]. Invalid values are not processed.
holes Array<Array<LatLng>> No Yes

Array of holes in a MapPolygon, which is an empty array by default. If an invalid value is passed, the default value will be used.

Note:

When coordinates of a hole coincide with the outline of the MapPolygon, it can lead to rendering anomalies, such as extra hollow regions being displayed.
clickable boolean No Yes

Indicates whether a MapPolygon is tappable. The default value is false. If an invalid value is passed, the default value will be used.

- true: yes

- false: no
fillColor number No Yes Fill color of a MapPolygon, in ARGB format. The default value is 0x00000000 (transparent). If an invalid value is passed, the default value will be used.
geodesic boolean No Yes

Indicates whether segments of a MapPolygon are geodesics. The default value is false. If an invalid value is passed, the default value will be used.

true: yes

false: no
strokeColor number No Yes Stroke color of a MapPolygon's outline, in ARGB format. The default value is 0xff000000 (black). If an invalid value is passed, the default value will be used.
jointType JointType No Yes Stroke joint type of a MapPolygon. The default value is JointType.DEFAULT. If an invalid value is passed, the default value will be used.
patterns Array<PatternItem> No Yes Pattern of a MapPolygon's outline, which is an empty array by default. If an invalid value is passed, the default value will be used.
strokeWidth number No Yes Stroke width of a MapPolygon's outline, in pixels. The value must be greater than or equal to 0. The default value is 10. If an invalid value is passed, the default value will be used.

Example:

let polygonOptions: mapCommon.MapPolygonOptions = {
  points: [
    { latitude: 41.893478, longitude: 116.4 },
    { latitude: 41.893478, longitude: 121.4 },
    { latitude: 45.893478, longitude: 121.4 },
    { latitude: 45.893478, longitude: 116.4 }
  ],
  holes: [],
  clickable: true,
  fillColor: 0xff00DE00,
  geodesic: false,
  strokeColor: 0xff000000,
  jointType: mapCommon.JointType.DEFAULT,
  patterns: [],
  strokeWidth: 10,
  visible: true,
  zIndex: 0
};

MapPolylineOptions

Describes the attributes of a MapPolyline. This API inherits from BaseOverlayOptions.

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

System capability: SystemCapability.Map.Core

Since: 4.1.0(11)

Name Type Read-Only Optional Description
points Array<LatLng> No No

Set of vertices of a MapPolyline. Invalid values are not processed.

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

Indicates whether a MapPolyline is tappable. The default value is false. If an invalid value is passed, the default value will be used.

- true: yes

- false: no

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

Color of a MapPolyline, in ARGB format. The default value is 0xff000000 (black). If an invalid value is passed, the default value will be used.

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

Colors for different segments of a MapPolyline, which is an empty array (indicating black) by default. The color value is in ARGB format. If an invalid value is passed, the default value will be used.

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

Style of the start vertex of a MapPolyline. The default value is CapStyle.BUTT. If an invalid value is passed, the default value will be used.

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

Style of the end vertex of a MapPolyline. The default value is CapStyle.BUTT. If an invalid value is passed, the default value will be used.

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

Indicates whether segments of a MapPolyline are geodesics. The default value is false. If an invalid value is passed, the default value will be used.

true: yes

false: no

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

Joint type of a MapPolyline. The default value is JointType.DEFAULT. If an invalid value is passed, the default value will be used.

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

Pattern of a MapPolyline, which is an empty array by default. If an invalid value is passed, the default value will be used.

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

Width of a MapPolyline, in pixels. The value ranges from 0 to 512. The default value is 10. If a value greater than 512 is passed, the value 512 will be used.

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

Indicates whether a MapPolyline is gradient. The default value is false. If an invalid value is passed, the default value will be used.

- true: yes

- false: no

Atomic service API: This API can be used in atomic services since version 4.1.0(11).
customTexture ResourceStr | image.PixelMap No Yes

Texture of a MapPolyline. You are advised to use an image with a transparent background as the texture.

Since: 5.0.0(12)

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

Note:

Since version 6.1.0(23), the function of adjusting texture spacing is supported. This can be achieved by using texture images with wider transparent backgrounds.
isTextureMappingUsed boolean No Yes

Indicates whether to use texture mapping to process textures. The default value is false.

- true: yes

- false: no

Since: 5.0.3(15)

Atomic service API: This API can be used in atomic services since version 5.0.3(15).
customTextures Array<ResourceStr | image.PixelMap> No Yes

Multiple texture images.

Since: 5.0.3(15)

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

Note:

If both customTexture and customTextures are passed, customTexture is used preferentially.
customTextureIndexes Array<number> No Yes

Texture index corresponding to each coordinate.

Since: 5.0.3(15)

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

Note:

If customTextures is passed, customTextureIndexes must be passed. In addition, the length of the customTextureIndexes array must be the same as that of the points array, and the value of each element in the customTextureIndexes array must range from 0 to the length of the customTextures array minus 1. If the conditions are not met, error code 401 will be returned.

Example:

let polylineOption: mapCommon.MapPolylineOptions = {
  points: [
    { latitude: 39.693478, longitude: 116.334595 },
    { latitude: 39.593478, longitude: 116.434595 },
    { latitude: 39.593478, longitude: 116.134595}
  ],
  clickable: true,
  color: 0xff000000,
  startCap: mapCommon.CapStyle.BUTT,
  endCap: mapCommon.CapStyle.BUTT,
  geodesic: false,
  jointType: mapCommon.JointType.DEFAULT,
  patterns: [{ type: 0, length: 100 }, { type: 0, length: 100 }, { type: 0, length: 100 }],
  visible: true,
  width: 20,
  zIndex: 0,
  gradient: false,
  // The icon must be stored in the resources/rawfile directory.
  customTexture: "icon/naviline_arrow.png",
  isTextureMappingUsed: false
};

BasePriorityOverlayParams

Describes the basic information about an overlay such as a Bubble or PointAnnotation. This API inherits from BaseOverlayOptions.

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)

Name Type Read-Only Optional Description
anchorU number No Yes Position of the anchor of a POI in the horizontal direction. The value ranges from 0 to 1. The default value is 0.5. If an invalid value is passed, the default value will be used.
anchorV number No Yes Position of the anchor of a POI in the vertical direction. The value ranges from 0 to 1. The default value is 1. If an invalid value is passed, the default value will be used.
forceVisible boolean No Yes

Indicates whether a POI is visible after collision. The default value is false. If an invalid value is passed, the default value will be used.

- true: yes

- false: no
priority number No Yes Collision priority. A larger value indicates a lower priority. The value must be greater than 0. The default value is Number.MAX_VALUE. If an invalid value is passed, the default value will be used.
minZoom number No Yes

Minimum map zoom level. The value ranges from 2 to 20. The default value is 2. If an invalid value is passed, the default value will be used. If this parameter is set to a value less than 2, the value 2 will be used instead.

Constraint: The minimum zoom level cannot be greater than the maximum zoom level and cannot be less than 2.
maxZoom number No Yes

Maximum map zoom level. The value ranges from 2 to 20. The default value is 20. If an invalid value is passed, the default value will be used. If this parameter is set to a value greater than 20, the value 20 will be used instead.

Constraints: The maximum zoom level cannot be greater than 20 and cannot be less than the minimum zoom level.

PointAnnotationParams

Describes the attributes of a PointAnnotation. This API inherits from BasePriorityOverlayParams.

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

System capability: SystemCapability.Map.Core

Since: 4.1.0(11)

Name Type Read-Only Optional Description
position LatLng No No

Anchor of a PointAnnotation icon. Invalid values are not processed.

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

Indicates whether to support deduplication when the PointAnnotation name is the same as a map POI name. The default value is false. If an invalid value is passed, the default value will be used.

- true: yes

- false: no

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

Note:

If the collision rule is set to CollisionRule.NONE, this parameter cannot be set.
collisionRule CollisionRule No Yes

Collision rule for a PointAnnotation. The default value is CollisionRule.NAME. If an invalid value is passed, the default value will be used.

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

Note:

If this parameter is set to CollisionRule.ALL, the overlay collision priority attribute priority must be set.
titles Array<Text> No No

Titles of a PointAnnotation. The minimum length of the array is 1 and the maximum length is 3.

Atomic service API: This API can be used in atomic services since version 4.1.0(11).
icon string | image.PixelMap | Resource No Yes

Icon of a PointAnnotation. If this parameter is not passed, the default icon is used.

- 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:

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

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

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

Note:

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

Indicates whether to display the icon for a PointAnnotation. The default value is true.

- true: yes

- false: no

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

PointAnnotation text position.

The default value is TextPosition.DEFAULT.

Since: 5.0.0(12)

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

Example:

let pointAnnotationOptions: mapCommon.PointAnnotationParams = {
  position: {
    latitude: 39.918,
    longitude: 116.397
  },
  repeatable: true,
  collisionRule: mapCommon.CollisionRule.NAME,
  titles: [{
    content: "Title1",
    color: 0xFF000000,
    fontSize: 15,
    strokeColor: 0xFFFFFFFF,
    strokeWidth: 2,
    fontStyle: mapCommon.FontStyle.ITALIC
  }],
  // The icon must be stored in the resources/rawfile directory.
  icon: "test.png",
  showIcon: true,
  anchorU: 0.5,
  anchorV: 1,
  forceVisible: false,
  priority: 3,
  minZoom: 2,
  maxZoom: 20,
  visible: true,
  zIndex: 10
};

BubbleParams

Describes the attributes of a Bubble. This API inherits from BasePriorityOverlayParams.

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)

Name Type Read-Only Optional Description
positions Array<Array<LatLng>> No No Position of a Bubble, which is calculated by the system based on multiple position segments. Invalid values are not processed.
icons Array<string | image.PixelMap | Resource> No No

Bubble icon. Invalid values are not processed.

- You must set the icons for four directions. The icons must have the same height and width.

- 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 image.PixelMap and Resource types.

Example:

let bubbleOptions: mapCommon.BubbleParams = {
  positions: [[{ latitude: 39.9, longitude: 116.4 }]],
  // Retrieve images in left, top, right, bottom order. The images must be stored in the resources/rawfile directory.
  icons: [
    'icon1.png',
    'icon2.png',
    'icon3.png',
    'icon4.png'
  ],
  forceVisible: true,
  priority: 3,
  minZoom: 2,
  maxZoom: 20,
  visible: true,
  zIndex: 1
};

Text

Describes the text attributes of a PointAnnotation title.

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)

Name Type Read-Only Optional Description
content string No No Title content. The maximum width is 136 vp. If the title exceeds the display limit, the overflowing portion will be replaced with an ellipsis (...).
color number No Yes Font color of the title, in ARGB format. The default value is 0xFF000000 (black).
fontSize number No Yes Font size of the title, in pixels. The default value is 15. The value range is [0, 100]. Values outside this range will be clamped to the nearest boundary.
strokeColor number No Yes Stroke color of the title, in ARGB format. The default value is 0xFFFFFFFF (white).
strokeWidth number No Yes Stroke width of the title, in pixels. The default value is 2. The value range is [0, 10]. Values outside this range will be clamped to the nearest boundary.
fontStyle FontStyle No Yes Font style of the title. The default value is FontStyle.REGULAR. If an invalid value is passed, the default value will be used.

Example:

let text: mapCommon.Text = {
  content: "Nanjing Confucius Temple",
  color: 0xFF000000,
  fontSize: 15,
  strokeColor: 0xFFFFFFFF,
  strokeWidth: 2,
  fontStyle: mapCommon.FontStyle.ITALIC
};

Padding

Sets the padding between the map and its edges.

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)

Name Type Read-Only Optional Description
left number No Yes Padding added to the left side of a map, in pixels. The default value is 0. If an invalid value is passed, the default value will be used.
top number No Yes Padding added at the top of a map, in pixels. The default value is 0. If an invalid value is passed, the default value will be used.
right number No Yes Padding added to the right side of a map, in pixels. The default value is 0. If an invalid value is passed, the default value will be used.
bottom number No Yes Padding added at the bottom of a map, in pixels. The default value is 0. If an invalid value is passed, the default value will be used.

Example:

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

VisibleRegion

Defines a VisibleRegion. A VisibleRegion contains four points that define a tetragon visible in the camera of a map. The tetragon may be a trapezoid instead of a rectangle because the camera may tilt. If the camera is directly over the center of the visible region, the shape is rectangular. If the camera tilts, the shape will be a trapezoid whose smallest side is closest to the point of view.

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)

Name Type Read-Only Optional Description
farLeft LatLng No No Upper left corner of the camera.
farRight LatLng No No Upper right corner of the camera.
bounds LatLngBounds No No Smallest bounding box that includes the visible region.
nearLeft LatLng No No Lower left corner of the camera.
nearRight LatLng No No Lower right corner of the camera.

Example:

// For details about the source of this.mapController in the example, please refer to the sample code for displaying a map in the development guide.
let projection: map.Projection = this.mapController?.getProjection();
let visibleRegion: mapCommon.VisibleRegion = projection.getVisibleRegion();

MapPoint

Coordinate point on the screen. The upper left vertex of the screen is used as the (0, 0) point. A positive value of positionX indicates that the visible region moves rightwards, while a negative value indicates that the visible region moves leftwards. A positive value of positionY indicates that the visible region moves downwards, while a negative value indicates that the visible region moves upwards.

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)

Name Type Read-Only Optional Description
positionX number No No X coordinate of a point, in pixels.
positionY number No No Y coordinate of a point, in pixels.

Example:

let point: mapCommon.MapPoint = {
  positionX: 100,
  positionY: 100
};

CustomMapStyleOptions

Custom style parameters.

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)

Name Type Read-Only Optional Description
styleId string No Yes

Custom style ID.

Note:

If both styleId and styleContent are passed, styleId is used. styleId can be created on the Petal Maps Studio platform.
styleContent string No Yes Offline style content. For details about the content format, please refer to Style Reference.

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"
};

ClusterItem

Describes a cluster item.

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)

Name Type Read-Only Optional Description
position LatLng No No Coordinates of a cluster item.

Example:

let clusterItem: mapCommon.ClusterItem = {
  position: {
    latitude: 39.99,
    longitude: 116.334595
  }
};

ClusterOverlayParams

Describes ClusterOverlay parameters.

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)

Name Type Read-Only Optional Description
clusterItems Array<ClusterItem> No No Array of cluster items.
distance number No No Clustering distance, in vp.

The API provides the method described in the following table to support custom cluster item icons.

Return Type Method
Promise<image.PixelMap>

getCustomIcon?(clusterItems: Array<ClusterItem>)

This API customizes icons for cluster items and returns the result asynchronously through a promise.

Example:

let clusterItem1: mapCommon.ClusterItem = {
  position: {
    latitude: 39.89,
    longitude: 116.335595
  }
};
let clusterItem2: mapCommon.ClusterItem = {
  position: {
    latitude: 39.99,
    longitude: 116.334595
  }
};
let array: Array<mapCommon.ClusterItem> = [
  clusterItem1,
  clusterItem2
];
let clusterOverlayParams: mapCommon.ClusterOverlayParams = { distance: 40, clusterItems: array };

[h2]getCustomIcon

getCustomIcon?(clusterItems: Array<ClusterItem>): Promise<image.PixelMap>

Customizes icons for cluster items. This API returns the result asynchronously through a promise.

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)

Name Type Mandatory Description
clusterItems Array<ClusterItem> Yes Array of cluster items.

Returns:

Type Description
Promise<image.PixelMap> Promise object, which returns image.PixelMap.

Example:

// Implement the getCustomIcon method in mapCommon.ClusterOverlayParams.
import { mapCommon } from '@kit.MapKit';
import { image } from '@kit.ImageKit';

export class ClusterOverlayParamsMore implements mapCommon.ClusterOverlayParams {
  clusterItems: mapCommon.ClusterItem[] = new Array();
  private offCanvas: OffscreenCanvas = new OffscreenCanvas(62, 62);
  private settings: RenderingContextSettings = new RenderingContextSettings(true);

  constructor(clusterItems: mapCommon.ClusterItem[], distance: number) {
    this.clusterItems = clusterItems;
    this.distance = distance;
  }

  distance: number = 0;

  // Customize a cluster item icon. For example, draw a circular icon with the longitude of the first item in clusterItems as the text.
  async getCustomIcon(clusterItems: mapCommon.ClusterItem[]): Promise<image.PixelMap> {
    let offContext = this.offCanvas.getContext("2d", this.settings);

    offContext.clearRect(0, 0, 62, 62);
    // Draw a circle.
    offContext.fillStyle = 0xff990000;
    offContext.beginPath();
    offContext.arc(31, 31, 30, 0, 6.28);
    offContext.stroke();
    offContext.fill();
    offContext.save();

    // Draw text in the circle. The text is the longitude of the first item in clusterItems.
    offContext.font = '20vp sans-serif';
    offContext.textAlign = 'center';
    offContext.textBaseline = 'middle';
    offContext.fillStyle = 0xffffffff;
    offContext.fillText(JSON.stringify(clusterItems[0].position.longitude).substring(0, 3), 31, 31);
    offContext.restore();
    let iconPixelMap = offContext.getPixelMap(0, 0, 62, 62);
    return iconPixelMap;
  }
}

ImageOverlayParams

Describes ImageOverlay parameters. This API inherits from BaseOverlayOptions.

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)

Name Type Read-Only Optional Description
bounds LatLngBounds No Yes Position of an ImageOverlay based on the specified rectangle. Either position or bounds must be set. When both parameters are set, bounds has a higher priority. When position is used, width is mandatory.
position LatLng No Yes Sets the position of an ImageOverlay. Either position or bounds must be set. When both parameters are set, bounds has a higher priority. When position is used, width is mandatory.
width number No Yes Width of an ImageOverlay, in meters. This parameter is valid only when position is specified. The value of this parameter must be a positive integer. The default value is 0.
height number No Yes Height of an ImageOverlay, in meters. This parameter is valid only when position and width are specified. The value of this parameter must be a positive integer. The default value is 0.
anchorU number No Yes

Position of the anchor of an ImageOverlay in the horizontal direction. The value ranges from 0 to 1. The default value is 0.5.

Note:

When bounds is specified, the value of anchorU changes the position of the anchor of the ImageOverlay in the horizontal direction, but does not change the range specified by bounds.
anchorV number No Yes

Position of the anchor of an ImageOverlay in the vertical direction. The value ranges from 0 to 1. The default value is 0.5.

Note:

When bounds is specified, the value of anchorV changes the position of the anchor of the ImageOverlay in the vertical direction, but does not change the range specified by bounds.
bearing number No Yes

Rotation angle of an ImageOverlay, in degrees.

0 degrees is due north, and angles increase clockwise. The value range is [0, 360). The default value is 0. 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.
clickable boolean No Yes

Indicates whether an ImageOverlay is tappable.

- true: yes

- false: no

The default value is false.
image ResourceStr | image.PixelMap No No

Image of an ImageOverlay.

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

Note:

ResourceStr indicates either Resource type or string type. Input parameters of the string type can be in either of the following formats:

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

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

Transparency of an overlay.

The value range is [0, 1],

where 0 indicates completely opaque and 1 indicates completely transparent.

The default value is 0.

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: 90
};

BuildingOverlayParams

Describes BuildingOverlay parameters.

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)

Name Type Read-Only Optional Description
points Array<LatLng> No No

Set of coordinates of the building bottom surface.

At least three coordinate points are required, and these coordinate points can form a complete plane when connected in clockwise direction.
totalHeight number No No

Height of the building from the ground, in meters.

The maximum value is 30000.
floorBottomHeight number No No Base height of the selected floor above the ground, in meters.
topFaceColor number No Yes

Color of the building top, in ARGB format.

The default color is red (0xffff0000).
sideFaceColor number No Yes

Color of the building sides, in ARGB format.

The default color is red (0xffff0000).
floorColor number No Yes

Top color of the selected floor, in ARGB format.

The default color is red (0xffff0000).
showLevel number No Yes Level at which the building starts to be displayed. The value range is [2,20]. The default value is 15. If the value is out of the range, the default value is used.
animationDuration number No Yes Animation duration, in milliseconds. The value must be greater than or equal to 100 ms. The default value is 0. If the value is out of the range, the default value is used.
sideTexture BuildingTexture No Yes Texture of the building sides.
floorTexture BuildingTexture No Yes Texture of the selected floor.

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 }
  };

BuildingTexture

Building texture.

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)

Name Type Read-Only Optional Description
image ResourceStr | image.PixelMap No No

Texture image.

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

Note:

ResourceStr indicates either Resource type or string type. Input parameters of the string type can be in either of the following formats:

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

- toDataURL format: For example, set image to image/png;base64,<Base64-encoded byte value of the icon file>.
width number No Yes Texture width, in meters. The value must be greater than or equal to 0. The default value is 3. If an invalid value is passed, the default value will be used.
height number No Yes Texture height, in meters. The value must be greater than or equal to 0. The default value is 3. If an invalid value is passed, the default value will be used.

Example:

let buildingTexture: mapCommon.BuildingTexture = {
  image: $r("app.media.floor_tex"),
  height: 10,
  width: 10
};

TraceOverlayParams

Describes TraceOverlay parameters.

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)

Name Type Read-Only Optional Description
points Array<LatLng> No No

Trajectory points.

The maximum number of points is 100000.
width number No Yes

Trajectory width, in pixels.

The default value is 10.

The value range is [0, 512]. If the value is greater than 512, 512 is used.
color number No Yes

Trajectory color, in ARGB format.

The default value is 0xaaff0000.
isMapMoving boolean No Yes

Indicates whether the map and trajectory move together.

- true: The map and trajectory move together.

- false: Only the trajectory moves.

The default value is false.
animationDuration number No Yes

Trajectory animation duration, in milliseconds. The minimum value is 100.

The default value is 5000.

Note:

If this parameter is set to a value less than 100, the default value 5000 will be used.
animationCallback Callback<number> No Yes Listens for the current location of the trajectory. This callback returns the trajectory point index.

Example:

// For details about the source of this.mapController in the example, please refer to the sample code for displaying a map in the development guide.
// 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 = await this.mapController.addTraceOverlay(traceOptions, markers);

MapArcParams

Describes MapArc parameters. This API inherits from BaseOverlayOptions.

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)

Name Type Read-Only Optional Description
startPoint LatLng No No Start point.
centerPoint LatLng No No Midpoint
endPoint LatLng No No End point.
color number No Yes Color of a MapArc, in ARGB format. The default value is 0xFFFFFFFF (white). If an invalid value is passed, the default value will be used.
width number No Yes Width of a MapArc, in pixels. The value must be greater than or equal to 0. The default value is 10. If an invalid value is passed, the default value will be used.

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
};

CoordinateLatLng

Specified coordinate system and 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 5.0.0(12).

System capability: SystemCapability.Map.Core

Since: 5.0.0(12)

Name Type Read-Only Optional Description
coordinateType CoordinateType No No Coordinate system type.
location LatLng No No Coordinates.

Example:

let location: mapCommon.CoordinateLatLng = {
  coordinateType: mapCommon.CoordinateType.GCJ02,
  location: { latitude: 31.984410259206815, longitude: 118.76625379397866 }
};

TileOverlayParams

Describes TileOverlay parameters. This API inherits from BaseOverlayOptions.

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)

Name Type Read-Only Optional Description
tileUrl string No No

URL of a TileOverlay.

It must start with http or https and contain placeholders {x}, {y}, and {z}.
transparency number No Yes

Transparency of a TileOverlay.

The value ranges from 0 to 1. The value 1 indicates completely transparent, and the value 0 indicates completely opaque.

The default value is 0.
fadeIn boolean No Yes

Indicates whether to enable TileOverlay fade-in.

- true: yes

- false: no

The default value is true.

Example:

let params: mapCommon.TileOverlayParams = {
  // URL of the TileOverlay, which must start with http or https and contain placeholders in the ?x={x}&y={y}&z={z} format.
  tileUrl: "https://xxx/xxx?x={x}&y={y}&z={z}",
  transparency: 0,
  fadeIn: false
};

TileOverlayOptions

Describes TileOverlay parameters. This API inherits from BaseOverlayOptions.

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

System capability: SystemCapability.Map.Core

Since: 6.0.0(20)

Name Type Read-Only Optional Description
tileUrl string No Yes

URL of a TileOverlay.

It must start with http or https and contain placeholders {x}, {y}, and {z}.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).
tileProvider TileProvider No Yes

Obtains a TileOverlay based on the coordinates.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).
transparency number No Yes

Transparency of a TileOverlay.

The value ranges from 0 to 1. The value 1 indicates completely transparent, and the value 0 indicates completely opaque.

The default value is 0.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).
fadeIn boolean No Yes

Indicates whether to enable TileOverlay fade-in.

- true: yes

- false: no

The default value is true.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).
diskCacheEnabled boolean No Yes

Indicates whether to enable disk caching.

true: yes

false: no

The default value is false.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).
diskCacheSize number No Yes

Disk cache size, in KB. The default value is 20480.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).
diskCachePath string No Yes

Disk cache path. This parameter is mandatory if disk caching is enabled.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).
tileDataReuse number[] No Yes

Rules for reusing lower-zoom tiles at higher zoom levels. By default, level reuse is disabled. The array must have a fixed length of 19, corresponding to zoom levels 2 through 20. If the array length is not 19, this parameter will be ignored. Values in the array must be monotonically increasing or remain constant; otherwise, they will be treated as invalid. All values in the array should be within the range [2, 20] and will be automatically rounded down. Any invalid values will not be processed.

Since: 6.1.1(24)

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

Example:

let params: mapCommon.TileOverlayOptions = {
  // URL of the TileOverlay, which must start with http or https and contain placeholders in the ?x={x}&y={y}&z={z} format.
  tileUrl: "https://xxx/xxx?x={x}&y={y}&z={z}",
  diskCacheEnabled: true,
  diskCacheSize: 20480,
  diskCachePath: '/data/storage/el2/database',
  // Configuration item for reusing lower-zoom tiles at higher zoom levels.
  tileDataReuse: [ 2, 3, 4, 5, 6, 6, 6, 6, 6, 6, 6, 6, 7, 7, 7, 7, 7, 7, 7 ]
};

HeatmapParams

Describes heatmap parameters.

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)

Name Type Read-Only Optional Description
id string No No Heatmap ID.
data WeightedLatLng[] No No Heatmap data (it is recommended that the number of heatmap data records be less than 10,000).
color Record<number, number> No Yes

Heatmap color, in ARGB format. The parameter value is in a key-value format. The key indicates the data density (value range: [0,1]), and the value indicates the color in ARGB format. Default values: { 0: 0x00026C39, 0.15: 0xAA138C4A, 0.3: 0xFF82CB67, 0.45: 0xFFE3F399, 0.6: 0xFFFEDE89, 0.75: 0xFFF67C4A, 0.9: 0xFFBE1827, 1: 0xFFA90426 }

If the key of a record is out of the valid range or the value is in an incorrect format, the record is removed. If no records are valid, the default value will be used.
intensity number | Record<number, number> No Yes

Heatmap Intensity. You can configure the intensity by level. The parameter value can be in a key-value format, where the key indicates the level and the value indicates the intensity. If the intensity value is a number, the same intensity is used for all levels.

If a value less than or equal to 0 is passed, the default value 1 is used.
opacity number | Record<number, number> No Yes Heatmap opacity. The value ranges from 0 to 1. The value 1 indicates completely transparent, and the value 0 indicates completely opaque. For values less than 0, the value 0 is used; for values greater than 1, the value 1 is used. If the opacity is a number, the same opacity is used for all levels. The default value is 0.
radius number | Record<number, number> No Yes Heatmap radius. You can configure the radius by level. The parameter value can be in a key-value format, where the key indicates the level and the value indicates the radius. If the radius value is a number, the same radius is used for all levels. The default value is 10. The default unit is RadiusUnit.PIXEL_UNIT.
radiusUnit RadiusUnit No Yes Radius unit. The default value is RadiusUnit.PIXEL_UNIT.
visible boolean No Yes

Indicates whether the heatmap is visible. The default value is true.

- true: yes

- false: no

RadiusUnit

Enumerates the radius units.

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)

Name Value Description
PIXEL_UNIT 0 Pixel.
METER_UNIT 1 Meter.

WeightedLatLng

Describes the weighted longitude and latitude.

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)

Name Type Read-Only Optional Description
point LatLng No No Longitude and latitude.
intensity number No Yes Weight of the intensity. The value range is [0,+∞). The default value is 1. If an invalid value is passed, the default value will be used.

TileProvider

type TileProvider = (x: number, y: number, z: number) => Promise<ArrayBuffer>

Obtains a TileOverlay based on the coordinates. This API returns the result asynchronously through a promise.

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)

Name Type Mandatory Description
x number Yes X coordinate.
y number Yes Y coordinate.
z number Yes Z coordinate.

Returns:

Type Description
Promise<ArrayBuffer> Promise object, which returns the TileOverlay.

MvtOverlayParams

Describes MvtOverlay parameters. This API inherits from BaseOverlayOptions.

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

System capability: SystemCapability.Map.Core.EnhancedOverlay

Since: 6.0.0(20)

Name Type Read-Only Optional Description
source MvtSource No No

Source of the MvtOverlay.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).
layers MvtLayer[] No No

Style array. It is recommended that the number of vector layers be less than 2000 to ensure smoothness of the MvtOverlay.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).
blurIntensity number | Record<number, number> No Yes

Blur intensity of the MvtOverlay. This parameter does not take effect for the 3D globe view.

The blur intensity ranges from 0 to 20. The decimal part is rounded down. The default value is 0. If an invalid value is passed, the default value will be used.

If the blurIntensity value is a number, the same intensity is used for all zoom levels.

If the blurIntensity value is key-value pairs, the key indicates the zoom level and the value indicates the blur intensity. The valid level range is [2, 20]. For a level value outside of this range, the nearest boundary value will be used. For example, the value { 5: 5, 10: 8, 18: 15 } indicates that the blur intensity is 0 (no blur) for levels 2–4, 5 for levels 5–9, 8 for levels 10–17, and 15 for levels 18–20.

Since: 6.0.2(22)

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

MvtSource

Describes the source of the 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)

Name Type Read-Only Optional Description
tileUrl string No Yes

URL for downloading MvtOverlay data. It must contain placeholders {x}, {y}, and {z}.

Note:

To add an MvtOverlay using an online resource (via the tileUrl method), you must apply for the network access permission ohos.permission.INTERNET.
tileProvider TileProvider No Yes Obtains a TileOverlay based on the coordinates.
minZoom number No Yes Minimum zoom level. The value range is [2, 20]. The default value is 2. If the value is invalid, the default value is used.
maxZoom number No Yes Maximum zoom level. The value range is [2, 20]. The default value is 20. If the value is invalid, the default value is used.

MvtLayer

Describes the style array, which is used to configure the style.

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)

Name Type Read-Only Optional Description
id string No No Unique ID, which is used to add, update, or remove an MvtOverlay.
type MvtLayerType No No MvtOverlay type.
sourceLayer string No No MvtOverlay name.
paint MvtPaint No Yes Rendering of a geometry, such as its fill and stroke.

MvtPaint

Configures the rendering of a geometry, such as its fill and stroke.

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)

Name Type Read-Only Optional Description
fillColor number | Expression No Yes

Fill color. The default value is 0x000000. If an invalid value is passed, the default value will be used. The value:

- Must be in hexadecimal RGB format.

- Can be obtained from an MvtOverlay's attributes.
fillOpacity number | Expression No Yes

Fill opacity. The default value is 0. If an invalid value is passed, the default value will be used. The value:

- The value range is [0, 1]. 0 indicates completely transparent, and 1 indicates completely opaque.

- Can be obtained from an MvtOverlay's attributes.

MvtLayerType

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

System capability: SystemCapability.Map.Core.EnhancedOverlay

Since: 6.0.0(20)

Name Value Description
FILL 'fill' Filled polygon.

Expression

Describes the overlay expression of 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)

Name Type Read-Only Optional Description
operator Operator No No Operator.
args string | string[] | Expression[] No No

Parameter.

Note:

The string[] and Expression[] types are reserved for future use.

Operator

Enumerates the operators.

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)

Name Value Description
GET 'get' GET operator.

FlowFieldOverlayParams

Describes FlowFieldOverlay parameters. This API inherits from BaseOverlayOptions.

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)

Name Type Read-Only Optional Description
data string No No FlowFieldOverlay data. For details about the data format, please refer to Flow Field Data Format Reference.
style ParticleStyle No Yes Particle style.

ParticleStyle

Describes the particle style.

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)

Name Type Read-Only Optional Description
count number No Yes Number of particles. The default value is 2000. If an invalid value is passed, the default value will be used. It is recommended that the value be less than 10000.
color number No Yes Particle color, in ARGB format. The default value is 0xffff69b4. If an invalid value is passed, the default value will be used.
maxSpeed number No Yes Maximum speed of a particle, in m/s. The default value is 70. It is recommended that the value be less than 255. If an invalid value is passed, the default value will be used.
speedFactor number No Yes Speed factor of a particle. The value ranges from 0 to 1. The default value is 0.2. If an invalid value is passed, the default value will be used.

MassPointItem

Massive point item.

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)

Name Type Read-Only Optional Description
itemId string No No Unique ID of an item.
position LatLng No No Longitude-latitude coordinates of an item.
title string No Yes Title.
snippet string No Yes Point content.

MassPointOverlayParams

Describes MassPointOverlay parameters.

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)

Name Type Read-Only Optional Description
id string No No Unique ID of a MassPointOverlay.
items MassPointItem[] No No Massive point list (it is recommended that the number of massive points be less than 100,000).
icon ResourceStr | image.PixelMap No No MassPointOverlay icon.
anchorU number No Yes Horizontal position of the icon anchor. The value ranges from 0 to 1. The default value is 0.5.
anchorV number No Yes Vertical position of the icon anchor. The value ranges from 0 to 1. The default value is 0.5.

LineText

Provides text for map line segments.

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

Name Type Read-Only Optional Description
lineNames string[] No No List of text content for segmented lines.
lineNameIndexes number[] No No

Line ranges used to display text within a segment.

Note:

- Each value must be greater than or equal to 0.

- The sequence of values must be monotonically non-decreasing.

- The length of the lineNameIndexes array must be exactly twice the length of the lineNames array.

If any of the conditions is violated, the parameter is considered invalid.
nameOnRight boolean No Yes

Specifies which side of the line the text is displayed on.

- true: right side

- false: left side

The default value is true. If an invalid value is passed, the default value will be used.
color number No Yes Color of the text content, in ARGB format. The default value is 0xFF000000. If an invalid value is passed, the default value will be used.
fontSize number No Yes Font size of the text content, in px. The default value is 15. The value range is [0, 100]. Values out of this range are clamped to the nearest boundary. null and undefined are treated as the default value.
strokeColor number No Yes Stroke color of the text content, which is in ARGB format. The default value is 0xFFFFFFFF. If an invalid value is passed, the default value will be used.
fontStyle FontStyle No Yes Font style of the text content. The default value is FontStyle.REGULAR. If an invalid value is passed, the default value will be used.

SphereParams

Attributes of the 3D globe, including enabling the day-night terminator, city lighting, animation duration, background, and 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 API version 26.0.0.

System capability: SystemCapability.Map.Core

Since: 26.0.0

Name Type Read-Only Optional Description
sunLightEnabled boolean No Yes

Indicates whether to enable the day-night terminator.

- true: yes

- false: no

The default value is true. If an invalid value is passed, the default value will be used.

Note:

The day-night terminator is the dividing line of solar illumination on the Earth's surface, separating the globe into day and night regions. The position of the terminator line on Earth changes continuously due to the Earth's rotation and orbital revolution.
cityLightEnabled boolean No Yes

Indicates whether to enable city lighting. The default value is true. If an invalid value is passed, the default value will be used.

- true: Enable city lighting.

- false: Disable city lighting.
animateDuration number No Yes Animation duration, in milliseconds. The value must be greater than or equal to 0. If an invalid value is passed, the default value will be used.
backgroundImage ResourceStr | image.PixelMap No Yes Background of the 3D globe.
coverageImage ResourceStr | image.PixelMap No Yes Overlay of the 3D globe.

MapSignalParams

Attributes of a signal line. This API inherits from BaseOverlayOptions.

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

Name Type Read-Only Optional Description
signalId string No No

ID of the signal line. null and undefined values will be ignored.

Note:

After a signal line is successfully added, Map Kit caches its signalId in the app process memory. When the line is deleted, this cache is retained by default. This allows you to re-add the cached signal line directly without network access as long as the app process remains alive.

If you need to delete the cached signalId, call the removeSignalLineCache API.
points LatLng[] No Yes Vertices of the signal line. The length range is [0, 10000]. The line length must be less than 200 km. If null or undefined is passed, 401 will be returned.
colors number[] No Yes Colors of the signal line. The length must be 3. The three colors (in ARGB format) correspond to weak, medium, and strong signals in sequence. The default value is [0xFFFC3C11, 0xFFFFDF42, 0xFF42B0FF] (red, yellow, and blue). The array length must be 3. If an invalid value is passed, the default value will be used.
width number No Yes Width of the signal line, in px. The value range is [0, 512] and the default value is 10. Values greater than 512 are clamped to 512. Values less than 0 are treated as 10. If null or undefined values are passed in, the default value will be used.
coordinateType CoordinateType No Yes Coordinate system type. The default value is CoordinateType.GCJ02. If an invalid value is passed, the default value will be used.

MapType

Enumerates the map types.

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

System capability: SystemCapability.Map.Core

Since: 4.1.0(11)

Name Value Description
STANDARD 0

Standard map, which shows roads, buildings, and natural features such as rivers.

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

Empty map, which has no data loaded.

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

Topographic map, which is a standard map that provides a clear and complete depiction of terrain features, while still retaining other map elements such as administrative boundaries, POIs, and building footprints.

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

Note:

- The topographic map is only visible at a zoom level greater than 5 and less than 14.

- The topographic map is not available on smart watches.
SATELLITE 3

Satellite map, which shows satellite imagery. It is available only in China.

Since: 6.0.0(20)

Atomic service API: This API can be used in atomic services since version 6.0.0(20).
HYBRID 4

Hybrid map, which displays both satellite imagery and road network information.

Since: 6.0.0(20)

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

PatternItemType

Describes the stroke pattern of a MapPolyline or the outline of a MapPolygon or MapCircle.

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)

Name Value Description
DASH 0 The MapPolyline, MapPolygon, and MapCircle are displayed with a dashed line style.
DOT 1 The MapPolyline, MapPolygon, and MapCircle are displayed with a dotted line style.
GAP 2 The MapPolyline, MapPolygon, and MapCircle are displayed with a gapped line style.

JointType

Enumerates the joint types of a MapPolyline or MapPolygon.

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)

Name Value Description
DEFAULT 0 Miter is used to connect paths.
BEVEL 1 Bevel is used to connect paths.
ROUND 2 Round is used to connect paths.

LogoAlignment

Enumerates the map logo alignment modes.

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

System capability: SystemCapability.Map.Core

Since: 4.1.0(11)

Name Value Description
BOTTOM_START 0

The map logo is placed in the lower left corner.

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

The map logo is placed in the lower right corner.

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

The map logo is placed in the upper left corner.

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

The map logo is placed in the upper right corner.

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

The map logo is placed at the top center.

Since: 5.1.1(19)

Atomic service API: This API can be used in atomic services since version 5.1.1(19).
BOTTOM_CENTER 5

The map logo is placed at the bottom center.

Since: 5.1.1(19)

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

CapStyle

Enumerates the start vertex and end vertex styles of a MapPolyline.

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)

Name Value Description
BUTT 0 The two ends of the line are parallel lines.
ROUND 1 The two ends of the line are extended by a half circle.
SQUARE 2 The two ends of the line are extended by a rectangle.

CollisionRule

Enumerates the rules of collision between map POIs.

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

System capability: SystemCapability.Map.Core

Since: 4.1.0(11)

Name Value Description
NONE 0

Neither names nor icons are involved in the collision.

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

Only names are involved in the collision.

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

Both icons and names are involved in the collision.

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

Icon collision rule. This rule applies only to Markers.

Since: 6.1.0(23)

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

FontStyle

Enumerates the font style of a PointAnnotation title.

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)

Name Value Description
REGULAR 0 Regular.
BOLD 1 Bold.
ITALIC 2 Italic.
BOLD_ITALIC 3 Bold and italic.
MEDIUM 4 Medium.
MEDIUM_ITALIC 5 Medium and italic.

CoordinateType

Enumerates the coordinate system types.

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)

Name Value Description
WGS84 0 WGS84.
GCJ02 1 GCJ02.

MyLocationDisplayType

Enumerates the display modes of the my-location icon.

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

System capability: SystemCapability.Map.Core

Since: 5.0.0(12)

Name Value Description
DEFAULT 0

Continuous location is performed. The camera does not move to my location, and the location blue dot follows the device's movement.

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

A single location is performed and the camera moves to the center of the map.

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

Continuous location is performed. The camera moves to the center of the map, and the location blue dot follows the device's movement.

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

Continuous location is performed. The camera moves to the center of the map, and the location blue dot rotates according to the device direction and follows the device's movement.

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

Note:

Required permission: ohos.permission.ACCELEROMETER
TRACK_ROTATE 4

Continuous location is performed. The location icon follows the movement of the device and rotates according to the device direction, but will not move to the center of the map.

Since: 6.0.0(20)

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

Note:

Required permission: ohos.permission.ACCELEROMETER
MAP_ROTATE 5

Location updates are continuously retrieved, and the camera is moved to the center of the map. The blue location dot will move with the device, and the map will rotate according to the device's orientation.

Since: 26.0.0

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

Note:

Required permission: ohos.permission.ACCELEROMETER
MAP_ROTATE_NO_CENTER 6

Location updates are continuously retrieved, and the camera is not moved to the center of the map. The blue location dot will move with the device, and the map will rotate according to the device's orientation.

Since: 26.0.0

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

Note:

Required permission: ohos.permission.ACCELEROMETER

DayNightMode

Enumerates the day/dark modes 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)

Name Value Description
DAY 0 Day mode.
NIGHT 1 Night mode.
AUTO 2 Automatic mode. If the system's dark mode is enabled, the night mode is used; otherwise, the day mode is used.

ScaleUnit

Enumerates map scale units (metric and imperial).

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)

Name Value Description
METRIC_UNIT 0 Metric unit.
IMPERIAL_UNIT 1 Imperial unit.

TextPosition

Enumerates the PointAnnotation text positions.

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)

Name Value Description
DEFAULT 0 Default mode.
TOP 1 The text is displayed above the icon.
BOTTOM 2 The text is displayed below the icon.
LEFT 3 The text is displayed to the left of the icon.
RIGHT 4 The text is displayed to the right of the icon.

MapElementType

Enumerates the map element types.

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)

Name Value Description
OVERLAY 1 Overlays, including the MapCircle, MapPolygon, MapPolyline, MapArc, ImageOverlay, and TraceOverlay.
POI 2 Base map POI.
CUSTOM_POI 3 Overlays that support collision, including the PointAnnotation and Bubble.
MARKER 4 Marker and ClusterOverlay.