Метод addLayer

Метод addLayer в Mapbox GL JS отвечает за добавление визуального слоя в текущий стиль карты. Слои формируют отображение географических данных поверх источников (source) и являются ключевым механизмом рендеринга векторных тайлов, GeoJSON и растровых данных.

Метод вызывается у экземпляра карты:

map.addLayer(layer, beforeId);

Параметры

layer (объект слоя) — конфигурация нового слоя. Минимально содержит:

  • id — уникальный идентификатор слоя
  • type — тип визуализации
  • source — источник данных (не всегда обязателен)
  • layout — параметры размещения и поведения
  • paint — стилизация отображения

beforeId (строка, опционально) — идентификатор слоя, перед которым вставляется новый слой. Управляет порядком отрисовки.

Требование наличия источника данных

Перед добавлением слоя почти всегда требуется регистрация источника через addSource:

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

После этого слой связывается с источником:

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

Исключения составляют некоторые слои, например background, sky, а также слои, использующие встроенные источники.

Типы слоёв

fill

Используется для отображения полигонов.

map.addLayer({
  id: 'regions',
  type: 'fill',
  source: 'states',
  paint: {
    'fill-color': '#3bb2d0',
    'fill-opacity': 0.5
  }
});

Применяется для:

  • административных границ
  • зон покрытия
  • геофенсинга

line

Отрисовка линий и контуров.

map.addLayer({
  id: 'roads',
  type: 'line',
  source: 'roads',
  paint: {
    'line-color': '#ff8800',
    'line-width': 2
  }
});

Поддерживает:

  • пунктирные линии
  • градиенты
  • переменную толщину через выражения

circle

Отображение точечных данных.

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

Используется для:

  • маркеров
  • событий
  • кластеризованных данных

symbol

Слой для текста и иконок.

map.addLayer({
  id: 'labels',
  type: 'symbol',
  source: 'places',
  layout: {
    'text-field': ['get', 'name'],
    'text-size': 14,
    'icon-image': 'marker-15'
  }
});

Поддерживает:

  • динамические подписи
  • иконки из спрайта
  • комбинированные метки

raster

Используется для тайловых изображений.

map.addLayer({
  id: 'satellite',
  type: 'raster',
  source: 'satellite'
});

Применяется для:

  • спутниковых снимков
  • тепловых карт в виде изображений

heatmap

Визуализация плотности точек.

map.addLayer({
  id: 'heat',
  type: 'heatmap',
  source: 'points',
  paint: {
    'heatmap-weight': 1,
    'heatmap-intensity': 1,
    'heatmap-color': [
      'interpolate',
      ['linear'],
      ['heatmap-density'],
      0, 'blue',
      1, 'red'
    ]
  }
});

Используется для:

  • анализа концентраций
  • визуализации активности

fill-extrusion

3D-экструзия полигонов.

map.addLayer({
  id: 'buildings',
  type: 'fill-extrusion',
  source: 'buildings',
  paint: {
    'fill-extrusion-height': ['get', 'height'],
    'fill-extrusion-color': '#aaa'
  }
});

Применяется для:

  • 3D зданий
  • объёмных карт

background

Фоновый слой стиля.

map.addLayer({
  id: 'background',
  type: 'background',
  paint: {
    'background-color': '#f0f0f0'
  }
});

Порядок слоёв и beforeId

Порядок добавления определяет визуальную иерархию. Последние добавленные слои отображаются поверх предыдущих.

Вставка перед слоем

map.addLayer(layerConfig, 'road-label');

Это позволяет точно управлять стеком отрисовки.

Типовые сценарии:

  • размещение маркеров над дорогами
  • вставка полигона под подписи
  • контроль слоёв UI

Layout и Paint свойства

Layout

Определяет структуру и поведение слоя:

  • видимость (visibility)
  • размещение текста
  • смещения и выравнивание
  • порядок иконок
layout: {
  visibility: 'visible',
  'text-field': '{name}'
}

Paint

Определяет визуальное оформление:

  • цвет
  • прозрачность
  • толщина
  • градиенты
paint: {
  'line-color': '#00ff00',
  'line-opacity': 0.8
}

Фильтрация данных слоя

Слои могут отображать только часть данных источника:

filter: ['==', ['get', 'type'], 'park']

Поддерживаются выражения:

  • логические операторы
  • сравнения
  • доступ к свойствам GeoJSON

Зависимость от масштаба

Слои могут ограничиваться диапазоном зума:

minzoom: 5,
maxzoom: 14

Это позволяет:

  • скрывать мелкие детали на глобальном уровне
  • оптимизировать производительность

Внутренний механизм добавления слоя

При вызове addLayer происходит:

  1. Проверка уникальности id
  2. Валидация схемы слоя
  3. Привязка к source
  4. Встраивание в style JSON
  5. Пересборка render tree
  6. Обновление GPU pipeline

Ошибки часто возникают при:

  • отсутствии источника
  • неверном типе слоя
  • дублировании id

Добавление слоёв после загрузки стиля

Добавление слоёв возможно только после события загрузки:

map.on('load', () => {
  map.addLayer({
    id: 'water',
    type: 'fill',
    source: 'water'
  });
});

Без этого состояния стиль может быть неинициализирован.

Управление слоями после добавления

Удаление слоя

map.removeLayer('layer-id');

Получение слоя

const layer = map.getLayer('layer-id');

Изменение свойств

map.setPaintProperty('roads', 'line-color', '#0000ff');
map.setLayoutProperty('labels', 'visibility', 'none');

Выражения в слоях

Mapbox GL JS поддерживает декларативные выражения:

paint: {
  'circle-radius': [
    'interpolate',
    ['linear'],
    ['zoom'],
    0, 2,
    10, 10
  ]
}

Применяются для:

  • масштабирования визуальных свойств
  • динамического стайлинга
  • данных, зависящих от атрибутов

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

Ключевые факторы влияния:

  • количество слоёв
  • сложность выражений
  • плотность геометрии
  • тип источника

Практика оптимизации:

  • объединение слоёв
  • использование фильтров вместо отдельных источников
  • минимизация layout-пересчётов
  • применение minzoom / maxzoom

Порядок отрисовки и стек рендеринга

Слои группируются по типам и отрисовываются в определённой последовательности:

  1. background
  2. fill
  3. line
  4. symbol
  5. circle
  6. raster / heatmap / extrusion

Внутри группы порядок определяется последовательностью addLayer.

Использование нескольких источников в одном слое

Некоторые слои поддерживают composite-источники через фильтрацию или объединение данных, но стандартный слой связывается только с одним source. Для объединения данных применяется:

  • vector tile sources
  • runtime aggregation
  • preprocessing GeoJSON

Обновление данных без пересоздания слоя

При изменении данных источника слой автоматически обновляется:

map.getSource('points').setData(newGeoJson);

addLayer при этом повторно не вызывается, что снижает нагрузку на рендеринг.

Частые ошибки использования

  • добавление слоя до загрузки стиля
  • использование несуществующего source
  • конфликт id между слоями
  • отсутствие обязательных paint свойств для некоторых типов
  • попытка изменения порядка без beforeId при добавлении

Архитектурная роль addLayer

Метод является точкой расширения визуального стиля карты. Через него формируется:

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

Он напрямую влияет на структуру style JSON, который является основой всей системы Mapbox GL JS.

Оглавление