`<geolocation>` HTML Geolocation-Element

Eingeschränkt verfügbar

Diese Funktion ist nicht Baseline, da sie in einigen der am weitesten verbreiteten Browser nicht funktioniert.

Experimentell: Dies ist eine experimentelle Technologie
Überprüfen Sie die Browser-Kompatibilitätstabelle sorgfältig vor der Verwendung auf produktiven Webseiten.

Das <geolocation> HTML-Element erstellt eine interaktive Steuerung, mit der der Benutzer seine Standortdaten mit der Seite teilen kann.

Es bietet:

Eine intuitive Benutzeroberfläche, die vom Browser definiert wird.
Ein Verfahren zur Verwaltung der erforderlichen Berechtigungen für die geolocation-Funktion.
API-Funktionen zum Zugriff auf Standortdaten und zur Reaktion auf empfangene Standortdaten und Berechtigungsänderungen.

Attribute

Dieses Element umfasst die globalen Attribute.

autolocate

Ein boolesches Attribut, das, wenn es auf true gesetzt ist, angibt, dass der Browser sofort Standortdaten abrufen soll, wenn das <geolocation>-Element gerendert wird, sofern die Berechtigung zuvor erteilt wurde. Wenn es auf false gesetzt ist, werden die Standortdaten erst abgerufen, wenn der Benutzer die Steuerung aktiviert. Der Standardwert ist false.

Wenn die Berechtigung vorher nicht erteilt wurde, hat dieses Attribut keine Auswirkung.

watch

Ein boolesches Attribut, das, wenn es auf true gesetzt ist, angibt, dass der Browser Standortdaten abrufen soll, wann immer sich die Position des Geräts des Benutzers ändert. Wenn es auf false gesetzt ist, werden die Standortdaten nur einmal abgerufen. Der Standardwert ist false.

Beschreibung

Das <geolocation>-Element bietet eine deklarative, browserdefinierte Steuerung zur Freigabe von Standortdaten. In Chrome beispielsweise verfügt der Button über ein "Landkarten-Pin"-Symbol und intuitiven Text ("Standort verwenden" in englischen Inhalten).

Es ermöglicht auch eine intuitive Verwaltung von Benutzerberechtigungen. Beispielsweise kann in Chrome der Benutzer, wenn er zuvor die Erlaubnis zur Nutzung der Standortdaten verweigert oder die Berechtigungsdialogbox ohne Entscheidung geschlossen hat, den Button erneut drücken, um seine Entscheidung zu aktualisieren. In Fällen, in denen die Erlaubnis zuvor verweigert wurde, informieren nachfolgende Dialoge den Benutzer darüber, dass er zuvor die Freigabe der Standortdaten nicht erlaubt hat, und fragen, ob er weiterhin keine Erlaubnis erteilen oder diese erlauben möchte.

Ein wesentlicher Aspekt des <geolocation>-Elements ist, dass es die bewusste Entscheidung des Benutzers widerspiegelt und eine mögliche Nutzung blockiert, die den Benutzer dazu verleiten könnte, seine Standortdaten unwissentlich bereitzustellen (siehe <geolocation>-Blockierung für weitere Informationen).

Die DOM-API-Schnittstelle des Elements, HTMLGeolocationElement, bietet Funktionen zum Zugriff auf zurückgegebene Positionsdaten, den aktuellen Berechtigungsstatus und Fehler, wenn das Abrufen der Daten nicht erfolgreich war, was die Menge des zu schreibenden JavaScript-Codes reduziert. Darüber hinaus stehen Ereignisse zur Verfügung, um Code als Reaktion auf empfangene Standortdaten, Änderungen des Berechtigungsstatus und Benutzerinteraktionen mit dem Berechtigungsdialog auszuführen.

Hinweis: Aus Leistungsgründen sind maximal drei <geolocation>-Elemente auf einer Seite zulässig. Wird dieses Kontingent überschritten, wird die Funktionalität aller <geolocation>-Elemente deaktiviert.

