WakeLockSentinel: release — Ereignis · JavaScript-Referenz

Signatur

wakeLockSentinel.addEventListener("release", handler)

Beschreibung

Das Ereignis release gehört zur Screen Wake Lock API. Ein WakeLockSentinel bekommt man von navigator.wakeLock.request("screen"). Solange die Sperre aktiv ist, schaltet der Bildschirm nicht ab und wird nicht gedimmt. Sobald die Sperre endet, feuert release genau einmal auf diesem Sentinel.

Es gibt zwei Auslöser: Entweder ruft Ihr Code sentinel.release() auf, oder der Browser gibt die Sperre selbst frei. Das passiert zum Beispiel, wenn der Tab in den Hintergrund wechselt (document.visibilityState === "hidden"), das Fenster minimiert wird, der Akku fast leer ist oder das System den Energiesparmodus aktiviert. Gerade den zweiten Fall können Sie nur über dieses Ereignis zuverlässig erkennen.

Typische Einsätze sind: die Oberfläche aktualisieren (etwa einen Schalter „Bildschirm bleibt an“ zurücksetzen), die Referenz auf den Sentinel verwerfen und die Sperre zusammen mit dem Ereignis visibilitychange neu anfordern, sobald die Seite wieder sichtbar ist.

Den Handler registrieren Sie mit addEventListener("release", handler) oder über die Eigenschaft onrelease. Der Handler bekommt ein einfaches Event. Es ist nicht abbrechbar und steigt nicht im DOM auf (kein Bubbling). Nach dem Ereignis ist sentinel.released gleich true.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname, hier immer `"release"`.
$handler Pflicht	(event: Event) => void		Die Rückruffunktion. Sie bekommt ein allgemeines `Event`, dessen `target` der freigegebene `WakeLockSentinel` ist.
$options	boolean \| AddEventListenerOptions	false	Optionale Einstellungen wie `{ once: true }` oder `{ signal }`. `once` ist hier überflüssig, weil das Ereignis pro Sentinel ohnehin nur einmal feuert.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler bekommt ein Event-Objekt.

Beispiele

Freigabe mit addEventListener überwachen

const requestWakeLock = async () => {
  try {
    const sentinel = await navigator.wakeLock.request("screen");
    console.log("Wake Lock aktiv:", !sentinel.released);

    sentinel.addEventListener("release", (event) => {
      console.log("Wake Lock freigegeben, released =", event.target.released);
    });

    // Nach 5 Sekunden manuell freigeben
    setTimeout(() => sentinel.release(), 5000);
  } catch (err) {
    console.error(`${err.name}: ${err.message}`);
  }
};

requestWakeLock();

Wake Lock aktiv: true (nach 5 s) Wake Lock freigegeben, released = true

Eigenschaft onrelease und Schalter in der Oberfläche

const toggle = document.querySelector("#keep-awake");
let sentinel = null;

toggle.addEventListener("change", async () => {
  if (toggle.checked) {
    sentinel = await navigator.wakeLock.request("screen");
    // Alternative zu addEventListener
    sentinel.onrelease = () => {
      toggle.checked = false;   // Oberfläche synchronisieren
      sentinel = null;
      console.log("Bildschirmsperre beendet");
    };
  } else {
    await sentinel?.release();
  }
});

Bildschirmsperre beendet

Nach einem Tab-Wechsel automatisch neu anfordern

let sentinel = null;
let wanted = true; // Nutzer möchte, dass der Bildschirm anbleibt

const acquire = async () => {
  sentinel = await navigator.wakeLock.request("screen");
  sentinel.addEventListener("release", () => {
    console.log("Vom System freigegeben (z. B. Tab verborgen)");
    sentinel = null;
  });
};

document.addEventListener("visibilitychange", async () => {
  if (wanted && !sentinel && document.visibilityState === "visible") {
    await acquire();
    console.log("Wake Lock erneut aktiv");
  }
});

acquire();

Vom System freigegeben (z. B. Tab verborgen) Wake Lock erneut aktiv

Listener mit AbortController entfernen

const controller = new AbortController();
const sentinel = await navigator.wakeLock.request("screen");

const onRelease = () => console.log("freigegeben");
sentinel.addEventListener("release", onRelease, { signal: controller.signal });

// Später: Listener entfernen, ohne die Sperre freizugeben
controller.abort();
// gleichwertig: sentinel.removeEventListener("release", onRelease);
await sentinel.release(); // kein Log mehr

// Wichtig · Fallstricke

Kein Neustart: Ein freigegebener Sentinel lässt sich nicht wieder aktivieren. Für eine neue Sperre müssen Sie navigator.wakeLock.request() erneut aufrufen. Das liefert einen neuen Sentinel, und dort müssen Sie den release-Handler wieder registrieren.
Automatische Freigabe: Wird die Seite verborgen, gibt der Browser die Sperre frei, ohne dass Ihr Code etwas tut. Ohne release-Handler bleibt die Oberfläche dann auf einem falschen Stand.
Das Ereignis feuert pro Sentinel höchstens einmal. Ein zweiter Aufruf von release() löst es nicht erneut aus.
request() funktioniert nur in einem sicheren Kontext (HTTPS), nur bei sichtbarem Dokument und nur, wenn die Permissions Policy screen-wake-lock es erlaubt. Sonst wird das Promise mit NotAllowedError abgelehnt.
Kompatibilität: Chromium-Browser ab Version 84, Safari ab 16.4, Firefox ab 126. Prüfen Sie die Unterstützung vorab mit \"wakeLock\" in navigator.

Siehe auch

WakeLockSentinel WakeLockSentinel.release() WakeLockSentinel.released WakeLock.request() EventTarget.addEventListener() HTMLTrackElement: cuechange