Настройка GeolocateControl

GeolocateControl представляет собой встроенный UI-компонент, обеспечивающий доступ к геолокации пользователя через браузерный механизм получения координат. В основе работы лежит Geolocation API, который предоставляет доступ к текущему местоположению устройства при наличии разрешения.

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

Подключение и базовая инициализация

GeolocateControl добавляется к экземпляру карты через метод addControl.

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({
    positionOptions: {
        enableHighAccuracy: true
    },
    trackUserLocation: true,
    showUserLocation: true
});

map.addControl(geolocate);

Контрол добавляется как стандартный элемент интерфейса и отображается в панели управления картой.

Конфигурация GeolocateControl

positionOptions

Параметр positionOptions напрямую передаётся в Geolocation API и определяет точность и поведение запроса координат.

Основные свойства:

  • enableHighAccuracy — включает повышенную точность (GPS вместо сети)
  • timeout — максимальное время ожидания координат
  • maximumAge — допустимость кэшированных данных
positionOptions: {
    enableHighAccuracy: true,
    timeout: 6000,
    maximumAge: 0
}

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

trackUserLocation

Опция trackUserLocation активирует непрерывное отслеживание перемещений пользователя.

trackUserLocation: true

Поведение:

  • карта автоматически обновляет позицию
  • маркер перемещается вместе с пользователем
  • обновляется зона точности

При отключённом режиме происходит единичное определение координат.

showUserLocation

Определяет визуализацию текущей позиции.

showUserLocation: true

При включении:

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

showAccuracyCircle

Управляет отображением окружности точности.

showAccuracyCircle: true

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

События GeolocateControl

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

geolocate

Срабатывает при успешном получении позиции.

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

Событие содержит объект coords:

  • latitude
  • longitude
  • accuracy
  • altitude (если доступно)
  • heading (направление движения)
  • speed

error

Срабатывает при ошибке доступа к геолокации.

map.on("error", (e) => {
    console.log("Ошибка геолокации", e);
});

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

  • отказ пользователя в доступе
  • отсутствие HTTPS
  • неподдерживаемый браузер
  • таймаут запроса

trackuserlocationstart

Активируется при начале отслеживания перемещения.

map.on("trackuserlocationstart", () => {
    console.log("Отслеживание включено");
});

trackuserlocationend

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

map.on("trackuserlocationend", () => {
    console.log("Отслеживание завершено");
});

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

trigger geolocation вручную

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

geolocate.trigger();

Этот вызов эквивалентен нажатию на кнопку управления.

stop tracking

Остановка отслеживания осуществляется через:

geolocate.stop();

После вызова:

  • прекращается обновление позиции
  • отключается watchPosition
  • маркер фиксируется на последней точке

Поведение в браузере

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

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

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

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

GeolocateControl может изменять:

  • центр карты
  • уровень зума
  • наклон и ориентацию

center map on location

const geolocate = new maplibregl.GeolocateControl({
    trackUserLocation: true,
    showUserLocation: true,
    showUserHeading: true
});

map.addControl(geolocate);

map.on("geolocate", (e) => {
    map.flyTo({
        center: [e.coords.longitude, e.coords.latitude],
        zoom: 14
    });
});

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

Контрол по умолчанию использует стандартную кнопку. Варианты кастомизации:

  • изменение позиции через position при добавлении:
map.addControl(geolocate, "top-right");

Возможные позиции:

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

Обработка ошибок и нестабильных условий

отсутствие сигнала GPS

При слабом сигнале:

  • увеличивается radius accuracy
  • возможны скачки координат
  • обновления становятся нерегулярными

мобильные устройства

Особенности:

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

десктопные браузеры

Чаще используется:

  • IP-based геолокация
  • Wi-Fi triangulation

Поведение при повторных вызовах

Повторный вызов trigger():

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

Взаимодействие с источниками данных карты

GeolocateControl часто интегрируется с:

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

Пример обновления слоя:

map.on("geolocate", (e) => {
    map.getSource("user-position").setData({
        type: "Point",
        coordinates: [e.coords.longitude, e.coords.latitude]
    });
});

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

При использовании trackUserLocation: true важно учитывать:

  • частоту обновлений GPS
  • нагрузку на рендер карты
  • количество перерисовок слоёв

Рекомендации по снижению нагрузки:

  • ограничение обновлений через debounce
  • отключение лишних анимаций
  • использование минимального количества слоёв, завязанных на позицию

Безопасность и ограничения доступа

Геолокация является чувствительной функцией браузера:

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

Контрол не может обойти эти ограничения и полностью зависит от поведения браузера и системы.

Оглавление