GeolocateControl

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

Основная роль компонента заключается в синхронизации состояния карты с реальным положением пользователя, включая автоматическое центрирование, отслеживание перемещения и визуализацию радиуса погрешности определения координат.

Контрол создаётся через конструктор GeolocateControl и добавляется на карту как обычный UI-элемент:

import maplibregl from "maplibre-gl";

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

const geolocate = new maplibregl.GeolocateControl();

map.addControl(geolocate);

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

Поведение при активации

При первом запуске контрол инициирует запрос к Geolocation API. Если пользователь предоставляет доступ, возвращается объект с координатами, точностью и временной меткой.

Полученные данные используются для:

  • установки маркера текущего положения;
  • отображения окружности точности (accuracy circle);
  • центрирования карты на позиции пользователя;
  • при включённом режиме отслеживания — обновления позиции при изменении координат.

Если доступ запрещён, генерируется событие ошибки.

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

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

positionOptions

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

const geolocate = new maplibregl.GeolocateControl({
    positionOptions: {
        enableHighAccuracy: true,
        timeout: 6000,
        maximumAge: 0
    }
});
  • enableHighAccuracy включает использование GPS (если доступен);
  • timeout задаёт максимальное время ожидания ответа;
  • maximumAge определяет допустимость кэшированных координат.

trackUserLocation

Включает режим постоянного отслеживания перемещения пользователя. В этом режиме карта обновляет позицию при каждом изменении координат:

trackUserLocation: true

При включении активируется поток наблюдения через watchPosition.

showUserLocation

Отвечает за отображение маркера пользователя. При значении false координаты используются только для логики карты, без визуального представления:

showUserLocation: true

showAccuracyCircle

Определяет отображение радиуса точности вокруг позиции:

showAccuracyCircle: true

Этот круг полезен для понимания погрешности GPS-сигнала.

fitBoundsOptions

Настройки анимации при центрировании карты:

fitBoundsOptions: {
    maxZoom: 16,
    duration: 1000
}

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

Методы управления

Контрол предоставляет программный интерфейс для ручного запуска геолокации.

trigger()

Метод инициирует запрос геопозиции без необходимости пользовательского клика:

geolocate.trigger();

При вызове происходит аналогичный процесс, как при нажатии кнопки интерфейса.

События

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

geolocate

Срабатывает при успешном получении координат:

map.on("geolocate", (e) => {
    console.log(e.coords.longitude, e.coords.latitude);
});

Объект события содержит:

  • coords.longitude
  • coords.latitude
  • coords.accuracy
  • timestamp

error

Возникает при ошибке получения местоположения:

map.on("error", (e) => {
    console.log(e.message);
});

Типичные причины:

  • отказ пользователя в доступе;
  • недоступность GPS;
  • истечение таймаута.

trackuserlocationstart

Срабатывает при включении режима отслеживания:

map.on("trackuserlocationstart", () => {
    console.log("tracking started");
});

trackuserlocationend

Срабатывает при остановке отслеживания:

map.on("trackuserlocationend", () => {
    console.log("tracking stopped");
});

outofmaxbounds

Возникает, если пользователь выходит за пределы заданного bounding box (если он используется в логике приложения):

map.on("outofmaxbounds", () => {
    console.log("user outside allowed bounds");
});

Внутренняя модель работы

Контрол опирается на два механизма браузера:

  • getCurrentPosition — однократное получение координат;
  • watchPosition — потоковое отслеживание изменений.

При включении tracking mode создаётся наблюдатель, который периодически возвращает новые координаты. Эти данные преобразуются в GeoJSON-совместимый формат и передаются в слой отображения.

Визуализация состоит из двух основных элементов:

  • точечный маркер (центр позиции);
  • окружность точности (радиус неопределённости).

Интеграция с источниками данных карты

Хотя контрол не создаёт отдельный source вручную в API карты, внутри MapLibre GL JS он использует внутренний geojson-источник для отрисовки пользовательской позиции. Этот источник обновляется при каждом событии геолокации.

Структура данных примерно соответствует:

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [longitude, latitude]
  },
  "properties": {
    "accuracy": 12
  }
}

На основе accuracy формируется окружность, аппроксимируемая полигоном.

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

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

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

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

Ограничения и особенности работы браузеров

Работа контроллера зависит от ограничений Geolocation API:

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

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

Управление состоянием кнопки

В интерфейсе контрол имеет несколько состояний:

  • неактивен (ожидание);
  • активен (поиск позиции);
  • отслеживание включено;
  • ошибка доступа.

Состояние влияет на визуальный стиль кнопки и наличие активной подсветки.

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

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

  • NavigationControl — для управления масштабом и поворотом;
  • FullscreenControl — для отображения карты на весь экран;
  • кастомными слоями, отображающими данные относительно позиции пользователя.

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

Поведение при потере сигнала

Если устройство теряет сигнал GPS или сеть, контроль сохраняет последнее известное положение. В режиме tracking обновления прекращаются, но маркер остаётся на карте до получения новых координат.

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

Оглавление