WakeLock: request() Methode

Baseline 2025
Newly available

Since March 2025, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

Sicherer Kontext: Diese Funktion ist nur in sicheren Kontexten (HTTPS) in einigen oder allen unterstützenden Browsern verfügbar.

Die request() Methode der WakeLock Schnittstelle gibt ein Promise zurück, das mit einem WakeLockSentinel Objekt erfüllt wird, wenn der systembedingte Bildschirm-Wachhaltewunsch gewährt wird.

Der Bildschirm-Wachhaltewunsch verhindert, dass Bildschirme von Geräten abgedunkelt oder gesperrt werden, wenn eine Anwendung weiterlaufen muss.

Syntax

js
request(type)

Parameter

type Optional

Ein String, der den Typ des Bildschirm-Wachhaltewunsches angibt, aus den folgenden aufgezählten Typen:

screen

Verhindert, dass der Bildschirm ausgeschaltet wird. Nur sichtbare Dokumente können den Bildschirm-Wachhaltewunsch erlangen.

Wird kein type-Parameter explizit angegeben, verwendet die request()-Methode standardmäßig den screen-Typ.

Rückgabewert

Ein Promise, das mit einem WakeLockSentinel Objekt aufgelöst wird.

Ausnahmen

NotAllowedError DOMException

Wird ausgelöst, wenn der Wachhaltewunsch nicht verfügbar ist, was aus folgenden Gründen passieren kann:

  • Die Nutzung dieser Funktion ist durch eine Berechtigungsrichtlinie blockiert.
  • Das Dokument ist nicht vollständig aktiv.
  • Der Sichtbarkeitsstatus des Dokuments ist hidden.
  • Der User Agent konnte den Wachhaltewunsch der Plattform nicht erlangen. Zum Beispiel kann dies passieren, wenn das Gerät wenig Batterieleistung hat.

Beispiele

Die folgende asynchrone Funktion fordert ein WakeLockSentinel Objekt an. Die request()-Methode ist in eine try...catch-Anweisung eingebettet, um Fälle zu handhaben, in denen der Browser die Anfrage aus irgendeinem Grund ablehnt.

js
const requestWakeLock = async () => {
  try {
    const wakeLock = await navigator.wakeLock.request("screen");
  } catch (err) {
    // The wake lock request fails - usually system-related, such as low battery.

    console.log(`${err.name}, ${err.message}`);
  }
};

requestWakeLock();

Der Bildschirm-Wachhaltewunsch kann vom Gerät widerrufen werden, nachdem er gewährt wurde. Das zurückgegebene WakeLockSentinel kann verwendet werden, um den Status des Wunsches zu überprüfen und/oder einen gehaltenen Bildschirm-Wachhaltewunsch manuell zu stornieren.

Spezifikationen

Specification
Screen Wake Lock API
# the-request-method

Browser-Kompatibilität

Siehe auch