IdleDetector.screenState — Eigenschaft · JavaScript-Referenz

Signatur

get IdleDetector.prototype.screenState

Beschreibung

Die Eigenschaft screenState eines IdleDetector-Objekts meldet, ob der Bildschirm des Geräts gerade gesperrt ist. Mögliche Werte sind "locked" (Bildschirmsperre oder Bildschirmschoner mit Sperre aktiv) und "unlocked". Solange die Erkennung nicht mit start() gestartet wurde und noch kein erster Zustand vorliegt, ist der Wert null.

Zusammen mit userState ("active" / "idle") können Web-Apps auf Abwesenheit reagieren, zum Beispiel in Chat- oder Kollaborationswerkzeugen den Status „abwesend“ setzen, laufende Vorgänge pausieren, Benachrichtigungen bündeln oder bei gesperrtem Bildschirm aufwendige Aktualisierungen aussetzen, um Ressourcen zu sparen.

Der Wert wird aktualisiert, sobald der Browser eine Änderung erkennt. Dabei wird das Ereignis change am IdleDetector ausgelöst. Den aktuellen Zustand liest man daher am besten im change-Handler aus, statt die Eigenschaft regelmäßig abzufragen.

Vor der Nutzung muss die Berechtigung "idle-detection" über IdleDetector.requestPermission() eingeholt werden. Dieser Aufruf ist nur nach einer Nutzeraktion möglich, etwa nach einem Klick.

Rückgabewert

Typ

"locked" | "unlocked" | null

Beschreibung

"locked" bei gesperrtem Bildschirm, "unlocked" bei entsperrtem Bildschirm, null, solange die Erkennung noch nicht läuft bzw. noch kein Zustand vorliegt.

Beispiele

Berechtigung anfragen, Erkennung starten und screenState lesen

const startBtn = document.querySelector('#start');

startBtn.addEventListener('click', async () => {
  if (!('IdleDetector' in window)) {
    console.log('IdleDetector wird nicht unterstützt.');
    return;
  }

  // Muss durch eine Nutzeraktion ausgelöst werden
  const permission = await IdleDetector.requestPermission();
  if (permission !== 'granted') {
    console.log('Berechtigung verweigert.');
    return;
  }

  const detector = new IdleDetector();
  console.log('Vor start():', detector.screenState);

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

  await detector.start({ threshold: 60_000 }); // Minimum: 60 Sekunden
});

Vor start(): null Nutzer: active, Bildschirm: unlocked // … nach Sperren des Bildschirms: Nutzer: idle, Bildschirm: locked

Hintergrund-Polling bei gesperrtem Bildschirm pausieren

let pollTimer = null;

const startPolling = () => {
  if (pollTimer) return;
  pollTimer = setInterval(async () => {
    const res = await fetch('/api/updates');
    console.log('Updates:', await res.json());
  }, 10_000);
};

const stopPolling = () => {
  clearInterval(pollTimer);
  pollTimer = null;
};

const watchScreen = async () => {
  const detector = new IdleDetector();
  detector.addEventListener('change', () => {
    if (detector.screenState === 'locked') {
      console.log('Bildschirm gesperrt – Polling pausiert');
      stopPolling();
    } else {
      console.log('Bildschirm entsperrt – Polling läuft');
      startPolling();
    }
  });
  await detector.start({ threshold: 120_000 });
};

// watchScreen() erst aufrufen, wenn die Berechtigung 'granted' ist
watchScreen().catch((err) => console.error(err.name, err.message));

Bildschirm entsperrt – Polling läuft Bildschirm gesperrt – Polling pausiert

Erkennung mit AbortController beenden

const controller = new AbortController();
const detector = new IdleDetector();

detector.addEventListener('change', () => {
  console.log('screenState:', detector.screenState);
});

await detector.start({ threshold: 60_000, signal: controller.signal });

// Später, z. B. beim Abmelden:
controller.abort();
console.log('Idle-Erkennung beendet');

screenState: unlocked Idle-Erkennung beendet

// Wichtig · Fallstricke

Experimentell und nur in Chromium: Chrome und Edge unterstützen die API ab Version 94. Firefox und Safari unterstützen sie nicht und haben sie aus Datenschutzgründen abgelehnt. Vor der Nutzung immer mit 'IdleDetector' in window prüfen, ob sie verfügbar ist.
Sicherer Kontext: Die API ist nur über HTTPS (oder localhost) verfügbar, und zwar in Fenstern und Dedicated Workern.
Berechtigung: IdleDetector.requestPermission() braucht eine Nutzeraktion. Ohne die Berechtigung "granted" wirft start() einen NotAllowedError. In iframes muss außerdem die Permissions Policy idle-detection erlaubt sein.
Wert null: Vor start() und bis zum ersten Zustandsbericht ist screenState null. Der Code sollte diesen Fall berücksichtigen.
threshold muss mindestens 60000 ms betragen, sonst wirft der Browser einen TypeError. Der Schwellenwert betrifft vor allem userState, die Sperre wird unabhängig davon gemeldet.
Datenschutz: Informationen über Anwesenheit sind sensibel. Nutzen Sie die Erkennung nur mit klarem Zweck und transparent für die Nutzer, und beenden Sie sie per AbortSignal, wenn sie nicht mehr gebraucht wird.

Siehe auch

IdleDetector.userState FileReader.readyState HTMLElement.translate IDBRequest.readyState MediaRecorder.state