Спецификация стиля | 2GIS Documentation

Спецификация формата стиля

Стиль 2GIS - это документ, который определяет внешний вид карты: какие данные рисовать, порядок их рисования и как стилизовать данные при отрисовке.

Первый публичный релиз спецификации стилей 2GIS для MapGL JS API.

Стили представляют собой объект в формате JSON. В корне объекта содержится общая информация о стиле, а также массив слоев карты, в котором находятся их настройки отображения.

{
  "version": 1,
  "name": "2GIS Night",
  "background": {
    "color": "#ffffff"
  },
  "labelingGroups": {...},
  "layers": [...]
}

Обязательный number.

Мажорная версия формата. Должна быть равна 1. Меняется только в случае появления ломающих изменений.

"version": 1

Опциональный string.

Читабельное название стиля.

"name": "Snowy"

Опциональный object.

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

Обязательный object.

Задает отображение фона для карты.

Содержит следующие поля:

color

Обязательный color.

Задает цвет заливки фона карты.

Опциональный object.

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

Может содержать следующие поля:

groups

Опциональный array из string. По умолчанию ['default'].

Задает строковые названия групп лейблинга. По умолчанию уже содержит группу default.

overlay

Опциональный array из string.

Здесь указываются группы, которые будут накладываться друг на друга.

Пример: overlay: [["group1", "group2"], ["group2", "group3", "group4"]]. Это значит, что пара group1 и group2 будут накладываться друг на друга в случае пересечения на карте. Группы group2, group3, group4 тоже друг с другом не будут будут бороться за место на карте, а будут накладываться друг на друга. Поэтому прокидываем массив, чтобы можно было указывать вот такие отношения между группами.

Если в каком-либо слое будет использоваться название группы, которая не описана в groups, такая группа будет игнорироваться, как будто она не указана для слоя.

Обязательный array из Layer.

Список слоев, которые доступны для стилизации гео-объектов. Набор параметров слоя зависит от его типа type.

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

  • polygon — полигон с закрашенным фоном и опциональной обводкой
  • line — линия с опциональной шириной и обводкой
  • dashedLine — пунктирная линия
  • point — иконка, подпись, иконка с подписью

Порядок отрисовки объектов стилевых слоев:

  1. Между объектами разных стилевых слоев, зависит от порядка слоев в массиве layers. Объект следующего стилевого слоя будет отрисован над объектом предыдущего.
  2. В рамках одного стилевого слоя, зависит от порядка объектов в источнике данных. Каждый следующий объект в источнике данных будет отрисован над предыдущим.

Например:

"layers": [
  {
    "id": "water",
    "type": "polygon",
    "style": {
      "color": "#0000ff"
    }
  }
]

ВАЖНО! В MapGL JS API стоит использовать только представленные в этой спецификации слои и свойства. В редакторе стилей для стилизации объектов доступен еще ряд слоев, но их спецификация еще находится на стадии черновика, и может поменяться.

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

Обязательный string.

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

Обязательный enum. Принимает значения: point, line, dashedLine, polygon.

Тип стилевого слоя.

Обязательный Expression<boolean>. Не поддерживает выражения: step, interpolate.

Задает фильтр для выборки объектов из данных для отрисовки в конкретном стилевом слое.

Например, такой фильтр выберет все объекты, у которых атрибут layer равен либо private, либо beach:

{
  "filter": ["match", ["get", "layer"], ["private", "beach"], true, false]
}

Такой вариант подберет все объекты, для которых выполнены 3 условия одновременно:

"filter": [
  "all",
  ["match", ["get", "class"], ["road"], true, false],
  ["match", ["get", "type"], ["main"], true, false],
  ["match", ["global", "navigatorOn"], [true], true, false]
]

А тут выберет все объекты, принадлежащие источнику данных с атрибутом sourceAttr равным data_source_1 или data_source_2:

{
  "filter": ["match", ["sourceAttr", "name"], ["data_source_1", "data_source_2"], true, false]
}

