目录

Functions

Modules to Import

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

newCameraPosition

newCameraPosition(cameraPosition: mapCommon.CameraPosition): CameraUpdate

Creates a CameraUpdate object to update the camera position.

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

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

System capability: SystemCapability.Map.Core

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
cameraPosition mapCommon.CameraPosition Yes New map camera position.

Returns:

Type Description
CameraUpdate Description of changes to the camera position, such as panning and zooming. This object can be used to call the map update API to change the map camera position.

Error codes:

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

ID Error Message
401 Invalid input parameter.

Example:

let target: mapCommon.LatLng = {
  latitude: 39.9,
  longitude: 116.4
};
let cameraPosition: mapCommon.CameraPosition = {
  target: target,
  zoom: 10
};
let cameraUpdate: map.CameraUpdate = map.newCameraPosition(cameraPosition);

newLatLng

newLatLng(latLng: mapCommon.LatLng, zoom?: number): CameraUpdate

Sets the map center 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)

Parameters:

Name Type Mandatory Description
latLng mapCommon.LatLng Yes Longitude and latitude.
zoom number No Zoom level. The value range is [2, 20]. For a value out of the range, the nearest boundary value is used.

Returns:

Type Description
CameraUpdate Description of changes to the camera position.

Error codes:

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

ID Error Message
401 Invalid input parameter.

Example:

let latLng: mapCommon.LatLng = {
  latitude: 39.9,
  longitude: 116.4
};
let cameraUpdate: map.CameraUpdate = map.newLatLng(latLng);

newLatLngBounds

newLatLngBounds(bounds: mapCommon.LatLngBounds, padding?: number): CameraUpdate

Sets the map's longitude and latitude ranges as well as the padding between the map region and map 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)

Parameters:

Name Type Mandatory Description
bounds mapCommon.LatLngBounds Yes Longitude and latitude ranges for displaying the map.
padding number No Padding between the map region and edges, in pixels. The default value is 0. Error code 401 will be returned for any invalid value.

Returns:

Type Description
CameraUpdate Description of changes to the camera position.

Error codes:

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

ID Error Message
401 Invalid input parameter.

Example:

let bounds: mapCommon.LatLngBounds = {
  northeast: {
    latitude: 33,
    longitude: 118
  },
  southwest: {
    latitude: 32,
    longitude: 119
  }
};
// Set the map's longitude and latitude ranges and specify the padding between the map region and map edges to 5 pixels.
let cameraUpdate: map.CameraUpdate = map.newLatLngBounds(bounds, 5);

newLatLngBounds

newLatLngBounds(bounds: mapCommon.LatLngBounds, width: number, height: number, padding: number): CameraUpdate

Sets the map's longitude and latitude ranges, the height and width of the latitude-longitude bounding box, and the padding between the map region and map 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 5.0.0(12).

System capability: SystemCapability.Map.Core

Since: 5.0.0(12)

Parameters:

Name Type Mandatory Description
bounds mapCommon.LatLngBounds Yes Longitude and latitude ranges for displaying the map.
width number Yes Screen width of the latitude-longitude bounding box, in pixels. The value must be greater than or equal to 0.
height number Yes Screen height of the latitude-longitude bounding box, in pixels. The value must be greater than or equal to 0.
padding number Yes Padding between the map region and map edges, in pixels.

Returns:

Type Description
CameraUpdate Description of changes to the camera position.

Error codes:

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

ID Error Message
401 Invalid input parameter.

Example:

let bounds: mapCommon.LatLngBounds = {
  northeast: {
    latitude: 31,
    longitude: 118
  },
  southwest: {
    latitude: 30.5,
    longitude: 123
  }
};
// Set the map's longitude and latitude ranges. Set both the width and height of the latitude-longitude bounding box to 1000 pixels, and set the padding between the map region and edges to 100 pixels.
let cameraUpdate: map.CameraUpdate = map.newLatLngBounds(bounds, 1000, 1000, 100);

newLatLngBounds

newLatLngBounds(bounds: mapCommon.LatLngBounds, padding: mapCommon.Padding): CameraUpdate

Sets the map's longitude and latitude ranges as well as the padding between the map region and the four map 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 5.0.1(13).

System capability: SystemCapability.Map.Core