Beziehung zur Geolocation-API

Die Geolocation-API bietet eine ältere Alternative zur Verarbeitung von Standortdaten. Diese API hat einige Nachteile, die das <geolocation>-Element beheben soll, insbesondere dass die Benutzeroberfläche und die zugrunde liegende Logik zur Anforderung der Daten jedes Mal von Grund auf neu implementiert werden müssen und die Handhabung der Berechtigungen unintuitiv sein kann.

Das <geolocation>-Element verwendet Funktionen der Geolocation-API im Hintergrund. Standardmäßig fordert der Browser Standortdaten einmal an, als ob die Methode Geolocation.getCurrentPosition() aufgerufen worden wäre. Wenn das watch-Attribut jedoch auf true gesetzt ist, aktualisiert der Browser die Daten jedes Mal, wenn sich die Position des Geräts ändert, als ob Geolocation.watchPosition() aufgerufen worden wäre.

Wenn die Daten erfolgreich abgerufen wurden, stehen sie in der HTMLGeolocationElement.position-Eigenschaft zur Verfügung, die ein GeolocationPosition-Objekt enthält. Wenn das Abrufen der Daten nicht erfolgreich war, stehen Fehlerinformationen in der HTMLGeolocationElement.error-Eigenschaft zur Verfügung, die ein GeolocationPositionError-Objekt enthält.

Einstellung der Sprachoption des Buttons

Das globale lang-Attribut wird vom <geolocation>-Element verwendet, um eine Sprache für den gerenderten Text auszuwählen. Das bedeutet, dass Sie ein lang-Attribut direkt auf das <geolocation>-Element oder auf einen seiner Vorfahren setzen können, um dem Browser mitzuteilen, welche Sprache für die Beschriftung des Buttons verwendet werden soll.

Wenn kein geeignetes lang-Attribut gesetzt ist, wird die bevorzugte Spracheinstellung des Browsers verwendet.

Einfügen von Fallback-Inhalten

Sie können Fallback-Inhalte zwischen die öffnenden und schließenden Tags des <geolocation>-Elements einfügen, die angezeigt werden, wenn es nicht unterstützt wird. Beispielsweise könnten Sie eine "Nicht unterstützt"-Meldung einfügen:

html

<geolocation>
  <p>Your browser doesn't support the Geolocation element.</p>
</geolocation>

Eine bessere Lösung in der Praxis könnte jedoch darin bestehen, ein reguläres <button>-Element einzufügen, das die Geolocation-API verwendet, um Standortdaten abzurufen:

html

<geolocation>
  <button id="fallback">Use location</button>
</geolocation>

`<geolocation>`-Blockierung

Ein zentrales Konzept bei der Gestaltung des <geolocation>-Elements ist, dass es die bewusste Entscheidung eines Benutzers widerspiegeln sollte, Positionsinformationen freizugeben, und gleichzeitig schlechte Akteure daran hindern sollte, Benutzer dazu zu verleiten, es zu aktivieren, beispielsweise durch Clickjacking. Aus diesem Grund führt der Browser für jedes gerenderte Element eine Liste der sogenannten Blockierungsgründe.

Wenn ein Blocker auf ein <geolocation>-Element aktiv ist, wird dessen Funktionalität entweder vorübergehend oder dauerhaft gesperrt (je nach Grund). Wenn ein <geolocation>-Element blockiert wird, gilt es als ungültig. Sie können überprüfen, ob es ungültig ist, indem Sie die HTMLGeolocationElement.isValid-Eigenschaft abfragen. Sie können auch den Grund, warum es ungültig ist, über die HTMLGeolocationElement.invalidReason-Eigenschaft zurückgeben — auf dieser Seite finden Sie eine vollständige Liste der möglichen Gründe.

Styling-Beschränkungen

