使用 Wake Lock API：保持裝置喚醒的最佳實踐

_zhiqiu發表於2024-09-18
API

在現代 Web 應用中，尤其是涉及影片播放、實時通訊、地圖導航等長時間執行的任務時，使用者常常希望裝置不要因為空閒而自動進入睡眠模式或螢幕變暗。為了解決這一問題，Web API 提供了一個名為 Wake Lock 的介面，允許開發者請求裝置保持喚醒狀態。

本文將詳細介紹如何使用 Wake Lock API 來控制裝置的喚醒狀態，提供示例程式碼，並討論一些常見的使用場景，尤其是如何確保網頁隱藏或顯示時自動管理喚醒鎖。

什麼是 Wake Lock API？

Wake Lock API 是一個用於防止裝置進入睡眠或螢幕變暗的 Web API。透過 Wake Lock API，開發者可以請求裝置保持活躍狀態，防止因為電源管理機制導致任務中斷。

目前，Wake Lock API 只支援一種型別的喚醒鎖：screen，它用於保持螢幕亮起，防止螢幕自動關閉或調暗。

使用 Wake Lock API 的前提

  • 瀏覽器支援：Wake Lock API 目前在大多數現代瀏覽器中都已經得到支援。
  • HTTPS 環境：該 API 需要透過 HTTPS 訪問才能正常工作。

基本用例

以下是一個簡單的示例，展示瞭如何使用 Wake Lock API 來保持螢幕喚醒：

// 建立一個全域性變數來儲存 WakeLock 例項
let wakeLock = null;

// 請求螢幕保持喚醒的函式
async function requestWakeLock() {
  try {
    // 請求螢幕喚醒鎖
    wakeLock = await navigator.wakeLock.request('screen');
    console.log('螢幕喚醒鎖已啟用');
    
    // 監聽喚醒鎖的釋放事件
    wakeLock.addEventListener('release', () => {
      console.log('螢幕喚醒鎖已釋放');
    });
  } catch (err) {
    console.error(`${err.name}, ${err.message}`);
  }
}

// 釋放喚醒鎖的函式
function releaseWakeLock() {
  if (wakeLock !== null) {
    wakeLock.release();
    wakeLock = null;
    console.log('螢幕喚醒鎖手動釋放');
  }
}

// 呼叫函式請求喚醒鎖
requestWakeLock();

// 在頁面關閉時釋放喚醒鎖
window.addEventListener('beforeunload', releaseWakeLock);

頁面可見性處理：自動管理喚醒鎖

由於當網頁被隱藏或切換到後臺時會自動釋放喚醒鎖，因此我們可以監聽 visibilitychange 事件來確保網頁重新可見時重新獲取喚醒鎖。當頁面恢復顯示時再次請求鎖定，頁面隱藏時則釋放喚醒鎖。

// 建立一個全域性變數來儲存 WakeLock 例項
let wakeLock = null;

// 請求螢幕保持喚醒的函式
async function requestWakeLock() {
  try {
    // 請求螢幕喚醒鎖
    wakeLock = await navigator.wakeLock.request('screen');
    console.log('螢幕喚醒鎖已啟用');
    
    // 監聽喚醒鎖的釋放事件
    wakeLock.addEventListener('release', () => {
      console.log('螢幕喚醒鎖已釋放');
    });
  } catch (err) {
    console.error(`${err.name}, ${err.message}`);
  }
}

// 釋放喚醒鎖的函式
function releaseWakeLock() {
  if (wakeLock !== null) {
    wakeLock.release();
    wakeLock = null;
    console.log('螢幕喚醒鎖手動釋放');
  }
}

// 處理頁面可見性變化
function handleVisibilityChange() {
  if (document.visibilityState === 'visible') {
    // 頁面重新可見時，重新請求喚醒鎖
    requestWakeLock();
  } else {
    // 頁面隱藏時，釋放喚醒鎖
    releaseWakeLock();
  }
}

// 監聽頁面可見性變化事件
document.addEventListener('visibilitychange', handleVisibilityChange);

// 頁面載入時立即請求喚醒鎖
requestWakeLock();

// 在頁面關閉時釋放喚醒鎖
window.addEventListener('beforeunload', releaseWakeLock);

使用場景

Wake Lock API 在以下幾種典型場景中非常有用：

1. 影片或音訊播放

在播放影片或音訊的應用中，使用者希望螢幕保持亮起，以便可以隨時調整播放進度或音量。透過 Wake Lock API，在媒體播放時保持螢幕喚醒，提供更好的使用者體驗。

videoElement.addEventListener('play', requestWakeLock);
videoElement.addEventListener('pause', releaseWakeLock);

2. 實時通訊應用

對於視訊通話、會議等實時通訊應用，螢幕關閉會影響使用者的互動體驗。使用 Wake Lock API，可以確保裝置在通話期間保持活躍，防止通話中斷。

if (isInCall) {
  requestWakeLock();
} else {
  releaseWakeLock();
}

3. 導航和地圖應用

在導航應用中，使用者通常需要長時間檢視螢幕來獲取行進路線資訊。使用 Wake Lock API，可以確保螢幕不會因為閒置而熄滅。

navigator.geolocation.watchPosition(() => {
  requestWakeLock();
}, () => {
  releaseWakeLock();
});

4. 遊戲或全屏應用

網頁遊戲或需要長時間使用者互動的全屏應用，也可以利用 Wake Lock API，避免遊戲過程中螢幕突然熄滅。

document.addEventListener('fullscreenchange', () => {
  if (document.fullscreenElement) {
    requestWakeLock();
  } else {
    releaseWakeLock();
  }
});

錯誤處理和相容性

雖然 Wake Lock API 提供了有用的功能，但它在某些裝置上可能受到電源管理策略的限制。因此，開發者在請求喚醒鎖時應當加入錯誤處理，以確保程式的健壯性。

if ('wakeLock' in navigator) {
  requestWakeLock();
} else {
  console.error('當前瀏覽器不支援 Wake Lock API');
}

瀏覽器相容性

- Chrome Edge Firefox Opera Safari Chrome Android Firefox Android Opera Android Safari iOS Samsung Internet WebView Android
WakeLock 84 84 126 70 16.4 84 126 60 16.4 14.0 84
request 84 84 126 70 16.4 84 126 60 16.4 14.0 84

iOS 版 Safari

  • 16.4 (Released 2023-03-27)
  • 部分支援
  • 在獨立的主螢幕Web應用程式不生效。詳情請看 bug 254545.

總結

Wake Lock API 為 Web 開發者提供了控制裝置喚醒狀態的能力，尤其適合那些需要保持螢幕長時間活躍的應用，如影片播放、實時通訊、導航等。透過監聽 visibilitychange 事件，應用程式可以智慧地管理喚醒鎖的狀態，在頁面可見時重新獲取鎖定，隱藏時釋放鎖定。

隨著更多瀏覽器對 Wake Lock API 的支援，它將會成為提升使用者體驗的重要工具。如果你的應用涉及到長時間的任務或需要保持螢幕亮起，建議整合這個 API 來最佳化使用者體驗。

相關文章