YandexMapClusterer

Компонент подгружает модуль @yandex/ymaps3-clusterer@0.0.1, принимает в settings YandexMapClustererOptions и позволяет оптимизировать отрисовку большого числа маркеров (кластеризация).

Имейте в виду

В Vue 3 производительность отрисовки большого числа маркеров будет значительно лучше, чем в Vue 2.

В случае с этим компонентом хочется поподробнее остановиться на доступных настройках.

Настройки

gridSize

По умолчанию: 64. Будет передан в settings.method в случае, если вы не заменили method чем-то своим.

Значение влияет на то, как будут группироваться маркеры на карте, а точнее - на охват группировки. Чем выше - тем больше маркеров будут объединяться в группы.

INFO

В параметр советуется передавать значения, кратные степеням двойки: 32, 64, 128 и пр.

С другими значениями он не испытывался.

clusterMarkerProps

Настройка позволяет указать параметры для маркера, в котором рисуется кластер.

Принимает то же самое, что и settings в YandexMapMarker, кроме coordinates.

Кроме того, настройка принимает все остальные настройки YandexMapMarker (position и пр.).

Для кластеров, position по умолчанию равен left-center top-center (так как обычно кластеры являются кружками). Вы можете изменить это поведение, передав, например, cluster-marker-props="{ position: 'default' }"

zoomOnClusterClick

При клике на кластер автоматически произойдёт зум в область маркеров (feature), входящих в него - почти как в Яндекс Картах 2.0.

Из-за поведения Яндекса в зум встроена логика, высчитывающая область таким образом, чтобы маркеры в ней точно не пропали, добавляя отступы для области на основе максимального расстояния между углами области.

Пропс принимает boolean или объект (см. ниже).

Совет

Событие trueBounds будет возвращаться всегда - даже если эта настройка выключена. Используйте их, чтобы реализовать эту функциональность самостоятельно.

Также сделать такое же поведение можно, используя объект clusterer.features из слота #cluster.

Настройки (когда объект)

• duration (по умолчанию: 500)

• easing (то же самое, что и в location)

• strategy:

  • zoomCorrect (по умолчанию): значение zoom дополнительно корректируется в целочисленное значение (в меньшую сторону).

    Так сделано в связи с найденной закономерностью, что Яндекс иногда скрывает маркеры при приближении к границам карты, но только не для целочисленных значений зума.

  • boundsCorrect: в данном сценарии из границ просто вычитается расстояние между верхним левым и нижним правым их углом для формирования большей области зума.

• disableMinimalZoomCorrectDiff: по умолчанию при стратегии zoomCorrect, если точки слишком близко к краям, зум дополнительно корректируется для удобства пользователя.

  Однако, это поведение может работать неправильно при больших gridSize. Этой настройкой вы можете это отключить.

settings

method

Передавать его требуется только в том случае, если вам требуется изменить метод отрисовки своей рендер-функцией. Если вы не передадите этот параметр, отрисовка будет работать автоматически на основе пропса gridSize и метода clusterByGrid от Яндекса.

tickTimeout

Из документации Яндекса: время, которое пройдёт перед тем, как случится ререндер.

Или, если перефразировать: время между ре-рендерами.

onRender

Метод, который будет вызываться перед каждой новой отрисовкой. Принимает аргумент с массивом ClustererObject.

Если вы вернёте в нём false, отрисовка выполнена не будет.

maxZoom

Если зум карты превышает maxZoom, маркеры будут выведены как-есть (без кластеризации).

features, marker, cluster

Если вы посмотрите в документацию Яндекса, там также будут вышеуказанные параметры. В нашей обертке, передавать их не требуется - они передадутся в Яндекса автоматически.

События

Помимо стандартного v-model, компонент возвращает:

trueBounds

Возвращается при клике на кластер и содержит точную область всех маркеров (feature), входящих в него.

updatedBounds

Возвращается при клике на кластер при включённой настройке zoomOnClusterClick и содержит скорректированную область, где:

• Для strategy zoomCorrect (по умолчанию) приходят скорректированные для целочисленного значения zoom границы (в этом случае событие приходит с задержкой)
• Для strategy boundsCorrect вычтено расстояние между верхним левым и нижним правым углом границ

Слоты

default

Слот с набором компонентов для отрисовки. Тестировался только с YandexMapMarker.

Для переданных в слот маркеров также будет автоматически задан случайно сгенерированный id, если он не был задан вами.

cluster

Слот с кластером. Под капотом представляет собой YandexMapMarker.

В слот передаются:

• clusterer: ClustererObject
• coordinates: clusterer.coordinates
• length: clusterer.features.length (число элементов в кластере)

Совет

Вы можете кастомизировать настройки маркера кластера параметром clusterMarkerProps.

Примеры использования

Простейший пример

<template>
  <yandex-map :settings="{ location }">
    <yandex-map-default-features-layer/>
    <yandex-map-default-scheme-layer/>

    <!-- Активируем зум при клике на #cluster -->
    <yandex-map-clusterer zoom-on-cluster-click>
      <yandex-map-marker
          v-for="(coordinates, index) in markers"
          :key="index"
          :settings="{ coordinates }"
      >
        <div class="hint">
          Cluster Marker #{{ index }}
        </div>
      </yandex-map-marker>

      <!-- Тут также есть clusterer и coordinates -->
      <template #cluster="{ length }">
        <div class="cluster">
          {{ length }}
        </div>
      </template>
    </yandex-map-clusterer>
  </yandex-map>
</template>

См. также: Кластеризатор маркеров