Geolocation.clearWatch() — Methode · JavaScript-Referenz

Signatur

Geolocation.prototype.clearWatch(id)

Beschreibung

clearWatch() ist das Gegenstück zu watchPosition(). Während watchPosition() den Callback bei jeder Standortänderung erneut aufruft und dafür eine numerische Watch-ID zurückgibt, stoppt clearWatch() mit genau dieser ID die Überwachung. Danach werden weder der Erfolgs- noch der Fehler-Callback noch einmal aufgerufen.

Man braucht die Methode immer dann, wenn eine fortlaufende Ortung nicht mehr benötigt wird: z. B. nach dem Ende einer Navigation oder Laufaufzeichnung, wenn eine Komponente ausgehängt wird (React-useEffect-Cleanup, Vue-onUnmounted), wenn der Tab in den Hintergrund wechselt oder sobald eine ausreichend genaue Position vorliegt. Eine aktive Überwachung hält GPS bzw. Funkmodule wach und verbraucht spürbar Akku. Deshalb sollte jede Überwachung, die man startet, auch wieder beendet werden.

Die Methode arbeitet synchron und gibt nichts zurück. Übergibt man eine unbekannte oder bereits beendete ID, passiert einfach nichts. Es wird keine Ausnahme geworfen.

Parameter

Name	Typ	Default	Beschreibung
$id Pflicht	number		Die von `navigator.geolocation.watchPosition()` zurückgegebene Watch-ID der Überwachung, die beendet werden soll.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Überwachung starten und per Button beenden

let watchId = null;

const startTracking = () => {
  watchId = navigator.geolocation.watchPosition(
    ({ coords }) => {
      console.log(`Position: ${coords.latitude.toFixed(5)}, ${coords.longitude.toFixed(5)} (±${Math.round(coords.accuracy)} m)`);
    },
    (err) => console.error('Ortungsfehler:', err.message),
    { enableHighAccuracy: true, maximumAge: 5000, timeout: 10000 }
  );
};

const stopTracking = () => {
  if (watchId !== null) {
    navigator.geolocation.clearWatch(watchId);
    watchId = null;
    console.log('Tracking beendet');
  }
};

document.querySelector('#start').addEventListener('click', startTracking);
document.querySelector('#stop').addEventListener('click', stopTracking);

Position: 52.52001, 13.40495 (±12 m) Position: 52.52010, 13.40512 (±8 m) Tracking beendet

Stoppen, sobald die gewünschte Genauigkeit erreicht ist

const getAccuratePosition = (minAccuracy = 20, maxWait = 15000) =>
  new Promise((resolve, reject) => {
    let best = null;

    const id = navigator.geolocation.watchPosition(
      (pos) => {
        if (!best || pos.coords.accuracy < best.coords.accuracy) best = pos;
        if (pos.coords.accuracy <= minAccuracy) {
          navigator.geolocation.clearWatch(id);
          clearTimeout(timer);
          resolve(pos);
        }
      },
      (err) => {
        navigator.geolocation.clearWatch(id);
        clearTimeout(timer);
        reject(err);
      },
      { enableHighAccuracy: true }
    );

    // Nach maxWait mit der besten bisherigen Position abbrechen
    const timer = setTimeout(() => {
      navigator.geolocation.clearWatch(id);
      best ? resolve(best) : reject(new Error('Keine Position erhalten'));
    }, maxWait);
  });

const pos = await getAccuratePosition();
console.log(`Genauigkeit: ${Math.round(pos.coords.accuracy)} m`);

Genauigkeit: 14 m

Aufräumen in einem React-Hook

import { useEffect, useState } from 'react';

export const useLivePosition = () => {
  const [coords, setCoords] = useState(null);

  useEffect(() => {
    if (!('geolocation' in navigator)) return;

    const id = navigator.geolocation.watchPosition(
      (pos) => setCoords(pos.coords),
      (err) => console.warn(err.message)
    );

    // Cleanup: Überwachung beenden, wenn die Komponente ausgehängt wird
    return () => navigator.geolocation.clearWatch(id);
  }, []);

  return coords;
};

Tracking pausieren, wenn der Tab unsichtbar wird

let watchId = null;
const onPos = (pos) => console.log('Update', pos.timestamp);

const start = () => {
  if (watchId === null) watchId = navigator.geolocation.watchPosition(onPos);
};
const stop = () => {
  if (watchId !== null) {
    navigator.geolocation.clearWatch(watchId);
    watchId = null;
  }
};

document.addEventListener('visibilitychange', () => {
  document.hidden ? stop() : start();
});

start();

// Wichtig · Fallstricke

Nur mit watchPosition-IDs: getCurrentPosition() liefert keine ID und lässt sich nicht mit clearWatch() abbrechen. Stattdessen begrenzt man die Wartezeit mit der Option timeout.
ID sichern: Geht die Watch-ID verloren (z. B. weil sie in einer lokalen Variable liegt, auf die man später keinen Zugriff mehr hat), kann die Überwachung nicht mehr gestoppt werden und läuft bis zum Schließen der Seite weiter. Das kostet Akku.
Kein Fehler bei ungültiger ID: Wer clearWatch() mit undefined, null oder einer veralteten ID aufruft, bekommt keine Fehlermeldung. Tippfehler bleiben dadurch leicht unbemerkt. Setzt die Variable nach dem Stoppen am besten auf null.
Nicht mit clearTimeout/clearInterval verwechseln: Die Watch-IDs sind eigene Nummern und haben nichts mit Timer-IDs zu tun.
Kompatibilität: Wird in allen modernen Browsern unterstützt. Die Geolocation-API steht nur in sicheren Kontexten zur Verfügung (HTTPS oder localhost) und setzt voraus, dass der Nutzer zugestimmt hat. In iframes kann die Permissions-Policy geolocation den Zugriff sperren.

Siehe auch

Geolocation.watchPosition() Geolocation.getCurrentPosition() Geolocation GeolocationPosition GeolocationPositionError Navigator.geolocation Selection.collapseToEnd()