Since: 5.0.1(13)

Parameters:

Name Type Mandatory Description
bounds mapCommon.LatLngBounds Yes Longitude and latitude ranges for displaying the map. Error code 401 will be returned for any invalid value.
padding mapCommon.Padding Yes

Padding between the map region and edges, in pixels. Error code 401 will be returned for any invalid value.

Note:

- The height of the map component, after subtracting the top and bottom padding values, must be at least 100 px.

- The width of the map component, after subtracting the left and right padding values, must be at least 100 px.

Returns:

Type Description
CameraUpdate Description of changes to the camera position.

Error codes:

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

ID Error Message
401 Invalid input parameter.

Example:

let bounds: mapCommon.LatLngBounds = {
  northeast: {
    latitude: 31,
    longitude: 118
  },
  southwest: {
    latitude: 30.5,
    longitude: 123
  }
};
// Initialization parameters. The left padding is 0 px and the bottom padding is 50 px.
let padding: mapCommon.Padding = {
  left: 0,
  bottom: 50
};
let cameraUpdate: map.CameraUpdate = map.newLatLngBounds(bounds, padding);

scrollBy

scrollBy(x: number, y: number): CameraUpdate

Moves the map center point by pixel.

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

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

System capability: SystemCapability.Map.Core

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
x number Yes Number of pixels to scroll horizontally. A positive value indicates that the visible region moves rightwards, while a negative value indicates that the visible region moves leftwards. The unit is px.
y number Yes Number of pixels to scroll vertically. A positive value indicates that the visible region moves downwards, while a negative value indicates that the visible region moves upwards. The unit is px.

Returns:

Type Description
CameraUpdate Description of changes to the camera position.

Error codes:

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

ID Error Message
401 Invalid input parameter.

Example:

let cameraUpdate: map.CameraUpdate = map.scrollBy(100, 200);

zoomBy

zoomBy(amount: number, focus?: mapCommon.MapPoint): CameraUpdate

Zooms in or out on a map by a specified value with the specified pixel point as the center.

The upper left vertex of the screen is used as the (0, 0) point. A positive value of focus.positionX indicates that the visible region moves rightwards, while a negative value indicates that the visible region moves leftwards. A positive value of focus.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)

Parameters:

Name Type Mandatory Description
amount number Yes Increment of the map zoom level.
focus mapCommon.MapPoint No Map center's coordinates on the screen.

Returns:

Type Description
CameraUpdate Description of changes to the camera position.

Error codes:

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

ID Error Message
401 Invalid input parameter.

Example:

let focus: mapCommon.MapPoint = {
  positionX: 100,
  positionY: 200
};
let cameraUpdate: map.CameraUpdate = map.zoomBy(10, focus);

zoomIn

zoomIn(): CameraUpdate

Zooms in on a map by 1 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)

Returns:

Type Description
CameraUpdate Description of changes to the camera position.

Example:

let cameraUpdate: map.CameraUpdate = map.zoomIn();

zoomOut

zoomOut(): CameraUpdate

Zooms out on a map by 1 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)

Returns:

Type Description
CameraUpdate Description of changes to the camera position.

Example:

let cameraUpdate: map.CameraUpdate = map.zoomOut();

zoomTo

zoomTo(zoom: number): CameraUpdate

Sets the zoom level 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 4.1.0(11).

System capability: SystemCapability.Map.Core

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
zoom number Yes Map zoom level. The value range is [2, 20]. For a value out of the range, the nearest boundary value is used.

Returns:

Type Description
CameraUpdate Description of changes to the camera position.

Error codes:

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

ID Error Message
401 Invalid input parameter.

Example:

let cameraUpdate: map.CameraUpdate = map.zoomTo(10);

calculateDistance

calculateDistance(from: mapCommon.LatLng, to: mapCommon.LatLng): number

Calculates the distance between coordinate points.

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

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

System capability: SystemCapability.Map.Core

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
from mapCommon.LatLng Yes Coordinates of the departure place.
to mapCommon.LatLng Yes Coordinates of the destination.

Returns:

Type Description
number

Distance between the specified two coordinate points, in meters.

If the input parameters are empty, 0 is returned.

Example:

