Mit der Screen Wake Lock API aktiv bleiben

Mit der Screen Wake Lock API können Sie verhindern, dass Geräte den Bildschirm dimmen oder sperren, wenn eine App weiterhin ausgeführt werden muss.

Was ist die Screen Wake Lock API?

Um eine schnelle Akkuentladung zu vermeiden, wechseln die meisten Geräte in den Ruhemodus, wenn sie nicht verwendet werden. Das ist in den meisten Fällen in Ordnung, bei einigen Anwendungen muss der Bildschirm jedoch eingeschaltet bleiben, damit sie ihre Arbeit erledigen können. Beispiele hierfür sind Koch-Apps, die die Schritte eines Rezepts anzeigen, oder Spiele wie Ball Puzzle, bei denen die Gerätebewegungs-APIs für die Eingabe verwendet werden.

Mit der Screen Wake Lock API können Sie verhindern, dass das Gerät den Bildschirm dimmt und sperrt. Diese Funktion ermöglicht neue Funktionen, für die bisher eine plattformspezifische App erforderlich war.

Mit der Screen Wake Lock API müssen Sie weniger auf komplizierte und potenziell stromintensive Umgehungslösungen zurückgreifen. Sie behebt die Mängel einer älteren API, die sich nur darauf beschränkte, das Display eingeschaltet zu lassen, und eine Reihe von Sicherheits- und Datenschutzproblemen aufwies.

Empfohlene Anwendungsfälle für die Screen Wake Lock API

RioRun, eine von The Guardian entwickelte Webanwendung, war ein perfekter Anwendungsfall (sie ist jedoch nicht mehr verfügbar). Die App führt dich auf einer virtuellen Audiotour durch Rio und folgt der Route des Olympischen Marathons 2016. Ohne Aktivierungssperren würden sich die Bildschirme der Nutzer während der Wiedergabe der Tour häufig ausschalten, was die Nutzung erschweren würde.

Natürlich gibt es noch viele weitere Anwendungsfälle:

  • Eine Rezept-App, bei der der Bildschirm eingeschaltet bleibt, während Sie einen Kuchen backen oder das Abendessen kochen
  • Eine Bordkarten- oder Ticket-App, die das Display eingeschaltet lässt, bis der Barcode gescannt wurde
  • Eine App im Kioskmodus, bei der das Display dauerhaft eingeschaltet bleibt
  • Eine webbasierte Präsentations-App, bei der der Bildschirm während einer Präsentation eingeschaltet bleibt

Aktueller Status

Schritt Status
1. Erläuternde Mitteilung erstellen
2. Ersten Entwurf der Spezifikation erstellen Abschließen
3. Feedback einholen und Design iterieren Abschließen
4. Ursprungstest Abgeschlossen
5. Starten Abschließen

Screen Wake Lock API verwenden

Wakelock-Typen

Die Screen Wake Lock API bietet derzeit nur eine Art von Wecksperre: screen.

screen Wakelock

Eine screen-Aktivierungssperre verhindert, dass sich das Display des Geräts ausschaltet, damit der Nutzer die auf dem Display angezeigten Informationen sehen kann.

Bildschirm-Wakelock erhalten

Wenn Sie eine Displaysperre anfordern möchten, müssen Sie die Methode navigator.wakeLock.request() aufrufen, die ein WakeLockSentinel-Objekt zurückgibt. Sie übergeben dieser Methode den gewünschten Wakelock-Typ als Parameter. Dieser ist derzeit auf 'screen' beschränkt und daher optional. Der Browser kann die Anfrage aus verschiedenen Gründen ablehnen, z. B. weil der Akkustand zu niedrig ist. Daher empfiehlt es sich, den Aufruf in eine try…catch-Anweisung einzubetten. Die Meldung der Ausnahme enthält im Falle eines Fehlers weitere Details.

Bildschirm-Wakelock aufheben

Außerdem benötigen Sie eine Möglichkeit, die Sperre für das Aufwecken des Displays aufzuheben. Dazu rufen Sie die Methode release() des WakeLockSentinel-Objekts auf. Wenn Sie keinen Verweis auf die WakeLockSentinel speichern, gibt es keine Möglichkeit, die Sperre manuell aufzuheben. Sie wird jedoch aufgehoben, sobald der aktuelle Tab nicht mehr sichtbar ist.

Wenn Sie die Sperre für das Aufwecken des Displays nach einem bestimmten Zeitraum automatisch aufheben möchten, können Sie window.setTimeout() verwenden, um release() aufzurufen, wie im folgenden Beispiel gezeigt.

// The wake lock sentinel.
let wakeLock = null;

