目录

Interface (ClusterOverlay)

Modules to Import

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

ClusterOverlay

ClusterOverlay class. The ClusterOverlay is used to display clustered markers on a map, optimizing performance and user experience when rendering a large number of markers. It merges multiple geographically close markers into a single cluster point and allows users to click the cluster point to expand and view specific markers. It is ideal for displaying dense POI data and preventing the map from becoming overly cluttered. An instance of this type will be returned when the addClusterOverlay method in the map.MapComponentController class is called.

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

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

System capability: SystemCapability.Map.Core

Since: 5.0.0(12)

Example:

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

[h2]on('clusterClick')

on(type: 'clusterClick', callback: Callback<Array<mapCommon.ClusterItem>>): void

Listens for ClusterOverlay tap events. This API uses an asynchronous callback to return the result.

You are advised to use ClusterOverlay.on(type: 'click').

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 5.0.0(12).

System capability: SystemCapability.Map.Core

Since: 5.0.0(12)

Parameters:

Name Type Mandatory Description
type string Yes 'clusterClick': event indicating a cluster item of a ClusterOverlay is tapped.
callback Callback<Array<mapCommon.ClusterItem>> Yes Callback used to return Array<mapCommon.ClusterItem>.

Example:

clusterOverlay.on("clusterClick", (clusterItems) => {
  console.info(`callback: ${clusterItems.length}`);
});

[h2]off('clusterClick')

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

Cancels the listening for ClusterOverlay tap events. This API uses an asynchronous callback to return the result.

You are advised to use ClusterOverlay.off(type: 'click').

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 5.0.0(12).

System capability: SystemCapability.Map.Core

Since: 5.0.0(12)

Parameters:

Name Type Mandatory Description
type string Yes 'clusterClick': event indicating a cluster item of a ClusterOverlay is tapped.
callback Callback<void> No Callback that returns no value.

Example:

clusterOverlay.off("clusterClick", () => {
  console.info("callback off");
});

[h2]on('click')

on(type: 'click', callback: Callback<Array<mapCommon.ClusterItem>>): void

Listens for events indicating a cluster item of a ClusterOverlay is tapped. This API can use multiple asynchronous callbacks to return the result.

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

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

System capability: SystemCapability.Map.Core

Since: 5.0.0(12)

Parameters:

Name Type Mandatory Description
type string Yes 'click': event indicating a cluster item of a ClusterOverlay is tapped.
callback Callback<Array<mapCommon.ClusterItem>> Yes Callback used to return Array<mapCommon.ClusterItem>. This callback is used to listen for events indicating a cluster item of a ClusterOverlay is tapped.

Example:

let callback1 = (clusterItem: Array<mapCommon.ClusterItem>) => {
  console.info("click", `callback1 clusterItem length: ${clusterItem.length}`);
};
let callback2 = (clusterItem: Array<mapCommon.ClusterItem>) => {
  console.info("click", `callback2 clusterItem length: ${clusterItem.length}`);
};
let callback3 = (clusterItem: Array<mapCommon.ClusterItem>) => {
  console.info("click", `callback3 clusterItem length: ${clusterItem.length}`);
};
clusterOverlay.on("click", callback1);
clusterOverlay.on("click", callback2);
clusterOverlay.on("click", callback3);

[h2]off('click')

off(type: 'click', callback?: Callback<Array<mapCommon.ClusterItem>>): void

Cancel the listening for events indicating a cluster item of a ClusterOverlay is tapped. This API can use multiple asynchronous callbacks to return the result.

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

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

System capability: SystemCapability.Map.Core

Since: 5.0.0(12)

Parameters:

Name Type Mandatory Description
type string Yes 'click': event indicating a cluster item of a ClusterOverlay is tapped.
callback Callback<Array<mapCommon.ClusterItem>> No

Callback used to return Array<mapCommon.ClusterItem>. This callback is used to cancel listening for events indicating a cluster item of a ClusterOverlay is tapped.

- If callback is null, cancel all callbacks.

- If callback is not null, cancel the specified callback.

Example:

let callback1 = (clusterItem: Array<mapCommon.ClusterItem>) => {
  console.info("click", `callback1 clusterItem`);
};
let callback2 = (clusterItem: Array<mapCommon.ClusterItem>) => {
  console.info("click", `callback2 clusterItem`);
};
let callback3 = (clusterItem: Array<mapCommon.ClusterItem>) => {
  console.info("click", `callback3 clusterItem`);
};
clusterOverlay.on("click", callback1);
clusterOverlay.on("click", callback2);
clusterOverlay.on("click", callback3);

