使用 Screen Wake Lock API 保持喚醒

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

什麼是「螢幕 Wake Lock API」?

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

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

使用 Screen Wake Lock API 時,就不必針對駭客或可能造成供電問題迅速解決的情況。這項 API 解決了舊版 API 的缺點,舊版 API 僅能讓螢幕保持開啟,且有許多安全性和隱私權問題。

Screen Wake Lock API 的建議用途

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

當然,還有許多其他用途:

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

目前狀態

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

使用 Screen Wake Lock API

Wake Lock 類型

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

screen Wake Lock

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

取得螢幕喚醒鎖定

如要要求螢幕喚醒鎖定,您必須呼叫會傳回 WakeLockSentinel 物件的 navigator.wakeLock.request() 方法。您可以將所需的喚醒鎖定類型做為參數傳遞至此方法,但目前僅限於 '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 生命週期

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

如要重新取得螢幕喚醒鎖定,請在發生 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 社群群組 (WICG) 和 Chrome 團隊想聽聽您對 Screen Wake Lock API 的想法和使用經驗。

請說明 API 設計

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

回報實作問題

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

  • 請前往 https://new.crbug.com 回報錯誤。請務必盡可能提供詳細資訊,提供重現錯誤的簡單操作說明,並將「元件」設為 Blink>WakeLockGlitch 非常適合讓您快速輕鬆地提出重新提案。

顯示對 API 的支援

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

實用連結

特別銘謝

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