WakeLockSentinel.release() — Methode · JavaScript-Referenz

Signatur

WakeLockSentinel.prototype.release()

Beschreibung

Mit release() gibst du eine Wake Lock, die du über navigator.wakeLock.request("screen") angefordert hast, ausdrücklich wieder frei. Danach darf das Gerät den Bildschirm wieder abdunkeln oder sperren, wie es in den Systemeinstellungen festgelegt ist.

Die Methode brauchst du immer dann, wenn der Bildschirm nicht mehr aktiv bleiben muss, zum Beispiel wenn ein Rezept-Schritt beendet ist, eine Präsentation stoppt, ein Video pausiert wird oder ein Workout-Timer abläuft. Ein Wake Lock, das du nicht mehr brauchst, verbraucht unnötig Akku.

Nach dem Aufruf steht sentinel.released auf true, und am Sentinel wird das Ereignis release ausgelöst. Ein freigegebener Sentinel lässt sich nicht wiederverwenden. Für eine neue Sperre forderst du mit navigator.wakeLock.request() einen neuen Sentinel an.

Wird die Seite unsichtbar, etwa durch einen Tab-Wechsel oder weil das Fenster minimiert wird, gibt der Browser die Sperre automatisch frei. Auch dann wird das Ereignis release ausgelöst. Soll die Sperre danach weiter gelten, musst du sie beim Ereignis visibilitychange neu anfordern.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das sich mit undefined erfüllt, sobald die Sperre aufgehoben ist. Auch bei einem bereits freigegebenen Sentinel erfüllt es sich ohne Fehler.

Beispiele

Wake Lock anfordern und wieder freigeben

let wakeLock = null;

const sperreAn = async () => {
  try {
    wakeLock = await navigator.wakeLock.request('screen');
    console.log('Wake Lock aktiv:', !wakeLock.released);
  } catch (err) {
    console.error(`${err.name}: ${err.message}`);
  }
};

const sperreAus = async () => {
  if (!wakeLock) return;
  await wakeLock.release();
  console.log('Freigegeben:', wakeLock.released);
  wakeLock = null;
};

await sperreAn();
// ... später, z. B. wenn der Timer abgelaufen ist
await sperreAus();

Wake Lock aktiv: true Freigegeben: true

Auf das release-Ereignis reagieren (auch bei automatischer Freigabe)

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

// Variante 1: addEventListener
sentinel.addEventListener('release', () => {
  console.log('Wake Lock wurde freigegeben');
});

// Variante 2: on-Eigenschaft
// sentinel.onrelease = () => console.log('freigegeben');

setTimeout(() => sentinel.release(), 5000);

Wake Lock wurde freigegeben

Umschalter mit Neuanforderung nach Tab-Wechsel

let sentinel = null;
let gewuenscht = false;
const button = document.querySelector('#wakelock-toggle');

const anfordern = async () => {
  sentinel = await navigator.wakeLock.request('screen');
  sentinel.addEventListener('release', () => {
    button.textContent = 'Bildschirm aktiv halten';
  });
  button.textContent = 'Wake Lock freigeben';
};

button.addEventListener('click', async () => {
  if (!('wakeLock' in navigator)) return alert('Nicht unterstützt');
  gewuenscht = !gewuenscht;
  if (gewuenscht) {
    await anfordern();
  } else {
    await sentinel?.release();
    sentinel = null;
  }
});

// Browser gibt die Sperre bei verstecktem Tab automatisch frei
document.addEventListener('visibilitychange', async () => {
  if (gewuenscht && document.visibilityState === 'visible') {
    await anfordern();
  }
});

// Wichtig · Fallstricke

Kein Wiederverwenden: Ein freigegebener Sentinel bleibt dauerhaft auf released === true. Für eine neue Sperre brauchst du einen neuen Aufruf von navigator.wakeLock.request().
Automatische Freigabe: Wird das Dokument unsichtbar, gibt der Browser die Sperre selbst frei. Dasselbe kann bei niedrigem Akkustand oder im Energiesparmodus passieren. Verlasse dich deshalb nicht darauf, dass die Sperre bis zu deinem release()-Aufruf bestehen bleibt, sondern reagiere auf das Ereignis release.
Mehrfacher Aufruf: Rufst du release() auf einem bereits freigegebenen Sentinel auf, ist das harmlos. Das Promise erfüllt sich trotzdem.
Referenz behalten: Du kannst die Sperre nur über den Sentinel wieder aufheben. Speichere ihn daher in einer Variablen, die außerhalb der Funktion erreichbar ist.
Kompatibilität: Die API setzt einen sicheren Kontext (HTTPS) voraus. Unterstützt wird sie von Chromium-Browsern ab Version 84, Safari ab 16.4 und Firefox ab 126. Prüfe vorher mit 'wakeLock' in navigator, ob der Browser sie kennt. Eine Permissions-Policy (screen-wake-lock) kann die Nutzung in iframes sperren.

Siehe auch

new SpeechSynthesisErrorEvent() WakeLock.request() ContentIndex.delete() CookieStore.delete() DOMTokenList.replace()