Параметры конструктора Map

Конструктор new mapboxgl.Map() в Mapbox GL JS принимает единый объект параметров, определяющий поведение, внешний вид и интерактивность карты. Структура этого объекта влияет на все ключевые аспекты инициализации рендеринга WebGL-сцены, подключение стиля, управление камерой и взаимодействие с DOM-контейнером.

Параметр container определяет DOM-элемент, в котором будет размещена карта. Может быть передан как строковый идентификатор или как непосредственная ссылка на элемент.

new mapboxgl.Map({
  container: 'map'
});

или

new mapboxgl.Map({
  container: document.getElementById('map')
});

Отсутствие корректного контейнера приводит к невозможности инициализации WebGL-контекста и выбрасыванию ошибки на этапе создания экземпляра.

style

style задаёт визуальное оформление карты через JSON-спецификацию стиля Mapbox. Этот параметр может быть URL-адресом, объектом стиля или идентификатором, если используется облачный сервис стилей.

new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/streets-v12'
});

Стиль определяет слои, источники данных, источники тайлов, фильтры и правила рендеринга. В момент загрузки происходит парсинг style-spec и построение графа слоёв.

center

Параметр center задаёт начальные координаты центра карты в формате [долгота, широта].

center: [69.2401, 53.2145]

Используется система координат WGS84. Порядок строго фиксирован: сначала долгота, затем широта. Нарушение порядка приводит к смещению отображаемой области.

zoom

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

zoom: 10

Типичные диапазоны зависят от источника тайлов, но обычно находятся в пределах от 0 до 22.

bearing

bearing задаёт угол поворота карты относительно северного направления. Значение выражается в градусах по часовой стрелке.

bearing: 45

Используется для создания наклонных и ориентированных картографических сцен.

pitch

pitch определяет наклон камеры относительно поверхности земли.

pitch: 60

При значениях выше 0 включается перспектива, что позволяет визуализировать объёмные слои, extrusion и 3D-объекты.

bounds и maxBounds

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

bounds: [
  [68.0, 52.0],
  [70.0, 54.0]
]

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

maxBounds: [
  [60, 40],
  [80, 60]
]

Оба параметра используют формат [[southWest], [northEast]] в координатах WGS84.

minZoom и maxZoom

Эти параметры ограничивают диапазон масштабирования:

minZoom: 5,
maxZoom: 18

minZoom предотвращает чрезмерное удаление, а maxZoom ограничивает приближение, что важно при работе с ограниченными тайловыми наборами или высоконагруженными слоями.

renderWorldCopies

renderWorldCopies управляет повторением карты по горизонтали.

renderWorldCopies: true

При значении true карта бесшовно повторяется, создавая эффект глобального покрытия. При false крайние меридианы ограничивают отображение.

antialias

Параметр antialias включает сглаживание WebGL-рендеринга.

antialias: true

Используется для улучшения визуального качества линий и полигонов, особенно при наклонной проекции. Влияет на производительность, так как увеличивает нагрузку на графический процессор.

hash

hash синхронизирует состояние карты с URL-хэшем.

hash: true

При включении параметры центра и масштаба отражаются в адресной строке, например:

#10/53.21/69.24

Это позволяет сохранять и передавать состояние карты через URL без дополнительного состояния приложения.

interactive

interactive управляет общей интерактивностью карты.

interactive: true

При false отключаются все пользовательские взаимодействия: панорамирование, масштабирование, вращение.

dragRotate, touchZoomRotate, keyboard

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

dragRotate: true,
touchZoomRotate: true,
keyboard: true
  • dragRotate включает вращение при перетаскивании
  • touchZoomRotate управляет мультитач-жестами
  • keyboard активирует управление через клавиши

Каждый из этих параметров влияет на слой обработки событий pointer/touch/keyboard внутри Mapbox GL JS.

attributionControl

attributionControl: true

Добавляет стандартный контрол атрибуции, отображающий данные об источниках картографических данных. При отключении требуется ручное добавление атрибуции в интерфейс.

customAttribution

Позволяет задать пользовательскую атрибуцию:

customAttribution: 'Данные: OpenStreetMap, собственные источники'

Строка или массив строк отображаются вместе с системной атрибуцией.

transformRequest

Один из наиболее мощных параметров, позволяющий перехватывать все сетевые запросы карты.

transformRequest: (url, resourceType) => {
  return {
    url: url,
    headers: {
      Authorization: 'Bearer TOKEN'
    }
  };
}

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

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

Этот механизм напрямую влияет на загрузку стилей, тайлов, шрифтов и спрайтов.

locale

locale позволяет переопределять локализацию текстов интерфейса и подписей.

locale: {
  'NavigationControl.ZoomIn': 'Увеличить',
  'NavigationControl.ZoomOut': 'Уменьшить'
}

Применяется для адаптации UI к различным языкам без модификации исходного стиля.

trackResize

trackResize: true

Автоматически отслеживает изменения размера контейнера и пересчитывает viewport карты. Основан на обработке событий resize и MutationObserver.

projection (дополнительный параметр)

В некоторых версиях используется параметр projection, задающий картографическую проекцию:

projection: 'mercator'

Поддерживаются альтернативные проекции, влияющие на геометрическое отображение поверхности Земли.

полный пример конфигурации

const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/light-v11',
  center: [69.2401, 53.2145],
  zoom: 9,
  bearing: 0,
  pitch: 30,
  minZoom: 5,
  maxZoom: 18,
  maxBounds: [
    [60, 40],
    [80, 60]
  ],
  renderWorldCopies: true,
  antialias: true,
  hash: true,
  interactive: true,
  dragRotate: true,
  touchZoomRotate: true,
  keyboard: true,
  attributionControl: false,
  customAttribution: ['OpenStreetMap contributors'],
  transformRequest: (url, type) => {
    return {
      url,
      headers: {
        'X-Custom-Header': 'value'
      }
    };
  },
  locale: {
    'NavigationControl.ZoomIn': 'Zoom +',
    'NavigationControl.ZoomOut': 'Zoom -'
  },
  trackResize: true
});

Каждый параметр конструктора участвует в формировании графа состояния карты, влияя на инициализацию WebGL, загрузку ресурсов, управление камерой и систему взаимодействия с пользователем.

Оглавление