HTMLGeolocationElement.position — Eigenschaft · JavaScript-Referenz

Signatur

get HTMLGeolocationElement.position

Beschreibung

Die Eigenschaft position des Interfaces HTMLGeolocationElement gibt ein GeolocationPosition-Objekt mit dem Standort des Benutzers zurück. Das gilt, sobald das deklarative <geolocation>-Element erfolgreich Standortdaten erhalten hat. Vorher, oder wenn die Abfrage fehlgeschlagen ist, ist der Wert null.

Das <geolocation>-Element ist ein vom Browser gezeichneter Button. Der Benutzer klickt ihn an und gibt damit seinen Standort frei. Das ist eine Alternative zum Aufruf von navigator.geolocation.getCurrentPosition() aus einem Skript. Weil der Klick eine eindeutige Benutzerabsicht zeigt, kann der Browser die Berechtigungsanfrage besser einordnen. Nach einer erfolgreichen Ermittlung löst das Element das Ereignis location aus. In dessen Handler liest man position üblicherweise aus.

Das Objekt hat denselben Aufbau wie bei der klassischen Geolocation-API: coords.latitude, coords.longitude, coords.accuracy, optional altitude, heading und speed, dazu einen timestamp. Ist das Attribut watch gesetzt, verfolgt das Element den Standort fortlaufend. position wird dann bei jeder Aktualisierung neu belegt, und jedes Mal wird ein location-Ereignis ausgelöst.

Rückgabewert

Typ

GeolocationPosition | null

Beschreibung

Die zuletzt ermittelte Position des Benutzers oder null, wenn noch keine Standortdaten vorliegen oder ein Fehler aufgetreten ist (siehe error).

Beispiele

Position nach dem Klick auf den Standort-Button auslesen

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

geo.addEventListener('location', () => {
  if (geo.position) {
    const { latitude, longitude, accuracy } = geo.position.coords;
    console.log(`Standort: ${latitude.toFixed(4)}, ${longitude.toFixed(4)} (±${Math.round(accuracy)} m)`);
  } else if (geo.error) {
    console.warn('Fehler:', geo.error.code, geo.error.message);
  }
});

Standort: 52.5200, 13.4050 (±25 m)

Funktionsprüfung mit Rückfall auf navigator.geolocation

const container = document.querySelector('#standort');

if ('HTMLGeolocationElement' in window) {
  const geo = document.createElement('geolocation');
  geo.addEventListener('location', () => {
    if (geo.position) zeigeKarte(geo.position.coords);
  });
  container.append(geo);
} else {
  // Klassischer Weg für Browser ohne <geolocation>-Element
  const button = document.createElement('button');
  button.textContent = 'Standort verwenden';
  button.addEventListener('click', () => {
    navigator.geolocation.getCurrentPosition(
      (pos) => zeigeKarte(pos.coords),
      (err) => console.warn(err.message)
    );
  });
  container.append(button);
}

function zeigeKarte({ latitude, longitude }) {
  console.log(`Karte zentriert auf ${latitude}, ${longitude}`);
}

Karte zentriert auf 48.1374, 11.5755

Fortlaufende Verfolgung mit dem watch-Attribut

// HTML: <geolocation id="tracker" watch></geolocation>
const tracker = document.querySelector('#tracker');
const route = [];

tracker.addEventListener('location', () => {
  const pos = tracker.position;
  if (!pos) return;
  route.push({
    lat: pos.coords.latitude,
    lng: pos.coords.longitude,
    zeit: new Date(pos.timestamp).toLocaleTimeString('de-DE')
  });
  console.log(`Punkte aufgezeichnet: ${route.length}`);
});

Punkte aufgezeichnet: 1 Punkte aufgezeichnet: 2

// Wichtig · Fallstricke

Experimentell: <geolocation> bzw. HTMLGeolocationElement gibt es bisher nur in Chromium-basierten Browsern (Origin Trial bzw. hinter einem Flag). Prüfen Sie die Unterstützung mit 'HTMLGeolocationElement' in window und sehen Sie einen Rückfall auf navigator.geolocation vor. Die Spezifikation kann sich noch ändern.
Der Wert ist null, bis der Benutzer das Element angeklickt und den Zugriff erlaubt hat. Lesen Sie position deshalb im location-Ereignis aus und nicht direkt beim Laden der Seite.
Bei einem Fehler, etwa einer verweigerten Berechtigung oder einer Zeitüberschreitung, bleibt position null. Die Ursache steht dann in error (GeolocationPositionError).
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wird ignoriert und wirft im Strict Mode einen TypeError.
Die API funktioniert nur in sicheren Kontexten (HTTPS). In iframes muss die Permissions Policy geolocation erlaubt sein.
Der Browser kann das Element deaktivieren, wenn es verdeckt, zu klein oder mit ungültigem CSS gestaltet ist, etwa bei schlechtem Kontrast. Den Grund liefern isValid und invalidReason.
Datenschutz: Standortdaten sind personenbezogen. Übertragen oder speichern Sie sie nur mit Einwilligung des Benutzers und nur so genau wie nötig.

Siehe auch

HTMLGeolocationElement.error HTMLGeolocationElement.isValid HTMLGeolocationElement.watch HTMLGeolocationElement.autolocate HTMLGeolocationElement.invalidReason