Navigator.wakeLock — Eigenschaft · JavaScript-Referenz

Signatur

Navigator.wakeLock

Beschreibung

navigator.wakeLock ist der Einstiegspunkt der Screen Wake Lock API. Die Eigenschaft liefert ein WakeLock-Objekt. Dessen einzige Methode request("screen") fordert eine Bildschirm-Wachsperre an und gibt ein Promise<WakeLockSentinel> zurück. Solange diese Sperre aktiv ist, dimmt das Betriebssystem den Bildschirm nicht und schaltet ihn auch nicht automatisch ab.

Typische Einsatzfälle sind Anwendungen, bei denen jemand länger auf den Bildschirm schaut, ohne ihn zu berühren: Kochrezepte, Navigations- und Karten-Apps, Präsentationen, Boarding-Pässe mit QR-Code, Fitness-Timer oder das Vorlesen von Noten und Texten. Bei Videos setzen Browser meist schon selbst eine Wachsperre, dort ist die API normalerweise nicht nötig.

Die Sperre gilt nur, solange das Dokument sichtbar ist. Wechselt man den Tab, minimiert das Fenster oder sperrt das Gerät, gibt der Browser die Sperre automatisch frei. Am zurückgegebenen WakeLockSentinel wird dann das Ereignis release ausgelöst. Wer die Sperre dauerhaft braucht, muss sie beim Ereignis visibilitychange neu anfordern.

Die API gibt es nur in sicheren Kontexten (HTTPS oder localhost). Außerdem kann eine Permissions Policy (screen-wake-lock) sie einschränken, zum Beispiel in iframes.

Rückgabewert

Typ

WakeLock

Beschreibung

Ein WakeLock-Objekt mit der Methode request(type). Der einzige derzeit gültige Wert für type ist "screen" (auch der Standardwert). request() gibt ein Promise<WakeLockSentinel> zurück. Der Sentinel bietet release(), die Eigenschaften released und type sowie das Ereignis release. In Browsern ohne Unterstützung fehlt die Eigenschaft, dann ist ihr Wert undefined.

Beispiele

Unterstützung prüfen und Wachsperre anfordern

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('Wachsperre aktiv:', sentinel.type);
    sentinel.addEventListener('release', () => {
      console.log('Wachsperre freigegeben');
    });
    return sentinel;
  } catch (err) {
    // z. B. NotAllowedError bei niedrigem Akku oder durch eine Policy
    console.error(`${err.name}: ${err.message}`);
    return null;
  }
};

requestWakeLock();

Wachsperre aktiv: screen

Sperre per Button umschalten (Rezept-App)

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

button.addEventListener('click', async () => {
  if (wakeLock && !wakeLock.released) {
    await wakeLock.release();
    wakeLock = null;
    button.textContent = 'Bildschirm anlassen';
    return;
  }
  try {
    wakeLock = await navigator.wakeLock.request('screen');
    button.textContent = 'Bildschirm darf ausgehen';
    wakeLock.addEventListener('release', () => {
      button.textContent = 'Bildschirm anlassen';
    });
  } catch (err) {
    console.error('Wachsperre nicht möglich:', err.name);
  }
});

Sperre nach Tab-Wechsel automatisch erneuern

let wakeLock = null;

const acquire = async () => {
  try {
    wakeLock = await navigator.wakeLock.request('screen');
    console.log('Wachsperre (neu) gesetzt');
  } catch (err) {
    console.error(err.name, err.message);
  }
};

document.addEventListener('visibilitychange', () => {
  // Der Browser gibt die Sperre beim Verstecken selbst frei
  if (document.visibilityState === 'visible' && wakeLock?.released) {
    acquire();
  }
});

acquire();

Wachsperre (neu) gesetzt

// Wichtig · Fallstricke

Nur in sicheren Kontexten: Über HTTP (außer localhost) fehlt navigator.wakeLock ganz. Prüfe die Unterstützung deshalb immer mit 'wakeLock' in navigator.
Automatische Freigabe: Wird das Dokument unsichtbar (Tab-Wechsel, Fenster minimiert, Gerät gesperrt), gibt der Browser die Sperre frei. Ein WakeLockSentinel lässt sich nicht wiederverwenden. Nach released === true musst du request() erneut aufrufen.
Fehlerfälle: request() kann mit NotAllowedError abgelehnt werden, etwa wenn die Permissions Policy screen-wake-lock die Sperre verbietet, das Dokument nicht sichtbar ist oder der Stromsparmodus bzw. ein niedriger Akkustand sie verhindert. Fange den Fehler deshalb immer mit try/catch ab.
iframes: Eingebettete Dokumente brauchen allow="screen-wake-lock" am <iframe>.
Akku und Nutzerfreundlichkeit: Fordere die Sperre nur an, wenn sie wirklich nötig ist, und gib sie so früh wie möglich wieder frei. Ideal ist ein sichtbarer Schalter, mit dem Nutzer selbst entscheiden.
Kompatibilität: Unterstützt in Chromium-Browsern seit Version 84, in Safari seit 16.4 (bei iOS-Web-Apps auf dem Home-Bildschirm erst ab 18.4 zuverlässig) und in Firefox seit Version 126. Die API sperrt nur den Bildschirm. Eine System-Wachsperre ("system"), die nur die CPU wach hält, ist nicht standardisiert.

Siehe auch

Navigator NavigationHistoryEntry.sameDocument Navigator.locks Navigator.appName Navigator.bluetooth