Параметры id, type, source

В Mapbox GL JS каждый слой карты представляет собой самостоятельную сущность, которая должна быть однозначно идентифицируема внутри стиля. Для этого используется параметр id. Он задаёт уникальное строковое имя слоя и выполняет роль ключа, по которому система обращается к конкретному слою в дереве рендеринга.

Основные свойства идентификатора:

  • Уникальность в пределах стиля — два слоя не могут иметь одинаковый id
  • Неизменяемость после добавления — при создании слоя идентификатор фиксируется
  • Использование в API — через id осуществляется добавление, удаление, вставка и обновление слоя

При работе с большим количеством слоёв важно соблюдать строгую систему именования, иначе управление стилем становится затруднительным.

Пример добавления слоя с идентификатором:

map.addLayer({
  id: 'roads-primary',
  type: 'line',
  source: 'openmaptiles'
});

Идентификатор используется также в методах управления порядком слоёв:

map.moveLayer('roads-primary', 'water-label');
map.removeLayer('roads-primary');

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

Параметр type

Параметр type определяет визуальную и логическую природу слоя. Он задаёт способ интерпретации данных из источника и метод их отрисовки. В Mapbox GL JS тип слоя напрямую влияет на допустимые свойства и поведение рендеринга.

Основные типы слоёв:

  • fill — заливка полигонов
  • line — линии (дороги, границы, маршруты)
  • symbol — текстовые и иконографические метки
  • circle — точечные объекты в виде кругов
  • fill-extrusion — 3D-экструзии зданий
  • raster — растровые тайлы
  • heatmap — тепловые карты
  • hillshade — рельеф
  • background — фон стиля

Каждый тип слоя определяет доступный набор paint- и layout-свойств. Например, у circle есть параметры радиуса и цвета, а у line — ширина и шаблон штриха.

Пример слоя типа circle:

map.addLayer({
  id: 'earthquakes',
  type: 'circle',
  source: 'earthquakes-data',
  paint: {
    'circle-radius': 6,
    'circle-color': '#ff0000'
  }
});

Пример слоя типа fill:

map.addLayer({
  id: 'countries-fill',
  type: 'fill',
  source: 'countries',
  paint: {
    'fill-color': '#0080ff',
    'fill-opacity': 0.5
  }
});

Выбор type определяет не только внешний вид, но и семантику слоя, поэтому ошибка в типе приводит к некорректному отображению или игнорированию свойств.

Параметр source

Параметр source указывает источник данных, из которого слой получает геометрические и атрибутивные данные. В Mapbox GL JS источники объявляются отдельно от слоёв и могут переиспользоваться.

source связывает слой с объектом данных, который может быть:

  • векторным (vector)
  • растровым (raster)
  • GeoJSON (geojson)
  • тайловым набором
  • изображением или видео

Источники регистрируются через addSource:

map.addSource('cities', {
  type: 'geojson',
  data: 'https://example.com/cities.geojson'
});

После этого слой может ссылаться на источник по его имени:

map.addLayer({
  id: 'cities-points',
  type: 'circle',
  source: 'cities'
});

Важные особенности source

1. Множественное использование Один источник может использоваться несколькими слоями одновременно:

map.addLayer({
  id: 'cities-points',
  type: 'circle',
  source: 'cities'
});

map.addLayer({
  id: 'cities-labels',
  type: 'symbol',
  source: 'cities'
});

Это позволяет разделять визуальные представления одной и той же геометрии.

2. Типизация источника

Тип источника должен соответствовать способу интерпретации данных. Например:

  • geojson — для динамических данных и локальных объектов
  • vector — для предзагруженных тайловых наборов
  • raster — для изображений и тайловых слоёв

Пример векторного источника:

map.addSource('composite', {
  type: 'vector',
  url: 'mapbox://mapbox.mapbox-streets-v8'
});

3. Ограничения связи source и type слоя

Не каждый type слоя может работать с любым source. Существует строгая совместимость:

  • fill, line, symbol, circle → vector, geojson
  • raster → только raster
  • heatmap → geojson
  • fill-extrusion → vector, geojson

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

Связь между id, type и source

Эти три параметра формируют базовую структуру любого слоя в Mapbox GL JS:

  • id отвечает за идентификацию и управление
  • type определяет способ визуализации
  • source предоставляет данные для отрисовки

Их взаимодействие можно представить как три уровня:

  • Идентичность слоя (id)
  • Логика отображения (type)
  • Данные (source)

Пример полной связки:

map.addSource('earthquakes', {
  type: 'geojson',
  data: '/data/earthquakes.geojson'
});

map.addLayer({
  id: 'earthquake-circles',
  type: 'circle',
  source: 'earthquakes',
  paint: {
    'circle-radius': 8,
    'circle-color': '#ff5722'
  }
});

Порядок добавления и зависимости

При работе с Mapbox GL JS критично соблюдать порядок:

  1. Сначала добавляется source
  2. Затем добавляется layer, использующий этот источник

Попытка создать слой без существующего источника приводит к ошибке выполнения.

// корректный порядок
map.addSource('data', {...});

map.addLayer({
  id: 'layer',
  type: 'circle',
  source: 'data'
});

Также важно учитывать порядок слоёв в стиле: слои рендерятся строго сверху вниз в порядке их добавления, если не используется beforeId.

Манипуляции через id в связке со source и type

Комбинация параметров позволяет выполнять точечные операции над визуализацией:

  • изменение типа слоя через удаление и повторное создание
  • переключение источника данных без изменения визуальной логики
  • динамическое обновление GeoJSON через setData

Пример обновления источника:

map.getSource('cities').setData(newData);

В этом случае type и id остаются неизменными, меняется только содержимое source, что обеспечивает стабильность визуальной структуры карты.

Оглавление