let fromLatLng: mapCommon.LatLng = {
  latitude: 38,
  longitude: 118
};
let toLatLng: mapCommon.LatLng = {
  latitude: 39,
  longitude: 119
};

let distance = map.calculateDistance(fromLatLng, toLatLng);

convertCoordinate

convertCoordinate(fromType: mapCommon.CoordinateType, toType: mapCommon.CoordinateType, location: mapCommon.LatLng): Promise<mapCommon.LatLng>

Converts coordinates from one coordinate system to another. Currently, this API supports only conversion from WGS84 coordinates to GCJ02 coordinates. This API uses a promise to return the result.

If you need a synchronous function, you are advised to use convertCoordinateSync.

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

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

System capability: SystemCapability.Map.Core

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
fromType mapCommon.CoordinateType Yes Original coordinate type. Currently, only WGS84 is supported.
toType mapCommon.CoordinateType Yes Target coordinate type. Currently, only GCJ02 is supported.
location mapCommon.LatLng Yes Coordinates to be converted.

Returns:

Type Description
Promise<mapCommon.LatLng> Promise used to return mapCommon.LatLng.

Error codes:

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

ID Error Message
401 Invalid input parameter.

Example:

let wgs84Position: mapCommon.LatLng = {
  latitude: 30,
  longitude: 118
};
let gcj02Position: mapCommon.LatLng = await map.convertCoordinate(mapCommon.CoordinateType.WGS84, mapCommon.CoordinateType.GCJ02, wgs84Position);

convertCoordinateSync

convertCoordinateSync(fromType: mapCommon.CoordinateType, toType: mapCommon.CoordinateType, location: mapCommon.LatLng): mapCommon.LatLng

Converts coordinates from one coordinate system to another. Currently, this API supports only conversion from WGS84 coordinates to GCJ02 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)

Parameters:

Name Type Mandatory Description
fromType mapCommon.CoordinateType Yes Original coordinate type. Currently, only WGS84 is supported.
toType mapCommon.CoordinateType Yes Target coordinate type. Currently, only GCJ02 is supported.
location mapCommon.LatLng Yes Coordinates to be converted.

Returns:

Type Description
mapCommon.LatLng Longitude-latitude object.

Error codes:

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

ID Error Message
401 Invalid input parameter.

Example:

let wgs84Position: mapCommon.LatLng = {
  latitude: 30,
  longitude: 118
};
// Convert the longitude-latitude coordinates.
let gcj02Position: mapCommon.LatLng =
  map.convertCoordinateSync(mapCommon.CoordinateType.WGS84, mapCommon.CoordinateType.GCJ02, wgs84Position);

rectifyCoordinate

rectifyCoordinate(context: common.Context, locations: Array<mapCommon.CoordinateLatLng>): Promise<Array<mapCommon.CoordinateLatLng>>

Checks whether the input coordinates need to be rectified based on the input coordinates, input coordinate system, and obtained current route location. If yes, this API returns the rectified coordinate system and coordinates. This API uses a promise to return the result.

  • The rectifyCoordinate API is solely designed to address the display offset of original coordinates on a Huawei map.

  • The rectifyCoordinate API supports only conversion from WGS84 coordinates to GCJ02 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)

Parameters:

Name Type Mandatory Description
context common.Context Yes Context.
locations Array<mapCommon.CoordinateLatLng> Yes Input coordinate system and coordinates.

Returns:

Type Description
Promise<Array<mapCommon.CoordinateLatLng>> Promise used to return the rectified coordinate system and coordinates.

Error codes:

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

ID Error Message
401 Invalid input parameter.
1002600013 The current routing location is unknown. Try again later.

Example:

let locations: Array<mapCommon.CoordinateLatLng> = [
  {
    // Enter coordinates of Hong Kong (China) and the WGS84 coordinate system. If the current map site uses the GCJ02 coordinate system, the GCJ02 coordinate system and the coordinates converted from WGS84 to GCJ02 are returned.
    coordinateType: mapCommon.CoordinateType.WGS84,
    location: { latitude: 22.280556, longitude: 114.984000 }
  }
];
// The method containing await needs to use the async keyword.
let arr: Array<mapCommon.CoordinateLatLng> = await map.rectifyCoordinate(this.getUIContext().getHostContext(), locations);