Опциональный number. Неотрицательное число от 0 до 20 включительно.

Минимальное значение зума карты для слоя. Если зум карты больше либо равен minzoom, то объекты слоя отображаться не будут.

Опциональный number. Неотрицательное число от 0 до 20 включительно.

Максимальное значение зума карты для слоя. Если зум карты меньше maxzoom, то объекты слоя отображаться не будут.

Опциональный object.

Объект задающий стилевые свойства конкретного слоя. Набор свойств зависит от типа слоя.

color

Опциональный color или Expression<color>. По умолчанию "#000000". Не поддерживает прямой вызов выражений-экстракторов: get, sourceAttr, global.

Цвет заливки.

strokeColor

Опциональный color или Expression<color>. По умолчанию "#000000". Не поддерживает прямой вызов выражений-экстракторов: get, sourceAttr, global.

Цвет обводки.

strokeWidth

Опциональный number или Expression<number>. Неотрицательное число. Измеряется в пикселях. По умолчанию 1.

Ширина обводки.

visibility

Опциональный enum. Возможные значения: visible, none. По умолчанию visible.

Определяет, будут ли объекты слоя рисоваться на карте или нет.

color

_Опциональный color или Expression<color>. По умолчанию "#000000". Не поддерживает прямой вызов выражений-экстракторов: get, sourceAttr, global. _

Цвет заливки.

width

Опциональный number или Expression<number>. Неотрицательное число. Измеряется в пикселях. По умолчанию 1.

Ширина линии.

visibility

Опциональный enum. Возможные значения: visible, none. По умолчанию visible.

Определяет, будут ли объекты слоя рисоваться на карте или нет.

color

Опциональный color или Expression<color>. По умолчанию "#000000". Не поддерживает прямой вызов выражений-экстракторов: get, sourceAttr, global.

Цвет заливки штриха.

width

Опциональный number или Expression<number>. Неотрицательное число. Измеряется в пикселях. По умолчанию 1.

Ширина линии.

dashLength

Опциональный number или Expression<number>. Неотрицательное число. Измеряется в пикселях. По умолчанию 1.

Длина штриха.

gapLength

Опциональный number или Expression<number>. Неотрицательное число. Измеряется в пикселях. По умолчанию 1.

Длина промежутка между штрихами.

gapColor

Опциональный color или Expression<color>. По умолчанию "rgba(0, 0, 0, 0)". Не поддерживает прямой вызов выражений-экстракторов: get, sourceAttr, global.

Цвет заливки промежутка между штрихами.

visibility

Опциональный enum. Возможные значения: visible, none. По умолчанию visible.

Определяет, будут ли объекты слоя рисоваться на карте или нет.

iconImage

Опциональный string или Expression<string>. Не поддерживает прямой вызов выражений-экстракторов: get, sourceAttr, global.

Имя иконки в стиле. Если параметр не указан, то иконка рисоваться не будет.

iconWidth

Опциональный number или Expression<number>. Число от 0 до 512 включительно. Измеряется в пикселях. По умолчанию 16. Не поддерживает прямой вызов выражений-экстракторов: get, sourceAttr, global.

Размер иконки.

iconAnchor

Опциональный array двух number. По умолчанию [0.5, 0.5].

Задает положение точки привязки объекта на иконке (якорь) к положению на карте.

Представляет собой массив [x, y], где x, y — относительные координаты, характеризующие положение якоря на иконке. К примеру:

  • [0, 0] — левый верхний угол иконки;
  • [0.5, 0.5] — центр иконки;
  • [1, 1] — правый нижний угол иконки;
  • [-1, -1] — якорь вне иконки, в данном случае иконка будет рисоваться со смещением от точки положения на карте.

textField

Опциональный string или Expression<string>. По умолчанию ['get', 'db_label'].

Текст подписи.

textFont

Опциональный string или Expression<string>. Не поддерживает прямой вызов выражений-экстракторов: get, sourceAttr, global.

