使用 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 Wake Lock 會防止裝置螢幕關閉，以便使用者查看畫面上顯示的資訊。

取得螢幕 Wake Lock

如要要求螢幕喚醒鎖定，您必須呼叫會傳回 WakeLockSentinel 物件的 navigator.wakeLock.request() 方法。您可以將所需的 Wake Lock 類型做為參數傳遞，該參數「目前」僅限於 '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 就會自動釋放。

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

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

document.addEventListener('visibilitychange', handleVisibilityChange);

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

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

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

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

示範

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

作業系統工作管理員中的螢幕 Wake Lock

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

意見回饋

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

請說明 API 設計

API 是否有任何功能無法正常運作？或者，您是否缺少實作想法所需的方法或屬性？

回報導入問題

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

  • 請前往 https://new.crbug.com 回報錯誤。請務必盡可能提供詳細資訊，提供重現錯誤的簡單操作說明，並將「元件」設為 Blink>WakeLock。Glitch 可讓您快速輕鬆地分享重現內容。

顯示 API 支援

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

實用連結

特別銘謝

主頁橫幅：Kate Stone Matheson 在 Unsplash 上提供。這部工作管理員影片由 Henry Lim 提供。