WakeLockSentinel — Schnittstelle · JavaScript-Referenz

Signatur

interface WakeLockSentinel extends EventTarget

Beschreibung

Ein WakeLockSentinel-Objekt erhält man nicht über einen Konstruktor, sondern als Ergebnis des Promises von navigator.wakeLock.request('screen'). Solange die Sperre aktiv ist, verhindert der Browser, dass der Bildschirm gedimmt oder abgeschaltet wird. Das ist sinnvoll für Rezept-Apps, Präsentationen, Navigations- oder Fitness-Anwendungen, QR-Code-Anzeigen und ähnliche Fälle, in denen Nutzer länger auf den Bildschirm schauen, ohne ihn zu berühren.

Die Schnittstelle erbt von EventTarget und bietet:

released (nur lesbar, boolean): true, sobald die Sperre freigegeben wurde.
type (nur lesbar, string): Art der Sperre, derzeit immer "screen".
release(): gibt die Sperre frei und liefert ein Promise<void>.
Ereignis release: wird ausgelöst, wenn die Sperre endet – manuell per release() oder automatisch durch den Browser (Tab wird versteckt, Akku schwach, Fenster minimiert usw.). Abonnierbar über addEventListener('release', …) oder die Eigenschaft onrelease.

Ein Sentinel ist nur einmal verwendbar: Nach der Freigabe lässt er sich nicht wieder aktivieren. Braucht man die Sperre erneut, etwa wenn der Tab wieder sichtbar wird, fordert man mit navigator.wakeLock.request() einen neuen Sentinel an.

Rückgabewert

Typ

WakeLockSentinel

Beschreibung

Wird vom Promise von navigator.wakeLock.request('screen') geliefert. Die Instanz steht für genau eine aktive Bildschirmsperre.

Beispiele

Wake Lock anfordern und Status prüfen

const requestWakeLock = async () => {
  if (!('wakeLock' in navigator)) {
    console.warn('Screen Wake Lock API wird nicht unterstützt');
    return null;
  }
  try {
    const sentinel = await navigator.wakeLock.request('screen');
    console.log('Typ:', sentinel.type, '| freigegeben:', sentinel.released);
    return sentinel;
  } catch (err) {
    // z. B. NotAllowedError bei schwachem Akku oder fehlender Berechtigung
    console.error(`${err.name}: ${err.message}`);
    return null;
  }
};

requestWakeLock();

Typ: screen | freigegeben: false

Manuell freigeben und auf das release-Ereignis reagieren

const sentinel = await navigator.wakeLock.request('screen');

sentinel.addEventListener('release', () => {
  console.log('Wake Lock beendet, released =', sentinel.released);
});

// Alternativ über die on-Eigenschaft:
// sentinel.onrelease = () => console.log('beendet');

// Nach 10 Sekunden wieder freigeben
setTimeout(async () => {
  await sentinel.release();
}, 10_000);

Wake Lock beendet, released = true

Sperre nach Tab-Wechsel automatisch erneuern

let sentinel = null;

const acquire = async () => {
  try {
    sentinel = await navigator.wakeLock.request('screen');
    sentinel.onrelease = () => console.log('Sperre vom System gelöst');
    console.log('Sperre aktiv');
  } catch (err) {
    console.error(err.name, err.message);
  }
};

// Der Browser löst die Sperre beim Verstecken des Tabs automatisch
document.addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'visible' && (sentinel === null || sentinel.released)) {
    acquire();
  }
});

document.querySelector('#start').addEventListener('click', acquire);

Sperre aktiv Sperre vom System gelöst Sperre aktiv

// Wichtig · Fallstricke

Kein Konstruktor: new WakeLockSentinel() wirft einen TypeError. Instanzen gibt es nur über navigator.wakeLock.request().
Automatische Freigabe: Wird das Dokument unsichtbar (Tab-Wechsel, Minimieren, Sperrbildschirm), gibt der Browser die Sperre von selbst frei. Du musst sie bei visibilitychange neu anfordern.
Einmalig verwendbar: Ein freigegebener Sentinel (released === true) lässt sich nicht reaktivieren. Ein erneuter Aufruf von release() ist harmlos und wirft keinen Fehler.
Fehlschläge: request() kann mit NotAllowedError abgelehnt werden, etwa bei aktivem Energiesparmodus, schwachem Akku, einer Permissions-Policy (screen-wake-lock) in iframes oder einem nicht sichtbaren Dokument. Fange den Fehler daher immer ab.
Sicherer Kontext: Die API steht nur über HTTPS (oder localhost) zur Verfügung. Firefox unterstützt sie erst ab Version 126, Safari ab 16.4 (in iOS-Home-Screen-Web-Apps erst ab 18.4 zuverlässig). Prüfe die Verfügbarkeit per 'wakeLock' in navigator.
Akku: Halte die Sperre nur so lange wie nötig und gib sie frei, sobald der Anwendungsfall endet, zum Beispiel wenn das Video pausiert oder die Präsentation vorbei ist.

Siehe auch

WakeLock WakeLock.prototype.request() WakeLockSentinel.prototype.release() WakeLockSentinel.released WakeLockSentinel.type Navigator.wakeLock