MarkerCluster

AMap.MarkerCluster

Used to display a large number of point markers, clustering them by distance to improve rendering performance. Point clustering supports user-defined styles and is called as a plugin. Construct a point cluster object and set its properties through MarkerClusterOptions

new AMap.MarkerCluster(map: Map, dataOptions: Array, MarkerClusterOptions: Object)

Tutorial

Parameter

map (Map) The map object to which point clustering needs to be added

dataOptions (Array) The point data that needs to be displayed in clusters

Attribute	Type	Description
lnglat	Array	The latitude and longitude information of the point markers
weight	number	The weight information of the point markers, clustering around the point with the highest weight

MarkerClusterOptions (Object) Point aggregation property settings

Attribute	Type	Description
gridSize	Number	The pixel size of the grid during aggregation calculation. Default is 60
maxZoom	Number	The maximum aggregation level. Aggregation is not performed above this level. The default value is 18, meaning that map markers will aggregate when the zoom level is 18 or below. Once you zoom in beyond level 18, markers will no longer aggregate and will be displayed directly
averageCenter	Boolean	Whether the icon position of the aggregation point is the center of all points within the aggregation. Default is true. If the data contains weight values, the point with the highest weight is used as the center for aggregation
clusterByZoomChange	Boolean	Whether to aggregate during map zooming. Default is false
styles	Array<Object>	Specifies the icon style of the point markers after clustering, which can be omitted. When omitted, the default style is used. This property becomes invalid when there are valid renderClusterMarker and renderMarker settings. The data elements correspond to the styles of cluster points with aggregation amounts of 1-10, 11-100, 101-1000… respectively; When the number of cluster styles set by the user is less than the actual number of overlapping points, the unset parts will be displayed according to the system default style; The style of a single icon includes the following properties: 1. {string} url: the URL address of the image displayed by the icon (required) 2. {AMap.Size} size: the size of the image displayed by the icon (required) 3. {AMap.Pixel} offset: the offset value of the icon's position on the map relative to the top-left corner of the icon. Default is (0,0), no offset (optional) 4. {AMap.Pixel} imageOffset: the offset value of the image relative to the visible area, the function of which is equivalent to the background-position property in CSS. Default is (0,0), no offset (optional) 5. {String} textColor: the color of the text, default is "#000000" (optional) 6. {Number} textSize: the size of the text, default is 10 (optional)
renderClusterMarker	function	This method is used to implement custom drawing of cluster points, which is implemented by the developer themselves. The API will call this method when drawing each cluster point, allowing for flexible setting of cluster point styles. Once renderClusterMarker is specified, styles become invalid. The input parameter of this function is an Object, which contains the following properties: 1. count: the number of Markers aggregated under the current cluster point 2. marker: the Marker displayed at the current cluster point
renderMarker	function	This method is used to implement custom drawing of non-clustered points, which is implemented by the developer themselves. The API will call this method when drawing each non-clustered point. The input parameter of this function is an Object, containing the following properties: marker: Non-clustered Marker object

Demo

// The data format is an array containing latitude and longitude information, as shown below. Among them, [latitude and longitude] lnglat is a required field, and [weight] weight is an optional field.
var points = [
  { weight: 8, lnglat: ["108.939621", "34.343147"] },
  { weight: 1, lnglat: ["112.985037", "23.15046"] },
  { weight: 1, lnglat: ["110.361899", "20.026695"] },
  { weight: 1, lnglat: ["121.434529", "31.215641"] },
];
// Load point cluster plugin
map.plugin(["AMap.MarkerCluster"], function () {
  var cluster = new AMap.MarkerCluster(map, points, {
    gridSize: 80, // Cluster grid pixel size
  });
});

Method

addData(dataOptions)

Add data based on the original data, with the same format as dataOptions

