HTMLGeolocationElement

Konstruktor

HTMLGeolocationElement() Experimentell

Erstellt eine neue HTMLGeolocationElement Objektinstanz. Beachten Sie, dass dieser Konstruktor nicht direkt aufgerufen wird, sondern über eine DOM-Methode wie Document.createElement().

Instanzeigenschaften

Erbt auch Eigenschaften vom übergeordneten Interface HTMLElement.

autolocate Experimentell

Ein boolescher Wert, der angibt, ob der Browser Standortdaten sofort anfordern soll, wenn das <geolocation> Element gerendert wird, vorausgesetzt, zuvor wurde die Erlaubnis erteilt. Reflektiert den Wert des <geolocation> autolocate Attributs.

error Schreibgeschützt Experimentell

Ein GeolocationPositionError Objekt, das Fehlerinformationen darstellt, im Falle eines Fehlers bei der Datenabfrage.

initialPermissionStatus Schreibgeschützt Experimentell

Ein enumerierter Wert, der den Erlaubnisstatus für die geolocation Funktion beim ersten Laden der Seite darstellt.

invalidReason Schreibgeschützt Experimentell

Ein enumerierter Wert, der den Grund darstellt, warum das <geolocation> Element ungültig ist (blockiert), falls dies der Fall ist.

isValid Schreibgeschützt Experimentell

Ein boolescher Wert, der angibt, ob das <geolocation> Element gültig oder ungültig (blockiert) ist.

permissionStatus Schreibgeschützt Experimentell

Ein String, der den aktuellen Erlaubnisstatus für die geolocation Funktion darstellt.

position Schreibgeschützt Experimentell

Ein GeolocationPosition Objekt, das die Position des Benutzers im Falle einer erfolgreichen Standort-Datenabfrage darstellt.

watch Experimentell

Ein boolescher Wert, der anzeigt, ob der Browser die Standortdaten des Benutzers kontinuierlich aktualisieren soll, sobald sich die Position des Geräts ändert, oder nur einmal abgerufen werden soll. Reflektiert den Wert des <geolocation> watch Attributs.

Instanzmethoden

Erbt Eigenschaften vom übergeordneten Interface HTMLElement.

Ereignisse

Erbt auch Ereignisse vom übergeordneten Interface HTMLElement.

location Experimentell

Wird ausgelöst, wann immer der Browser Standortdaten oder Fehlerinformationen erhält, wenn die Standortabfrage nicht erfolgreich war.

promptaction Experimentell

Wird ausgelöst, wann immer der Benutzer das <geolocation> Element aktiviert und eine Option aus dem resultierenden Dialogfeld auswählt, entweder um geolocation Erlaubnis zu erteilen oder zu verweigern.

promptdismiss Experimentell

Wird ausgelöst, wann immer der Benutzer das <geolocation> Element aktiviert und das resultierende Dialogfeld schließt, indem Sie den "Schließen"-Button oder die Esc Taste drücken.

validationstatuschange Experimentell

Wird ausgelöst, wann immer sich der isValid Wert des <geolocation> Elements ändert.

Beschreibung

Das HTMLGeolocationElement Interface repräsentiert das <geolocation> Element, welches ein interaktives Steuerungselement erstellt, damit der Benutzer seine Standortdaten mit der Seite teilen kann.

Wenn der Benutzer das Steuerungselement aktiviert, wird ihm ein Dialogfeld angezeigt, in dem er um Erlaubnis gebeten wird, seine Standortdaten zu teilen. Wenn die Erlaubnis erteilt wird, versucht der Browser im Hintergrund, die Standortdaten des Benutzers mithilfe der Geolocation API abzurufen.

Standardmäßig fordert der Browser einmal Standortdaten an, als ob die Methode Geolocation.getCurrentPosition() aufgerufen worden wäre. Wenn jedoch das watch Attribut auf true gesetzt ist, aktualisiert der Browser die Daten immer dann, wenn sich die Position des Geräts ändert, als ob Geolocation.watchPosition() aufgerufen worden wäre.

Wenn die Datenabfrage abgeschlossen ist, wird das location Ereignis ausgelöst, das es Ihnen ermöglicht, entsprechend zu reagieren, zum Beispiel indem Sie die Daten abrufen und die Position auf einer Karte plotten.

• Wenn Standortdaten erfolgreich abgerufen werden, sind sie in der HTMLGeolocationElement.position Eigenschaft verfügbar, die ein GeolocationPosition Objekt enthält.
• Wenn das Abrufen von Daten nicht erfolgreich ist, sind Fehlerinformationen in der HTMLGeolocationElement.error Eigenschaft verfügbar, die ein GeolocationPositionError Objekt enthält.

