WakeLock.request() — Methode · JavaScript-Referenz

Signatur

WakeLock.prototype.request(type)

Beschreibung

navigator.wakeLock.request() verhindert, dass das Gerät den Bildschirm abdunkelt, ausschaltet oder sperrt, solange die Sperre aktiv ist. Das ist nützlich für Anwendungen, bei denen Nutzer länger auf den Bildschirm schauen, ohne ihn zu berühren, z. B. Rezept-Apps, Navigationsanzeigen, Präsentationen, QR-Code-Tickets, Workout-Timer oder Dashboards.

Das zurückgegebene Promise wird mit einem WakeLockSentinel erfüllt. Über dieses Objekt gibst du die Sperre mit release() wieder frei und erfährst über das release-Ereignis, wann das System sie von sich aus beendet hat. Die Sperre ist an die Sichtbarkeit des Dokuments gebunden: Wechselt der Tab in den Hintergrund oder wird das Fenster minimiert, gibt der Browser sie automatisch frei. Sie muss dann bei erneuter Sichtbarkeit (Ereignis visibilitychange) neu angefordert werden.

Das System kann die Anfrage ablehnen, etwa bei niedrigem Akkustand, im Energiesparmodus, wenn das Dokument nicht sichtbar oder nicht aktiv ist oder eine Berechtigungsrichtlinie (Permissions-Policy: screen-wake-lock) die Nutzung verbietet. In diesen Fällen wird das Promise mit einer NotAllowedError-DOMException abgelehnt. Deshalb sollte man request() immer in try/catch aufrufen.

Parameter

Name	Typ	Default	Beschreibung
$type	"screen"	"screen"	Art der Wachhaltesperre. Derzeit ist nur `"screen"` spezifiziert. Damit wird verhindert, dass der Bildschirm abgedunkelt oder ausgeschaltet wird. Andere Werte lösen einen `TypeError` aus.

Rückgabewert

Typ

Promise<WakeLockSentinel>

Beschreibung

Ein Promise, das mit einem WakeLockSentinel erfüllt wird, sobald die Sperre gewährt wurde. Wird die Anfrage abgelehnt, wird es mit einer DOMException vom Typ NotAllowedError zurückgewiesen.

Beispiele

Bildschirm wach halten mit Fehlerbehandlung

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('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.error('Wake Lock abgelehnt:', 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. (nach Rückkehr in den Tab)

Umschalter für eine Rezept-Ansicht

// <button id="toggle">Bildschirm wach halten</button>
const button = document.querySelector('#toggle');
let sentinel = null;

button.addEventListener('click', async () => {
  if (sentinel && !sentinel.released) {
    await sentinel.release();
    sentinel = null;
    button.textContent = 'Bildschirm wach halten';
    return;
  }
  try {
    sentinel = await navigator.wakeLock.request('screen');
    button.textContent = 'Wachhalten beenden';
    sentinel.addEventListener('release', () => {
      button.textContent = 'Bildschirm wach halten';
    });
  } catch (err) {
    alert(`Nicht möglich: ${err.message}`);
  }
});

// Wichtig · Fallstricke

Automatische Freigabe: Wird das Dokument unsichtbar (Tab-Wechsel, Minimieren, Sperrbildschirm), gibt der Browser die Sperre frei. Neu anfordern über visibilitychange, sonst geht der Bildschirm doch aus.
Sicherer Kontext: Nur über HTTPS (oder localhost) verfügbar. navigator.wakeLock ist sonst undefined.
Ablehnung: Energiesparmodus, niedriger Akkustand, ein nicht sichtbares Dokument oder Permissions-Policy: screen-wake-lock=() führen zu NotAllowedError. In iframes muss die Nutzung über allow="screen-wake-lock" freigegeben werden.
Kompatibilität: Chromium ab 84, Safari ab 16.4 (in iOS-Home-Screen-Web-Apps erst ab 18.4 zuverlässig), Firefox ab 126. Vorher per Feature-Erkennung ('wakeLock' in navigator) prüfen.
Akku: Sperre nur so lange halten wie nötig und mit WakeLockSentinel.release() aktiv freigeben. Mehrere request()-Aufrufe erzeugen jeweils eigene Sentinels, die alle einzeln freigegeben werden müssen.

Siehe auch

WakeLock WakeLockSentinel WakeLockSentinel.release() Navigator.wakeLock new PaymentRequest()