HTMLGeolocationElement.invalidReason — Eigenschaft · JavaScript-Referenz

Signatur

HTMLGeolocationElement.invalidReason

Beschreibung

Das <geolocation>-Element ist ein vom Browser gerendertes Bedienelement. Über einen Klick darauf gibt der Nutzer bewusst den Standort frei. Damit Seiten den Nutzer nicht zu einem Klick verleiten können (Clickjacking), prüft der Browser laufend, ob das Element sichtbar, unverdeckt, korrekt gestaltet und in einem erlaubten Kontext eingebunden ist. Ist eine dieser Bedingungen verletzt, gilt das Element als ungültig: Klicks lösen dann keine Berechtigungsabfrage aus.

invalidReason nennt den Grund dafür als Zeichenkette. Ist das Element gültig (isValid === true), ist der Wert ein leerer String "". Mögliche Werte sind unter anderem:

"type_invalid": Der Elementtyp bzw. die Konfiguration ist ungültig.
"illegal_subframe": Das Element steckt in einem Cross-Origin-<iframe>, für das die Permissions Policy geolocation nicht erlaubt ist.
"unsuccessful_registration": Das Element konnte nicht registriert werden, z. B. weil zu viele Berechtigungselemente auf der Seite sind.
"recently_attached": Das Element wurde gerade erst in das DOM eingefügt. Es ist erst nach einer kurzen Schonfrist bedienbar.
"intersection_changed": Position oder Größe haben sich gerade verändert.
"intersection_out_of_viewport_or_clipped": Das Element liegt ganz oder teilweise außerhalb des sichtbaren Bereichs oder wird abgeschnitten.
"intersection_occluded_or_distorted": Das Element wird von anderen Inhalten verdeckt oder ist verzerrt, etwa durch Transformationen.
"style_invalid": Unzulässiges CSS, z. B. zu geringer Kontrast, zu kleine Schrift oder Transparenz.

Praktisch nützlich ist die Eigenschaft für die Fehlersuche und für eine Nutzerführung, die sich an den Zustand anpasst. Lies den Wert am besten im Handler des Ereignisses validationstatuschange aus, denn der Status kann sich jederzeit ändern, etwa beim Scrollen, durch Animationen oder überlagernde Dialoge.

Rückgabewert

Typ

string

Beschreibung

Ein Aufzählungswert wie "style_invalid" oder "intersection_occluded_or_distorted". Ist das Element gültig, ist es ein leerer String "".

Beispiele

Gültigkeitsgrund beim Statuswechsel protokollieren

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

geo.addEventListener('validationstatuschange', () => {
  if (geo.isValid) {
    console.log('Standort-Button ist bedienbar');
  } else {
    console.warn(`Blockiert: ${geo.invalidReason}`);
  }
});

Blockiert: recently_attached Standort-Button ist bedienbar

Verständliche Hinweise für Nutzer anzeigen

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

const messages = {
  illegal_subframe: 'Standortfreigabe ist in diesem eingebetteten Rahmen nicht erlaubt.',
  intersection_out_of_viewport_or_clipped: 'Bitte scrolle, bis der Standort-Button vollständig sichtbar ist.',
  intersection_occluded_or_distorted: 'Der Standort-Button wird verdeckt – schließe offene Dialoge.',
  style_invalid: 'Der Button ist fehlerhaft gestaltet (Entwicklerfehler).'
};

geo.onvalidationstatuschange = () => {
  hint.textContent = geo.isValid ? '' : (messages[geo.invalidReason] ?? '');
};

Styling-Fehler während der Entwicklung finden

const geo = document.createElement('geolocation');
geo.style.opacity = '0.3'; // unzulässig: Element muss voll deckend sein
document.body.append(geo);

// Schonfrist nach dem Einfügen abwarten
setTimeout(() => {
  console.log(geo.isValid, JSON.stringify(geo.invalidReason));
}, 1000);

false "style_invalid"

Feature-Erkennung vor der Nutzung

if ('HTMLGeolocationElement' in window) {
  const geo = document.querySelector('geolocation');
  console.log('Aktueller Grund:', geo.invalidReason || '(gültig)');
} else {
  // Fallback auf die klassische API
  navigator.geolocation.getCurrentPosition(
    (pos) => console.log(pos.coords.latitude, pos.coords.longitude),
    (err) => console.error(err.message)
  );
}

Aktueller Grund: (gültig)

// Wichtig · Fallstricke

Experimentell: Das <geolocation>-Element gibt es bisher nur in Chromium-basierten Browsern, teils nur hinter Flags oder in Origin Trials. Firefox und Safari unterstützen es nicht. Prüfe die Unterstützung vorab mit 'HTMLGeolocationElement' in window und halte navigator.geolocation als Ausweichlösung bereit.
Die Liste der möglichen Werte kann sich noch ändern, während die Spezifikation reift. Wer die Werte fest in eine Zuordnungstabelle schreibt, sollte deshalb eine Standardmeldung für unbekannte Werte vorsehen.
Direkt nach dem Einfügen in das DOM ist der Wert meist "recently_attached". Das ist kein Fehler, sondern eine absichtliche Schonfrist gegen Clickjacking.
Der Wert ist flüchtig: Scrollen, CSS-Animationen, Overlays oder Größenänderungen können ihn jederzeit ändern. Frage ihn deshalb nicht nur einmal ab, sondern reagiere auf validationstatuschange.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wird ignoriert, im Strict Mode löst sie einen TypeError aus.
Zeige Nutzern nicht einfach die rohen Werte an. Übersetze sie in verständliche Hinweise.

Siehe auch

HTMLGeolocationElement.initialPermissionStatus HTMLGeolocationElement.isValid HTMLGeolocationElement.position HTMLGeolocationElement.autolocate HTMLGeolocationElement.error