HTMLGeolocationElement.error — Eigenschaft · JavaScript-Referenz

Signatur

HTMLGeolocationElement.error

Beschreibung

Die Eigenschaft error des HTMLGeolocationElement-Interfaces (das DOM-Interface des deklarativen <geolocation>-Elements) enthält Informationen über den letzten fehlgeschlagenen Versuch, Standortdaten zu ermitteln. Ist der Versuch erfolgreich oder wurde noch keiner gestartet, ist der Wert null.

Klickt jemand auf das Element, fragt der Browser die Berechtigung ab und ermittelt danach den Standort. Das Ergebnis kommt über das location-Event an. Im Event-Handler prüft man zuerst error: Bei einem Fehler findet man hier ein GeolocationPositionError-Objekt mit code und message, andernfalls steht der Standort in der Eigenschaft position.

Die Fehlercodes sind dieselben wie bei der klassischen Geolocation-API:

1 – PERMISSION_DENIED: Die Berechtigung wurde verweigert.
2 – POSITION_UNAVAILABLE: Der Standort konnte nicht bestimmt werden, z. B. weil kein GPS- oder Netzwerksignal vorhanden war.
3 – TIMEOUT: Die Ermittlung hat zu lange gedauert.

Weil die Eigenschaft schreibgeschützt ist, wird sie nur ausgelesen. Sie eignet sich gut, um im Fehlerfall passende Hinweise anzuzeigen oder auf eine manuelle Adresseingabe umzuschalten.

Rückgabewert

Typ

GeolocationPositionError | null

Beschreibung

Ein GeolocationPositionError-Objekt mit code und message, wenn der letzte Versuch fehlgeschlagen ist, sonst null.

Beispiele

Fehler im location-Event auswerten

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

geo.addEventListener('location', () => {
  if (geo.error) {
    console.warn(`Fehler ${geo.error.code}: ${geo.error.message}`);
    return;
  }
  const { latitude, longitude } = geo.position.coords;
  console.log(`Standort: ${latitude}, ${longitude}`);
});

Fehler 1: User denied Geolocation

Verständliche Fehlermeldung je nach Code anzeigen

const geo = document.querySelector('geolocation');
const status = document.querySelector('#status');

const meldungen = {
  [GeolocationPositionError.PERMISSION_DENIED]: 'Standortzugriff wurde abgelehnt. Bitte geben Sie Ihre PLZ manuell ein.',
  [GeolocationPositionError.POSITION_UNAVAILABLE]: 'Ihr Standort konnte nicht bestimmt werden.',
  [GeolocationPositionError.TIMEOUT]: 'Die Standortermittlung hat zu lange gedauert. Bitte erneut versuchen.'
};

geo.onlocation = () => {
  const err = geo.error;
  status.textContent = err
    ? meldungen[err.code] ?? 'Unbekannter Fehler.'
    : 'Standort erfolgreich ermittelt.';
};

Feature-Erkennung mit Fallback auf navigator.geolocation

const zeigeFehler = (err) => console.error(`Geolocation-Fehler (${err.code}): ${err.message}`);

if ('HTMLGeolocationElement' in window) {
  const geo = document.createElement('geolocation');
  geo.addEventListener('location', () => {
    if (geo.error) zeigeFehler(geo.error);
    else console.log(geo.position.coords);
  });
  document.body.append(geo);
} else {
  // Klassischer Weg für Browser ohne <geolocation>-Element
  const button = document.createElement('button');
  button.textContent = 'Standort verwenden';
  button.onclick = () => navigator.geolocation.getCurrentPosition(
    (pos) => console.log(pos.coords),
    zeigeFehler,
    { timeout: 10000 }
  );
  document.body.append(button);
}

// Wichtig · Fallstricke

Experimentell: Das <geolocation>-Element und damit HTMLGeolocationElement gibt es bisher nur in Chromium-basierten Browsern (teilweise nur als Origin Trial). Prüfen Sie die Unterstützung vorher mit 'HTMLGeolocationElement' in window und bieten Sie einen Fallback über navigator.geolocation an.
Der Wert ist null, bevor ein Versuch stattgefunden hat und nachdem einer erfolgreich war. Prüfen Sie ihn deshalb immer, bevor Sie auf error.code zugreifen, zum Beispiel mit geo.error?.code.
Werten Sie error am besten im location-Event aus. Direkt nach dem Klick steht dort unter Umständen noch der Zustand des vorherigen Versuchs.
Der Text in message dient der Fehlersuche. Er hängt vom Browser ab, ist nicht übersetzt und sollte nicht direkt angezeigt werden. Nutzen Sie für Meldungen an Nutzer stattdessen code.
Geolocation funktioniert nur in einem sicheren Kontext (HTTPS). In eingebetteten iframes muss sie zusätzlich über die Permissions Policy (allow="geolocation") freigegeben sein, sonst kommt ein PERMISSION_DENIED-Fehler.

Siehe auch

CSSStyleDeclaration.parentRule HTMLGeolocationElement.autolocate HTMLGeolocationElement.watch HTMLGeolocationElement.isValid HTMLGeolocationElement.position