IdleDetector: change — Ereignis · JavaScript-Referenz

Signatur

idleDetector.addEventListener("change", handler)

Beschreibung

Das change-Ereignis der IdleDetector-Schnittstelle (Idle Detection API) wird ausgelöst, wenn sich der Wert von IdleDetector.userState ("active" ↔ "idle") oder IdleDetector.screenState ("unlocked" ↔ "locked") ändert. Man registriert den Handler entweder mit addEventListener("change", handler) oder über die Eigenschaft onchange.

Das Ereignis ist ein einfaches Event ohne zusätzliche Daten. Die neuen Zustände liest man direkt am Detektor ab, meist über event.target.userState und event.target.screenState.

Typische Einsatzfälle sind Chat- und Kollaborations-Anwendungen, die einen Status wie „abwesend“ anzeigen, Kiosk-Systeme, die sich nach Inaktivität zurücksetzen, oder Anwendungen, die teure Hintergrundarbeit pausieren, wenn der Bildschirm gesperrt ist.

Wichtig: Das Ereignis wird erst ausgelöst, nachdem IdleDetector.requestPermission() den Wert "granted" geliefert hat und idleDetector.start({ threshold }) aufgerufen wurde. Der Schwellenwert threshold legt fest, nach wie vielen Millisekunden ohne Eingabe der Nutzer als "idle" gilt. Er muss mindestens 60 000 ms betragen.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname, immer `"change"`.
$handler Pflicht	(event: Event) => void		Callback, der bei jeder Zustandsänderung aufgerufen wird. `event.target` ist der `IdleDetector`.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once` oder `signal` zum späteren Entfernen.

Beispiele

Präsenzstatus mit addEventListener überwachen

const startIdleWatch = async () => {
  if (!('IdleDetector' in window)) {
    console.log('Idle Detection API nicht unterstützt');
    return;
  }
  // Berechtigung muss aus einer Nutzeraktion heraus angefragt werden
  const permission = await IdleDetector.requestPermission();
  if (permission !== 'granted') {
    console.log('Berechtigung verweigert');
    return;
  }

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

  await detector.start({ threshold: 60_000 });
  console.log('IdleDetector gestartet');
};

document.querySelector('#watch').addEventListener('click', startIdleWatch);

IdleDetector gestartet Nutzer: idle, Bildschirm: unlocked Nutzer: idle, Bildschirm: locked Nutzer: active, Bildschirm: unlocked

onchange-Eigenschaft für Chat-Status

const setStatus = (text) => {
  document.querySelector('#status').textContent = text;
};

const initPresence = async () => {
  if ((await IdleDetector.requestPermission()) !== 'granted') return;

  const detector = new IdleDetector();
  detector.onchange = () => {
    if (detector.screenState === 'locked') {
      setStatus('Offline (Bildschirm gesperrt)');
    } else if (detector.userState === 'idle') {
      setStatus('Abwesend');
    } else {
      setStatus('Online');
    }
  };
  await detector.start({ threshold: 5 * 60_000 });
};

document.querySelector('#enable-presence').onclick = initPresence;

Überwachung per AbortController beenden

const controller = new AbortController();

const watch = async () => {
  if ((await IdleDetector.requestPermission()) !== 'granted') return;

  const detector = new IdleDetector();
  const onChange = () => console.log('Zustand:', detector.userState);
  detector.addEventListener('change', onChange);

  // start() mit signal: abort() stoppt den Detektor
  await detector.start({ threshold: 60_000, signal: controller.signal });

  controller.signal.addEventListener('abort', () => {
    detector.removeEventListener('change', onChange);
    console.log('Idle-Überwachung beendet');
  });
};

document.querySelector('#start').onclick = watch;
document.querySelector('#stop').onclick = () => controller.abort();

Zustand: idle Idle-Überwachung beendet

// Wichtig · Fallstricke

Browser-Kompatibilität: Die API ist experimentell und nur in Chromium-basierten Browsern verfügbar (Chrome/Edge/Opera ab Version 94). Firefox und Safari lehnen sie aus Datenschutzgründen ab. Vor der Nutzung sollte man deshalb immer mit 'IdleDetector' in window prüfen, ob sie vorhanden ist.
Sicherer Kontext & Berechtigung: Die API steht nur über HTTPS zur Verfügung. IdleDetector.requestPermission() muss durch eine Nutzeraktion (transiente Aktivierung) ausgelöst werden, sonst wird die Anfrage abgelehnt. In iframes ist zusätzlich die Permissions-Policy idle-detection nötig.
Schwellenwert: Liegt threshold unter 60 000 ms, verwirft start() das Promise mit einem TypeError. Ohne erfolgreichen Aufruf von start() wird nie ein change-Ereignis ausgelöst.
Keine Ereignisdaten: Das Ereignis enthält keine alten oder neuen Werte. Wer den vorherigen Zustand braucht, muss ihn selbst speichern.
Datenschutz: Da Inaktivitätsdaten Rückschlüsse auf das Verhalten von Nutzern erlauben, sollte man klar erklären, wofür sie verwendet werden, und die Überwachung per AbortSignal beenden, wenn sie nicht mehr gebraucht wird.

Siehe auch

HTMLElement: change CookieStore: change DevicePosture: change Screen: change Element: gesturechange PreferenceObject: change