Шрифт для текстовой подписи. Если не задан, то подпись рисоваться не будет вне зависимости от наличия textFont.

textColor

Опциональный color или Expression<color>. По умолчанию "#000000". Не поддерживает прямой вызов выражений-экстракторов: get, sourceAttr, global.

Цвет текста.

textFontSize

Опциональный number или Expression<number>. Число от 0 до 512 включительно. Измеряется в пикселях. По умолчанию 16. Не поддерживает прямой вызов выражений-экстракторов: get, sourceAttr, global.

Размер шрифта текстовой подписи.

textLineHeight

Опциональный number. Неотрицательное число. Измеряется в единицах относительно размера шрифта. По умолчанию 1.2.

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

textLetterSpacing

Опциональный number. Неотрицательное число. Измеряется в единицах относительно размера шрифта. По умолчанию 0.

Межбуквенный интервал текста.

textPlacement

Опциональный enum. Возможные значения: topCenter, rightCenter, bottomCenter, leftCenter. По умолчанию bottomCenter.

Расположение текста относительно иконки. Если иконка не задана, то параметр не используется.

  • topCenter — сверху по центру
  • bottomCenter — снизу по центру
  • leftCenter — слева по центру
  • rightCenter — справа по центру

textOffset

Опциональный number или Expression<number>. Неотрицательное число. Измеряется в пикселях. По умолчанию 0.

Отступ текста от иконки. Направление задается в зависимости от значения параметра textPlacement.

textHaloColor

Опциональный color или Expression<color>. По умолчанию "rgba(0, 0, 0, 0)".

Цвет гало вокруг текста.

textHaloWidth

Опциональный number. Неотрицательное число. Измеряется в пикселях. По умолчанию 0.

Размер гало вокруг текста.

textMaxLengthPerLine

Опциональный number. Целое положительное число. По умолчанию 30.

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

Например, при значении 3 текст "Великий Новгород" будет разбит на 2 строки:

Великий
Новгород

allowOverlap

Опциональный boolean. По умолчанию false.

Если значение равно true, то:

  • объект не будет участвовать в лейблинге — будет всегда отображаться;
  • стилевые свойства iconLabelingGroup и textLabelingGroup игнорируются.

iconLabelingGroup

Опциональный enum. Возможные значения — строки определенные в поле groups объекта labelingGroups в корне объекта стиля. По умолчанию default.

Задает группу лейблинга для иконки.

iconLabelingMargin

Опциональный LabelingMargin.

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

iconPriority

Опциональный number. Целое неотрицательно число. По умолчанию 0.

Приоритет иконки для лейблинга. Чем выше значение, тем иконка важнее.

textLabelingGroup

Опциональный enum. Возможные значения — строки определенные в поле groups объекта labelingGroups в корне объекта стиля. По умолчанию default.

Задает группу лейблинга для текстовой подписи textField.

textLabelingMargin

Опциональный LabelingMargin.

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

textPriority

Опциональный number. Целое неотрицательно число. По умолчанию 0.

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

Если значение больше iconPriority, то в качестве приоритета подписи будет использоваться iconPriority.

Если иконка не прошла лейблинг, то подпись не будет отображаться.

visibility

Опциональный enum. Возможные значения: visible, none. По умолчанию visible.

Определяет, будут ли объекты слоя рисоваться на карте или нет.

Обычное JSON число в диапазоне значений от -2147483 и до 2147483.

Если не сказано иного, число может быть дробным, но все значения будут округляться до 3-го знака после запятой.

{
  "textFontSize": 16
}

Обычная булева переменная, принимающая 2 значения: true или false.

{
  "allowOverlap": true
}

Цвет задается всегда строкой в одном из следующем варианте:

{
    "color": "#ff0",
    "color": "#ffff00",
    "color": "#ffff00aa",
    "color": "rgb(255, 255, 0)",
    "color": "rgba(255, 255, 0, 1)",
    "color": "hsl(100, 50%, 50%)",
    "color": "hsla(100, 50%, 50%, 1)"
}

