GeolocateControl

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

Не все браузеры поддерживают геолокацию, а некоторые пользователи могут отключить эту функцию. Для поддержки геолокации в современных браузерах, включая Chrome, сайт должен обслуживаться по протоколу HTTPS. Если поддержка геолокации недоступна, GeolocateControl будет отображаться как отключенный.

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

У GeolocateControl есть два режима. Если trackUserLocation равно false (по умолчанию), элемент управления действует как кнопка: при нажатии камера карты наводится на местоположение пользователя. Если пользователь переместится, карта не обновится. Этот режим лучше всего подходит для настольных компьютеров. Если trackUserLocation равно true, элемент управления действует как переключатель, который при активации отслеживает изменения местоположения пользователя. В этом режиме у GeolocateControl есть три состояния взаимодействия: * active — камера карты автоматически обновляется при изменении местоположения пользователя, удерживая точку местоположения в центре. Начальное состояние; также устанавливается при нажатии кнопки GeolocateControl. * passive — точка местоположения пользователя автоматически обновляется, но камера карты — нет. Возникает, когда пользователь начинает перемещать карту. * disabled — возникает, если геолокация недоступна, отключена или в доступе отказано.

Эти состояния взаимодействия нельзя задать программно; они устанавливаются на основе действий пользователя.

Диаграмма состояний

Примеры

map.addControl(new GeolocateControl({
    positionOptions: {
        enableHighAccuracy: true
    },
    trackUserLocation: true
}));

// Initialize the geolocate control.
let geolocate = new GeolocateControl({
  positionOptions: {
      enableHighAccuracy: true
  },
  trackUserLocation: true
});
// Add the control to the map.
map.addControl(geolocate);
// Set an event listener that fires
// when a trackuserlocationend event occurs.
geolocate.on('trackuserlocationend', () => {
  console.log('A trackuserlocationend event has occurred.')
});

// Initialize the geolocate control.
let geolocate = new GeolocateControl({
  positionOptions: {
      enableHighAccuracy: true
  },
  trackUserLocation: true
});
// Add the control to the map.
map.addControl(geolocate);
// Set an event listener that fires
// when a trackuserlocationstart event occurs.
geolocate.on('trackuserlocationstart', () => {
  console.log('A trackuserlocationstart event has occurred.')
});

// Initialize the geolocate control.
let geolocate = new GeolocateControl({
  positionOptions: {
      enableHighAccuracy: true
  },
  trackUserLocation: true
});
// Add the control to the map.
map.addControl(geolocate);
// Set an event listener that fires
// when an userlocationlostfocus event occurs.
geolocate.on('userlocationlostfocus', function() {
  console.log('An userlocationlostfocus event has occurred.')
});

// Initialize the geolocate control.
let geolocate = new GeolocateControl({
  positionOptions: {
      enableHighAccuracy: true
  },
  trackUserLocation: true
});
// Add the control to the map.
map.addControl(geolocate);
// Set an event listener that fires
// when an userlocationfocus event occurs.
geolocate.on('userlocationfocus', function() {
  console.log('An userlocationfocus event has occurred.')
});

// Initialize the geolocate control.
let geolocate = new GeolocateControl({
  positionOptions: {
      enableHighAccuracy: true
  },
  trackUserLocation: true
});
// Add the control to the map.
map.addControl(geolocate);
// Set an event listener that fires
// when a geolocate event occurs.
geolocate.on('geolocate', () => {
  console.log('A geolocate event has occurred.')
});

// Initialize the geolocate control.
let geolocate = new GeolocateControl({
  positionOptions: {
      enableHighAccuracy: true
  },
  trackUserLocation: true
});
// Add the control to the map.
map.addControl(geolocate);
// Set an event listener that fires
// when an error event occurs.
geolocate.on('error', () => {
  console.log('An error event has occurred.')
});

// Initialize the geolocate control.
let geolocate = new GeolocateControl({
  positionOptions: {
      enableHighAccuracy: true
  },
  trackUserLocation: true
});
// Add the control to the map.
map.addControl(geolocate);
// Set an event listener that fires
// when an outofmaxbounds event occurs.
geolocate.on('outofmaxbounds', () => {
  console.log('An outofmaxbounds event has occurred.')
});

См. также

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

События

Событие trackuserlocationend типа Event будет вызвано, когда GeolocateControl перейдет в фоновое состояние. Это происходит, когда пользователь перемещает камеру во время активной блокировки позиции. Применяется только если trackUserLocation равно true. В фоновом состоянии точка на карте обновляется при изменении местоположения, но камера — нет.

Событие trackuserlocationstart типа Event будет вызвано, когда GeolocateControl перейдет в состояние активной блокировки. Это происходит либо после первого успешного получения местоположения пользователя через Geolocation API (за этим последует событие geolocate), либо когда пользователь нажимает кнопку геолокации в фоновом состоянии: карта центрируется по последнему известному местоположению и переходит в состояние активной блокировки (событие geolocate не последует, если только местоположение пользователя не изменится).

Событие userlocationlostfocus типа Event будет вызвано, когда GeolocateControl перейдет в фоновое состояние. Это происходит, когда пользователь перемещает камеру во время активной блокировки позиции. Применяется только если trackUserLocation равно true. В фоновом состоянии точка на карте обновляется при изменении местоположения, но камера — нет.

Событие userlocationfocus типа Event будет вызвано, когда GeolocateControl перейдет в состояние активной блокировки. Это происходит, когда пользователь нажимает кнопку геолокации в фоновом состоянии: карта центрируется по последнему известному местоположению и переходит в состояние активной блокировки.