Parameter: dataOptions (dataOptions) Added data, such as: [{ weight: 1, lnglat: [\"116.105381\", \"39.937183\"] }, ...]

Demo:

cluster.addData([{ weight: 1, lnglat: ["116.195445", "39.914601"] }]);

setData(dataOptions)

Set cluster point data, this method will reset the original data, the format is the same as dataOptions

Parameter: dataOptions (dataOptions) Set data, such as: [{ weight: 1, lnglat: [\"116.105381\", \"39.937183\"] }, ...]

Demo:

cluster.setData([{ weight: 1, lnglat: ["116.195445", "39.914601"] }]);

getClustersCount()

Get the total number of aggregation points at the current zoom level

return value: (Number) Total number of aggregation points

Demo:

cluster.getClustersCount();

getGridSize()

Set the pixel size of the aggregation grid

return value: (Number) Pixel size of the aggregation grid

Demo:

cluster.getGridSize();

setGridSize(size)

Get the pixel size of the aggregation grid

Parameter: size(Number) Pixel Size

Demo:

cluster.setGridSize(40);

getMaxZoom()

Get the Maximum Aggregation Level of Point Markers on the Map

return value: (Number) Maximum Aggregation Level of Point Markers

Demo:

cluster.getMaxZoom();

setMaxZoom(zoom)

Set the Maximum Aggregation Level of Point Markers on the Map

Parameter: zoom (Number) Maximum Aggregation Level

Demo:

cluster.setMaxZoom(18);

setStyles(Map)

Set the style aggregation point of the styles attribute, the format is the same as opts.styles, this attribute is invalid when there are valid renderClusterMarker and renderMarker settings

Parameter: Map (Array<Object>) Icon style

Demo:

cluster.setStyles([
  {
    //The style of the aggregation point when the aggregation quantity is 1-10
    url: "//a.amap.com/jsapi_demos/static/images/blue.png", //The address of the image displayed by the icon
    size: new AMap.Size(32, 32), //The size of the image displayed by the icon
    offset: new AMap.Pixel(-16, -16), //The offset value of the icon's position on the map relative to the upper-left corner of the icon
    textColor: "#fff", //The color of the text
  },
  {
    //The style of aggregation points when the aggregation quantity is between 11-100
    url: "//a.amap.com/jsapi_demos/static/images/green.png",
    size: new AMap.Size(32, 32),
    offset: new AMap.Pixel(-16, -16),
    textColor: "#fff",
  },
  {
    //The style of aggregation points when the aggregation quantity is between 101-1000
    url: "//a.amap.com/jsapi_demos/static/images/orange.png",
    size: new AMap.Size(36, 36),
    offset: new AMap.Pixel(-18, -18),
  },
]);

getStyles()

Get the icon style of point marker set by styles

return value: (Array<Object>) Icon style of point marker

Demo:

cluster.getStyles();

getMap()

Get map object

return value: (Map) Map object

Demo:

cluster.getMap();

setMap(Map)

Set map object

Parameter: Map (Map) Map object

Demo:

cluster.setMap(map);

isAverageCenter()

Get whether the position of a single cluster point is the average center of all markers within the cluster

return value: (Boolean) Boolean value

Demo:

cluster.isAverageCenter();

setAverageCenter(averageCenter)

Set whether the cluster point position is the center of all cluster points

Parameter: averageCenter (Boolean) If set to true, the average position of all internal markers will be calculated, and the position of the cluster point will be updated to this average position. If set to false, the position of the cluster point will not be set to the average center of all internal markers

Demo:

cluster.setAverageCenter(true);

Event

Event Name

Description

click

Click event

cluster: Clicked cluster point object

lnglat: Coordinates of the clicked point

target: Cluster plugin object

marker: Point objects included in the clicked cluster point

cluster.on("click", (data) => {
  console.log(data);
  //data.cluster: Clicked cluster point object
  //data.lnglat: Coordinates of the clicked point
  //data.target: Cluster plugin object
  //data.marker: Point objects included in the clicked cluster point
});

For event object property descriptions, go to:MapsEvent