Обычные JSON строки, помещенные в кавычки.

{
  "name": "Snowy style"
}

Строки принимающие только фиксированный список значений. Список значений задается для каждого свойства отдельно.

Например, параметр visibility может принимать только два значения visible и none:

{
  "visibility": "visible"
}
{
  "visibility": "none"
}

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

Числовой массив:

[0, 0];

Массив, задающий expression:

['interpolate', ['linear'], ['zoom'], 10, 0, 15, 10];

Обычный JSON объект.

{
  "key1": "SomeValue",
  "key2": [0, 1],
  "key3": {
      "innerKey1": true,
  }
}

Позволяет задавать отступы лейблинга у объектов. Представляет собой JSON объект со следующей структурой:

{
  "topBottom": 10,
  "leftRight": 15,
}

topBottom

Опциональный number. Неотрицательное число. Измеряется в пикселях. По умолчанию 0.

leftRight

Опциональный number. Неотрицательное число. Измеряется в пикселях. По умолчанию 0.

Выражения задают формулу для вычисления значения свойства. Используются в качестве значений некоторых свойств стилевых слоев, например, для filter или style.strokeWidth. Подробнее, про поддержку выражений свойствами конкретного слоями смотри в спецификации слоев в разделе «Layers».

Для удобства, произвольное выражение вычисляющее значение с типом T обозначаем Expression<T>.

Например:

{
  "filter": ["match", ["get", "type"], ["area"], true, false],
  "style": {
    "strokeWidth": ["interpolate", ["linear"], ["zoom"], 10, 5, 15, 8],
  }
}

Каждое выражение представляется JSON массивом. Первый элемент массива — строковое наименование выражения, например, "match". Все последующие элементы, если таковые предусмотрены в конкретном выражении — это аргументы выражения. Каждый аргумент может быть как конечным значением свойства, так и другим выражением, которое нужно вычислить.

[expression_name, argument_0, argument_1, ...]:

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

Все выражения разбиты на несколько смысловых групп, которые описаны ниже.

Выражения, позволяющие получить значение атрибута объекта в данных get, атрибута источника данных sourceAttr или глобальной переменной global.

get

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

Схема

["get", string]: value

Пример:

['get', 'objectAttrName'];

sourceAttr

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

Схема:

["sourceAttr", string]: value

Пример:

['sourceAttr', 'sourceAttrName'];

global

Позволяет получить глобальную стилевую переменную.

Схема:

["global", string]: value

Пример:

['global', 'globalVariableName'];

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

match

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

Схема:

["match",
  extractor: ExtractorExpression<InputType>,
  expected_1: InputType[], output_1: OutputType,
  expected_2: InputType[], output_2: OutputType,
  ...,
  fallback: OutputType
]: OutputType

Обозначения в схеме:

  • InputType — значение проверяемого свойства, string или number
  • OutputType — возвращаемое значение, может быть любым из поддерживаемых в спецификации типов
  • extractor — экстрактор-выражение для получения значения проверяемого свойства
  • expected_n — массив ожидаемых значений extractor
  • output_n — возвращаемое значение при совпадении результата extractor с одним из значения массива expected_n
  • fallback — возвращаемое по умолчанию значение

Пример:

{
  "filter": [
    "match",
    // Достает значение атрибута layer стилизуемого объекта
    ["get", "layer"],
    // Возвращает true, если значение layer совпадет с одним из значений массива
    ["private", "beach"], true,
    // По умолчанию вернет false
    false
  ]
}

Передавать можно несколько кейсов для сравнения:

{
  "color": [
    "match",
    // Достает значение атрибута type стилизуемого объекта
    ["get", "type"],
    // Возвращает черный цвет, если type = building
    ["building"], "#000000",
    // Возвращает зеленый цвет, если type = building
    ["area"], "#00FF00",
    // ...
    // По умолчанию возвращает белый
    "#FFFFFF"
  ]
}

