GetClusterLeaves

В источниках типа geojson в Mapbox GL JS включается механизм кластеризации, позволяющий объединять близко расположенные точки в единые визуальные группы. При взаимодействии с такими группами часто требуется получить исходные объекты, входящие в конкретный кластер. Для этого используется метод getClusterLeaves, предоставляемый источником данных (GeoJSONSource).

Метод getClusterLeaves

Метод предназначен для извлечения «листьев» кластера — исходных точек, которые были агрегированы в один кластер.

Сигнатура:

source.getClusterLeaves(clusterId, limit, offset, callback);

Параметры метода

clusterId (number) Идентификатор кластера, полученный из свойства cluster_id. Используется для указания конкретного кластера, из которого необходимо извлечь элементы.

limit (number) Максимальное количество возвращаемых элементов. Используется для ограничения объёма выборки и управления производительностью при больших кластерах.

offset (number) Смещение в списке элементов кластера. Позволяет реализовать постраничную выборку (pagination), когда кластер содержит большое количество точек.

callback (function) Функция обратного вызова, которая вызывается после получения данных.

Сигнатура callback:

function(error, features)
  • error — объект ошибки, если операция завершилась неудачно
  • features — массив GeoJSON Feature объектов, входящих в кластер

Поведение метода

Метод выполняет запрос к источнику данных и возвращает исходные точки, которые были агрегированы в указанный кластер. Эти данные соответствуют исходным GeoJSON-объектам до применения алгоритма кластеризации.

Особенности поведения:

  • возвращаются только объекты внутри указанного кластера
  • порядок элементов не гарантируется
  • данные возвращаются в формате GeoJSON Feature
  • поддерживается частичная выборка через limit и offset

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

map.on('click', 'clusters-layer', (e) => {
    const features = map.queryRenderedFeatures(e.point, {
        layers: ['clusters-layer']
    });

    const clusterId = features[0].properties.cluster_id;

    const source = map.getSource('earthquakes');

    source.getClusterLeaves(clusterId, 10, 0, (err, leaves) => {
        if (err) return;

        console.log(leaves);
    });
});

В данном примере:

  • определяется клик по слою кластеров
  • извлекается cluster_id
  • запрашиваются первые 10 объектов внутри кластера

Постраничная выборка данных

При работе с крупными кластерами часто используется комбинация limit и offset.

function loadAllLeaves(source, clusterId, accumulated = [], offset = 0) {
    source.getClusterLeaves(clusterId, 100, offset, (err, leaves) => {
        if (err) return;

        accumulated.push(...leaves);

        if (leaves.length === 100) {
            loadAllLeaves(source, clusterId, accumulated, offset + 100);
        } else {
            console.log('Все элементы кластера:', accumulated);
        }
    });
}

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

Ограничения и особенности

  • Метод работает только с источниками, у которых включена кластеризация (cluster: true)
  • Доступен только после полной загрузки источника данных
  • Производительность зависит от размера кластера и глубины выборки
  • Не изменяет исходные данные, а лишь предоставляет доступ к ним

Использование в аналитике и интерфейсах

getClusterLeaves применяется в сценариях, где требуется детальный доступ к данным внутри кластера:

  • построение списков объектов при клике на кластер
  • отображение карточек отдельных точек
  • анализ плотности распределения данных
  • фильтрация и агрегация на стороне клиента

Отличие от других методов кластерного API

Mapbox GL JS предоставляет несколько методов для работы с кластерами:

  • getClusterExpansionZoom — вычисляет уровень масштабирования для раскрытия кластера
  • getClusterChildren — возвращает непосредственные дочерние элементы кластера
  • getClusterLeaves — возвращает конечные исходные точки кластера

В отличие от getClusterChildren, метод getClusterLeaves всегда возвращает именно исходные геообъекты, а не промежуточные кластеры, что делает его более затратным при больших наборах данных, но точным для детального анализа.

Обработка ошибок

Типичные ситуации, приводящие к ошибке:

  • передан несуществующий clusterId
  • источник не поддерживает кластеризацию
  • источник ещё не загружен
  • превышены ограничения по глубине выборки

Обработка ошибки выполняется через первый аргумент callback:

source.getClusterLeaves(id, 10, 0, (err, leaves) => {
    if (err) {
        console.error(err);
        return;
    }

    // обработка данных
});
Оглавление