Основные функции

Mapbox GL JS представляет собой библиотеку для рендеринга интерактивных карт на WebGL, где ключевой функцией выступает создание экземпляра карты и управление его состоянием через конфигурационный объект.

Основная точка входа — создание объекта карты:

mapboxgl.accessToken = 'YOUR_ACCESS_TOKEN';

const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/streets-v12',
  center: [69.2401, 53.2144],
  zoom: 10
});

Ключевые параметры и их назначение:

  • container — DOM-элемент, в котором отображается карта
  • style — стиль карты (векторные тайлы, JSON-стили Mapbox Style Specification)
  • center — координаты центра [lng, lat]
  • zoom — уровень масштабирования
  • pitch — наклон камеры (3D-эффекты)
  • bearing — поворот карты

Именно этот объект становится центральной точкой управления всей логикой отображения.

Работа со стилями карты

Система стилей является фундаментальной частью архитектуры Mapbox GL JS. Стиль определяет визуальное представление слоёв, источников данных и фильтров.

Изменение стиля выполняется динамически:

map.setStyle('mapbox://styles/mapbox/dark-v11');

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

map.on('style.load', () => {
  // повторное добавление слоёв и источников
});

Основные особенности системы стилей:

  • Полная декларативность (JSON)
  • Поддержка условного рендеринга
  • Возможность динамического изменения через API
  • Разделение источников данных и визуального представления

Источники данных (Sources)

Источники определяют, откуда берутся данные для отображения на карте.

Типы источников:

  • geojson
  • vector
  • raster
  • image
  • video

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

map.addSource('points', {
  type: 'geojson',
  data: {
    type: 'FeatureCollection',
    features: [
      {
        type: 'Feature',
        geometry: {
          type: 'Point',
          coordinates: [69.2401, 53.2144]
        }
      }
    ]
  }
});

Особенности:

  • Источник может быть динамически обновляемым
  • Поддерживает потоковые данные
  • Может использоваться несколькими слоями одновременно

Слои (Layers)

Слои отвечают за визуализацию данных из источников.

Добавление слоя:

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

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

  • fill — полигоны
  • line — линии
  • circle — точки
  • symbol — текст и иконки
  • raster — растровые тайлы
  • heatmap — тепловые карты
  • fill-extrusion — 3D-экструзии

Слои обрабатываются снизу вверх, что влияет на порядок отображения.

Динамическое изменение данных

Mapbox GL JS поддерживает обновление данных без перезагрузки карты:

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

source.setData({
  type: 'FeatureCollection',
  features: []
});

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

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

Фильтрация и выражения

Одной из мощнейших возможностей является система выражений (expressions), позволяющая задавать поведение слоёв на основе данных.

Пример фильтра:

map.setFilter('points-layer', ['==', ['get', 'type'], 'city']);

Условное окрашивание:

paint: {
  'circle-color': [
    'match',
    ['get', 'category'],
    'A', '#ff0000',
    'B', '#00ff00',
    '#0000ff'
  ]
}

Возможности выражений:

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

Обработка событий

Система событий позволяет реагировать на действия пользователя и изменения карты.

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

map.on('load', () => {});
map.on('click', (e) => {});
map.on('move', () => {});
map.on('zoom', () => {});

Обработка клика по слою:

map.on('click', 'points-layer', (e) => {
  console.log(e.features[0]);
});

События позволяют реализовать:

  • интерактивные карты
  • выбор объектов
  • всплывающие панели
  • навигационную логику

Маркеры и всплывающие окна

Для пользовательских объектов используются маркеры:

const marker = new mapboxgl.Marker()
  .setLngLat([69.2401, 53.2144])
  .addTo(map);

Попапы:

const popup = new mapboxgl.Popup()
  .setLngLat([69.2401, 53.2144])
  .setHTML('<h3>Точка</h3>')
  .addTo(map);

Возможности:

  • привязка к координатам
  • динамическое содержимое
  • управление позиционированием

Камера и управление видом

Карта в Mapbox GL JS рассматривается как камера, которую можно перемещать и анимировать.

Методы управления:

map.flyTo({
  center: [69.2401, 53.2144],
  zoom: 12,
  speed: 1.2
});

Другие методы:

  • panTo() — плавное перемещение
  • zoomTo() — изменение масштаба
  • rotateTo() — вращение
  • easeTo() — анимация с настройками

Интерактивность и пользовательские режимы

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

  • drag (перетаскивание)
  • scroll zoom (масштаб колесом)
  • touch zoom (мультитач)
  • double click zoom

Отключение взаимодействий:

map.scrollZoom.disable();
map.dragRotate.disable();

Это важно для интеграции в сложные интерфейсы.

Работа с изображениями и иконками

Добавление кастомной иконки:

map.loadImage('icon.png', (error, image) => {
  map.addImage('custom-icon', image);
});

Использование в слоях:

layout: {
  'icon-image': 'custom-icon'
}

Функциональность:

  • регистрация изображений в стиле
  • использование в symbol слоях
  • кэширование ресурсов

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

Mapbox GL JS построена на WebGL, что обеспечивает аппаратное ускорение, но требует правильной оптимизации:

Ключевые принципы:

  • минимизация количества слоёв
  • использование vector tiles вместо GeoJSON при больших данных
  • кластеризация точек
  • lazy loading источников
  • использование setData только при необходимости

Пример кластеризации:

map.addSource('points', {
  type: 'geojson',
  data: geojsonData,
  cluster: true,
  clusterMaxZoom: 14,
  clusterRadius: 50
});

Контроль загрузки и жизненный цикл

Карта проходит несколько стадий:

  • load
  • idle
  • styledata
  • render
  • error

Пример контроля:

map.on('idle', () => {
  console.log('карта полностью загружена');
});

Это важно для:

  • асинхронной подгрузки слоёв
  • управления зависимостями
  • синхронизации UI

Интеграция с внешними данными

Mapbox предоставляет инфраструктуру API, которая часто используется вместе с Mapbox GL JS:

  • Mapbox Tiles API
  • Geocoding API
  • Directions API
  • Static Images API

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

  1. получение координат через geocoding
  2. отображение результата на карте
  3. построение маршрута
  4. визуализация слоями Mapbox GL JS

Работа с 3D-графикой

Поддержка 3D реализуется через:

  • fill-extrusion
  • pitch камеры
  • lighting model

Пример:

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

Это позволяет строить:

  • 3D города
  • визуализацию высот
  • архитектурные сцены

Управляющие элементы интерфейса

Встроенные контролы:

map.addControl(new mapboxgl.NavigationControl());
map.addControl(new mapboxgl.ScaleControl());
map.addControl(new mapboxgl.FullscreenControl());

Назначение:

  • навигация
  • масштаб
  • полноэкранный режим
  • геолокация пользователя

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

Работа с координатами — основа взаимодействия с картой.

Пример конвертации:

const lngLat = map.unproject([100, 100]);
const point = map.project([69.2401, 53.2144]);

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

  • позиционирования UI
  • кастомных оверлеев
  • вычисления расстояний на экране
Оглавление