<geolocation> HTML-элемент геолокации

Элемент <geolocation> HTML создаёт интерактивный элемент управления, с помощью которого пользователь может предоставить странице данные о своём местоположении.

Он обеспечивает:

• Интуитивно понятный интерфейс, определяемый браузером.
• Процесс обработки разрешений, необходимых для функции geolocation.
• Функции API для доступа к данным о местоположении и реакции на полученные данные о местоположении и изменения разрешений.

Атрибуты

Этот элемент включает глобальные атрибуты.

autolocate

Логический атрибут, который при значении true указывает, что браузер должен немедленно получить данные о местоположении при отображении элемента <geolocation>, если разрешение было предоставлено ранее. Если установлено значение false, данные о местоположении не будут получены, пока пользователь не активирует элемент управления. По умолчанию — false.

Если разрешение не было предоставлено ранее, этот атрибут не действует.

watch

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

Описание

Элемент <geolocation> предоставляет элемент управления для передачи данных о местоположении, интерфейс которого задаётся браузером. Например, в Chrome на кнопке отображается значок «булавки на карте» и понятный текст («Use location» в англоязычном интерфейсе).

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

Ключевой аспект элемента <geolocation> заключается в том, что он отражает осознанный выбор пользователя и блокирует возможные способы обманом заставить пользователя невольно предоставить данные о своём местоположении (подробнее см. в разделе блокировка <geolocation>).

Интерфейс DOM API этого элемента, HTMLGeolocationElement, предоставляет средства для доступа к возвращённым данным о местоположении, текущему состоянию разрешения и сведениям об ошибках, если получить данные не удалось. Это позволяет сократить объём необходимого кода JavaScript. Также доступны события, позволяющие выполнять код в ответ на получение данных о местоположении, изменение состояния разрешения и взаимодействие пользователя с диалоговым окном разрешения.

Связь с Geolocation API

Geolocation API — это более старый альтернативный способ работы с данными о местоположении. У этого API есть ряд недостатков, которые призван устранить элемент <geolocation>. Самый существенный из них заключается в том, что пользовательский интерфейс и основную логику запроса данных каждый раз необходимо реализовывать с нуля, а обработка разрешений может быть неинтуитивной.

Элемент <geolocation> в фоновом режиме использует возможности Geolocation API. По умолчанию браузер запрашивает данные о местоположении один раз, как если бы был вызван метод Geolocation.getCurrentPosition(). Однако, если для атрибута watch установлено значение true, браузер обновляет данные при каждом изменении положения устройства, как если бы был вызван метод Geolocation.watchPosition().

Если данные успешно получены, они доступны в свойстве HTMLGeolocationElement.position, содержащем объект GeolocationPosition. Если получить данные не удалось, сведения об ошибке доступны в свойстве HTMLGeolocationElement.error, содержащем объект GeolocationPositionError.

Настройка языка кнопки

Глобальный атрибут lang используется элементом <geolocation> для выбора языка отображаемого текста. Это означает, что можно задать атрибут lang непосредственно для элемента <geolocation> или одного из его предков, чтобы указать браузеру, на каком языке отображать текст кнопки.

Если подходящий атрибут lang не задан, используется предпочитаемый язык браузера.

Добавление резервного содержимого

Между открывающим и закрывающим тегами элемента <geolocation> можно добавить резервное содержимое, которое будет отображаться, если этот элемент не поддерживается. Например, можно добавить сообщение «Не поддерживается»:

<geolocation>
  <p>Your browser doesn't support the Geolocation element.</p>
</geolocation>

Однако для реального использования лучше добавить обычный элемент <button>, который использует Geolocation API для получения данных о местоположении:

<geolocation>
  <button id="fallback">Use location</button>
</geolocation>

Блокировка <geolocation>

Одна из ключевых идей, лежащих в основе элемента <geolocation>, заключается в том, что он должен отражать осознанный выбор пользователя раскрыть сведения о местоположении и не позволять злоумышленникам обманом заставлять пользователей активировать его, например с помощью кликджекинга. Поэтому браузер хранит так называемые причины блокировки для каждого отображённого элемента.

Если для элемента <geolocation> действует блокировка, он не может функционировать (заблокирован) — временно или навсегда, в зависимости от причины. Заблокированный элемент <geolocation> считается недействительным. Проверить, является ли он недействительным, можно с помощью свойства HTMLGeolocationElement.isValid. Причину недействительности можно получить с помощью свойства HTMLGeolocationElement.invalidReason — полный список возможных причин см. на этой странице.

Ограничения стилизации

Для элемента <geolocation> предусмотрен ряд ограничений на CSS-стили, которые можно к нему применить. Некоторые из них предназначены для обеспечения основных требований доступности; при их несоблюдении кнопка деактивируется. Другие задают определённые значения или диапазоны значений для различных свойств.

Любые свойства, не перечисленные в следующих подразделах и не являющиеся логически эквивалентными физическим свойствам, перечисленным в следующих подразделах, игнорируются при задании для элемента <geolocation>.

Ограничения доступности

Отображаемая кнопка <geolocation> деактивируется (нажатие на неё не даст эффекта), если не соблюдены следующие ограничения:

• Контрастность цветов color и background-color должна быть не ниже 3:1.
• Значение font-size не должно быть меньше значения small (для ключевых слов) или его вычисленного значения (для других типов значений).

Ограничения значений

Для элемента <geolocation> действуют следующие ограничения на значения CSS-свойств. Если предпринята попытка задать для элемента <geolocation> значения, выходящие за указанные ограничения, значение корректируется до соответствующего ограничения (для точного ограничения значения) или до ближайшей вычисленной верхней или нижней границы (для ограничения диапазона).

opacity

1.0

line-height

normal