// Function that attempts to request a screen wake lock.
const requestWakeLock = async () => {
  try {
    wakeLock = await navigator.wakeLock.request();
    wakeLock.addEventListener('release', () => {
      console.log('Screen Wake Lock released:', wakeLock.released);
    });
    console.log('Screen Wake Lock released:', wakeLock.released);
  } catch (err) {
    console.error(`${err.name}, ${err.message}`);
  }
};

// Request a screen wake lock…
await requestWakeLock();
// …and release it again after 5s.
window.setTimeout(() => {
  wakeLock.release();
  wakeLock = null;
}, 5000);

Das WakeLockSentinel-Objekt hat die Eigenschaft released, die angibt, ob ein Sentinel bereits veröffentlicht wurde. Der Wert ist anfangs false und ändert sich in true, sobald ein "release"-Ereignis gesendet wird. Anhand dieser Property können Webentwickler erkennen, wann eine Sperre aufgehoben wurde, sodass sie dies nicht manuell verfolgen müssen. Sie ist seit Chrome 87 verfügbar.

Lebenszyklus von Bildschirm-Wakelocks

Wenn Sie mit der Demo für die Bildschirmsperre spielen, werden Sie feststellen, dass die Bildschirmsperre auf die Sichtbarkeit der Seite reagiert. Das bedeutet, dass die Bildschirmsperre automatisch aufgehoben wird, wenn Sie einen Tab oder ein Fenster minimieren oder von einem Tab oder Fenster mit aktiver Bildschirmsperre zu einem anderen wechseln.

Wenn Sie den Bildschirm-Wakelock wiedererlangen möchten, achten Sie auf das Ereignis visibilitychange und fordern Sie bei dessen Auftreten einen neuen Bildschirm-Wakelock an:

const handleVisibilityChange = async () => {
  if (wakeLock !== null && document.visibilityState === 'visible') {
    await requestWakeLock();
  }
};

document.addEventListener('visibilitychange', handleVisibilityChange);

Auswirkungen auf Systemressourcen minimieren

Sollten Sie in Ihrer App eine Sperre für das Aufwecken des Displays verwenden? Der Ansatz, den Sie wählen, hängt von den Anforderungen Ihrer App ab. Unabhängig davon sollten Sie den möglichst schlanken Ansatz für Ihre App verwenden, um die Auswirkungen auf die Systemressourcen zu minimieren.

Bevor Sie Ihrer App eine Sperre für das Aufwecken des Displays hinzufügen, sollten Sie überlegen, ob Ihre Anwendungsfälle mit einer der folgenden alternativen Lösungen gelöst werden können:

Demo

Sehen Sie sich die Demo für Screen Wake Lock und die Demoquelle an. Beachten Sie, dass die Sperre für das Aktivieren des Displays automatisch aufgehoben wird, wenn Sie zwischen Tabs oder Apps wechseln.

Bildschirm-Wakelocks im Task-Manager des Betriebssystems

Sie können im Task-Manager Ihres Betriebssystems nachsehen, ob eine Anwendung verhindert, dass Ihr Computer in den Ruhemodus wechselt. Im Video unten ist der macOS-Aktivitätsmonitor zu sehen, der anzeigt, dass Chrome eine aktive Bildschirmsperre hat, die das System aktiv hält.

Feedback

Die Web Platform Incubator Community Group (WICG) und das Chrome-Team möchten Ihre Meinung und Erfahrungen mit der Screen Wake Lock API hören.

Informationen zum API-Design

Funktioniert die API nicht wie erwartet? Fehlen Methoden oder Eigenschaften, die Sie für die Implementierung Ihrer Idee benötigen?

Problem mit der Implementierung melden

Haben Sie einen Fehler in der Chrome-Implementierung gefunden? Oder unterscheidet sich die Implementierung von der Spezifikation?

  • Melden Sie den Fehler unter https://new.crbug.com. Geben Sie dabei so viele Details wie möglich an, machen Sie eine einfache Anleitung zum Nachstellen des Fehlers und setzen Sie Components auf Blink>WakeLock. Glitch eignet sich hervorragend, um schnell und einfach Reproduktionen zu teilen.

Unterstützung für die API anzeigen

Beabsichtigen Sie, die Screen Wake Lock API zu verwenden? Ihre öffentliche Unterstützung hilft dem Chrome-Team, Funktionen zu priorisieren, und zeigt anderen Browseranbietern, wie wichtig es ist, sie zu unterstützen.

Nützliche Links

Danksagungen

Hero-Image von Kate Stone Matheson auf Unsplash. Video zum Task-Manager mit freundlicher Genehmigung von Henry Lim