Свойства объектов

В экосистеме Mapbox GL JS под объектами (features) обычно понимаются элементы пространственных данных формата GeoJSON, которые отображаются на карте как геометрия с набором атрибутов. Эти атрибуты называются свойствами объектов (feature properties) и представляют собой обычные пары ключ–значение, встроенные в описание геометрии.

Структура GeoJSON-фичи включает три ключевых компонента: type, geometry и properties. Именно properties является центральным контейнером пользовательских данных, которые затем используются в стилизации, фильтрации и логике отображения.

Классическая схема:

  • geometry — координаты и тип геометрии (Point, LineString, Polygon)
  • properties — словарь атрибутов
  • type: "Feature" — обозначение GeoJSON-объекта

Пример:

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [71.4304, 51.1284]
  },
  "properties": {
    "name": "Astana Center",
    "population": 120000,
    "category": "capital"
  }
}

Роль свойств в рендеринге карты

В Mapbox GL JS свойства объектов выступают основой для data-driven styling — подхода, при котором внешний вид слоёв определяется не статическими значениями, а данными конкретных объектов.

Свойства используются в следующих контекстах:

  • стилизация (paint и layout свойства слоёв)
  • фильтрация (filter)
  • выражения (expressions)
  • интерактивность (hover, click)
  • запросы к объектам на карте

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

Доступ к свойствам через API

Mapbox GL JS предоставляет несколько механизмов доступа к properties после загрузки данных на карту.

queryRenderedFeatures

Метод queryRenderedFeatures возвращает массив объектов, попадающих в заданную область экрана. Каждый объект содержит properties.

map.on('click', (e) => {
  const features = map.queryRenderedFeatures(e.point);

  features.forEach(f => {
    console.log(f.properties.name);
  });
});

Каждый элемент результата — это расширенная версия GeoJSON feature, дополненная служебными полями (например, layer, source).

querySourceFeatures

В отличие от рендеренных объектов, этот метод работает напрямую с источником данных:

const features = map.querySourceFeatures('cities');

features.forEach(f => {
  console.log(f.properties.population);
});

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

Использование свойств в стилях

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

Интерполяция значений

'circle-radius': [
  'interpolate',
  ['linear'],
  ['get', 'population'],
  1000, 4,
  1000000, 20
]

Здесь свойство population управляет размером круга: чем больше значение, тем больше радиус.

Использование get

Функция get извлекает значение свойства объекта:

'fill-color': [
  'case',
  ['==', ['get', 'category'], 'capital'],
  '#ff0000',
  '#00ff00'
]

В этом случае цвет зависит от значения category.

Логические выражения

Свойства могут использоваться в условиях:

'filter': ['>=', ['get', 'population'], 50000]

Фильтр оставляет только объекты, у которых население больше или равно 50 000.

Типы свойств объектов

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

Строки

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

"name": "Central Park"

Числа

Применяются для количественных параметров:

"height": 350

Булевы значения

Используются для флагов:

"isActive": true

Массивы и вложенные структуры

Хотя поддержка в выражениях ограничена, данные могут храниться:

"tags": ["park", "urban", "tourism"]

Свойства и состояния объектов (feature state)

Помимо статических properties, в Mapbox GL JS существует динамическое состояние объектов (feature state), которое изменяется без перезагрузки источника данных.

Отличие properties и feature state

  • properties — часть данных GeoJSON, неизменяемая во время работы карты
  • feature state — временные значения, задаваемые через API
map.setFeatureState(
  { source: 'cities', id: 123 },
  { hover: true }
);

Использование в стиле:

'circle-color': [
  'case',
  ['boolean', ['feature-state', 'hover'], false],
  '#ff0000',
  '#0000ff'
]

Идентификаторы объектов и свойства

Для работы feature state требуется стабильный id. Он может быть задан в свойствах:

{
  "type": "Feature",
  "id": 42,
  "properties": {
    "name": "Station A"
  }
}

Если id отсутствует, Mapbox GL JS может использовать индекс, но это снижает предсказуемость поведения при обновлениях данных.

Свойства и фильтрация слоёв

Фильтры слоёв опираются исключительно на properties объектов источника.

Пример сложного фильтра:

filter: [
  'all',
  ['==', ['get', 'type'], 'restaurant'],
  ['>=', ['get', 'rating'], 4]
]

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

Изменение данных и влияние на свойства

При обновлении источника через setData свойства полностью пересчитываются:

map.getSource('cities').setData(newGeojson);

Любые выражения, фильтры и стили автоматически пересчитываются на основе новых properties.

Производительность при работе со свойствами

Внутренняя архитектура Mapbox GL JS оптимизирована для быстрого доступа к свойствам, однако существуют важные ограничения:

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

На практике рекомендуется:

  • хранить минимально необходимый набор properties
  • избегать дублирования данных
  • использовать feature state для временных эффектов

Свойства векторных тайлов

При работе с vector tiles свойства приходят уже упакованными в тайлы и имеют ограничения:

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

Это связано с оптимизацией передачи данных по сети.

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

Свойства часто применяются для управления поведением интерфейса:

map.on('mouseenter', 'cities-layer', (e) => {
  const name = e.features[0].properties.name;
  popup.setLngLat(e.lngLat).setText(name).addTo(map);
});

Здесь properties.name используется для генерации пользовательского интерфейса.

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

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

Пример связки:

  • properties.population
  • выражение ['get', 'population']
  • стиль circle-radius

Эта цепочка формирует динамическое поведение карты без ручного расчёта параметров.

Связь с платформой Mapbox

Mapbox предоставляет инфраструктуру, в которой свойства объектов являются частью более широкой системы:

  • тайловые сервисы
  • стили JSON
  • источники данных
  • SDK для веба и мобильных платформ

В этой архитектуре свойства выступают универсальным языком описания данных, который используется во всех слоях системы визуализации.

Оглавление