AttributionControl

Назначение и роль контроля атрибуции

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

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

Поведение по умолчанию

В стандартной конфигурации Mapbox GL JS контрол атрибуции:

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

Если карта использует данные Mapbox, атрибуция включается автоматически, так как это является обязательным требованием использования платформы.

Инициализация и подключение

AttributionControl добавляется либо через параметры инициализации карты, либо динамически через API.

import mapboxgl from "mapbox-gl";

mapboxgl.accessToken = "YOUR_ACCESS_TOKEN";

const map = new mapboxgl.Map({
  container: "map",
  style: "mapbox://styles/mapbox/streets-v12",
  center: [69.2401, 53.2145],
  zoom: 10
});

В этом случае контроль уже присутствует по умолчанию.

Явное добавление AttributionControl

Контроль можно сконфигурировать через параметр attributionControl:

const map = new mapboxgl.Map({
  container: "map",
  style: "mapbox://styles/mapbox/streets-v12",
  attributionControl: true
});

Также можно добавить его вручную:

const map = new mapboxgl.Map({
  container: "map",
  style: "mapbox://styles/mapbox/streets-v12",
  attributionControl: false
});

map.addControl(new mapboxgl.AttributionControl());

Настройка параметров AttributionControl

Контроль поддерживает набор опций, позволяющих изменять поведение и внешний вид.

const attribution = new mapboxgl.AttributionControl({
  compact: true,
  customAttribution: "Данные: OpenStreetMap contributors"
});

map.addControl(attribution);
compact
  • true — отображение в виде компактной кнопки;
  • false — развернутый список атрибуций.

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

customAttribution

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

customAttribution: "Satellite imagery © Example Provider"

Структура отображения атрибуции

AttributionControl объединяет несколько типов источников:

  • базовый стиль карты;
  • векторные тайлы;
  • растровые тайлы;
  • сторонние GeoJSON источники;
  • пользовательские слои.

Каждый источник может добавлять собственную строку атрибуции через свойство:

map.addSource("custom-data", {
  type: "geojson",
  data: "data.geojson",
  attribution: "Custom dataset © Company"
});

Все строки автоматически агрегируются контролом.

Динамическое обновление атрибуции

AttributionControl реагирует на изменения состояния карты:

  • смена стиля (setStyle);
  • добавление или удаление источников;
  • переключение видимости слоёв;
  • загрузка новых тайлов.

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

Управление через API карты

Контрол можно модифицировать программно:

const attributionControl = map
  .getContainer()
  .querySelector(".mapboxgl-ctrl-attrib");

Однако корректный способ взаимодействия — через методы карты:

map.addControl(new mapboxgl.AttributionControl(), "bottom-right");
map.removeControl(attributionControl);

Позиционирование на карте

Контроль поддерживает стандартные позиции интерфейса:

  • top-left
  • top-right
  • bottom-left
  • bottom-right

Пример:

map.addControl(
  new mapboxgl.AttributionControl(),
  "bottom-left"
);

Визуальное поведение и CSS

AttributionControl оформляется через стандартные классы:

  • .mapboxgl-ctrl
  • .mapboxgl-ctrl-attrib
  • .mapboxgl-ctrl-attrib-inner

Переопределение стилей:

.mapboxgl-ctrl-attrib {
  font-size: 11px;
  background: rgba(255, 255, 255, 0.8);
  border-radius: 4px;
}

Компактный режим управляется классом:

  • .mapboxgl-compact

Работа в мобильных интерфейсах

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

Особенности поведения:

  • раскрытие по нажатию;
  • сворачивание при потере фокуса;
  • адаптивная ширина блока.

Пользовательские сценарии расширения

AttributionControl может использоваться как основа для кастомных решений.

Добавление динамических атрибуций
map.addControl(
  new mapboxgl.AttributionControl({
    customAttribution: [
      "Terrain data © Provider A",
      "Traffic data © Provider B"
    ]
  })
);
Интеграция с внешними источниками данных

При подключении сторонних API можно централизованно управлять атрибуциями:

map.addSource("external", {
  type: "vector",
  url: "mapbox://examples.8fgz4egr",
  attribution: "External tiles © Data Partner"
});

Взаимодействие с другими контролами

AttributionControl обычно используется совместно с:

  • ZoomControl
  • NavigationControl
  • ScaleControl
  • FullscreenControl

Он занимает минимальное пространство интерфейса и не конфликтует с другими элементами управления.

Особенности поведения при отключении

Если контроль отключён:

attributionControl: false

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

Ограничения и требования

  • Атрибуции должны быть всегда видимыми при использовании коммерческих данных;
  • нельзя скрывать AttributionControl без альтернативного отображения источников;
  • кастомные стили не должны нарушать читаемость текста;
  • динамические источники должны предоставлять корректное поле attribution.

Типовые ошибки при работе

  • удаление контроля без замены альтернативной атрибуцией;
  • дублирование строк из разных источников;
  • игнорирование обновлений при смене стиля;
  • некорректное использование customAttribution (передача нестроковых значений).

Внутренний механизм агрегации

AttributionControl формирует итоговый список через объединение:

  1. атрибуций базового стиля;
  2. атрибуций источников (source.attribution);
  3. пользовательских атрибуций;
  4. системных обязательных записей.

После объединения выполняется дедупликация строк и сортировка перед рендерингом интерфейса.

Оглавление