Die Ereignisse promptaction und promptdismiss ermöglichen es Ihnen, auf die Benutzerinteraktionen mit dem <geolocation> Dialogfeld zu reagieren, beispielsweise um den Benutzer zu bitten, eine andere Wahl zu treffen, falls die Erlaubnis zum Zugriff auf die Daten verweigert wurde.

Wenn ein Blocker auf einem <geolocation> Element aktiv ist, wird es funktionsunfähig gemacht (ungültig), entweder vorübergehend oder dauerhaft, je nach Grund. 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 - siehe diese Seite für eine vollständige Liste möglicher Gründe.

Beispiele

Grundlegende Nutzung

Für minimale Beispiele, die das <geolocation> Element und das zugehörige HTMLGeolocationElement Objekt verwenden, um Standortdaten zurückzugeben, siehe unser Grundbeispiel (Quellcode) und Grundlagen-Beispiel für Beobachtung (Quellcode).

Siehe die <geolocation> Referenzseite für eine Schritt-für-Schritt-Anleitung.

Integriertes Kartenbeispiel

Dieses Beispiel nutzt das <geolocation> Element, um Ihren aktuellen Standort abzurufen, der auf einer Karte dargestellt wird, die mit Leaflet JS gerendert wird. Das Beispiel verwendet auch einen regulären <button> Fallback, um die Standortdaten in nicht unterstützenden Browsern abzurufen.

HTML

Wir fügen ein <geolocation> Element mit einem autolocate Attribut ein, damit der Browser versucht, Standortdaten automatisch abzurufen, vorausgesetzt, die geolocation Erlaubnis wurde zuvor erteilt. Im <geolocation> Element nisten wir ein <button> Fallback, welches in Browsern, die <geolocation> nicht unterstützen, dargestellt wird, um Standortdaten anfordern zu können.

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

Als nächstes fügen wir ein <p> Element ein, um Statusnachrichten und Fehler auszugeben.

<p id="status">Status:</p>

Zuletzt fügen wir ein <div> Element ein, um die Karte darin darzustellen.

<div id="map"></div>

JavaScript

In unserem Skript beginnen wir damit, eine Referenz zum Status-<p> Element zu erhalten:

const statusElem = document.querySelector("#status");

Als nächstes überprüfen wir, ob das <geolocation> Element unterstützt wird, indem wir typeof HTMLGeolocationElement === "function" testen:

if (typeof HTMLGeolocationElement === "function") {
  // <geolocation> is supported
} else {
  // <geolocation> is not supported; use fallback button
}

Wenn <geolocation> unterstützt wird, wird der if Block ausgeführt. Er beginnt damit, eine Referenz zum <geolocation> Element zu erhalten:

const geo = document.querySelector("geolocation");

Als nächstes fügen wir einen location Ereignislistener zum resultierenden HTMLGeolocationElement Objekt hinzu, um zu erkennen, wann die Standortanforderung zurückgegeben wird. Wenn die Daten erfolgreich zurückgegeben werden, greifen wir über die HTMLGeolocationElement.position Eigenschaft darauf zu und holen die Breitengrad- und Längengradwerte ab. Wir protokollieren diese in die Konsole und zeichnen sie dann auf einer Karte, indem wir sie zusammen mit einer Referenz zum HTMLGeolocationElement Objekt in die drawMap() Funktion (die wir später definieren werden) übergeben. Wenn die Anfrage fehlschlägt, greifen wir über die HTMLGeolocationElement.error Eigenschaft auf den Fehler zu und protokollieren die Fehlermeldung in die Konsole.

geo.addEventListener("location", () => {
  if (geo.position) {
    console.log(
      `${geo.position.coords.latitude},${geo.position.coords.longitude}`,
    );
    drawMap(geo.position.coords.latitude, geo.position.coords.longitude, geo);
  } else if (geo.error) {
    console.log(geo.error.message);
  }
});

Als nächstes fügen wir promptdismiss und promptaction Ereignislistener zum resultierenden HTMLGeolocationElement Objekt hinzu. Diese ermöglichen es uns, Funktionen als Antwort auf das Schließen oder die Auswahl einer Option im <geolocation> Dialogfeld durch den Benutzer auszuführen.

geo.addEventListener("promptdismiss", notifyUserRetrySelection);
geo.addEventListener("promptaction", notifyUserGrantPermission);

