HTMLGeolocationElement: validationstatuschange — Ereignis · JavaScript-Referenz

Signatur

geolocationElement.addEventListener("validationstatuschange", handler)

Beschreibung

Das Ereignis validationstatuschange gehört zum Interface HTMLGeolocationElement, also zum deklarativen HTML-Element <geolocation>. Über dieses Element fragt eine Seite den Standort ab, nachdem die Person bewusst darauf geklickt hat. Der Browser gibt das Element nur frei, wenn es gut erkennbar dargestellt wird: ausreichender Kontrast, keine Verdeckung, keine Transparenz, eine sinnvolle Größe, sichtbar im Viewport, kein unzulässiger Frame-Kontext und Ähnliches. Ob das zutrifft, zeigt die Eigenschaft isValid. Den Grund für eine Sperre liefert invalidReason.

Sobald isValid von true auf false wechselt oder umgekehrt, feuert der Browser validationstatuschange. Den Handler registrierst du mit addEventListener("validationstatuschange", handler) oder über die Eigenschaft onvalidationstatuschange. Der Handler bekommt ein einfaches Event-Objekt. Die eigentlichen Informationen liest du direkt am Element aus (event.target.isValid, event.target.invalidReason).

Typische Einsatzfälle:

Beim Entwickeln herausfinden, warum das Element nicht klickbar ist, etwa weil das CSS unzulässig ist oder ein Overlay das Element verdeckt.
Einen Ersatz anzeigen, zum Beispiel eine manuelle Adresseingabe, solange das Element gesperrt ist.
Die Oberfläche anpassen, wenn das Element gerade erst eingefügt wurde oder sich seine Position geändert hat. Der Browser sperrt es dann kurzzeitig.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"validationstatuschange"`.
$handler Pflicht	(event: Event) => void		Callback-Funktion. Sie bekommt ein allgemeines `Event`. Das auslösende `HTMLGeolocationElement` steht in `event.target`.
$options	boolean \| AddEventListenerOptions	false	Optionale Einstellungen wie `once`, `signal` oder `capture`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Das Ereignisobjekt selbst ist ein einfaches Event ohne zusätzliche Eigenschaften.

Beispiele

Gültigkeitswechsel mit addEventListener protokollieren

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

geo.addEventListener("validationstatuschange", (event) => {
  const el = event.target;
  if (el.isValid) {
    console.log("Element ist benutzbar");
  } else {
    console.warn(`Element gesperrt: ${el.invalidReason}`);
  }
});

Element gesperrt: recently_attached Element ist benutzbar

Ersatz-Eingabe über onvalidationstatuschange ein- und ausblenden

const geo = document.querySelector("geolocation");
const fallback = document.getElementById("plz-eingabe");

const updateUi = () => {
  // Manuelle Postleitzahl-Eingabe nur zeigen, wenn das Element gesperrt ist
  fallback.hidden = geo.isValid;
};

geo.onvalidationstatuschange = updateUi;
updateUi(); // Anfangszustand sofort übernehmen

Listener mit AbortController wieder entfernen

const geo = document.querySelector("geolocation");
const controller = new AbortController();

const onStatus = () => {
  console.log("isValid:", geo.isValid);
};

geo.addEventListener("validationstatuschange", onStatus, {
  signal: controller.signal,
});

// Sobald ein Standort vorliegt, wird der Status nicht mehr gebraucht
geo.addEventListener("location", () => {
  controller.abort(); // alternativ: geo.removeEventListener("validationstatuschange", onStatus)
  console.log("Standort:", geo.position?.coords.latitude);
}, { once: true });

isValid: true Standort: 52.52

Feature-Erkennung vor der Nutzung

if ("HTMLGeolocationElement" in window) {
  const geo = document.createElement("geolocation");
  geo.addEventListener("validationstatuschange", () => {
    console.log(geo.isValid ? "bereit" : `gesperrt (${geo.invalidReason})`);
  });
  document.body.append(geo);
} else {
  // Fallback auf die imperative API
  navigator.geolocation.getCurrentPosition(
    (pos) => console.log(pos.coords),
    (err) => console.error(err.message)
  );
}

gesperrt (recently_attached) bereit

// Wichtig · Fallstricke

Experimentell: <geolocation> und HTMLGeolocationElement gibt es bisher nur in Chromium-basierten Browsern, und dort nur im Origin Trial oder hinter einem Flag. Die API kann sich noch ändern. Prüfe die Unterstützung immer vorher, etwa mit "HTMLGeolocationElement" in window, und plane einen Fallback über navigator.geolocation ein.
Anfangszustand: Beim Laden der Seite feuert das Ereignis nicht unbedingt. Lies isValid deshalb zusätzlich einmal direkt aus.
Vorübergehende Sperren: Direkt nach dem Einfügen ins DOM oder nach einer Positionsänderung ist das Element kurz gesperrt (z. B. invalidReason "recently_attached" oder ein Grund, der mit dem Sichtbereich zu tun hat). Das Ereignis kann dadurch schnell hintereinander mehrmals feuern. Aufwendige Reaktionen darauf solltest du bündeln (Debounce).
Styling: Unzulässiges CSS macht das Element dauerhaft ungültig, zum Beispiel zu geringer Kontrast, opacity unter 1, Transformationen oder eine zu kleine Schrift. Das ist eine Schutzmaßnahme gegen Clickjacking und lässt sich nicht per Skript umgehen.
Das Ereignis lässt sich nicht abbrechen. preventDefault() hat keine Wirkung.

Siehe auch

HTMLTextAreaElement: selectionchange HTMLGeolocationElement: location HTMLGeolocationElement: promptaction HTMLGeolocationElement: promptdismiss HTMLMediaElement: durationchange