Типы результатов

В контексте работы с Mapbox GL JS под «результатами» понимаются различные структуры данных, которые возвращаются библиотекой при взаимодействии с картой, слоями, источниками данных и внешними сервисами. Эти результаты формируются на разных уровнях: от геокодинга до выборки векторных фич и обработки событий рендеринга.

Архитектура Mapbox GL JS строится вокруг концепции слоёв (layers), источников данных (sources) и событий (events), поэтому типы результатов напрямую отражают эти сущности.

Геокодинг: результаты поиска местоположений

Одним из наиболее распространённых типов результатов являются ответы геокодера (Mapbox Geocoding API), которые используются через mapbox-gl-geocoder или прямые HTTP-запросы.

Структура результата геокодинга

Каждый результат представляет собой объект GeoJSON Feature:

{
  "id": "place.123456",
  "type": "Feature",
  "place_type": ["place"],
  "text": "Karaganda",
  "place_name": "Karaganda, Kazakhstan",
  "center": [72.9800, 49.8060],
  "geometry": {
    "type": "Point",
    "coordinates": [72.9800, 49.8060]
  },
  "properties": {}
}

Основные поля результата

place_type — тип объекта (город, адрес, POI и т.д.)
text — краткое название
place_name — полное человекочитаемое название
center — координаты центра результата
geometry — геометрия в формате GeoJSON

Особенности обработки

Результаты геокодинга:

всегда соответствуют спецификации GeoJSON Feature
могут содержать вложенные контексты (country, region, postcode)
сортируются по релевантности
могут включать bounding box для автоматического масштабирования карты

Результаты выборки объектов карты (queryRenderedFeatures)

Метод queryRenderedFeatures возвращает набор объектов, которые уже отрисованы на карте в текущем viewport.

Формат результата

const features = map.queryRenderedFeatures(point, {
  layers: ['cities-layer']
});

Результат:

[
  {
    "type": "Feature",
    "id": 42,
    "layer": {
      "id": "cities-layer",
      "type": "circle"
    },
    "source": "cities",
    "properties": {
      "name": "Karaganda",
      "population": 500000
    },
    "geometry": {
      "type": "Point",
      "coordinates": [72.98, 49.8]
    }
  }
]

Особенности rendered features

возвращаются только объекты, видимые в текущем состоянии карты
учитывают стилизацию и фильтры слоёв
зависят от zoom, pitch и bearing
включают только уже обработанные WebGL-слои

Типичные сценарии

обработка кликов по объектам карты
выделение объектов под курсором
построение интерактивных интерфейсов поверх карты

Результаты выборки исходных данных (querySourceFeatures)

Метод querySourceFeatures работает на уровне источника данных, а не рендеринга.

const features = map.querySourceFeatures('cities-source', {
  sourceLayer: 'cities'
});

Формат результата

[
  {
    "type": "Feature",
    "properties": {
      "name": "Karaganda"
    },
    "geometry": {
      "type": "Point",
      "coordinates": [72.98, 49.8]
    }
  }
]

Отличия от rendered features

Характеристика	queryRenderedFeatures	querySourceFeatures
Уровень	Рендер	Источник данных
Видимость	Только видимые	Все доступные
Учет стилей	Да	Нет
Производительность	Ниже при сложных сценах	Выше

Практическое значение

анализ данных до рендеринга
фильтрация объектов без визуального контекста
работа с большими наборами данных

Результаты событий карты (Event objects)

Mapbox GL JS генерирует множество событий, каждое из которых содержит объект результата.

Пример события click

map.on('click', (e) => {
  console.log(e);
});

Структура event object

{
  "type": "click",
  "point": { "x": 120, "y": 300 },
  "lngLat": { "lng": 72.98, "lat": 49.8 },
  "features": [
    {
      "type": "Feature",
      "properties": {
        "name": "Karaganda"
      }
    }
  ]
}

Ключевые поля

point — координаты в пикселях
lngLat — географические координаты
features — объекты под курсором
target — карта как DOM-элемент

Значение event results

Эти результаты используются для:

интерактивных интерфейсов
построения popups
динамического изменения стиля карты
маршрутизации пользовательских действий

Результаты загрузки источников (source events)

Источники данных генерируют события загрузки и обновления.

Событие `sourcedata`

map.on('sourcedata', (e) => {
  console.log(e.sourceId, e.isSourceLoaded);
});

Формат результата

{
  "type": "sourcedata",
  "sourceId": "cities-source",
  "isSourceLoaded": true,
  "dataType": "source"
}

Основные состояния

загрузка источника
обновление данных
завершение загрузки
ошибка источника

Результаты рендеринга (render results)

Рендер-события позволяют отслеживать процесс отрисовки карты.

Событие `render`

map.on('render', () => {
  console.log('frame rendered');
});

Событие `idle`

map.on('idle', () => {
  console.log('map is fully rendered');
});

Характеристика результата

Результаты рендеринга не являются геоданными. Это служебные сигналы:

завершение WebGL-прохода
стабилизация состояния карты
готовность к взаимодействию

Результаты работы фильтров и выражений

Mapbox GL JS использует expression system для вычисления динамических значений.

Пример выражения

paint: {
  'circle-radius': [
    'interpolate',
    ['linear'],
    ['get', 'population'],
    1000, 5,
    1000000, 20
  ]
}

Результат вычисления

Каждый слой получает вычисленное значение:

{
  "circle-radius": 12
}