使用 Screen Wake Lock API 保持喚醒

當應用程式需要持續執行時，螢幕 Wake Lock API 可防止裝置變暗或鎖定螢幕。

Pete LePage

Thomas Steiner

什麼是 Screen Wake Lock API？

為避免耗盡電力，大多數裝置在閒置時會快速進入休眠狀態。雖然這樣通常沒問題，但部分應用程式需要讓螢幕保持喚醒狀態，才能完成工作。例如：顯示食譜步驟的烹飪應用程式，或是使用裝置動作 API 做為輸入的遊戲，例如 Ball Puzzle。

Screen Wake Lock API 可防止裝置調暗及鎖定螢幕。這項功能可提供全新體驗，而這類體驗先前需要平台專屬應用程式才能實現。

Screen Wake Lock API 可減少對耗電的權宜解決方案的需求。舊版 API 只能讓螢幕保持開啟狀態，且有許多安全性和隱私權問題，而新版 API 則解決了這些缺點。

Screen Wake Lock API 的建議用途

RioRun 是由 The Guardian 開發的網路應用程式，是絕佳的用例 (但已無法使用)。這款應用程式會帶你進行里約的虛擬語音導覽，沿著 2016 年奧運馬拉松的路線前進。如果沒有喚醒鎖定，導覽播放時使用者的螢幕會頻繁關閉， 導致難以使用。

當然，還有許多其他用途：

• 食譜應用程式，可在你烘烤蛋糕或烹煮晚餐時保持螢幕開啟
• 登機證或票券應用程式，可讓螢幕保持開啟，直到條碼掃描完畢為止
• 持續開啟螢幕的資訊亭式應用程式
• 網頁式簡報應用程式，可在簡報期間保持螢幕開啟

目前狀態

使用 Screen Wake Lock API

Wake Lock 類型

Screen Wake Lock API 目前只提供一種喚醒鎖定：screen。

screen Wake Lock

screen喚醒鎖定功能可防止裝置螢幕關閉，讓使用者查看螢幕上顯示的資訊。

取得螢幕 Wake Lock

如要要求螢幕喚醒鎖定，請呼叫 navigator.wakeLock.request() 方法，該方法會傳回 WakeLockSentinel 物件。您會將所需的喚醒鎖定類型做為參數傳遞至這個方法，目前僅限於 'screen'，因此為選用。 瀏覽器可能會因各種原因拒絕要求 (例如電池電量過低)，因此建議將呼叫包裝在 try…catch 陳述式中。如果失敗，例外狀況的訊息會包含更多詳細資料。

釋放螢幕 Wake Lock

您還需要釋放螢幕喚醒鎖定的方法，只要呼叫 WakeLockSentinel 物件的 release() 方法即可。如果沒有儲存 WakeLockSentinel 的參照，就無法手動釋放鎖定，但目前分頁變成隱藏時，鎖定就會釋放。

如要在經過一段時間後自動釋放螢幕喚醒鎖定，可以使用 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，請監聽 visibilitychange 事件，並在發生事件時要求新的螢幕 Wake Lock：

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

document.addEventListener('visibilitychange', handleVisibilityChange);

盡量減少對系統資源的影響

您是否應在應用程式中使用螢幕喚醒鎖定？採用的方法取決於應用程式的需求。無論如何，您都應盡可能使用最輕量的方法，減少應用程式對系統資源的影響。

在應用程式中加入螢幕喚醒鎖定功能前，請先考量是否能透過下列替代解決方案解決您的使用案例：

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

示範

請參閱 Screen Wake Lock 示範和示範來源。 請注意，切換分頁或應用程式時，螢幕喚醒鎖定會自動解除。

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

你可以使用作業系統的工作管理員，查看是否有應用程式導致電腦無法進入睡眠模式。下方影片顯示 macOS 的「活動監視器」，指出 Chrome 有效的螢幕喚醒鎖定，可讓系統保持喚醒狀態。

意見回饋

Web Platform Incubator Community Group (WICG) 和 Chrome 團隊很想聽聽您對 Screen Wake Lock API 的想法和使用體驗。

介紹 API 設計

API 是否有任何異常狀況？或者，是否缺少實作構想所需的方法或屬性？

• 在 Screen Wake Lock API GitHub 存放區中提報規格問題，或在現有問題中新增您的想法。

回報導入問題

您是否發現 Chrome 實作方式有錯誤？還是實作方式與規格不同？

• 請前往 https://new.crbug.com 回報錯誤。請務必盡可能提供詳細資料、簡單的錯誤重現說明，並將「Components」設為 Blink>WakeLock。

支援 API

您是否打算使用 Screen Wake Lock API？您的公開支持有助於 Chrome 團隊優先處理相關功能，並向其他瀏覽器供應商展現支援這些功能的重要性。

• 在 WICG Discourse 討論串中，分享您打算如何使用 API。
• 使用主題標記 #WakeLock 傳送推文給 @ChromiumDev，告訴我們您在何處使用這項功能，以及使用方式。

實用連結

• 規格候選建議 | 編輯者草案
• 螢幕喚醒鎖定示範 | 螢幕喚醒鎖定示範來源
• 追蹤錯誤
• ChromeStatus.com 項目
• 使用 Wake Lock API 進行實驗
• Blink 元件：Blink>WakeLock

特別銘謝

主頁橫幅，由 Unsplash 的 Kate Stone Matheson 提供。 工作管理員影片由 Henry Lim 提供。