WakeLock: request()-Methode

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used 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 das System-Bildschirm-Aufwach-Sperre gewährt wird.

Die Bildschirm-Aufwach-Sperre verhindert, dass die Bildschirme von Geräten gedimmt oder gesperrt werden, wenn eine Anwendung weiterlaufen muss.

Syntax

js
request(type)

Parameter

type Optional

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

screen

Verhindert das Ausschalten des Bildschirms. Nur sichtbare Dokumente können die Bildschirm-Aufwach-Sperre erwerben.

Wenn kein type-Parameter explizit angegeben wird, 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 die Aufwach-Sperre nicht verfügbar ist, was folgende Gründe haben kann:

  • Die Verwendung dieser Funktion ist durch eine Permissions Policy blockiert.
  • Das Dokument ist nicht vollständig aktiv.
  • Der Sichtbarkeitsstatus des Dokuments ist hidden.
  • Der User Agent konnte die Aufwach-Sperre der Plattform nicht erwerben. Dies könnte zum Beispiel passieren, wenn das Gerät wenig Akku hat.

Beispiele

Die folgende asynchrone Funktion fordert ein WakeLockSentinel-Objekt an. Die request()-Methode wird in einer try...catch-Anweisung eingeschlossen, 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();

Die Bildschirm-Aufwach-Sperre kann vom Gerät widerrufen werden, nachdem sie gewährt wurde. Das zurückgegebene WakeLockSentinel kann verwendet werden, um den Status der Sperre zu überprüfen und/oder eine gehaltene Bildschirm-Aufwach-Sperre manuell zu annullieren.

Spezifikationen

Specification
Screen Wake Lock API
# the-request-method

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch