WakeLock — Schnittstelle · JavaScript-Referenz

Signatur

interface WakeLock

Beschreibung

Das Interface WakeLock gehört zur Screen Wake Lock API. Es ist über navigator.wakeLock erreichbar und stellt genau eine Methode bereit: request(type). Diese liefert ein Promise, das mit einem WakeLockSentinel erfüllt wird. Solange dieses Sentinel aktiv ist, dunkelt das Betriebssystem den Bildschirm nicht ab und sperrt das Gerät nicht.

Typische Einsatzfälle sind Anwendungen, bei denen der Nutzer längere Zeit auf den Bildschirm schaut, ohne ihn zu berühren: Kochrezepte, Navigation, Präsentationen, Scanner für QR-Codes, Fitness-Timer oder Anzeigetafeln. Wenn die Sperre nicht mehr gebraucht wird, sollte man sie mit WakeLockSentinel.release() freigeben, damit der Akku geschont wird.

Wichtig: Der Browser gibt die Sperre automatisch frei, sobald das Dokument unsichtbar wird, etwa beim Tab-Wechsel oder beim Minimieren. Soll die Sperre danach weiter gelten, muss man sie im visibilitychange-Ereignis neu anfordern. Derzeit gibt es nur den Typ "screen".

Parameter

Name	Typ	Default	Beschreibung
$type	"screen"	"screen"	Parameter von `WakeLock.prototype.request(type)`: Art der Sperre. Aktuell ist nur `"screen"` spezifiziert.

Rückgabewert

Typ

Promise<WakeLockSentinel>

Beschreibung

request() gibt ein Promise zurück, das mit einem WakeLockSentinel erfüllt wird. Es wird mit NotAllowedError abgelehnt, wenn die Sperre nicht erlaubt ist (z. B. wegen Permissions Policy, unsichtbarem Dokument oder Energiesparmodus).

Beispiele

Unterstützung prüfen und Sperre anfordern

const requestWakeLock = async () => {
  if (!('wakeLock' in navigator)) {
    console.log('Screen Wake Lock API wird nicht unterstützt.');
    return null;
  }
  try {
    const sentinel = await navigator.wakeLock.request('screen');
    console.log('Wake Lock aktiv:', !sentinel.released);
    sentinel.addEventListener('release', () => {
      console.log('Wake Lock wurde freigegeben.');
    });
    return sentinel;
  } catch (err) {
    console.error(`${err.name}: ${err.message}`);
    return null;
  }
};

requestWakeLock();

Wake Lock aktiv: true

Sperre nach Tab-Wechsel automatisch erneuern

let wakeLock = null;

const acquire = async () => {
  try {
    wakeLock = await navigator.wakeLock.request('screen');
  } catch (err) {
    console.warn('Wake Lock nicht möglich:', err.name);
  }
};

// Beim Zurückkehren in den Tab neu anfordern
document.addEventListener('visibilitychange', async () => {
  if (wakeLock !== null && document.visibilityState === 'visible') {
    await acquire();
    console.log('Wake Lock erneuert.');
  }
});

acquire();

Wake Lock erneuert.

Umschalter für eine Rezept-Ansicht

const button = document.querySelector('#keep-awake');
let sentinel = null;

button.addEventListener('click', async () => {
  if (sentinel && !sentinel.released) {
    await sentinel.release();
    sentinel = null;
    button.textContent = 'Bildschirm anlassen';
  } else {
    sentinel = await navigator.wakeLock.request('screen');
    button.textContent = 'Bildschirm darf ausgehen';
  }
});

// Wichtig · Fallstricke

Nur in sicheren Kontexten (HTTPS) verfügbar. Außerdem kann die Permissions Policy screen-wake-lock die Nutzung einschränken, z. B. in iframes.
Die Sperre wird automatisch freigegeben, wenn das Dokument unsichtbar wird. Deshalb im visibilitychange-Handler neu anfordern.
request() schlägt mit NotAllowedError fehl, wenn das Dokument nicht aktiv oder sichtbar ist, oder wenn das System es ablehnt, etwa bei niedrigem Akkustand oder im Energiesparmodus. Fehler also immer mit try/catch abfangen.
Kompatibilität: Chrome/Edge ab 84, Safari ab 16.4 (in iOS-Home-Screen-Web-Apps erst ab 18.4 zuverlässig), Firefox ab 126. Vorher mit 'wakeLock' in navigator prüfen.
Die API verhindert nur, dass sich der Bildschirm abdunkelt. Hintergrundprozesse oder CPU-Sperren gehören nicht dazu. Sperren nur so lange halten wie nötig, um den Akku zu schonen.

Siehe auch

Lock BarProp Blob Fence FileList