JSON конфигурация стилей

Стилизация карт в Google Maps JavaScript API основана на декларативной JSON-конфигурации, которая описывает визуальные параметры объектов карты через набор правил. Такой подход позволяет отделить логику отображения карты от бизнес-логики приложения и управлять внешним видом через структурированные данные, а не императивный код.

Основой системы стилей является объект MapTypeStyle, который описывает правило изменения визуального представления конкретного типа объектов карты. Эти правила объединяются в массив и передаются в параметр styles при инициализации карты.

Каждый элемент массива стилей представляет собой объект с четырьмя ключевыми компонентами:

  • featureType — тип географического объекта
  • elementType — часть объекта, к которой применяется стиль
  • stylers — массив изменений визуальных свойств
  • дополнительные параметры фильтрации (в расширенных сценариях)

Общий шаблон выглядит следующим образом:

[
  {
    featureType: "road",
    elementType: "geometry",
    stylers: [
      { color: "#ffffff" },
      { visibility: "simplified" }
    ]
  }
]

featureType: классификация объектов карты

featureType определяет, к какому типу географических данных применяется стиль. В рамках Google Maps JavaScript API выделяются основные категории:

  • road — дороги всех уровней
  • water — водоёмы
  • landscape — ландшафтные элементы
  • poi — точки интереса (POI)
  • administrative — административные границы
  • transit — транспортная инфраструктура

Пример настройки всех водоёмов:

{
  featureType: "water",
  stylers: [
    { color: "#0e1626" },
    { visibility: "on" }
  ]
}

Если featureType не указан, стиль применяется ко всем объектам указанного elementType.

elementType: детализация элементов объекта

elementType управляет тем, какая часть объекта изменяется. Возможные значения:

  • geometry — геометрия объекта (форма, заливка)
  • labels — подписи и текст
  • labels.text — текстовая часть подписи
  • labels.icon — иконки маркеров

Комбинация featureType и elementType позволяет точно управлять визуальной иерархией карты.

Пример скрытия всех подписей:

{
  elementType: "labels",
  stylers: [
    { visibility: "off" }
  ]
}

stylers: система визуальных трансформаций

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

Основные свойства:

color

Определяет цвет элемента.

{ color: "#ff0000" }

visibility

Управляет отображением:

  • on — включено
  • off — отключено
  • simplified — упрощённое отображение
{ visibility: "simplified" }

weight

Используется для линий (например, дорог).

{ weight: 2 }

saturation

Регулирует насыщенность цвета (от -100 до 100).

{ saturation: -80 }

lightness

Изменяет яркость (от -100 до 100).

{ lightness: 40 }

gamma

Корректирует гамму отображения.

{ gamma: 0.5 }

Комбинирование правил стилей

Стили применяются последовательно, и порядок элементов массива имеет значение. Более поздние правила могут переопределять предыдущие.

Пример комплексной конфигурации:

const styles = [
  {
    featureType: "all",
    elementType: "labels",
    stylers: [{ visibility: "off" }]
  },
  {
    featureType: "road",
    elementType: "geometry",
    stylers: [
      { color: "#2c2c2c" },
      { lightness: -10 }
    ]
  },
  {
    featureType: "water",
    elementType: "geometry",
    stylers: [
      { color: "#000d1a" }
    ]
  }
];

Такая структура часто используется для создания «тёмных» карт или карт с минималистичной визуализацией.

JSON-стили в объекте Map

Конфигурация передаётся при создании экземпляра карты через параметр styles:

const map = new google.maps.Map(document.getElementById("map"), {
  center: { lat: 40.7128, lng: -74.0060 },
  zoom: 12,
  styles: styles
});

При этом стили применяются поверх базовой темы карты, предоставляемой платформой Google через сервис картографии.

Именованные стили и StyledMapType

Помимо прямой передачи массива, используется объект StyledMapType, позволяющий создавать переключаемые темы карты.

const styledMap = new google.maps.StyledMapType(styles, {
  name: "Custom Style"
});

map.mapTypes.set("styled_map", styledMap);
map.setMapTypeId("styled_map");

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

Фильтрация объектов через featureType

Гибкость JSON-конфигурации позволяет работать с иерархией объектов. Например, можно изменить только подписи административных границ:

{
  featureType: "administrative.province",
  elementType: "labels.text.fill",
  stylers: [
    { color: "#444444" }
  ]
}

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

Работа с цветовой моделью

Цвета в стилях задаются в HEX-формате. При этом важно учитывать, что платформа интерпретирует цвет как базовое значение, на которое могут накладываться корректировки lightness и saturation.

Пример нейтральной палитры:

[
  {
    featureType: "all",
    elementType: "geometry",
    stylers: [{ color: "#e0e0e0" }]
  },
  {
    featureType: "road",
    elementType: "geometry",
    stylers: [{ color: "#ffffff" }]
  }
]

Управление плотностью визуальных элементов

Стили позволяют управлять информационной плотностью карты. Уменьшение количества элементов достигается комбинацией:

  • отключения labels
  • упрощения geometry
  • изменения visibility

Пример минималистичной конфигурации:

[
  {
    featureType: "all",
    elementType: "labels",
    stylers: [{ visibility: "off" }]
  },
  {
    featureType: "poi",
    stylers: [{ visibility: "off" }]
  },
  {
    featureType: "road",
    elementType: "geometry",
    stylers: [{ visibility: "simplified" }]
  }
]

Наследование и приоритеты

Система стилей не поддерживает классическое наследование, но использует приоритеты:

  1. Более специфичный featureType перекрывает общий (all)
  2. Более точный elementType перекрывает общий (geometry)
  3. Позднее правило в массиве имеет больший приоритет

Это поведение важно учитывать при построении сложных тем, особенно в крупных приложениях на базе Google Maps JavaScript API, где стили часто генерируются динамически.

Динамическая генерация JSON-стилей

В реальных приложениях стили часто формируются программно:

function createNightTheme() {
  return [
    {
      featureType: "all",
      elementType: "geometry",
      stylers: [{ color: "#1d2c4d" }]
    },
    {
      featureType: "water",
      elementType: "geometry",
      stylers: [{ color: "#0e1626" }]
    }
  ];
}

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

Оглавление