Screen Wake Lock API

Die meisten Geräte schalten ihren Bildschirm standardmäßig nach einer bestimmten Zeit ab, um die Lebensdauer der Hardware zu verlängern. Moderne Geräte tun dies, um Batterieleistung zu sparen. Obwohl dies eine nützliche Funktion ist, benötigen einige Anwendungen, dass der Bildschirm wach bleibt, um optimal genutzt zu werden.

Die Screen Wake Lock API verhindert, dass der Bildschirm ausgeschaltet, gedimmt oder gesperrt wird. Sie bietet eine einfache plattformbasierte Lösung, damit sichtbare (aktive) Dokumente die Plattform-Bildschirm-Wachhaltung ("screen wake lock") erwerben können.

Es gibt viele Anwendungsfälle, bei denen es sinnvoll ist, den Bildschirm eingeschaltet zu lassen, wie beim Lesen eines E-Books, bei der Navigation mit einer Karte, beim Folgen eines Rezepts, bei einer Präsentation vor einem Publikum, beim Scannen eines QR-/Barcodes oder bei Anwendungen, die Sprach- oder Gestensteuerung nutzen, anstatt taktile Eingaben (die Standardmethode zum Wachhalten eines Bildschirms).

Sie erhalten ein WakeLockSentinel-Objekt, indem Sie die navigator.wakeLock.request() Promise-basierte Methode aufrufen, die aufgelöst wird, wenn die Plattform dies zulässt. Ein Antrag kann aus verschiedenen Gründen abgelehnt werden, einschließlich Systemeinstellungen (wie Energiesparmodus oder niedrigem Batteriestand) oder wenn das Dokument nicht aktiv oder sichtbar ist. Es ist eine gute Praxis, eine Referenz auf das Sentinel-Objekt zu speichern, um die Anwendung später steuern zu lassen, ob sie es freigeben möchte.

Das Sentinel ist an das zugrundeliegende System-Wachhaltungssystem gebunden. Es kann vom System freigegeben werden, wenn beispielsweise die Batterieleistung zu niedrig ist oder das Dokument nicht aktiv oder sichtbar ist. Es kann auch manuell über die WakeLockSentinel.release()-Methode freigegeben werden. Nachdem es freigegeben wurde, kann ein WakeLockSentinel nicht mehr verwendet werden. Wenn eine Bildschirm-Wachhaltung erneut/immer noch erforderlich ist, muss die Anwendung eine neue anfordern.

Die Screen Wake Lock API sollte verwendet werden, um den Bildschirm zur Verbesserung der Benutzerfreundlichkeit eingeschaltet zu lassen. Es ist eine gute Idee, auf der Benutzeroberfläche ein Feedback anzuzeigen, um zu zeigen, ob die Wachhaltung aktiv ist, und dem Benutzer eine Möglichkeit zu geben, sie zu deaktivieren, wenn er dies wünscht.

WakeLock

Verhindert, dass sich Bildschirme von Geräten dimmen oder sperren, wenn eine Anwendung weiterhin laufen muss.

WakeLockSentinel

Bietet Zugriff auf die zugrundeliegende Plattform-Wachhaltung und kann manuell freigegeben und erneut angefordert werden, wenn es referenziert wird. Erhalten Sie eine Instanz des Objekts, indem Sie WakeLock.request aufrufen.

Navigator.wakeLock Schreibgeschützt

Gibt eine WakeLock-Objektinstanz zurück, von der aus alle anderen Funktionen zugänglich sind.

Permissions-Policy: screen-wake-lock

Der Zugriff auf die API wird durch die Permissions-Policy-Richtlinie screen-wake-lock beschränkt. Siehe Sicherheitsüberlegungen unten.

Dieser Code prüft die Unterstützung der Wachhaltung und aktualisiert die Benutzeroberfläche entsprechend.

if ("wakeLock" in navigator) {
  isSupported = true;
  statusElem.textContent = "Screen Wake Lock API supported!";
} else {
  wakeButton.disabled = true;
  statusElem.textContent = "Wake lock is not supported by this browser.";
}

Das folgende Beispiel zeigt, wie ein WakeLockSentinel-Objekt angefordert wird. Die WakeLock.request-Methode ist Promise-basiert, sodass wir eine asynchrone Funktion erstellen können, die wiederum die Benutzeroberfläche aktualisiert, um anzuzeigen, dass die Wachhaltung aktiv ist.

// Create a reference for the Wake Lock.
let wakeLock = null;

// create an async function to request a wake lock
try {
  wakeLock = await navigator.wakeLock.request("screen");
  statusElem.textContent = "Wake Lock is active!";
} catch (err) {
  // The Wake Lock request has failed - usually system related, such as battery.
  statusElem.textContent = `${err.name}, ${err.message}`;
}

