使用 Screen Wake Lock API 保持喚醒

Screen Wake Lock API 可讓您在應用程式需要持續運作時，避免裝置變暗或鎖定螢幕。

Pete LePage
Thomas Steiner

什麼是 Screen Wake Lock API？

為避免耗電，大多數裝置會在閒置時快速進入休眠狀態。雖然這是正常情況，但某些應用程式需要保持螢幕喚醒狀態才能完成工作。舉例來說，會顯示食譜步驟的烹飪應用程式，或像 Ball Puzzle 這類遊戲使用裝置動作 API 做為輸入內容。

Screen Wake Lock API 可用來防止裝置變暗及鎖定螢幕。此功能提供了新的體驗，現在需要特定平台的應用程式。

Screen Wake Lock API 減少了不必要的入侵和可能耗盡電力的解決方法。這個 API 解決了舊版 API 的缺點，過去僅是讓螢幕保持開啟狀態，而且存在許多安全性與隱私權問題。

Screen Wake Lock API 的建議用途

RioRun 是一款由 The Guardian 開發的網路應用程式，但它已無法使用。應用程式會帶領你進行里約的虛擬語音導覽，閱讀 2016 年奧運馬拉鬆的路線。如果沒有 Wake Lock，使用者的螢幕就會在導覽期間頻繁關閉，導致使用難以使用。

當然，這些用途還有很多用途：

  • 食譜應用程式，在您烤蛋糕或煮晚餐時讓螢幕保持開啟
  • 登機證或票券應用程式 會在掃描條碼前讓螢幕保持開啟
  • 資訊站風格的應用程式，可持續開啟螢幕
  • 網頁式簡報應用程式可在簡報期間 保持螢幕喚醒

目前狀態

步驟 狀態
1. 建立說明 不適用
2. 建立規格的初始草稿 完成
3. 收集意見回饋並改進設計 完成
4. 來源試用 課程結束
5.啟動 完成

使用 Screen Wake Lock API

Wake Lock 類型

Screen Wake Lock API 目前只提供一種 Wake Lock：screen。

screen Wake Lock

screen Wake Lock 會防止裝置螢幕關閉，讓使用者可以查看畫面上顯示的資訊，

啟用螢幕 Wake Lock

如要要求螢幕 Wake Lock，您必須呼叫傳回 WakeLockSentinel 物件的 navigator.wakeLock.request() 方法。您可以將所需的 Wake Lock 類型做為參數傳遞，該類型「目前」只限 'screen'，因此是「選用」。瀏覽器可能會基於各種原因拒絕要求 (例如電池電量過低)，因此建議您將呼叫納入 try…catch 陳述式中。發生失敗時，例外狀況會附上更多詳細資料。

撤銷螢幕 Wake Lock

您也必須藉由呼叫 WakeLockSentinel 物件的 release() 方法，釋出螢幕 Wake Lock。如果您未儲存 WakeLockSentinel 的參照，就無法手動釋出鎖定，但目前的分頁隱藏後，系統就會釋出鎖定。

如果您想在一段時間後自動釋出螢幕 Wake Lock，可以使用 window.setTimeout() 呼叫 release()，如以下範例所示。

// 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);

WakeLockSentinel 物件具有名為 released 的屬性，表示該標記是否已釋放。其值一開始為 false，並在分派 "release" 事件後變更為 true。這個屬性可以協助網頁程式開發人員瞭解鎖定推出的時間，這樣他們就不需要手動追蹤。自 Chrome 87 起已推出。

螢幕 Wake Lock 生命週期

按照螢幕 Wake Lock 示範功能進行遊戲時，您會發現螢幕 Wake Lock 會影響頁面瀏覽權限。這表示當您將分頁或視窗最小化時，或者在已啟用螢幕 Wake Lock 的分頁或視窗之間切換時，螢幕 Wake Lock 就會自動釋放。

如要取得螢幕 Wake Lock，請監聽 visibilitychange 事件，並在發生該事件時要求新的螢幕 Wake Lock：

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

document.addEventListener('visibilitychange', handleVisibilityChange);

將您對系統資源的影響降至最低

您應該在應用程式中使用螢幕 Wake Lock 嗎？ 採取的方法視應用程式的需求而定。無論如何，您應盡可能讓應用程式使用最輕便的方法，將對系統資源的影響降到最低。

在應用程式中新增螢幕 Wake Lock 之前，請先評估下列替代解決方案是否能解決您的用途：

  • 如果應用程式執行長時間的下載作業，建議您使用背景擷取功能。
  • 如果應用程式是從外部伺服器同步處理資料，請考慮使用背景同步處理。

操作示範

請參閱螢幕 Wake Lock 示範和示範來源。 請注意，切換分頁或應用程式時，螢幕 Wake Lock 會自動釋放。

OS 工作管理員中的螢幕 Wake Lock

您可以使用作業系統的工作管理員，查看是否有應用程式阻止電腦休眠。下方影片展示的是 macOS 活動監控器，指出 Chrome 設有主動螢幕 Wake Lock，讓系統保持喚醒狀態。

意見回饋：

歡迎透過 Web Platform Incubator Community Group (WICG) 與 Chrome 團隊，瞭解您對於 Screen Wake Lock API 的想法和使用經驗。

告訴我們 API 設計

API 有沒有正常運作的問題嗎？或者您需要實作提案的方法或屬性嗎？

回報導入問題

您在執行 Chrome 時發現錯誤了嗎？還是實作與規格不同？

  • 前往 https://new.crbug.com 回報錯誤。請務必盡可能附上詳細資料，提供重現錯誤的簡易操作說明，並將「Components」設為 Blink>WakeLock。Glitch 適合用來快速分享簡單快速的提案。

展現對 API 的支援

是否打算使用 Screen Wake Lock API？您的公開支援可協助 Chrome 團隊決定功能的優先順序，以及向其他瀏覽器廠商瞭解這項功能有多重要。

實用連結

特別銘謝

Kate Stone Matheson 在 Unsplash 上提供的主頁橫幅。工作管理員視訊由 Henry Lim 提供。