white-space

nowrap

user-select

none

appearance

auto

box-sizing

content-box

vertical-align

middle

text-emphasis

initial

text-shadow

initial

outline-offset

0 или больше.

font-weight

200 или больше.

word-spacing

От 0 до 0.5em включительно.

letter-spacing

От -0.05em до 0.2em включительно.

letter-spacing

От -0.05em до 0.2em включительно.

min-height

1em или больше.

max-height

3em или меньше. Значение none допустимо.

min-width

Вычисленное значение fit-content или меньше.

border-width

1em или меньше.

Сложные ограничения

Следующие ограничения сложнее, чем простые ограничения значений:

Внутренний отступ в блочном направлении

Если для block-size задано значение auto, свойства padding-block-start и padding-block-end (а также соответствующие физические свойства для текущего режима письма) ограничены максимальным значением 1em и должны быть равны.

Внутренний отступ во встроенном направлении

Если для inline-size задано значение auto, свойства padding-inline-start и padding-inline-end (а также соответствующие физические свойства для текущего режима письма) ограничены максимальным значением 5em и должны быть равны.

Свойства, которые можно задавать обычным образом

Следующие CSS-свойства можно использовать обычным образом:

• font-kerning
• font-optical-sizing
• font-stretch
• font-synthesis-weight
• font-synthesis-style
• font-synthesis-small-caps
• font-feature-settings
• forced-color-adjust
• text-rendering
• align-self
• anchor-name
• aspect-ratio
• border, border-top, border-right, border-bottom и border-left
• clear
• color-scheme
• contain-intrinsic-width
• contain-intrinsic-height
• container-name
• container-type
• counter-reset, counter-increment и counter-set
• flex, flex-grow, flex-shrink и flex-basis
• float
• height
• isolation
• justify-self
• left
• order
• orphans
• outline, outline-color и outline-style
• overflow-anchor
• overscroll-behavior, overscroll-behavior-inline, overscroll-behavior-block, overscroll-behavior-x и overscroll-behavior-y
• page
• position
• position-anchor
• right
• scroll-margin, scroll-margin-top, scroll-margin-right, scroll-margin-bottom и scroll-margin-left
• scroll-padding, scroll-padding-top, scroll-padding-right, scroll-padding-bottom, scroll-padding-left, scroll-padding-inline-start, scroll-padding-block-start, scroll-padding-block-start, scroll-padding-inline-end и scroll-padding-block-end
• text-spacing-trim
• text-transform
• top
• visibility
• x
• y
• ruby-position
• user-select
• width
• will-change
• z-index

Доступность

У элемента <geolocation> есть доступное имя, заданное на установленном для него языке. Кроме того, ему назначена role button, благодаря которой программы экранного доступа распознают его как кнопку.

Кроме того, элементу <geolocation> по умолчанию задано значение 0 для tabindex, поэтому в отношении фокуса клавиатуры он ведёт себя как настоящий элемент <button>.

Наконец, сведения об ограничениях стилизации элемента <geolocation>, установленных для обеспечения основных требований доступности, приведены в разделе Ограничения доступности.

Примеры

Пример базового использования

В этом примере элемент <geolocation> используется для получения вашего текущего местоположения, которое выводится под кнопкой в элементе <p>. В примере также предусмотрен обычный резервный вариант <button> для получения данных о местоположении в браузерах, не поддерживающих этот элемент.

HTML

Мы добавляем элемент <geolocation> с вложенным резервным вариантом <button>, который будет отображаться в браузерах, не поддерживающих <geolocation>. Также добавляем элемент <p>, в который будут выводиться данные о местоположении и ошибки.

<geolocation>
  <button id="fallback">Use location</button>
</geolocation>
<p id="output"></p>

JavaScript

В нашем скрипте сначала получаем ссылку на выходной элемент <p>. Затем проверяем поддержку элемента <geolocation> с помощью typeof HTMLGeolocationElement === "function":

• Если элемент поддерживается, сначала получаем ссылку на элемент <geolocation>, а затем добавляем обработчик события location. Когда пользователь нажимает кнопку и данные получены, обработчик выводит координаты (широту и долготу) в выходной элемент <p> (полученные через свойство position) или сообщение об ошибке, если получить данные не удалось (полученное через свойство error).
• Если элемент не поддерживается, получаем ссылку на резервный элемент <button> и получаем и выводим те же данные. Однако на этот раз мы используем обработчик события click для кнопки и вызов Geolocation.getCurrentPosition() для получения данных.

const outputElem = document.querySelector("#output");

if (typeof HTMLGeolocationElement === "function") {
  const geo = document.querySelector("geolocation");
  geo.addEventListener("location", () => {
    if (geo.position) {
      outputElem.textContent += `(${geo.position.coords.latitude},${geo.position.coords.longitude}), `;
    } else if (geo.error) {
      outputElem.textContent += `${geo.error.message}, `;
    }
  });
} else {
  const fallback = document.querySelector("#fallback");
  fallback.addEventListener("click", () => {
    navigator.geolocation.getCurrentPosition(
      (position) => {
        outputElem.textContent += `(${position.coords.latitude}, ${position.coords.longitude}), `;
      },
      (error) => {
        outputElem.textContent += `${error.message}, `;
      },
    );
  });
}

Результат

Посмотрите, как этот код работает в браузере (исходный код). Также доступна версия этого примера с атрибутом watch у элемента <geolocation>, которая получает данные о местоположении при каждом изменении положения устройства пользователя (см. работающую версию и исходный код).

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

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

Техническая сводка

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

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

См. также

• HTMLGeolocationElement
• geolocation Политика разрешений
• API геолокации
• API разрешений
• Представляем элемент HTML <geolocation> на developer.chrome.com (2026)