Можно использовать любой из существующих ExtractorExpression<T>, например, экстрактор глобальной стилевой переменной:

{
  "color": [
    "match",
    // Достает значение глобального атрибута trafficOn.
    ["global", "trafficOn"],
    // Возвращает красный, если trafficOn == true.
    [true], "rgb(255, 0, 0)",
    // По умолчанию вернет белый.
    "#ffffff"
  ]
}

all

Логическое выражение, возвращает true, если все переданные аргументы будут true, иначе вернет false.

Используется для фильтрации данных сразу по нескольким атрибутам:

Схема:

["all", boolean, boolean, ...]: boolean
  • boolean — булево значение либо Expression<boolean>
"filter": [
  "all",
  // true — если источник данных объекта имеет аттрибут type == road
  ["match", ["sourceAttr", "type"], ["roads"], true, false],
  // true — если атрибут объект имеет category == highway
  ["match", ["get", "category"], ["highway"], true, false],
  // true — если значение атрибута будет равно true
  ["get", "isPaid"],
]

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

interpolate

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

Значения масштаба — это number, указанные в строго возрастающем порядке, а интерполируемая величина может быть либо number, либо color. Если текущее значение масштаба карты меньше первого(последнего) масштаба заданного в выражении, то выражение вернет значение соответствующее первому(последнему) масштабу в выражении.

Доступные алгоритмы интерполяции значений:

  • ["linear"] — линейная интерполяция.
  • ["exponential", base] — экспоненциальная интерполяция, где base — опциональный number, принимающий значения от 0 и до 2 включительно, по умолчанию равный 1.

Схема:

["interpolate",
  interpolation: ["linear"] | ["exponential", base],
  ['zoom'],
  zoom_1: number, output_1: OutputType,
  zoom_2: number, output_2: OutputType,
  //...
]: OutputType

Обозначения в схеме:

  • OutputType — возвращаемое значение, может быть либо number либо color
  • interpolation — алгоритм интерполяции значений
  • zoom_n — значение зума карты
  • output_n — соответствующее zoom_n значение интерполируемого свойств

Например, так можно задать зависимость ширины от масштаба карты

{
  "width": [
    "interpolate", ["linear"], ["zoom"],
    // При масштабе <= 10, значение ширины равно 5
    10, 5,
    // При масштабе от 10 до 15, значение ширины будет интерполироваться от 5 до 8
    15, 8,
    // При масштабе >= 15, значение ширины равно 8
  ]
}

А так можно интерполировать цвет текста:

{
  "textColor": [
    "interpolate", ["exponential"], ["zoom"],
    // Color at zoom 14
    14, "#ff0000",
    // Color at zoom 17
    17, "#000",
    // Color at zoom 19
    19, "rgba(0, 100, 200, 50%)"
  ]
}

step

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

Схема:

["step",
  defaultValue : OutputType,
  zoom_1: number, output_1: OutputType,
  zoom_2: number, output_2: OutputType,
  //...
]: OutputType

Обозначения в схеме:

  • OutputType — возвращаемое значение, может быть любым из поддерживаемых в спецификации типов
  • defaultValue — Значение по умолчанию
  • zoom_n — значение зума карты, number указанные в строго возрастающем порядке
  • output_n — соответствующее zoom_n значение интерполируемого свойств

Например, так можно задать размер шрифта подписи

{
  "fontSize": [
    "step", ["zoom"],
    // fontSize = 12, когда зум < 10
    12,
    // fontSize = 16, когда зум >= 10
    10, 16,
    // fontSize = 22, когда зум >= 15
    15, 22,
    //...
  ]
}

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

{
  "textFont": [
    "step", ["zoom"],
    // textFont = "Noto_Sans", когда зум < 15
    "Noto_Sans",
    // textFont = "Noto_Sans_Bold", когда зум >= 15
    15, "Noto_Sans_Bold",
    //...
  ]
}