使用 Screen Wake Lock API 保持喚醒

Pete LePage

Thomas Steiner

發布日期：2018 年 12 月 18 日

Browser Support

Source

什麼是 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

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。這個屬性可協助網頁開發人員瞭解鎖定何時已釋出，不必手動追蹤。

螢幕 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);

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

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

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

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

示範

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

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

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

意見回饋

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

回報錯誤。並盡可能提供完整細節。提供明確的錯誤重現步驟，並將「Components」(元件) 設為 Blink>WakeLock。

資源

特別銘謝

工作管理員影片由 Henry Lim 提供。