Событие geolocate типа Event будет вызвано при каждом успешном обновлении местоположения через Geolocation API. data — объект Position, возвращаемый функцией обратного вызова в Geolocation.getCurrentPosition() или Geolocation.watchPosition().

Событие error типа Event будет вызвано при каждом обновлении местоположения через Geolocation API, завершившемся ошибкой. data — объект PositionError, возвращаемый функцией обратного вызова в Geolocation.getCurrentPosition() или Geolocation.watchPosition().

Событие outofmaxbounds типа Event будет вызвано при каждом успешном обновлении местоположения через Geolocation API, если местоположение пользователя находится за пределами maxBounds карты. data — объект Position, возвращаемый функцией обратного вызова в Geolocation.getCurrentPosition() или Geolocation.watchPosition().

Наследует

• Evented<GeolocateControlEventType>

Реализует

• IControl

Краткое описание конструкторов

Конструктор

new GeolocateControl(options: GeolocateControlOptions): GeolocateControl

Параметры

Возвращает

GeolocateControl

Переопределяет

Evented<GeolocateControlEventType>.constructor

Краткое описание методов

_isOutOfMapMaxBounds()

_isOutOfMapMaxBounds(position: GeolocationPosition): boolean

Проверяет, находится ли Position из Geolocation API за пределами maxBounds карты.

Параметры

Возвращает

boolean

true, если позиция находится за пределами maxBounds карты; в противном случае возвращает false.

_onSuccess()

_onSuccess(position: GeolocationPosition): void

При получении нового местоположения через Geolocation API обновляет GeolocateControl.

Параметры

Возвращает

void

_updateCamera()

_updateCamera(position: GeolocationPosition): void

Обновляет местоположение камеры, чтобы центрировать её на текущем местоположении

Параметры

Возвращает

void

_updateMarker()

_updateMarker(position?: GeolocationPosition): void

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

Параметры

Возвращает

void

fire()

Сигнатура вызова

fire(event: GeolocateEvent | GeolocatePositionEvent | GeolocateErrorEvent): this

Вызывает все обработчики, зарегистрированные для типа события.

Параметры

Возвращает

this

Унаследовано от

Evented.fire

Сигнатура вызова

fire(type: keyof GeolocateControlEventType, properties?: object): this

Совместимость с сигнатурой (type: string, properties: Object) из предыдущих версий. См. https://github.com/mapbox/mapbox-gl-js/issues/6522, https://github.com/mapbox/mapbox-gl-draw/issues/766

Параметры

Возвращает

this

Унаследовано от

Evented.fire

listens()

listens(type: keyof GeolocateControlEventType): boolean

Возвращает true, если у этого экземпляра Evented или любого перенаправленного экземпляра Evented есть обработчик для указанного типа.

Параметры

Возвращает

boolean

true, если для указанного типа события зарегистрирован хотя бы один обработчик, в противном случае — false

Унаследовано от

Evented.listens

off()

off<T extends keyof GeolocateControlEventType>(type: T, listener: (event: GeolocateControlEventType[T]) => void): this

Удаляет ранее зарегистрированный обработчик события.

Параметры типа

Параметры

Возвращает

this

Унаследовано от

Evented.off

on()

on<T extends keyof GeolocateControlEventType>(type: T, listener: (event: GeolocateControlEventType[T]) => void): Subscription

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

Параметры типа

Параметры

Возвращает

Subscription

Унаследовано от

Evented.on

onAdd()

onAdd(map: Map): HTMLElement

Регистрирует элемент управления на карте и позволяет ему зарегистрировать прослушиватели событий и ресурсы. Этот метод вызывается внутри Map.addControl.

Параметры

Возвращает

HTMLElement

Элемент-контейнер элемента управления. Элемент должен быть создан самим элементом управления и возвращен методом onAdd без добавления в DOM: при необходимости карта вставит элемент управления в DOM.

Реализация

IControl.onAdd

once()

Сигнатура вызова

once<T extends keyof GeolocateControlEventType>(type: T): Promise<GeolocateControlEventType[T]>

Добавляет прослушиватель, который будет вызван только один раз для указанного типа события.

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

Параметры типа

Параметры

Возвращает

Promise<GeolocateControlEventType[T]>

промис, который разрешается объектом события

Унаследовано от

Evented.once

Сигнатура вызова

once<T extends keyof GeolocateControlEventType>(type: T, listener: (event: GeolocateControlEventType[T]) => void): this

Добавляет прослушиватель, который будет вызван только один раз для указанного типа события.

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

Параметры типа

Параметры

Возвращает

this

this, если передан прослушиватель

Унаследовано от

Evented.once

onRemove()

onRemove(): void

Отменяет регистрацию элемента управления на карте и позволяет ему отсоединить прослушиватели событий и освободить ресурсы. Этот метод вызывается внутри Map.removeControl.

Возвращает

void

Реализация

IControl.onRemove

setEventedParent()

setEventedParent(parent?: Evented<EventTypeMap>, data?: EventedParentData | (() => EventedParentData)): this

Передает все события, возникающие в этом экземпляре Evented, родительскому экземпляру Evented.

Параметры

Возвращает

this

Унаследовано от

Evented.setEventedParent

trigger()

trigger(): boolean

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

Возвращает

boolean

false, если вызван до добавления элемента управления на карту; в противном случае возвращает true.

Пример

// Initialize the geolocate control.
let geolocate = new GeolocateControl({
 positionOptions: {
   enableHighAccuracy: true
 },
 trackUserLocation: true
});
// Add the control to the map.
map.addControl(geolocate);
map.on('load', () => {
  geolocate.trigger();
});