使用 Screen Wake Lock API 保持喚醒

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

Pete LePage

Thomas Steiner

什麼是「螢幕 Wake Lock API」？

為避免電量消耗，大多數裝置在閒置時都會快速進入休眠模式 閒置中。雖然這是最常見的情況，但有些應用程式 以完成工作。例如烹飪應用程式 顯示食譜或遊戲步驟 例如 Ball Puzzle，也就是使用裝置 支援輸入動作 API

Screen Wake Lock API 可用來防止裝置變暗 並鎖定螢幕。這個 功能可提供全新的體驗。這些功能目前已是必須依平台使用的應用程式才能使用。

Screen Wake Lock API 可減少網站遭到入侵的前置作業， 耗電替代方法。解決了舊版 API 的缺點 這些技術會限制螢幕保持開啟 而且新增了多個 安全性和隱私權問題。

Screen Wake Lock API 的建議用途

RioRun 這是由 Guardian 開發的網頁應用程式 是理想用途 (但已無法使用)。 應用程式會根據 2016 年的路線展開裡約虛擬語音導覽 奧運馬拉松 如果沒有 Wake Lock播放遊覽時經常關閉螢幕 也讓網站難以使用

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

• 食譜應用程式可讓你烘焙蛋糕或烹飪時持續開啟螢幕 晚餐
• 可持續顯示螢幕畫面的登機證或票券應用程式 直到掃描條碼為止
• 持續顯示螢幕的資訊站應用程式
• 可持續顯示螢幕畫面的網頁式簡報應用程式 進行簡報時

目前狀態

使用螢幕 Wake Lock API

Wake Lock 類型

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

screen Wake Lock

screen Wake Lock 會讓裝置螢幕無法旋轉 關閉，以便使用者查看畫面上顯示的資訊。

取得螢幕 Wake Lock

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

釋出螢幕 Wake Lock

您還需要另一個方式才能解除螢幕 Wake Lock，方法是呼叫 WakeLockSentinel 物件的 release() 方法。 如果您沒有儲存 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 的屬性， 指出 Sentinel 是否已發行。 其值為初始值為 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 社群群組 (WICG) Chrome 小組想知道 以及使用 Screen Wake Lock API 的心得和經驗。

請與我們分享 API 設計

是否有 API 未正常運作？或 沒有你需要實現創意的方法或屬性嗎？

• 在 Screen Wake Lock API GitHub 存放區中提出規格問題 或為現有問題補充意見

回報導入問題

您發現 Chrome 實作錯誤嗎？另一種是實作 該怎麼辦？

• 前往 https://new.crbug.com 回報錯誤。請務必盡量附上 請盡可能詳細說明，提供重現錯誤的簡單操作說明，以及 將「元件」設為 Blink>WakeLock。Glitch 的表現非常好 以便快速輕鬆地提出重現問題

顯示對 API 的支援

你打算使用 Screen Wake Lock API 嗎？你的公開支援讓 Chrome 團隊會優先開發功能，並向其他瀏覽器廠商說明這些功能 對他們來說至關重要

• 歡迎前往 WICG Discourse 討論串，說明您打算如何使用這個 API。
• 使用主題標記將推文傳送至 @ChromiumDev #WakeLock敬上 ，並說明你使用這項服務的位置和方式。

實用連結

• 規格建議人選 |編輯者草稿
• 螢幕 Wake Lock 示範 |「螢幕 Wake Lock」示範來源
• 追蹤錯誤
• ChromeStatus.com 項目
• 試用 Wake Lock API
• 閃爍元件：Blink>WakeLock

特別銘謝

主頁橫幅製作者： 《Kate Stone Matheson》在 Unsplash 上。 工作管理員視訊來源： Henry Lim。