// Cancel only the event response of the callback1 object. When a click event occurs, callback2 and callback3 will be called.
clusterOverlay.off('click', callback1);
// Cancel all click event responses.
clusterOverlay.off('click');

[h2]on('markerClusterClick')

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

Listens for events indicating a Marker of a ClusterOverlay is tapped. This API uses an asynchronous callback to return the result.

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

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

System capability: SystemCapability.Map.Core

Since: 5.0.3(15)

Parameters:

Name Type Mandatory Description
type string Yes 'markerClusterClick': event indicating a Marker of a ClusterOverlay is tapped.
callback Callback<MarkerClusterInfo> Yes

Callback used to return Callback<MarkerClusterInfo>. This callback is used to listen for events indicating a Marker of a ClusterOverlay is tapped.

MarkerClusterInfo includes:

- marker: Marker on a ClusterOverlay.

- clusterItems: array of cluster items.

Example:

let callback1 = (markerClusterInfo: map.MarkerClusterInfo) => {
  console.info("markerClusterClick", `callback1 markerClusterInfo`);
};
let callback2 = (markerClusterInfo: map.MarkerClusterInfo) => {
  console.info("markerClusterClick", `callback2 markerClusterInfo`);
};
let callback3 = (markerClusterInfo: map.MarkerClusterInfo) => {
  console.info("markerClusterClick", `callback3 markerClusterInfo`);
};
clusterOverlay.on("markerClusterClick", callback1);
clusterOverlay.on("markerClusterClick", callback2);
clusterOverlay.on("markerClusterClick", callback3);

[h2]off('markerClusterClick')

off(type: 'markerClusterClick', callback?: Callback<MarkerClusterInfo>): void

Cancels the listening for events indicating a Marker of a ClusterOverlay is tapped. This API uses an asynchronous callback to return the result.

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

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

System capability: SystemCapability.Map.Core

Since: 5.0.3(15)

Parameters:

Name Type Mandatory Description
type string Yes 'markerClusterClick': event indicating a Marker of a ClusterOverlay is tapped.
callback Callback<MarkerClusterInfo> No

Callback used to return Callback<MarkerClusterInfo>. This callback is used to cancel the listening for events indicating a Marker of a ClusterOverlay is tapped.

- If callback is null, cancel all callbacks.

- If callback is not null, cancel the specified callback.

MarkerClusterInfo includes:

- marker: Marker on a ClusterOverlay.

- clusterItems: array of cluster items.

Example:

let callback1 = (markerClusterInfo: map.MarkerClusterInfo) => {
  console.info("markerClusterClick", `callback1 markerClusterInfo`);
};
let callback2 = (markerClusterInfo: map.MarkerClusterInfo) => {
  console.info("markerClusterClick", `callback2 markerClusterInfo`);
};
let callback3 = (markerClusterInfo: map.MarkerClusterInfo) => {
  console.info("markerClusterClick", `callback3 markerClusterInfo`);
};
clusterOverlay.on("markerClusterClick", callback1);
clusterOverlay.on("markerClusterClick", callback2);
clusterOverlay.on("markerClusterClick", callback3);
// Cancel only the event response of the callback1 object. When a markerClusterClick event occurs, callback2 and callback3 will be called.
clusterOverlay.off('markerClusterClick', callback1);
// Cancel all markerClusterClick event responses.
clusterOverlay.off('markerClusterClick');

[h2]addItem

addItem(item: mapCommon.ClusterItem): Promise<void>

Adds a cluster item. This API uses a promise to return the result.

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

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

System capability: SystemCapability.Map.Core

Since: 5.0.0(12)

Parameters:

Name Type Mandatory Description
item mapCommon.ClusterItem Yes Cluster item.

Returns:

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

Example:

let clusterItem: mapCommon.ClusterItem = {
  position: {
    latitude: 31.98,
    longitude: 118.766
  }
};
await clusterOverlay.addItem(clusterItem);

[h2]remove

remove(): Promise<void>

Removes a ClusterOverlay. This API uses a promise to return the result.

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

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

System capability: SystemCapability.Map.Core

Since: 5.0.0(12)

Returns:

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

Example:

await clusterOverlay.remove();