Schließlich definieren wir die notifyUserRetrySelection() und notifyUserGrantPermission() Funktionen, auf die in den beiden vorherigen Ereignislistenern verwiesen wird. Erstere gibt eine Nachricht im Status-Absatz aus, die dem Benutzer sagt, er solle die Taste erneut drücken und Standorterlaubnis erteilen, da wir in diesem Fall möchten, dass der Benutzer es immer noch einmal versucht. Letztere nutzt die HTMLGeolocationElement.permissionStatus Eigenschaft, um zu überprüfen, ob der Erlaubnisstatus denied oder prompt ist und fordert den Benutzer auf, die Taste erneut zu drücken und Standorterlaubnis zu erteilen, falls dies nötig ist. Falls der Benutzer die Erlaubnis bereits erteilt hat, müssen wir nicht noch einmal fragen.

function notifyUserRetrySelection() {
  statusElem.textContent =
    'Please press the "Use location" button again and allow location for this site.';
}

function notifyUserGrantPermission() {
  if (geo.permissionStatus === "denied" || geo.permissionStatus === "prompt") {
    statusElem.textContent =
      'Please press the "Use location" button again and allow location for this site.';
  }
}

Wenn <geolocation> nicht unterstützt wird, wird der else Block ausgeführt. Dieser beginnt damit, eine Referenz zum Fallback-<button> Element zu erhalten:

const fallback = document.querySelector("#fallback");

Als nächstes fügen wir einen click Ereignishandler zum resultierenden HTMLButtonElement Objekt hinzu. Innerhalb davon nutzen wir einen Geolocation.getCurrentPosition() Aufruf, um die Erfolgs- und Fehlerszenarien im HTMLGeolocationElement Codepfad zu emulieren. Das Ergebnis ist dasselbe — wir zeichnen entweder die Standortdaten auf einer Karte, indem wir sie zusammen mit einer Referenz zum HTMLButtonElement Objekt in die drawMap() Funktion übergeben, oder geben die Fehlermeldung im Status-Absatz aus.

fallback.addEventListener("click", () => {
  navigator.geolocation.getCurrentPosition(
    (position) => {
      drawMap(position.coords.latitude, position.coords.longitude, fallback);
    },
    (error) => {
      statusElem.textContent += `${error.message}, `;
    },
  );
});

Der letzte Schritt ist die Definition der drawMap() Funktion, die die Breitengrad- und Längengrad-Daten als Argumente annimmt, zusammen mit einer Referenz zum Button, der den Befehl ausgelöst hat. Der Funktionskörper nutzt Leaflet JS Code (siehe den Leaflet Quick Start Guide für eine Erklärung), um die Position des Benutzers auf der Karte zu plotten, gibt eine Erfolgsmeldung im Statusabsatz aus und versteckt den Button. Der letzte Schritt ist eine Vereinfachung, um zu verhindern, dass der Code fehlerhaft wird, wenn der Benutzer die Taste nach einem Erfolg erneut drückt.

function drawMap(lat, long, btn) {
  const map = L.map("map").setView([lat, long], 13);
  L.tileLayer("https://tile.openstreetmap.org/{z}/{x}/{y}.png", {
    maxZoom: 19,
    attribution:
      '&copy; <a href="http://www.openstreetmap.org/copyright">OpenStreetMap</a>',
  }).addTo(map);
  const marker = L.marker([lat, long]).addTo(map);

  statusElem.textContent = "Map drawn successfully.";
  btn.style.display = "none";
}

Ergebnis

Sehen Sie diesen Code live in Aktion (Quellcode). Versuchen Sie, die Demos in einem unterstützenden Browser und einem nicht unterstützenden Browser zu betrachten, wenn möglich, und achten Sie auf den Unterschied im Berechtigungsdialogfluss, wenn Sie die Erlaubnis zur Nutzung von geolocation erteilen.

Versuchen Sie auch Folgendes:

• Nachdem Sie die geolocation Erlaubnis erteilt und die Karte gesehen haben, versuchen Sie, diese Erlaubnis über die verfügbaren Browsereinstellungen zu widerrufen, und laden Sie die Seite neu, um das Beispiel zurückzusetzen.
• Versuchen Sie nun, die Erlaubnis zur Nutzung von geolocation zu verweigern oder das Erlaubnisdialogfeld zu schließen und beachten Sie, wie die von uns eingerichteten Ereignislistener für promptdismiss und promptaction dazu führen, dass eine Nachricht im Statusabsatz ausgegeben wird, um dem Benutzer zu helfen, die Seite zu nutzen.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• <geolocation> Element
• Die geolocation Berechtigungsrichtlinie
• Geolocation API
• Permissions API
• Vorstellung des <geolocation> HTML-Elements auf developer.chrome.com (2026)