new IdleDetector() — Methode · JavaScript-Referenz

Signatur

new IdleDetector()

Beschreibung

Der Konstruktor IdleDetector() gehört zur Idle Detection API. Er erzeugt ein Objekt, das den Leerlaufzustand des Benutzers (userState: "active" oder "idle") und den Zustand des Bildschirms (screenState: "locked" oder "unlocked") beobachten kann. Anders als ein reiner Seiten-Timer berücksichtigt die API Eingaben im gesamten System, also auch in anderen Programmen und auf anderen Bildschirmen.

Direkt nach dem Erzeugen überwacht das Objekt noch nichts. Erst ein Aufruf von detector.start({ threshold, signal }) startet die Überwachung. Vorher muss der Benutzer die Berechtigung über IdleDetector.requestPermission() erteilt haben, und diese Anfrage muss aus einer Benutzeraktion heraus kommen (z. B. einem Klick). Zustandswechsel werden über das Ereignis change gemeldet.

Typische Anwendungsfälle sind Chat- und Kollaborations-Anwendungen, die den Status „abwesend“ anzeigen, Kiosk-Systeme, die sich nach Inaktivität zurücksetzen, und Anwendungen, die aufwendige Aufgaben wie Benachrichtigungen oder Synchronisation pausieren, solange niemand am Gerät ist.

Rückgabewert

Typ

IdleDetector

Beschreibung

Ein neues IdleDetector-Objekt (erbt von EventTarget). Solange start() nicht aufgerufen wurde, sind userState und screenState null.

Beispiele

Unterstützung prüfen und Detektor erzeugen

if ('IdleDetector' in window) {
  const detector = new IdleDetector();
  console.log(detector.userState, detector.screenState);
} else {
  console.log('Idle Detection API wird nicht unterstützt.');
}

null null

Berechtigung per Klick anfordern und Überwachung starten

const button = document.querySelector('#idle-start');
const controller = new AbortController();

button.addEventListener('click', async () => {
  const permission = await IdleDetector.requestPermission();
  if (permission !== 'granted') {
    console.log('Berechtigung verweigert.');
    return;
  }

  const detector = new IdleDetector();
  detector.addEventListener('change', () => {
    console.log(`Benutzer: ${detector.userState}, Bildschirm: ${detector.screenState}`);
  });

  try {
    // Schwellenwert: mindestens 60 000 ms (1 Minute)
    await detector.start({ threshold: 60_000, signal: controller.signal });
    console.log('Überwachung gestartet.');
  } catch (err) {
    console.error(`${err.name}: ${err.message}`);
  }
});

Überwachung gestartet. Benutzer: idle, Bildschirm: unlocked

Chat-Status „Abwesend“ setzen und Überwachung beenden

const controller = new AbortController();

const watchPresence = async (setStatus) => {
  const detector = new IdleDetector();
  detector.onchange = () => {
    const away = detector.userState === 'idle' || detector.screenState === 'locked';
    setStatus(away ? 'abwesend' : 'online');
  };
  await detector.start({ threshold: 5 * 60_000, signal: controller.signal });
};

watchPresence((status) => console.log(`Status: ${status}`));

// Später, z. B. beim Abmelden:
const stopWatching = () => controller.abort();

Status: abwesend

// Wichtig · Fallstricke

Experimentell: Die API gibt es nur in Chromium-Browsern (ab Version 94). Firefox und Safari lehnen sie aus Datenschutzgründen ab. Prüfe die Unterstützung immer mit 'IdleDetector' in window.
Sicherer Kontext: Die API funktioniert nur über HTTPS (bzw. localhost). Sie steht in Window und dedizierten Workern zur Verfügung.
Berechtigung: Die Anfrage IdleDetector.requestPermission() muss aus einer Benutzeraktion heraus kommen. Ohne erteilte Berechtigung lehnt start() mit einem NotAllowedError ab. In iframes muss die Berechtigungsrichtlinie idle-detection erlaubt sein.
Schwellenwert: threshold muss mindestens 60 000 ms betragen, sonst wirft start() einen TypeError.
Datenschutz: Mit Leerlaufdaten lässt sich erkennen, wann jemand anwesend ist, und das kann zur Überwachung missbraucht werden. Nutze die API nur mit klarem Zweck und transparent für die Benutzer.
Der Konstruktor selbst startet noch keine Überwachung. Beenden lässt sie sich nur über das AbortSignal, das an start() übergeben wurde. Eine eigene stop()-Methode gibt es nicht.

Siehe auch

new BarcodeDetector() new NDEFRecord() new BlobEvent() new DOMRect() new DragEvent()