Das folgende Beispiel zeigt, wie die zuvor erworbene Wachhaltung freigegeben wird.

wakeLock.release().then(() => {
  wakeLock = null;
});

Dieses Beispiel aktualisiert die Benutzeroberfläche, wenn die Wachhaltung aus irgendeinem Grund freigegeben wurde (z. B. beim Navigieren weg vom aktiven Fenster/Tab).

wakeLock.addEventListener("release", () => {
  // the wake lock has been released
  statusElem.textContent = "Wake Lock has been released";
});

Der folgende Code fordert die Wachhaltung erneut an, falls sich die Sichtbarkeit des Dokuments ändert und die Wachhaltung freigegeben wird.

document.addEventListener("visibilitychange", async () => {
  if (wakeLock !== null && document.visibilityState === "visible") {
    wakeLock = await navigator.wakeLock.request("screen");
  }
});

Sie können den vollständigen Code hier auf GitHub finden. Die Demo verwendet einen Button, um eine Wachhaltung anzufordern und auch freizugeben, was wiederum die Benutzeroberfläche aktualisiert. Die Benutzeroberfläche aktualisiert sich auch, wenn die Wachhaltung automatisch aus irgendeinem Grund freigegeben wird. Es gibt ein Kontrollkästchen, das, wenn es aktiviert ist, die Wachhaltung automatisch neu anfordert, wenn sich der Sichtbarkeitszustand des Dokuments ändert und wieder sichtbar wird.

• Geben Sie die Bildschirm-Wachhaltung frei, wenn der Benutzer die Aktivität beendet, die den immer aktiven Bildschirm erforderte. Beispielsweise könnte eine Ticketing-App, die QR-Codes zur Übertragung von Ticketinformationen verwendet, die Bildschirm-Wachhaltung anfordern, wenn der QR-Code angezeigt wird (damit der Code erfolgreich gescannt wird), sie aber danach freigeben. Eine Präsentations-App könnte die Wachhaltung nur während einer aktiven Präsentation halten, aber nicht, wenn die Präsentation bearbeitet wird.
• Wenn Ihre App lang andauernde Downloads durchführt, ziehen Sie in Betracht, den Hintergrundabruf zu verwenden.
• Wenn Ihre App Daten von einem entfernten Server synchronisiert, ziehen Sie in Betracht, die Hintergrundsynchronisierung zu verwenden.
• Nur aktive Dokumente können Bildschirm-Wachhaltungen anfordern, und zuvor erworbene Halterungen werden automatisch freigegeben, wenn das Dokument inaktiv wird. Stellen Sie daher sicher, dass Sie die Bildschirm-Wachhaltung bei Bedarf erneut anfordern, wenn das Dokument aktiv wird (lauschen Sie auf das visibilitychange-Ereignis).

Der Zugriff auf die Screen Wake Lock API wird durch die Permissions Policy-Richtlinie screen-wake-lock kontrolliert.

Beim Verwenden der Permissions Policy ist die Standard-Zulassungsliste für screen-wake-lock auf self gesetzt. Dies erlaubt die Nutzung der Wachhaltung in Nested Frames mit gleichem Ursprung, verhindert jedoch, dass Drittanbieter-Inhalte die Halterung nutzen. Drittanbieter-Nutzung kann aktiviert werden, indem der Server zunächst den Permissions-Policy-Header setzt, um einer bestimmten Drittanbieter-Herkunft die Berechtigung zu erteilen.

Permissions-Policy: screen-wake-lock=(self b.example.com)

Dann muss das Attribut allow="screen-wake-lock" dem Frame-Containerelement für Quellen aus dieser Herkunft hinzugefügt werden:

<iframe src="https://b.example.com" allow="screen-wake-lock"/></iframe>

Browser können die Bildschirm-Wachhaltung auch in einem bestimmten Dokument aus einem implementationsspezifischen Grund blockieren, wie z. B. eine Benutzer- oder Plattform-Einstellung. Es wird erwartet, dass sie einen unaufdringlichen Mechanismus bereitstellen, um den Benutzer zu informieren, wenn die Wachhaltung aktiv ist, und den Benutzern die Möglichkeit geben, die Bildschirm-Wachhaltung der Anwendung zu entfernen.

Die Permissions API screen-wake-lock-Berechtigung kann verwendet werden, um zu testen, ob der Zugriff auf die Bildschirm-Wachhaltung granted, denied oder prompt (erfordert Benutzerbestätigung in Form eines Prompts) ist.

• Bleiben Sie wach mit der Screen Wake Lock API
• Eine Demo der Screen Wake Lock API auf Glitch