Mit der Screen Wake Lock API aktiv bleiben

Die Screen Wake Lock API bietet eine Möglichkeit, zu verhindern, dass Geräte den Bildschirm dimmen oder sperren, wenn eine App weiter ausgeführt werden muss.

Was ist die Screen Wake Lock API?

Um eine Entladung des Akkus zu vermeiden, wechseln die meisten Geräte schnell in den Ruhemodus, wenn sie inaktiv sind. Dies ist in der Regel in Ordnung. Bei einigen Anwendungen muss der Bildschirm jedoch eingeschaltet bleiben, um ihre Arbeit zu erledigen. Beispiele hierfür sind Koch-Apps, die die Schritte eines Rezepts zeigen, oder ein Spiel wie Ball Puzzle, das die Device Motion APIs für die Eingabe verwendet.

Die Screen Wake Lock API bietet eine Möglichkeit, zu verhindern, dass das Gerät den Bildschirm dimmt und sperren kann. Diese Funktion ermöglicht neue Möglichkeiten, für die bisher eine plattformspezifische App erforderlich war.

Die Screen Wake Lock API reduziert die Notwendigkeit für Hacking- und potenziell energieintensive Problemumgehungen. Sie behebt die Mängel einer älteren API, die auf das Einschalten des Bildschirms beschränkt war und eine Reihe von Sicherheits- und Datenschutzproblemen aufwies.

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

RioRun, eine von The Guardian entwickelte Web-App, war ein perfekter Anwendungsfall (obwohl sie nicht mehr verfügbar ist). Die App nimmt dich mit auf eine virtuelle Audiotour durch Rio, die der Route des olympischen Marathons 2016 folgt. Ohne Wakelocks wurden die Bildschirme der Nutzer häufig ausgeschaltet, während die Tour abgespielt wurde, was die Nutzung schwierig machte.

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

  • Eine Rezepte-App, bei der der Bildschirm eingeschaltet bleibt, während Sie einen Kuchen backen oder ein Abendessen kochen
  • Eine Bordkarten- oder Ticket-App, die den Bildschirm eingeschaltet lässt, bis der Barcode gescannt wurde
  • Eine App im Kioskstil, die den Bildschirm kontinuierlich eingeschaltet hält
  • Eine webbasierte App für Präsentationen, die den Bildschirm eingeschaltet lässt,

Aktueller Status

Step Status
1. Erklärende Erklärung erstellen
2. Ersten Entwurf der Spezifikation erstellen Abschließen
3. Feedback einholen und Design iterieren Abschließen
4. Ursprungstest Abschließen
5. Starten Abschließen

Screen Wake Lock API verwenden

Wakelock-Typen

Die Screen Wake Lock API bietet derzeit nur einen Wakelock-Typ: screen.

screen-Wakelock

Ein screen-Wakelock verhindert, dass der Bildschirm des Geräts ausgeschaltet wird, sodass der Nutzer die auf dem Bildschirm angezeigten Informationen sehen kann.

Display-Wakelock einrichten

Um eine Display-Wakelock anzufordern, musst du die Methode navigator.wakeLock.request() aufrufen, die ein WakeLockSentinel-Objekt zurückgibt. Sie übergeben dieser Methode den gewünschten Wakelock-Typ als Parameter, der aktuell auf 'screen' beschränkt und daher optional ist. Der Browser kann die Anfrage aus verschiedenen Gründen ablehnen, z. B. weil der Akkuladestand zu niedrig ist. Daher empfiehlt es sich, den Aufruf in eine try…catch-Anweisung einzubinden. Die Meldung der Ausnahme enthält im Falle eines Fehlers weitere Details.

Bildschirm-Wakelock freigeben

Du benötigst auch eine Möglichkeit, die Display-Wakelock freizugeben. Dazu musst du die Methode release() des WakeLockSentinel-Objekts aufrufen. Wenn Sie keinen Verweis auf den WakeLockSentinel speichern, gibt es keine Möglichkeit, die Sperre manuell aufzuheben. Sie wird jedoch freigegeben, sobald der aktuelle Tab unsichtbar ist.

Wenn die Displaysperre nach einer bestimmten Zeit automatisch freigegeben werden soll, können Sie release() wie im folgenden Beispiel mit window.setTimeout() aufrufen.

// 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 eine Eigenschaft namens released, die angibt, ob bereits ein Sentinel freigegeben wurde. Der Wert lautet anfangs false und ändert sich in true, sobald ein "release"-Ereignis gesendet wird. Mithilfe dieser Eigenschaft können Webentwickler erkennen, wann eine Sperre aufgehoben wurde, sodass sie dies nicht manuell nachverfolgen müssen. Die Funktion ist ab Chrome 87 verfügbar.

Lebenszyklus der Display-Wakelocks

Wenn Sie mit der Demo für Display-Wakelocks spielen, werden Sie feststellen, dass die Seitensichtbarkeit von Bildschirm-Wakelocks abhängig ist. Das bedeutet, dass die Displaysperre automatisch aufgehoben wird, wenn Sie einen Tab oder ein Fenster minimieren oder von einem Tab oder Fenster wegwechseln, in dem eine Bildschirm-Wakelock aktiviert ist.

Wenn du die Displaysperre noch einmal anfordern möchtest, warte auf das Ereignis visibilitychange und fordere eine neue Displaysperre an:

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

document.addEventListener('visibilitychange', handleVisibilityChange);

Auswirkungen auf Systemressourcen minimieren

Sollte ich einen Bildschirm-Wakelock in der App verwenden? Der verwendete Ansatz hängt von den Anforderungen Ihrer Anwendung ab. Unabhängig davon sollten Sie den einfachsten Ansatz für Ihre Anwendung verwenden, um ihre Auswirkungen auf die Systemressourcen zu minimieren.

Bevor Sie Ihrer App eine Bildschirm-Wakelock hinzufügen, überlegen Sie, ob Ihre Anwendungsfälle mit einer der folgenden alternativen Lösungen gelöst werden könnten:

Demo

Sehen Sie sich die Demo für die Displaysperre und die Demoquelle an. Die Display-Wakelock wird automatisch freigegeben, wenn du zwischen Tabs oder Apps wechselst.

Bildschirm-Wakelocks im Task-Manager des Betriebssystems

Mit dem Task-Manager Ihres Betriebssystems können Sie feststellen, ob eine Anwendung den Ruhemodus des Computers verhindert. Das folgende Video zeigt die Aktivitätsanzeige von macOS. Sie weist darauf hin, dass Chrome eine aktive Bildschirm-Wakelock hat, die das System aktiv hält.

Feedback

Die Web Platform Incubator Community Group (WICG) und das Chrome-Team möchten mehr über Ihre Gedanken und Erfahrungen im Hinblick auf die Screen Wake Lock API erfahren.

Informationen zum API-Design

Gibt es etwas an der API, das nicht wie erwartet funktioniert? Oder fehlen Methoden oder Eigenschaften, die Sie zur Implementierung Ihrer Idee benötigen?

Problem mit der Implementierung melden

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

  • Melde einen Fehler unter https://new.crbug.com. Gib so viele Details wie möglich an, stelle eine einfache Anleitung zum Reproduzieren des Fehlers bereit und setze Components auf Blink>WakeLock. Mit Glitch lassen sich schnelle und einfache Reproduktionen teilen.

Unterstützung für die API zeigen

Möchtest du die Screen Wake Lock API 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. Task-Manager-Video mit freundlicher Genehmigung von Henry Lim.