Структура стиля Mapbox

Стиль в Mapbox GL JS представляет собой JSON-объект, описывающий визуальную модель карты: источники данных, слои их отображения, правила рендеринга, шрифты, спрайты и глобальные параметры сцены. Архитектурно стиль является декларативной спецификацией, которую движок Mapbox GL интерпретирует для построения WebGL-сцены.

Основой любого стиля служит строго определённая структура, соответствующая спецификации Style Specification (version 8).

Корневой объект стиля включает несколько ключевых секций:

  • version — версия спецификации стиля
  • name — человекочитаемое имя стиля
  • sources — источники пространственных данных
  • layers — слои визуализации
  • sprite — путь к спрайтам иконок
  • glyphs — шаблон URL для шрифтов
  • transition — параметры анимации изменений
  • light, fog, terrain — параметры 3D-сцены (опционально)
  • metadata — произвольные пользовательские данные

Минимально корректный стиль уже должен содержать хотя бы version, sources и layers.

Версия спецификации

Поле version фиксирует совместимость формата:

{
  "version": 8
}

Значение 8 является актуальным стандартом для Mapbox GL JS и MapLibre GL. Оно определяет доступные типы слоёв, выражений и поведение рендера.

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

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

Основные типы источников:

  • vector — векторные тайлы
  • raster — растровые тайлы
  • geojson — локальные GeoJSON-данные
  • image — одиночные изображения с геопривязкой
  • video — видеопотоки с геопривязкой

Пример структуры:

{
  "sources": {
    "cities": {
      "type": "vector",
      "url": "mapbox://examples.cities"
    },
    "earthquakes": {
      "type": "geojson",
      "data": "https://example.com/earthquakes.geojson"
    }
  }
}

Источник сам по себе не отображается — он становится видимым только через слой.

Слои (layers) как центральная модель визуализации

Секция layers определяет, как данные из источников будут визуализированы. Каждый слой — это объект с набором свойств.

Обязательные поля слоя:

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

Дополнительно:

  • source-layer — слой внутри векторного тайла
  • filter — фильтрация объектов
  • minzoom / maxzoom — диапазон видимости

Пример:

{
  "id": "city-points",
  "type": "circle",
  "source": "cities",
  "paint": {
    "circle-radius": 6,
    "circle-color": "#ff5500"
  }
}

Типы слоёв и их назначение

Mapbox GL JS поддерживает фиксированный набор типов слоёв:

Геометрические слои

  • fill — полигоны
  • line — линии
  • circle — точки
  • symbol — текст и иконки

Специализированные слои

  • heatmap — тепловые карты плотности
  • fill-extrusion — 3D-экструзии зданий
  • raster — растровые тайлы
  • hillshade — рельеф
  • background — фон
  • sky — небо

Каждый тип слоя имеет собственный набор свойств paint и layout.

Раздел layout и paint

Слои делятся на две логические группы свойств.

Layout

layout управляет структурой отображения:

  • видимость (visibility)
  • порядок символов
  • размещение текста и иконок
  • поведение вдоль линий

Пример:

"layout": {
  "visibility": "visible",
  "text-field": "{name}",
  "text-size": 12
}

Paint

paint отвечает за визуальные характеристики:

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

Пример:

"paint": {
  "line-color": "#3b9ddd",
  "line-width": 2
}

Выражения (expressions) как вычислительный слой стиля

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

Пример условного выражения:

"circle-color": [
  "case",
  [">", ["get", "mag"], 5], "#ff0000",
  "#00ff00"
]

Выражения могут:

  • выполнять математические операции
  • обращаться к свойствам данных
  • учитывать zoom-уровень
  • использовать условия case, match
  • интерполировать значения

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

Фильтры слоёв

filter ограничивает набор объектов, попадающих в слой.

Пример:

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

Фильтры могут комбинироваться:

  • логические операции (all, any, none)
  • сравнения (==, !=, >, <)
  • проверки наличия свойств

Фильтрация выполняется до рендеринга, что влияет на производительность.

Источники спрайтов (sprite)

sprite задаёт базовый URL, откуда загружаются изображения иконок:

"sprite": "mapbox://sprites/user/style-id"

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

Шрифты (glyphs)

glyphs определяет шаблон URL для загрузки векторных шрифтов:

"glyphs": "mapbox://fonts/mapbox/{fontstack}/{range}.pbf"

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

Переходы (transition)

transition задаёт глобальную анимацию изменения стиля:

"transition": {
  "duration": 300,
  "delay": 0
}

Эти параметры применяются ко всем анимируемым свойствам (цвет, размер, прозрачность), если локально не переопределены.

3D и пространственные параметры

Современные стили включают поддержку трёхмерной сцены.

Light

Параметр light управляет освещением:

  • направление света
  • интенсивность
  • цвет окружающего освещения

Terrain

terrain активирует рельеф на основе DEM-данных:

"terrain": {
  "source": "terrain-source",
  "exaggeration": 1.5
}

Fog

fog добавляет атмосферную перспективу, создавая эффект глубины.

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

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

Пример логики:

  1. background
  2. raster
  3. fill
  4. line
  5. symbol

Неправильный порядок слоёв приводит к визуальным артефактам и перекрытию объектов.

Метаданные

metadata используется для хранения произвольной информации:

"metadata": {
  "theme": "dark",
  "owner": "data-team"
}

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

Композиционная природа стиля

Стиль Mapbox GL JS не является статичным описанием карты. Он представляет собой композицию:

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

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

Оглавление