WakeLockSentinel.released — Eigenschaft · JavaScript-Referenz

Signatur

WakeLockSentinel.released

Beschreibung

Die Eigenschaft released einer WakeLockSentinel zeigt, ob die zugehörige Bildschirmsperre (Wake Lock) schon freigegeben wurde. Direkt nach einem erfolgreichen Aufruf von navigator.wakeLock.request("screen") ist der Wert false. Er wechselt auf true, sobald die Sperre endet, und bleibt danach dauerhaft true.

Eine Sperre kann auf zwei Arten enden:

Durch Ihren Code: Sie rufen sentinel.release() auf.
Durch den Browser: Das passiert zum Beispiel, wenn der Tab in den Hintergrund wechselt (document.visibilityState === "hidden"), das Fenster minimiert wird oder der Energiesparmodus bzw. ein niedriger Akkustand eingreift.

In beiden Fällen wird das Ereignis release an der Sentinel ausgelöst, und released steht danach auf true.

Die Eigenschaft ist nützlich, um zu prüfen, ob eine gespeicherte Sentinel noch gilt. Das brauchen Sie etwa, wenn Sie die Sperre nach der Rückkehr in den Tab neu anfordern oder in der Oberfläche anzeigen wollen, ob der Bildschirm gerade wach gehalten wird. Eine freigegebene Sentinel lässt sich nicht wieder aktivieren. Dafür müssen Sie immer eine neue Sentinel anfordern.

Rückgabewert

Typ

boolean

Beschreibung

false, solange die Bildschirmsperre aktiv ist. true, sobald sie freigegeben wurde, egal ob durch release() oder durch den Browser.

Beispiele

Status vor und nach release() prüfen

const demo = async () => {
  try {
    const sentinel = await navigator.wakeLock.request("screen");
    console.log("Nach request:", sentinel.released);

    await sentinel.release();
    console.log("Nach release:", sentinel.released);
  } catch (err) {
    console.error(`Wake Lock fehlgeschlagen: ${err.name} – ${err.message}`);
  }
};

demo();

Nach request: false Nach release: true

Sperre nach Tab-Wechsel automatisch neu anfordern

let sentinel = null;

const requestWakeLock = async () => {
  try {
    sentinel = await navigator.wakeLock.request("screen");
    sentinel.addEventListener("release", () => {
      console.log("Wake Lock freigegeben, released =", sentinel.released);
    });
    console.log("Wake Lock aktiv");
  } catch (err) {
    console.error(err.name, err.message);
  }
};

// Der Browser gibt die Sperre frei, wenn der Tab in den Hintergrund wechselt
document.addEventListener("visibilitychange", () => {
  const needsNewLock = sentinel === null || sentinel.released;
  if (document.visibilityState === "visible" && needsNewLock) {
    requestWakeLock();
  }
});

requestWakeLock();

Wake Lock aktiv Wake Lock freigegeben, released = true Wake Lock aktiv

Status-Anzeige in der Oberfläche (z. B. Koch-App)

const statusEl = document.querySelector("#wakelock-status");
const toggleBtn = document.querySelector("#wakelock-toggle");
let sentinel = null;

const render = () => {
  const active = sentinel !== null && !sentinel.released;
  statusEl.textContent = active ? "Bildschirm bleibt an" : "Bildschirm darf ausgehen";
  toggleBtn.textContent = active ? "Deaktivieren" : "Aktivieren";
};

toggleBtn.addEventListener("click", async () => {
  if (sentinel && !sentinel.released) {
    await sentinel.release();
  } else if ("wakeLock" in navigator) {
    sentinel = await navigator.wakeLock.request("screen");
    sentinel.addEventListener("release", render);
  }
  render();
});

render();

// Wichtig · Fallstricke

Nur lesbar: Wenn Sie etwas an released zuweisen, hat das keine Wirkung (im Strict Mode gibt es einen TypeError). Zum Freigeben nutzen Sie release().
Keine Reaktivierung: Steht der Wert einmal auf true, bleibt die Sentinel unbrauchbar. Fordern Sie mit navigator.wakeLock.request() eine neue an.
Automatische Freigabe: Der Browser gibt die Sperre selbst frei, wenn die Seite unsichtbar wird. Verlassen Sie sich deshalb nicht darauf, dass eine einmal angeforderte Sperre dauerhaft gilt. Reagieren Sie stattdessen auf visibilitychange oder auf das Ereignis release.
Zeitpunkt: Nach await sentinel.release() ist released garantiert true. Innerhalb eines release-Ereignis-Handlers ist der Wert ebenfalls schon true.
Kompatibilität: Die API gibt es nur in sicheren Kontexten (HTTPS). In Iframes kann sie über die Permissions-Policy screen-wake-lock gesperrt sein. Ältere Browser, darunter Firefox vor Version 126 und Safari vor 16.4, kennen navigator.wakeLock nicht. Prüfen Sie die Unterstützung deshalb vorher mit "wakeLock" in navigator.
Die Eigenschaft released kam erst nachträglich in die Spezifikation. In sehr frühen Chromium-Implementierungen (vor Version 87) kann sie deshalb undefined sein.

Siehe auch

MediaTrackSettings.deviceId WakeLockSentinel.type AbortSignal.reason CloseEvent.reason Document.referrer