Das <geolocation>-Element hat mehrere Einschränkungen hinsichtlich der CSS-Stile, die darauf angewendet werden können. Einige dieser Einschränkungen sind dazu gedacht, grundlegende Zugänglichkeit sicherzustellen und deaktivieren den Button, wenn sie nicht eingehalten werden. Einige erzwingen bestimmte Werte oder Wertebereiche für verschiedene Eigenschaften.

Alle Eigenschaften, die nicht in den folgenden Unterabschnitten aufgeführt sind oder die logisch einem physischen in den folgenden Unterabschnitten aufgeführten Attribut entsprechen, werden ignoriert, wenn sie auf das <geolocation>-Element gesetzt werden.

Zugänglichkeitsbeschränkungen

Der gerenderte <geolocation>-Button wird deaktiviert (bedeutet, dass das Drücken keine Wirkung hat), wenn die folgenden Einschränkungen nicht eingehalten werden:

Das Farbkontrast-Verhältnis zwischen color und background-color muss mindestens 3:1 betragen.
Die font-size darf nicht kleiner als der small-Wert sein (im Falle von Schlüsselwortwerten) oder dessen berechneter Wert (im Falle anderer Werttypen).

Wertebeschränkungen

Die folgenden CSS-Eigenschaftswertebeschränkungen werden auf das <geolocation>-Element angewendet. Wenn versucht wird, diese Eigenschaften auf dem <geolocation>-Element auf Werte außerhalb der aufgeführten Beschränkungen zu setzen, wird der Wert auf den jeweiligen Beschränkungswert angepasst (im Fall einer genauen Wertebeschränkung) oder auf den nächstgelegenen berechneten oberen oder unteren Grenzwert (im Fall einer Bereichsbeschränkung).

opacity: 1.0
line-height: normal
white-space: nowrap
user-select: none
appearance: auto
box-sizing: content-box
vertical-align: middle
text-emphasis: initial
text-shadow: initial
outline-offset: 0 oder größer.
font-weight: 200 oder größer.
word-spacing: Zwischen 0 und 0.5em, inklusive.
letter-spacing: Zwischen -0.05em und 0.2em, inklusive.
letter-spacing: Zwischen -0.05em und 0.2em, inklusive.
min-height: 1em oder größer.
max-height: 3em oder geringer. none ist ein akzeptierter Wert.
min-width: Der berechnete Wert von fit-content oder weniger.
border-width: 1em oder weniger.

Komplexe Beschränkungen

Die folgenden Beschränkungen sind komplexer als einfache Wertebeschränkungen:

Blockrichtungs-Polsterung: Wenn die block-size auf auto gesetzt ist, sind die padding-block-start und padding-block-end (und gleichwertige physische Eigenschaften für das aktuelle Schreibmodus) auf maximal 1em beschränkt und müssen gleich sein.
Inline-Richtungs-Polsterung: Wenn die inline-size auf auto gesetzt ist, sind die padding-inline-start und padding-inline-end (und gleichwertige physische Eigenschaften für das aktuelle Schreibmodus) auf maximal 5em beschränkt und müssen gleich sein.

Eigenschaften, die normal gesetzt werden können

Die folgenden CSS-Eigenschaften können normal verwendet werden:

Barrierefreiheit

Das <geolocation>-Element hat einen zugänglichen Namen, der in der festgelegten Sprache geschrieben ist. Es hat ebenfalls eine Rolle als button, damit es von Screenreadern als Button erkannt wird.

Darüber hinaus hat das <geolocation>-Element einen Standardwert für tabindex von 0, sodass es sich in Bezug auf die Tastaturfokussierung wie ein echter <button> verhält.

Verweisen Sie schließlich zurück auf den Abschnitt Zugänglichkeitsbeschränkungen für Informationen zu Styling-Beschränkungen, die auf das <geolocation>-Element angewendet werden, um grundlegende Anforderungen an die Barrierefreiheit durchzusetzen.

Beispiele

Beispiel für grundlegende Nutzung

