ScaleControl

Назначение и роль компонента

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

Компонент является частью системы встроенных контролов MapLibre GL JS и реализует интерфейс управления картой через единый механизм добавления и удаления элементов управления.

Базовая инициализация

ScaleControl создаётся как экземпляр класса ScaleControl и добавляется на карту через метод addControl.

import maplibregl from 'maplibre-gl';

const map = new maplibregl.Map({
    container: 'map',
    style: 'https://demotiles.maplibre.org/style.json',
    center: [37.6173, 55.7558],
    zoom: 10
});

const scale = new maplibregl.ScaleControl({
    maxWidth: 120,
    unit: 'metric'
});

map.addControl(scale, 'bottom-left');

Контрол может быть размещён в одной из стандартных позиций интерфейса: top-left, top-right, bottom-left, bottom-right.

Параметры конфигурации

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

maxWidth

Определяет максимальную ширину шкалы в пикселях.

  • Тип: number
  • Значение по умолчанию: 100
  • Влияет на масштабирование линии при изменении зума

Чем больше значение, тем более детализированная шкала отображается на экране.

unit

Определяет систему единиц измерения.

Поддерживаемые значения:

  • metric — метры и километры
  • imperial — футы и мили
  • nautical — морские мили
const scale = new maplibregl.ScaleControl({
    unit: 'imperial'
});

Выбор единиц влияет на автоматический пересчёт расстояний при отрисовке шкалы.

Принцип работы масштабной линейки

ScaleControl вычисляет расстояние на основе текущей проекции карты и масштаба зума. Используется геодезическая модель для корректного отображения расстояний на сфере Земли.

Основные этапы вычисления:

  1. Определение текущего центра карты
  2. Расчёт расстояния в метрах для пиксельного интервала
  3. Преобразование в выбранные единицы измерения
  4. Подбор “красивого” значения шкалы (1, 2, 5, 10, 20, 50 и т.д.)
  5. Обновление DOM-элемента контроля

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

ScaleControl автоматически подписывается на события карты:

  • move
  • zoom
  • rotate (косвенно влияет через пересчёт проекции)

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

Поведение при различных масштабах

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

Пример типичной адаптации:

  • z = 2 → 500 км
  • z = 8 → 10 км
  • z = 14 → 200 м
  • z = 18 → 20 м

Алгоритм подбора значений стремится сохранить читаемость и избегает дробных чисел.

Визуальная структура и CSS

ScaleControl рендерится как HTML-элемент внутри контейнера карты. Структура обычно включает:

  • контейнер контроля
  • горизонтальную линию шкалы
  • текстовое обозначение расстояния

Базовые классы:

  • .maplibregl-ctrl-scale
  • .maplibregl-ctrl

Пример кастомизации внешнего вида:

.maplibregl-ctrl-scale {
    background-color: rgba(0, 0, 0, 0.5);
    border-radius: 4px;
    padding: 2px 6px;
    color: white;
    font-size: 12px;
}

Изменение внешнего вида не влияет на вычисления, так как логика полностью отделена от представления.

Программное управление

Хотя ScaleControl в основном автономен, его можно удалять и повторно добавлять в зависимости от состояния приложения.

map.removeControl(scale);

map.addControl(scale, 'top-right');

Некоторые реализации позволяют менять единицы измерения динамически через доступ к экземпляру:

scale.setUnit('imperial');

Интеграция с адаптивными интерфейсами

ScaleControl часто используется в интерфейсах, где требуется динамическая адаптация под размер экрана:

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

При уменьшении доступного пространства шкала может быть перенесена в менее приоритетную область интерфейса или скрыта.

Особенности работы в WebGL-контексте

MapLibre GL JS использует WebGL для рендеринга карты, однако ScaleControl работает полностью через DOM. Это создаёт разделение:

  • карта рендерится в GPU
  • шкала рендерится в HTML/CSS

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

Точность и геодезические особенности

Расчёт расстояний в ScaleControl основан на сферической модели Земли. Это означает:

  • высокая точность на большинстве масштабов
  • небольшие погрешности при больших расстояниях
  • корректное поведение в широтных проекциях

На высоких широтах возможны визуальные отклонения, связанные с проекцией Web Mercator.

Использование нескольких масштабных контролов

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

map.addControl(new maplibregl.ScaleControl({ unit: 'metric' }), 'bottom-left');
map.addControl(new maplibregl.ScaleControl({ unit: 'imperial' }), 'bottom-left');

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

Поведение при изменении стиля карты

При смене стиля (setStyle) ScaleControl сохраняет своё состояние, так как не зависит от источников данных стиля. Однако после полной перезагрузки стиля карта пересчитывает параметры зума и центра, что приводит к обновлению шкалы.

Расширение функциональности

ScaleControl может служить базой для кастомных контролов, реализующих дополнительную логику:

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

Типовая схема расширения:

class ExtendedScaleControl extends maplibregl.ScaleControl {
    onAdd(map) {
        const container = super.onAdd(map);
        // дополнительная логика
        return container;
    }
}

Ограничения и нюансы

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

Поведение в высоконагруженных приложениях

ScaleControl практически не влияет на производительность, поскольку:

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

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

Связь с другими контролами

ScaleControl часто используется совместно с:

  • NavigationControl (масштабирование и вращение)
  • AttributionControl (источники данных)
  • GeolocateControl (позиционирование пользователя)

В таких конфигурациях масштабная линейка служит ориентиром для всех остальных элементов интерфейса.

Оглавление