GeolocateControl

Назначение и поведение компонента

GeolocateControl представляет собой встроенный UI-контрол библиотеки Mapbox GL JS, предназначенный для определения текущего местоположения устройства через браузерный Geolocation API и отображения его на карте.

Контрол объединяет несколько функций:

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

Компонент тесно интегрирован с системой источников данных (sources) и слоёв (layers) Mapbox GL JS, автоматически создавая и обновляя геопространственные объекты.

Инициализация и добавление на карту

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

import mapboxgl from "mapbox-gl";

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

const geolocate = new mapboxgl.GeolocateControl({
  positionOptions: {
    enableHighAccuracy: true
  },
  trackUserLocation: true
});

map.addControl(geolocate);

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

Основные параметры конфигурации

positionOptions

Определяет настройки браузерного API геолокации.

positionOptions: {
  enableHighAccuracy: true,
  timeout: 6000,
  maximumAge: 0
}

Ключевые параметры:

  • enableHighAccuracy — использование GPS и других высокоточных источников
  • timeout — максимальное время ожидания координат
  • maximumAge — допустимость кэшированных координат

trackUserLocation

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

  • false — одноразовое определение координат
  • true — непрерывное обновление позиции

При включении режима карта автоматически реагирует на перемещения пользователя.

showUserLocation

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

  • true — отображение синей точки
  • false — скрытие маркера при сохранении логики геолокации

showAccuracyCircle

Отвечает за визуализацию погрешности определения координат.

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

showUserHeading

Отображает направление движения устройства при наличии данных компаса.

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

fitBoundsOptions

Настройки поведения камеры при получении координат.

fitBoundsOptions: {
  maxZoom: 16
}

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

События GeolocateControl

Компонент генерирует несколько событий, интегрированных в event system карты.

geolocate

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

geolocate.on("geolocate", (e) => {
  const lng = e.coords.longitude;
  const lat = e.coords.latitude;
});

Событие содержит объект GeolocationPosition, включающий:

  • координаты
  • точность
  • временную метку

error

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

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

  • отказ пользователя в доступе
  • отсутствие GPS/сигнала
  • таймаут запроса
geolocate.on("error", (error) => {
  console.log(error.message);
});

outofmaxbounds

Срабатывает при выходе пользователя за пределы заданного maxBounds карты.

Используется в сценариях ограниченной геозоны:

  • корпоративные карты
  • локальные сервисы доставки
  • внутренние системы навигации

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

trigger()

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

geolocate.trigger();

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

_onAdd / _onRemove (внутренние)

Методы жизненного цикла, вызываемые системой карты:

  • инициализация DOM-элементов
  • подключение источников данных
  • очистка ресурсов

Не используются напрямую в пользовательском коде.

Поведение источников данных

GeolocateControl автоматически создаёт GeoJSON source:

{
  type: "FeatureCollection",
  features: [
    {
      type: "Feature",
      geometry: {
        type: "Point",
        coordinates: [lng, lat]
      },
      properties: {
        accuracy: accuracyValue
      }
    }
  ]
}

На основе этого источника формируются слои:

  • точка пользователя
  • окружность точности
  • направление движения (при наличии)

Режимы работы

Однократное определение позиции

Стандартный режим:

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

Подходит для:

  • поиска ближайших объектов
  • фиксации стартовой позиции

Непрерывное отслеживание

Активируется через trackUserLocation.

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

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

Используется в:

  • навигационных системах
  • трекинге перемещений
  • логистике

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

GeolocateControl напрямую управляет Camera API Mapbox GL JS:

  • flyTo для плавного перемещения
  • easeTo для мягкой анимации
  • fitBounds при учёте точности

Логика центрирования зависит от параметров:

  • текущий zoom
  • accuracy radius
  • trackUserLocation

Поведение при ошибках

Ошибки геолокации классифицируются:

PERMISSION_DENIED

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

POSITION_UNAVAILABLE

Устройство не может определить координаты.

TIMEOUT

Превышено время ожидания ответа GPS.

Каждый тип ошибки передаётся через событие error.

Производительность и ограничения

GeolocateControl зависит от браузерного API, что накладывает ограничения:

  • недоступность в insecure context (HTTP без HTTPS)
  • снижение точности в помещении
  • энергозатратность при track mode
  • вариативность поведения между устройствами

В условиях высокой частоты обновлений возможно:

  • увеличение нагрузки на main thread
  • частые перерисовки карты
  • рост потребления батареи

Пользовательский интерфейс

Контрол добавляет кнопку в стандартную панель управления Mapbox GL JS.

Состояния кнопки:

  • inactive — геолокация не запущена
  • loading — идёт запрос координат
  • active — позиция найдена и отображается
  • tracking — активное отслеживание

Визуальные индикаторы синхронизируются с состоянием API.

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

При задании maxBounds карта реагирует на позицию пользователя:

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

Связь с другими компонентами Mapbox GL JS

GeolocateControl взаимодействует с:

  • NavigationControl (совместное управление камерой)
  • Sources API (GeoJSON источники)
  • Layers API (визуализация точки и радиуса)
  • Events system карты

В сложных приложениях он часто используется совместно с:

  • routing engines
  • geocoding services
  • real-time tracking systems
Оглавление