AttributionControl

Назначение и роль в интерфейсе карты

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

Контроль атрибуции является частью стандартных UI-компонентов MapLibre GL JS и тесно связан с системой управления элементами карты (controls system), где каждый контрол реализует единый интерфейс добавления, удаления и позиционирования на карте.

Базовое подключение и поведение по умолчанию

При создании экземпляра карты AttributionControl обычно добавляется автоматически, если не отключён явно.

const map = new maplibregl.Map({
    container: 'map',
    style: 'https://demotiles.maplibre.org/style.json',
    center: [0, 0],
    zoom: 2,
    attributionControl: true
});

При значении attributionControl: true создаётся стандартный контрол, который:

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

Создание и добавление вручную

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

const attribution = new maplibregl.AttributionControl();

map.addControl(attribution, 'bottom-right');

Позиционирование контролов в MapLibre GL JS поддерживает четыре стандартные области:

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

Конфигурация параметров

AttributionControl принимает объект конфигурации, позволяющий изменять поведение отображения.

compact

Параметр compact управляет режимом отображения атрибуции.

const attribution = new maplibregl.AttributionControl({
    compact: true
});
  • true — компактный режим, атрибуция скрывается за кнопкой;
  • false — полное отображение списка источников.

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

customAttribution

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

const attribution = new maplibregl.AttributionControl({
    customAttribution: [
        'Данные: OpenStreetMap',
        'Геокодирование: собственный сервис'
    ]
});

Возможные формы значения:

  • строка;
  • массив строк.

Эти значения добавляются к автоматически собранным атрибуциям и отображаются совместно с ними.

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

MapLibre GL JS позволяет изменять атрибуцию после инициализации карты.

Добавление контроллера

map.addControl(new maplibregl.AttributionControl({
    compact: false
}));

Удаление контроллера

map.removeControl(attribution);

Удаление полностью убирает UI-элемент и освобождает ресурсы, связанные с его отображением.

Взаимодействие со стилем карты

AttributionControl автоматически реагирует на изменения стиля (setStyle). При каждом обновлении:

  • пересобирается список sources;
  • извлекаются attribution поля из источников;
  • обновляется DOM-контейнер контроллера.

Пример смены стиля:

map.setStyle('https://demotiles.maplibre.org/style2.json');

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

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

Атрибуции формируются из спецификации стиля MapLibre GL:

  • sources.*.attribution
  • style.attribution

Пример:

{
    "sources": {
        "osm": {
            "type": "vector",
            "url": "https://example.com/tiles",
            "attribution": "© OpenStreetMap contributors"
        }
    }
}

Эти значения автоматически попадают в AttributionControl.

Скрытие стандартного контроля

В некоторых интерфейсах стандартный контрол отключается, если требуется полностью кастомный UI.

const map = new maplibregl.Map({
    container: 'map',
    style: 'style.json',
    attributionControl: false
});

В таком случае ответственность за отображение атрибуции переносится на разработчика.

Кастомная реализация отображения

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

const attributionText = map.getAttributionControl()._container?.innerText;

Однако более корректный подход — формировать список источников через стиль и хранить его отдельно от UI MapLibre.

Стилизация через CSS

DOM-структура AttributionControl позволяет изменять внешний вид через CSS.

Основные классы:

  • .maplibregl-ctrl
  • .maplibregl-ctrl-attrib
  • .maplibregl-ctrl-attrib-button

Пример изменения внешнего вида:

.maplibregl-ctrl-attrib {
    font-size: 11px;
    color: #444;
    background: rgba(255, 255, 255, 0.8);
    border-radius: 4px;
    padding: 4px 6px;
}

Компактная кнопка:

.maplibregl-ctrl-attrib-button {
    width: 24px;
    height: 24px;
}

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

В условиях ограниченного экрана compact: true становится стандартной практикой. Контрол:

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

Порядок отображения и приоритет источников

При формировании списка атрибуции учитывается:

  1. customAttribution
  2. style.attribution
  3. sources.*.attribution

Дублирующиеся записи обычно фильтруются внутренним механизмом MapLibre GL JS.

Интеграция с пользовательскими контролами

AttributionControl может использоваться совместно с другими контролами:

  • NavigationControl
  • ScaleControl
  • кастомные UI-компоненты

Пример компоновки:

map.addControl(new maplibregl.NavigationControl(), 'top-right');
map.addControl(new maplibregl.AttributionControl({ compact: true }), 'bottom-right');
map.addControl(new maplibregl.ScaleControl(), 'bottom-left');

Поведение при смене контейнера и ресайзе

Контрол не требует ручного обновления при изменении размера карты. Он:

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

Ограничения и особенности реализации

  • не предназначен для расширенной логики управления источниками;
  • не предоставляет API фильтрации отдельных атрибуций;
  • зависит от корректного заполнения attribution в стиле;
  • визуально связан с DOM, а не с canvas-рендерингом карты.

Поведение при отсутствии атрибуций

Если в стиле отсутствуют источники с атрибуцией и не задан customAttribution, контрол может:

  • не отображать список источников;
  • оставаться в виде минимального UI-элемента (в зависимости от режима и версии).

Типичные сценарии использования

  • карты с OpenStreetMap-данными и обязательной атрибуцией;
  • корпоративные карты с объединёнными источниками данных;
  • приложения с кастомным брендингом, где атрибуция частично скрыта в компактном режиме;
  • мобильные интерфейсы с ограниченным пространством UI.
Оглавление