API геолокации

Базовая версия Широко доступна

Эта функция хорошо отработана и работает на многих устройствах и версиях браузеров. Она доступна в браузерах с июля 2015 года.

Защищённый контекст: Эта функция доступна только в защищённых контекстах (HTTPS), в некоторых или во всех поддерживающих браузерах.

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

Веб-расширения, которые хотят использовать объект Geolocation, должны добавить разрешение "geolocation" в свой манифест. Операционная система пользователя запросит у пользователя разрешение на доступ к местоположению при первом запросе.

Основные понятия и использование

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

Доступ к API геолокации осуществляется через вызов navigator.geolocation; это заставит браузер пользователя запросить разрешение на доступ к данным о его местоположении. Если пользователь соглашается, браузер использует лучшие доступные на устройстве возможности для доступа к этой информации (например, GPS).

Теперь разработчик может получить доступ к этой информации о местоположении несколькими способами:

Geolocation.getCurrentPosition(): Получает текущее местоположение устройства.
Geolocation.watchPosition(): Регистрирует обработчик функций, который будет вызываться автоматически каждый раз, когда меняется положение устройства, возвращая обновлённое местоположение.

В обоих случаях вызов метода принимает до трёх аргументов:

Обязательная функция обратного вызова успеха: если получение местоположения успешно, функция обратного вызова выполняется с объектом GeolocationPosition в качестве единственного параметра, предоставляя доступ к данным о местоположении.
Необязательная функция обратного вызова ошибки: если получение местоположения не удалось, функция обратного вызова выполняется с объектом GeolocationPositionError в качестве единственного параметра, предоставляя информацию о том, что пошло не так.
Необязательный объект, который предоставляет параметры для получения данных о местоположении.

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

Интерфейсы

Geolocation: Основной класс этого API — содержит методы для получения текущего местоположения пользователя, отслеживания изменений его местоположения и удаления ранее установленного наблюдения.
GeolocationPosition: Представляет местоположение пользователя. Экземпляр GeolocationPosition возвращается успешным вызовом одного из методов, содержащихся в Geolocation, внутри обратного вызова успеха и содержит отметку времени плюс объект GeolocationCoordinates.
GeolocationCoordinates: Представляет координаты местоположения пользователя; экземпляр GeolocationCoordinates содержит широту, долготу и другую важную связанную информацию.
GeolocationPositionError: Объект GeolocationPositionError возвращается при неудачном вызове одного из методов, содержащихся в Geolocation, в обратном вызове ошибки, и содержит код и сообщение об ошибке.

Расширения других интерфейсов

Navigator.geolocation: Точка входа в API. Возвращает экземпляр объекта Geolocation, с помощью которого можно получить доступ ко всем остальным функциям.

Соображения безопасности

API геолокации позволяет пользователям программно получать информацию о местоположении в защищённых контекстах.

Доступ может быть дополнительно контролируется директивой Политики разрешений geolocation. Список разрешённых значений по умолчанию для geolocation — self, что позволяет получить доступ к информации о местоположении только в вложенных фреймах того же происхождения. Доступ третьих сторон активируется установкой заголовка ответа Permissions-Policy для предоставления разрешения определённому происхождению третьей стороны:

Permissions-Policy: geolocation=(self b.example.com)

Атрибут allow="geolocation" должен быть добавлен к элементу iframe с источниками из этого происхождения:

<iframe src="https://b.example.com" allow="geolocation"/></iframe>

Данные о местоположении могут раскрывать информацию, которую владелец устройства не хочет делиться. Поэтому пользователи должны предоставить явное разрешение через запрос при вызове Geolocation.getCurrentPosition() или Geolocation.watchPosition() (если состояние разрешения ещё не granted или denied). Срок действия предоставленного разрешения зависит от агента пользователя и может быть основан на времени, сессии или даже быть постоянным. API разрешений geolocation может быть использован для проверки того, доступ к использованию информации о местоположении granted, denied или prompt (требуется подтверждение пользователя после запроса).

Примеры

См. примеры кода в Использование API геолокации.

Спецификации

Спецификация
Геолокация # geolocation_interface

Совместимость с браузерами

	Рабочие столы					Мобильные устройства
	Chrome	Edge	Firefox	Opera	Safari	Chrome Android	Firefox для Android	Opera Android	Safari на IOS	Samsung Internet	WebView Android
`Geolocation_API`	5	12	3.5 GPSD (GPS демон) поддержка добавлена в Firefox 3.6. Местоположение на основе Wi-Fi предоставляется Google (конфиденциальность) или пользовательский провайдер (инструкции MLS).	10.6	5	18	4	11	≤3	1.0	≤37
`clearWatch`	5	12	3.5	10.6	5	18	4	11	≤3	1.0	≤37
`getCurrentPosition`	5	12	3.5	10.6	5	18	4	11	≤3	1.0	≤37
`secure_context_required`	50	79	55	37	10	50	55	37	10	5.0	51 Защищённый контекст требуется только для приложений, нацеленных на Android Nougat (7) и выше. См. баг 40465140.
`watchPosition`	5	12	3.5	10.6	5	18	4	11	≤3	1.0	≤37

Доступность

Поскольку определение местоположения на основе Wi-Fi часто предоставляется Google, стандартный API геолокации может быть недоступен в Китае. Вы можете использовать локальных сторонних поставщиков, таких как Baidu, Autonavi или Tencent. Эти сервисы используют IP-адрес пользователя и/или локальное приложение для улучшения определения местоположения.

См. также

© 2005–2024 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API