本頁面由 Cloud Translation API 翻譯而成。

使用 Screen Wake Lock API 保持喚醒

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

Pete LePage

Thomas Steiner

什麼是 Screen Wake Lock API？

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

Screen Wake Lock API 提供一種方法，可防止裝置調低亮度和鎖定螢幕。這項功能可提供先前需要特定平台應用程式的全新體驗。

螢幕 Wake Lock API 可減少使用不當且可能耗電的因應措施。這項 API 解決了舊版 API 的缺點，舊版 API 只能讓螢幕保持開啟，且有許多安全性和隱私權問題。

Screen Wake Lock API 的建議用途

RioRun 是 The Guardian 開發的網頁應用程式，是這類應用程式的完美用途 (但現已停用)。這款應用程式會帶您前往里約，沿著 2016 年奧運馬拉松的路線進行虛擬語音導覽。如果沒有喚醒鎖定，使用者在導覽播放時螢幕會經常關閉，導致導覽功能難以使用。

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

食譜應用程式，可在您烘焙蛋糕或烹飪晚餐時保持螢幕開啟
登機證或票證應用程式，在條碼掃描完成前保持螢幕開啟狀態
可讓螢幕持續開啟的資訊站式應用程式
以網頁為基礎的簡報應用程式，可在簡報期間保持螢幕開啟

目前狀態

步驟	狀態
1. 建立說明	不適用
2. 建立規格初稿	完成
3. 收集意見回饋並重複設計	完成
4. 來源試用	完成
5. 啟動	完成

使用 Screen Wake Lock API

Wake Lock 類型

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

`screen` Wake Lock

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

注意：舊版規格允許額外的 system 喚醒鎖定，可防止裝置的 CPU 進入待機模式，讓應用程式可以繼續執行。我們決定暫時不採用這類型別。

取得螢幕喚醒鎖定

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

釋放螢幕喚醒鎖定

您還需要一種釋放螢幕喚醒鎖定的方法，方法是呼叫 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 起推出。

螢幕喚醒鎖定機制生命週期

當您使用螢幕喚醒鎖定功能示範時，您會發現螢幕喚醒鎖定功能對網頁可見度相當敏感。也就是說，當您將分頁或視窗縮小，或切換至螢幕喚醒鎖定功能已啟用的分頁或視窗時，螢幕喚醒鎖定功能就會自動釋放。

如要重新取得螢幕喚醒鎖定，請在發生 visibilitychange 事件時，聆聽並要求新的螢幕喚醒鎖定：

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

document.addEventListener('visibilitychange', handleVisibilityChange);

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

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

在應用程式中加入螢幕喚醒鎖定功能前，請先考慮是否可使用下列其中一種替代方案解決您的用途：

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

示範

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

作業系統工作管理員中的螢幕 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 回報錯誤。請務必盡可能提供詳細資訊，提供重現錯誤的簡單操作說明，並將「元件」設為 Blink>WakeLock。Glitch 可讓您快速輕鬆地分享重現步驟。

顯示對 API 的支援

您是否打算使用 Screen Wake Lock API？您的公開支持有助於 Chrome 團隊決定功能優先順序，並向其他瀏覽器供應商顯示支援這些功能的重要性。

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

實用連結

特別銘謝

主頁橫幅：Kate Stone Matheson 在 Unsplash 上提供。感謝 Henry Lim 提供的任務管理員影片。