Синтаксис выражений

Выражения в MapLibre GL JS представляют собой формальный язык описания вычислений, используемый внутри стилей для динамического управления визуальными свойствами слоёв. Они позволяют задавать значения не только как константы, но и как функции от данных, масштаба, состояния фич и других параметров карты. Синтаксис основан на JSON-массивах, где первый элемент определяет тип операции, а последующие — аргументы.

Любое выражение в MapLibre GL JS записывается в виде массива:

["оператор", аргумент1, аргумент2, ...]

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

Пример простого выражения:

["get", "name"]

Здесь выполняется получение значения свойства name из текущего объекта данных.

Константные значения

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

10
"road"
true

Такие значения трактуются как постоянные и не зависят от контекста карты.

Доступ к данным фич

MapLibre GL JS предоставляет набор операторов для работы с данными объекта слоя.

Получение свойства

["get", "property_name"]

Извлекает значение свойства текущего объекта.

Проверка наличия свойства

["has", "property_name"]

Возвращает логическое значение.

Длина значения

["length", ["get", "name"]]

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

Доступ к идентификатору

["id"]

Возвращает идентификатор фичи.

Геометрия и свойства

["geometry-type"]
["properties"]

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

Выражения, зависящие от масштаба

MapLibre GL JS поддерживает динамическое изменение стиля в зависимости от zoom level.

Получение масштаба

["zoom"]

Возвращает текущий уровень масштабирования.

Интерполяция по масштабу

Наиболее часто используемый оператор — interpolate.

["interpolate", ["linear"], ["zoom"], 5, 1, 10, 5]

Здесь значение плавно изменяется от 1 при zoom 5 до 5 при zoom 10.

Поддерживаются различные типы интерполяции:

  • "linear" — линейная
  • "exponential" — экспоненциальная
  • "cubic-bezier" — кривые Безье

Условные выражения

match

Позволяет реализовать сопоставление значений:

["match",
  ["get", "type"],
  "primary", "#ff0000",
  "secondary", "#00ff00",
  "#000000"
]

Если значение свойства type совпадает с одним из перечисленных, возвращается соответствующий цвет, иначе — значение по умолчанию.

case

Используется для последовательной проверки условий:

["case",
  ["==", ["get", "population"], 0], "#ccc",
  ["<", ["get", "population"], 1000], "#f0f0f0",
  "#333"
]

Условия проверяются по порядку до первого истинного.

Арифметические и логические операции

MapLibre GL JS поддерживает стандартные операции:

["+", 2, 3]
["-", 10, 5]
["*", 4, 2]
["/", 8, 2]

Логические операции:

["==", 1, 1]
["!=", 1, 2]
["<", 5, 10]
["<=", 5, 5]
["all", true, false]
["any", true, false]
["!", false]

Работа с цветами

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

RGB и RGBA

["rgb", 255, 0, 0]
["rgba", 255, 0, 0, 0.5]

HSL

["hsl", 120, 1, 0.5]

Извлечение каналов цвета

["to-rgba", ["color", "#ff0000"]]

Работа с массивами и объектами

Создание массива

["array", 1, 2, 3]

Доступ по индексу

["at", 0, ["get", "coordinates"]]

Доступ к объекту

["object", "key1", "value1", "key2", "value2"]

Работа с типами данных

Приведение типов

["to-number", "10"]
["to-string", 10]
["to-boolean", 1]

Переменные внутри выражений

let

Позволяет объявлять локальные переменные:

["let",
  "base", 10,
  "mult", 2,
  ["*", ["var", "base"], ["var", "mult"]]
]

var

Используется для доступа к переменным:

["var", "base"]

Работа с состоянием фич

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

["feature-state", "selected"]

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

Типовые шаблоны выражений

Динамический цвет в зависимости от свойства

["match",
  ["get", "class"],
  "water", "#2b8cff",
  "road", "#999999",
  "#000000"
]

Изменение толщины линии по масштабу

["interpolate",
  ["linear"],
  ["zoom"],
  5, 0.5,
  10, 3,
  15, 8
]

Прозрачность по значению свойства

["interpolate",
  ["linear"],
  ["get", "density"],
  0, 0,
  100, 1
]

Композиция выражений

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

Пример:

["case",
  ["has", "population"],
  ["interpolate",
    ["linear"],
    ["get", "population"],
    0, 0.2,
    1000000, 1
  ],
  0
]

Здесь условие проверяет наличие свойства, а затем применяется интерполяция.

Контекст вычислений

Выражения вычисляются в нескольких контекстах:

  • стиль слоя (paint, layout)
  • свойства фичи
  • текущий zoom
  • feature state

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

Ограничения синтаксиса

Система выражений не поддерживает произвольный JavaScript-код. Допустимы только заранее определённые операторы. Это обеспечивает:

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

Выражения не могут обращаться к внешним API, глобальным объектам или выполнять побочные эффекты.

Особенности вычисления

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