输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
文档管理中心
全部文档版本说明工具设计指南与API参考开发与测试上架分发与运营问题处理与运维最佳实践行业解决方案
指南与API参考
指南
API
高级筛选
API version全部版本
设备全部
元服务API集不筛选
您当前正在浏览HarmonyOS最新文档，覆盖已发布的所有API版本，可在API参考中筛选您使用的API版本。详细的版本配套关系请参考版本说明。
指南与API参考API参考应用服务Map Kit（地图服务）ArkTS APImap（地图显示功能）Interface (ClusterOverlay)

Interface (ClusterOverlay)

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+Wearable5.1.0(18)+
更新时间: 2026-09-04 10:41
复制页面
本文导读
展开章节

导入模块

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

ClusterOverlay

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+Wearable5.1.0(18)+

聚合图层类。ClusterOverlay用于在地图上展示聚合后的标记点，以优化大量标记点显示时的性能和用户体验。它将地理位置相近的多个标记点合并为一个聚合点，并支持点击聚合点展开查看具体标记点。适用于展示大量POI数据、避免地图过于拥挤的情况。在调用map.MapComponentController类的addClusterOverlay方法时会返回该类型的实例。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Map.Core

起始版本： 5.0.0(12)

示例：

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

on('clusterClick')

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+Wearable5.1.0(18)+

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

监听cluster的点击事件。使用callback异步回调。

建议使用ClusterOverlay.on(type: 'click')。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Map.Core

起始版本： 5.0.0(12)

参数：

展开
参数名 类型 必填 说明
type string 是 'clusterClick'：聚合图层的聚合点点击监听事件。
callback Callback<Array<mapCommon.ClusterItem>> 是 回调函数，返回Array<mapCommon.ClusterItem>。

示例：

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

off('clusterClick')

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+Wearable5.1.0(18)+

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

取消监听cluster的点击事件。使用callback异步回调。

建议使用ClusterOverlay.off(type: 'click')。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Map.Core

起始版本： 5.0.0(12)

参数：

展开
参数名 类型 必填 说明
type string 是 'clusterClick'：聚合图层的聚合点点击监听事件。
callback Callback<void> 否 回调函数，无返回结果。

示例：

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

on('click')

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+Wearable5.1.0(18)+

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

监听聚合图层的聚合点点击事件。支持传递多个callback异步回调。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Map.Core

起始版本： 5.0.0(12)

参数：

展开
参数名 类型 必填 说明
type string 是 'click'：监听聚合图层的聚合点点击事件。
callback Callback<Array<mapCommon.ClusterItem>> 是 回调函数，返回Array<mapCommon.ClusterItem>，监听聚合图层的聚合点点击事件。

示例：

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

off('click')

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+Wearable5.1.0(18)+

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

取消监听聚合图层的聚合点点击事件。支持传递多个callback异步回调。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Map.Core

起始版本： 5.0.0(12)

参数：

展开
参数名 类型 必填 说明
type string 是 'click'：监听聚合图层的聚合点点击事件。
callback Callback<Array<mapCommon.ClusterItem>> 否

回调函数，返回Array<mapCommon.ClusterItem>，取消监听聚合图层的聚合点点击事件。

- callback为空：取消所有callback回调。

- callback非空：取消指定的callback回调。

示例：

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

// 只取消callback1对象的事件响应，当click事件发生时，callback2和callback3会正常被调用
clusterOverlay.off('click', callback1);
// 取消全部click事件响应
clusterOverlay.off('click');

on('markerClusterClick')

Phone5.0.3(15)+PC/2in15.0.3(15)+Tablet5.0.3(15)+Wearable5.1.0(18)+

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

监听聚合图层的标记点击事件。使用callback异步回调。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本5.0.3(15)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Map.Core

起始版本： 5.0.3(15)

参数：

展开
参数名 类型 必填 说明
type string 是 'markerClusterClick'：聚合图层的标记点击监听事件。
callback Callback<MarkerClusterInfo> 是

回调函数，返回Callback<MarkerClusterInfo>，监听聚合图层的标记点击事件。

MarkerClusterInfo包括：

- marker：聚合图层的标记。

- clusterItems：聚合节点数组。

示例：

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

off('markerClusterClick')

Phone5.0.3(15)+PC/2in15.0.3(15)+Tablet5.0.3(15)+Wearable5.1.0(18)+

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

取消监听聚合图层的标记点击事件。使用callback异步回调。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本5.0.3(15)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Map.Core

起始版本： 5.0.3(15)

参数：

展开
参数名 类型 必填 说明
type string 是 'markerClusterClick'：聚合图层的标记点击监听事件。
callback Callback<MarkerClusterInfo> 否

回调函数，返回Callback<MarkerClusterInfo>，取消监听聚合图层的标记点击事件。

- callback为空：取消所有callback回调。

- callback非空：取消指定的callback回调。

MarkerClusterInfo包括：

- marker：聚合图层的标记。

- clusterItems：聚合节点数组。

示例：

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);
// 只取消callback1对象的事件响应，当markerClusterClick事件发生时，callback2和callback3会正常被调用
clusterOverlay.off('markerClusterClick', callback1);
// 取消全部markerClusterClick事件响应
clusterOverlay.off('markerClusterClick');

addItem

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+Wearable5.1.0(18)+

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

新增聚合节点。使用Promise异步回调。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Map.Core

起始版本： 5.0.0(12)

参数：

展开
参数名 类型 必填 说明
item mapCommon.ClusterItem 是 待聚合节点。

返回值：

展开
类型 说明
Promise<void> Promise对象。无返回结果的Promise对象。

示例：

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

remove

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+Wearable5.1.0(18)+

remove(): Promise<void>

移除聚合图层。使用Promise异步回调。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Map.Core

起始版本： 5.0.0(12)

返回值：

展开
类型 说明
Promise<void> Promise对象。无返回结果的Promise对象。

示例：

await clusterOverlay.remove();
Class (AnimationSet)
Interface (ImageOverlay)
简体中文
华为开发者联盟 版权所有 ©2026
问题反馈
使用条款
华为开发者联盟用户协议
关于华为开发者联盟与隐私的声明
Cookies
开源软件声明