Dieses Beispiel verwendet das <geolocation>-Element, um Ihre aktuelle Position abzurufen, die unter dem Button in einem <p>-Element ausgegeben wird. Das Beispiel verwendet auch einen regulären <button>-Fallback, um die Standortdaten in nicht unterstützten Browsern abzurufen.

HTML

Wir fügen ein <geolocation>-Element mit einem <button>-Fallback darin ein, das in Browsern gerendert wird, die <geolocation> nicht unterstützen. Außerdem fügen wir ein <p>-Element ein, um Standortdaten und Fehler auszugeben.

html

<geolocation>
  <button id="fallback">Use location</button>
</geolocation>
<p id="output"></p>

JavaScript

In unserem Skript starten wir, indem wir eine Referenz zum Ausgabeelement <p> erhalten. Wir erkennen dann, ob das <geolocation>-Element unterstützt wird, indem wir typeof HTMLGeolocationElement === "function" testen:

Wenn es unterstützt wird, holen wir zuerst eine Referenz auf das <geolocation>-Element und fügen dann einen location-Event-Listener hinzu. Wenn der Button gedrückt wird und die Daten abgerufen werden, gibt der Listener die (Breiten- und Längengrad-)Koordinaten in das Ausgabeelement <p> (abgerufen über die position-Eigenschaft) oder eine Fehlermeldung, wenn das Abrufen der Daten nicht erfolgreich war (abgerufen über die error-Eigenschaft) aus.
Wenn es nicht unterstützt wird, holen wir eine Referenz auf das Fallback-<button>-Element und rufen die gleichen Daten ab und geben sie aus, jedoch verwenden wir dieses Mal einen click-Event-Listener auf dem Button und einen Aufruf von Geolocation.getCurrentPosition(), um die Daten abzurufen.

const outputElem = document.querySelector("#output");

if (typeof HTMLGeolocationElement === "function") {
  const geo = document.querySelector("geolocation");
  geo.addEventListener("location", () => {
    if (geo.position) {
      outputElem.textContent += `(${geo.position.coords.latitude},${geo.position.coords.longitude}), `;
    } else if (geo.error) {
      outputElem.textContent += `${geo.error.message}, `;
    }
  });
} else {
  const fallback = document.querySelector("#fallback");
  fallback.addEventListener("click", () => {
    navigator.geolocation.getCurrentPosition(
      (position) => {
        outputElem.textContent += `(${position.coords.latitude}, ${position.coords.longitude}), `;
      },
      (error) => {
        outputElem.textContent += `${error.message}, `;
      },
    );
  });
}

Ergebnis

Sehen Sie sich diesen Code live an (Quellcode). Sie können auch eine Version dieses Beispiels finden, die das watch-Attribut auf dem <geolocation>-Element enthält und daher Standortdaten jedes Mal abruft, wenn sich die Positionsangaben des Geräts des Benutzers ändern (sehen Sie es live an und den Quellcode).

Versuchen Sie, die Demos in einem unterstützten und einem nicht unterstützten Browser anzuzeigen, wenn möglich, und beachten Sie den Unterschied im Ablauf der Berechtigungsdialoge, wenn Sie die Erlaubnis zur Nutzung der geolocation erteilen oder verweigern.

Für eine Erläuterung eines umfassenderen Beispiels, das Standortdaten verwendet, um eine Karte Ihrer Umgebung zu erstellen, siehe die Referenzseite HTMLGeolocationElement.

Technische Zusammenfassung

Inhaltskategorien	Fließinhalt, Satzinhalt, interaktiver Inhalt, fühlbarer Inhalt.
Zulässiger Inhalt	Jeder geeignete transparente Fallback-Inhalt.
Wegefall der Tags	Kein, sowohl die Start- als auch die Endmarkierung sind obligatorisch.
Zulässige Eltern	Jedes Element, das Satzinhalt akzeptiert.
Implizite ARIA-Rolle	Keine entsprechende Rolle
Zulässige ARIA-Rollen	`button`
DOM-Schnittstelle	[`HTMLGeolocationElement`](/de/docs/Web/API/HTMLGeolocationElement)