WakeLock: request() Methode
Baseline
2025
Neu verfügbar
Seit March 2025 funktioniert diese Funktion auf aktuellen Geräten und in aktuellen Browserversionen. Auf älteren Geräten oder in älteren Browsern funktioniert sie möglicherweise nicht.
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
request(type)
Parameter
typeOptional-
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
NotAllowedErrorDOMException-
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.
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
| Spezifikation |
|---|
| Screen Wake Lock API # the-request-method |