---
title: "<ScriptGoogleMapsMarkerClusterer>"
description: "将附近的高级标记分组，并自定义其聚类渲染方式。"
canonical_url: "https://nuxt-scripts.zhcndoc.com/scripts/google-maps/api/marker-clusterer"
last_updated: "2026-08-11T09:33:14.561Z"
---

在较低缩放级别下，将附近的标记分组成聚类。将其放置在 [`<ScriptGoogleMaps>`](/scripts/google-maps/api/script-google-maps) 组件内。Google 的[标记聚类指南](https://developers.google.com/maps/documentation/javascript/marker-clustering)介绍了该库及其无障碍设计理念。

<script-types filter="ScriptGoogleMapsMarkerClusterer" script-key="google-maps">



</script-types>

## 安装

需要 `@googlemaps/markerclusterer` 作为对等依赖：

```bash
pnpm add @googlemaps/markerclusterer
```

## 用法

子标记会自动注册和注销自身。

```vue
<script setup lang="ts">
const locations = ref([
  { id: 1, name: 'Sydney Opera House', position: { lat: -33.8568, lng: 151.2153 } },
  { id: 2, name: 'Bondi Beach', position: { lat: -33.8908, lng: 151.2743 } },
  { id: 3, name: 'Taronga Zoo', position: { lat: -33.8433, lng: 151.2411 } },
])
</script>

<template>
  <ScriptGoogleMaps
    api-key="your-api-key"
    :map-options="{
      center: { lat: -33.86, lng: 151.24 },
      zoom: 12,
    }"
  >
    <ScriptGoogleMapsMarkerClusterer>
      <ScriptGoogleMapsMarker
        v-for="location in locations"
        :key="location.id"
        :position="location.position"
      >
        <ScriptGoogleMapsInfoWindow>
          <div>{{ location.name }}</div>
        </ScriptGoogleMapsInfoWindow>
      </ScriptGoogleMapsMarker>
    </ScriptGoogleMapsMarkerClusterer>
  </ScriptGoogleMaps>
</template>
```

### 动态标记

通过响应式方式添加或移除的标记（例如通过 `v-for` 使用变化的列表）会自动向聚类器注册或从聚类器注销。

```vue
<script setup lang="ts">
const locations = ref([/* 初始位置 */])

function addLocation(position: google.maps.LatLngLiteral) {
  locations.value.push({ id: Date.now(), name: 'New', position })
}
</script>

<template>
  <ScriptGoogleMaps api-key="your-api-key">
    <ScriptGoogleMapsMarkerClusterer>
      <ScriptGoogleMapsMarker
        v-for="loc in locations"
        :key="loc.id"
        :position="loc.position"
      />
    </ScriptGoogleMapsMarkerClusterer>
  </ScriptGoogleMaps>
</template>
```

### 自定义算法

通过 `options` 传递 `algorithm` 来自定义聚类行为。查看 [`@googlemaps/markerclusterer` 文档](https://googlemaps.github.io/js-markerclusterer/) 了解可用算法。

该组件会在创建聚类器时读取 `options`，之后不会再监听该属性。要在运行时更改算法或其他聚类器选项，请重新挂载组件。

```vue
<script setup lang="ts">
import { SuperClusterAlgorithm } from '@googlemaps/markerclusterer'

const clustererOptions = {
  algorithm: new SuperClusterAlgorithm({ radius: 200 }),
}
</script>

<template>
  <ScriptGoogleMaps api-key="your-api-key">
    <ScriptGoogleMapsMarkerClusterer :options="clustererOptions">
      <ScriptGoogleMapsMarker
        v-for="loc in locations"
        :key="loc.id"
        :position="loc.position"
      />
    </ScriptGoogleMapsMarkerClusterer>
  </ScriptGoogleMaps>
</template>
```

### 自定义聚类渲染器

使用 `#renderer` 插槽通过 Vue 模板自定义聚类的外观。该插槽接收 `cluster`（包含 `count`、`position`、`markers`）、`stats` 和 `map`（Google Maps 实例）。

```vue
<template>
  <ScriptGoogleMaps api-key="your-api-key">
    <ScriptGoogleMapsMarkerClusterer>
      <template #renderer="{ cluster }">
        <div
          style="
            background: #4285f4;
            color: white;
            border-radius: 50%;
            width: 40px;
            height: 40px;
            display: flex;
            align-items: center;
            justify-content: center;
            font-weight: bold;
          "
        >
          {{ cluster.count }}
        </div>
      </template>

      <ScriptGoogleMapsMarker
        v-for="loc in locations"
        :key="loc.id"
        :position="loc.position"
      />
    </ScriptGoogleMapsMarkerClusterer>
  </ScriptGoogleMaps>
</template>
```

`#renderer` 插槽会覆盖 `renderer` 选项。每个聚类都会获得自己的 `AdvancedMarkerElement`，并将插槽内容作为其视觉表现。

<callout>

聚类器仅在实例就绪后才渲染其默认插槽。这可防止子标记在聚类器能够接收它们之前挂载。

</callout>