HTMLGeolocationElement: location — Ereignis · JavaScript-Referenz

Signatur

geolocationElement.addEventListener("location", handler)

Beschreibung

Das location-Ereignis gehört zur Schnittstelle HTMLGeolocationElement, also zum neuen deklarativen <geolocation>-Element. Klickt der Nutzer auf das Element und erteilt die Berechtigung, fragt der Browser die Position ab. Sobald ein Ergebnis vorliegt, wird location ausgelöst – egal ob die Abfrage erfolgreich war oder fehlgeschlagen ist.

Das Ereignis selbst ist ein einfaches Event ohne eigene Nutzdaten. Die eigentlichen Daten liest man im Handler direkt am Element aus: element.position enthält bei Erfolg ein GeolocationPosition-Objekt (mit coords und timestamp), element.error bei einem Fehlschlag ein GeolocationPositionError. Die jeweils andere Eigenschaft ist null.

Den Handler registriert man entweder mit addEventListener("location", handler) oder über die Eigenschaft onlocation bzw. das HTML-Attribut onlocation. Mit dem Attribut watch beobachtet das Element die Position laufend (ähnlich wie navigator.geolocation.watchPosition()). Dann wird location bei jeder Positionsänderung erneut ausgelöst. Mit autolocate wird die Position automatisch abgefragt, wenn die Berechtigung bereits erteilt ist.

Das Element ersetzt in vielen Fällen den imperativen Aufruf von navigator.geolocation.getCurrentPosition(). Weil der Nutzer aktiv auf ein vom Browser gezeichnetes Bedienelement klickt, ist die Berechtigungsanfrage für ihn besser nachvollziehbar, und ein einmal verweigerter Zugriff lässt sich leichter erneut erteilen.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"location"`.
$handler Pflicht	(event: Event) => void		Callback, das beim Eintreffen von Positionsdaten oder eines Fehlers aufgerufen wird. `event.target` ist das `HTMLGeolocationElement`, dessen Eigenschaften `position` und `error` du auslesen kannst.
$options	boolean \| AddEventListenerOptions	false	Optionen wie `once`, `signal` oder `capture`.

Rückgabewert

Typ

void

Beschreibung

addEventListener() gibt nichts zurück. Die Nutzdaten stehen in element.position (GeolocationPosition | null) bzw. element.error (GeolocationPositionError | null).

Beispiele

Position per addEventListener auswerten

// HTML: <geolocation id="geo"></geolocation>
// <p id="status"></p>
const geo = document.querySelector('#geo');
const status = document.querySelector('#status');

geo.addEventListener('location', () => {
  if (geo.position) {
    const { latitude, longitude, accuracy } = geo.position.coords;
    status.textContent = `Standort: ${latitude.toFixed(4)}, ${longitude.toFixed(4)} (±${Math.round(accuracy)} m)`;
  } else if (geo.error) {
    status.textContent = `Fehler ${geo.error.code}: ${geo.error.message}`;
  }
});

Standort: 52.5200, 13.4050 (±25 m)

Handler über die onlocation-Eigenschaft

const geo = document.createElement('geolocation');
document.body.append(geo);

geo.onlocation = (event) => {
  const el = event.target;
  if (el.error) {
    console.warn('Ortung fehlgeschlagen:', el.error.message);
    return;
  }
  console.log('Zeitstempel:', new Date(el.position.timestamp).toISOString());
};

// Handler wieder entfernen
// geo.onlocation = null;

Zeitstempel: 2025-01-15T10:32:07.000Z

Laufende Beobachtung mit watch und Abmelden per AbortController

// HTML: <geolocation id="tracker" watch></geolocation>
// <button id="stop">Tracking beenden</button>
const tracker = document.querySelector('#tracker');
const controller = new AbortController();
const track = [];

const onLocation = () => {
  if (!tracker.position) return;
  const { latitude, longitude } = tracker.position.coords;
  track.push([latitude, longitude]);
  console.log(`Punkt ${track.length}:`, latitude, longitude);
};

tracker.addEventListener('location', onLocation, { signal: controller.signal });

document.querySelector('#stop').addEventListener('click', () => {
  controller.abort(); // entspricht removeEventListener('location', onLocation)
  tracker.watch = false; // Beobachtung beenden
  console.log('Aufgezeichnete Punkte:', track.length);
});

Punkt 1: 52.52 13.405 Punkt 2: 52.5201 13.4052 Aufgezeichnete Punkte: 2

Feature-Erkennung mit Fallback

const supportsElement = typeof window.HTMLGeolocationElement === 'function';

if (supportsElement) {
  const geo = document.createElement('geolocation');
  geo.addEventListener('location', () => console.log(geo.position ?? geo.error));
  document.body.append(geo);
} else if ('geolocation' in navigator) {
  const btn = document.createElement('button');
  btn.textContent = 'Standort verwenden';
  btn.addEventListener('click', () => {
    navigator.geolocation.getCurrentPosition(
      (pos) => console.log(pos),
      (err) => console.log(err)
    );
  });
  document.body.append(btn);
}

// Wichtig · Fallstricke

Experimentell: <geolocation> und damit das location-Ereignis gibt es bisher nur in Chromium-basierten Browsern (Origin Trial bzw. hinter einem Flag). Firefox und Safari unterstützen es nicht. Prüfe die Unterstützung immer mit 'HTMLGeolocationElement' in window und sieh einen Fallback über navigator.geolocation vor.
Erfolg und Fehler im selben Ereignis: Es gibt kein separates Fehler-Ereignis. Prüfe im Handler immer beide Eigenschaften, position und error. Greifst du bei einem Fehler ungeprüft auf position.coords zu, wirft das einen TypeError.
Keine Nutzdaten am Event: Das Ereignis ist ein einfaches Event. Eigenschaften wie event.coords gibt es nicht.
Sicherer Kontext und Berechtigungsrichtlinie: Das Element funktioniert nur über HTTPS (bzw. localhost). In iframes muss die Permissions-Policy geolocation erlaubt sein.
Gültigkeit des Elements: Der Browser deaktiviert das Element, wenn es verdeckt, zu klein, zu transparent oder mit zu geringem Kontrast gestaltet ist, oder wenn es gerade erst eingeblendet wurde. Dann wird kein location ausgelöst. Den Zustand kannst du über invalid bzw. invalidReason und das Ereignis validationstatuschange prüfen.
Datenschutz und Akku: Mit watch wird location oft ausgelöst. Beende die Beobachtung, wenn du sie nicht mehr brauchst. Positionsdaten sind personenbezogene Daten und sollten nur mit Zweckbindung übertragen werden.

Siehe auch

HTMLGeolocationElement: promptaction HTMLGeolocationElement: promptdismiss HTMLGeolocationElement: validationstatuschange HTMLDialogElement: cancel HTMLMediaElement: emptied HTMLFormElement: formdata HTMLFormElement: submit