概览
本教程介绍了如何利用标记聚类在地图上显示大量标记。您可以将 @googlemaps/markerclusterer 库与 Maps JavaScript API 配合使用，并将邻近标记合并成聚类，以简化标记在地图上的显示方式。
若要了解标记聚类的运作方式，请查看下面的地图。
聚类上的数字表示其包含的标记数量。请注意，在放大任何聚类位置时，聚类上的数字都会减少，其中的各个标记会逐渐显示在地图上。缩小地图会将标记再次合并成聚类。
以下示例显示了创建此地图所需的完整代码。
TypeScript
function initMap(): void {
const map = new google.maps.Map(
document.getElementById("map") as HTMLElement,
{
zoom: 3,
center: { lat: -28.024, lng: 140.887 },
}
);
const infoWindow = new google.maps.InfoWindow({
content: "",
disableAutoPan: true,
});
// Create an array of alphabetical characters used to label the markers.
const labels = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
// Add some markers to the map.
const markers = locations.map((position, i) => {
const label = labels[i % labels.length];
const marker = new google.maps.Marker({
position,
label,
});
// markers can only be keyboard focusable when they have click listeners
// open info window when marker is clicked
marker.addListener("click", () => {
infoWindow.setContent(label);
infoWindow.open(map, marker);
});
return marker;
});
// Add a marker clusterer to manage the markers.
new MarkerClusterer({ markers, map });
}
const locations = [
{ lat: -31.56391, lng: 147.154312 },
{ lat: -33.718234, lng: 150.363181 },
{ lat: -33.727111, lng: 150.371124 },
{ lat: -33.848588, lng: 151.209834 },
{ lat: -33.851702, lng: 151.216968 },
{ lat: -34.671264, lng: 150.863657 },
{ lat: -35.304724, lng: 148.662905 },
{ lat: -36.817685, lng: 175.699196 },
{ lat: -36.828611, lng: 175.790222 },
{ lat: -37.75, lng: 145.116667 },
{ lat: -37.759859, lng: 145.128708 },
{ lat: -37.765015, lng: 145.133858 },
{ lat: -37.770104, lng: 145.143299 },
{ lat: -37.7737, lng: 145.145187 },
{ lat: -37.774785, lng: 145.137978 },
{ lat: -37.819616, lng: 144.968119 },
{ lat: -38.330766, lng: 144.695692 },
{ lat: -39.927193, lng: 175.053218 },
{ lat: -41.330162, lng: 174.865694 },
{ lat: -42.734358, lng: 147.439506 },
{ lat: -42.734358, lng: 147.501315 },
{ lat: -42.735258, lng: 147.438 },
{ lat: -43.999792, lng: 170.463352 },
];
declare global {
interface Window {
initMap: () => void;
}
}
window.initMap = initMap;
JavaScript
function initMap() {
const map = new google.maps.Map(document.getElementById("map"), {
zoom: 3,
center: { lat: -28.024, lng: 140.887 },
});
const infoWindow = new google.maps.InfoWindow({
content: "",
disableAutoPan: true,
});
// Create an array of alphabetical characters used to label the markers.
const labels = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
// Add some markers to the map.
const markers = locations.map((position, i) => {
const label = labels[i % labels.length];
const marker = new google.maps.Marker({
position,
label,
});
// markers can only be keyboard focusable when they have click listeners
// open info window when marker is clicked
marker.addListener("click", () => {
infoWindow.setContent(label);
infoWindow.open(map, marker);
});
return marker;
});
// Add a marker clusterer to manage the markers.
new MarkerClusterer({ markers, map });
}
const locations = [
{ lat: -31.56391, lng: 147.154312 },
{ lat: -33.718234, lng: 150.363181 },
{ lat: -33.727111, lng: 150.371124 },
{ lat: -33.848588, lng: 151.209834 },
{ lat: -33.851702, lng: 151.216968 },
{ lat: -34.671264, lng: 150.863657 },
{ lat: -35.304724, lng: 148.662905 },
{ lat: -36.817685, lng: 175.699196 },
{ lat: -36.828611, lng: 175.790222 },
{ lat: -37.75, lng: 145.116667 },
{ lat: -37.759859, lng: 145.128708 },
{ lat: -37.765015, lng: 145.133858 },
{ lat: -37.770104, lng: 145.143299 },
{ lat: -37.7737, lng: 145.145187 },
{ lat: -37.774785, lng: 145.137978 },
{ lat: -37.819616, lng: 144.968119 },
{ lat: -38.330766, lng: 144.695692 },
{ lat: -39.927193, lng: 175.053218 },
{ lat: -41.330162, lng: 174.865694 },
{ lat: -42.734358, lng: 147.439506 },
{ lat: -42.734358, lng: 147.501315 },
{ lat: -42.735258, lng: 147.438 },
{ lat: -43.999792, lng: 170.463352 },
];
window.initMap = initMap;
CSS
/*
* Always set the map height explicitly to define the size of the div element
* that contains the map.
*/
#map {
height: 100%;
}
/*
* Optional: Makes the sample page fill the window.
*/
html,
body {
height: 100%;
margin: 0;
padding: 0;
}
HTML
<html>
<head>
<title>Marker Clustering</title>
<script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>
<link rel="stylesheet" type="text/css" href="./style.css" />
<script type="module" src="./index.js"></script>
</head>
<body>
<div id="map"></div>
<!--
The `defer` attribute causes the callback to execute after the full HTML
document has been parsed. For non-blocking uses, avoiding race conditions,
and consistent behavior across browsers, consider loading using Promises
with https://www.npmjs.com/package/@googlemaps/js-api-loader.
-->
<script
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
defer
></script>
</body>
</html>
试用示例
为便于说明，本教程利用 locations 数组向地图添加了一组标记。您可以从其他来源获取地图标记。如需了解详情，请参阅创建标记指南。
添加标记聚类器
请按以下步骤添加标记聚类器：
- 将标记聚类库添加到网页或应用中。该库可在 NPM（地址为 @googlemaps/markerclusterer）以及 GitHub 上的代码库中找到。
NPM
使用 NPM 安装最新版本的 @googlemaps/markerclusterer 库。
npm install @googlemaps/markerclusterer
CDN
以下脚本会从 unpkg.com CDN 加载该库最新的 1.x.x 版本。
<script src="https://unpkg.com/@googlemaps/markerclusterer/dist/index.min.js"></script>
- 在应用中添加标记聚类器。
以下代码用于向地图添加标记聚类器。
NPM
import { MarkerClusterer } from "@googlemaps/markerclusterer"; const markerCluster = new MarkerClusterer({ map, markers });CDN
使用 CDN 访问时，该库可在
markerClusterer全局下找到。const markerCluster = new markerClusterer.MarkerClusterer({ map, markers });此示例将
markers数组传递给MarkerClusterer。 - 自定义标记聚类器。
- 通过渲染程序接口自定义聚类图标。
- 修改用于生成聚类的算法。
了解详情
您可以在 GitHub 上的代码库中查看更复杂的标记聚类示例，并查看该库的参考文档。