locate: метод и параметры

Метод locate в библиотеке Leaflet используется для определения географического положения устройства через браузерный Geolocation API и последующей работы с полученными координатами на карте. Он принадлежит объекту карты и позволяет запускать процесс определения местоположения с различными параметрами точности, поведения карты и режима отслеживания.

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

Базовый синтаксис

map.locate(options);

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

Основные параметры метода locate

setView

Параметр setView определяет автоматическое центрирование карты на найденной позиции пользователя.

map.locate({ setView: true });

При значении true карта автоматически перемещается к координатам пользователя. Дополнительно может использоваться совместно с параметром maxZoom.

maxZoom

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

map.locate({
  setView: true,
  maxZoom: 16
});

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

watch

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

map.locate({ watch: true });

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

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

map.stopLocate();

timeout

Параметр timeout задаёт максимальное время ожидания ответа от Geolocation API в миллисекундах.

map.locate({ timeout: 10000 });

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

maximumAge

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

map.locate({ maximumAge: 60000 });

Значение указывается в миллисекундах. Если координаты были получены ранее указанного времени, они могут быть повторно использованы без нового запроса к GPS или сети.

enableHighAccuracy

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

map.locate({ enableHighAccuracy: true });

При включении браузер пытается использовать GPS, Wi-Fi и другие источники для повышения точности, что увеличивает потребление ресурсов и может замедлить получение результата.

Комбинирование параметров locate

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

map.locate({
  setView: true,
  maxZoom: 15,
  watch: true,
  timeout: 8000,
  maximumAge: 30000,
  enableHighAccuracy: true
});

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

События, связанные с locate

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

locationfound

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

map.on('locationfound', function (e) {
  console.log(e.latlng);
  console.log(e.accuracy);
});

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

  • latlng — координаты пользователя
  • accuracy — радиус точности в метрах
  • bounds — предполагаемые границы области

locationerror

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

map.on('locationerror', function (e) {
  console.log(e.message);
});

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

Структура объекта события locationfound

{
  latlng: LatLng,
  accuracy: Number,
  altitude: Number | null,
  altitudeAccuracy: Number | null,
  heading: Number | null,
  speed: Number | null,
  timestamp: Number
}

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

Остановка отслеживания

При включённом режиме watch: true геолокация продолжает обновляться до явного прекращения.

map.stopLocate();

Метод завершает поток обновлений и освобождает ресурсы браузера.

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

Геолокация зависит от реализации браузера и разрешений пользователя. Основные особенности:

  • требуется HTTPS-соединение (за редкими исключениями localhost)
  • пользователь должен явно разрешить доступ
  • точность зависит от доступных источников (GPS, IP, Wi-Fi)
  • поведение enableHighAccuracy может различаться

Взаимодействие locate с картой Leaflet

Метод тесно связан с объектом карты и влияет на её состояние:

  • центрирование карты через setView
  • изменение масштаба через maxZoom
  • добавление маркеров и окружностей через обработчики событий

Пример визуализации позиции:

map.on('locationfound', function (e) {
  L.marker(e.latlng).addTo(map);
  L.circle(e.latlng, e.accuracy).addTo(map);
});

Особенности работы в режиме watch

Режим watch создаёт постоянный поток обновлений координат. Это влияет на:

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

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

Типичные сценарии применения параметров locate

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

map.locate({
  setView: true,
  maxZoom: 14
});

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

Навигация в реальном времени

map.locate({
  watch: true,
  enableHighAccuracy: true
});

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

Быстрое определение без высокой точности

map.locate({
  timeout: 5000,
  maximumAge: 120000
});

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

Обработка ошибок locate

Типичные причины возникновения locationerror:

  • пользователь отклонил доступ к геолокации
  • превышено время ожидания (timeout)
  • недоступны источники позиционирования
  • ограничения браузера или устройства
map.on('locationerror', function (e) {
  if (e.code === 1) {
    console.log('Доступ запрещён');
  }
});

Связь locate с внешними слоями карты

Результаты locate часто используются для динамического добавления слоёв:

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

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

Поведение при отсутствии поддержки Geolocation API

Если браузер не поддерживает геолокацию, событие locationerror срабатывает немедленно. В этом случае объект map не получает координаты, а выполнение логики, завязанной на locationfound, не происходит.

Оглавление