Screen Wake Lock API

概念與用法

大多數裝置預設會在指定時間後關閉螢幕以延長硬體壽命。現代裝置這樣做是為了節省電池電量。雖然這是一個有用的功能，但某些應用程式需要螢幕保持喚醒狀態才能最有效地執行。

螢幕喚醒鎖 API 可防止螢幕關閉、變暗或鎖定。它為可見（活動）文件提供了基於平臺的簡單解決方案，用於獲取平臺螢幕喚醒鎖。

保持螢幕常亮有許多用例，包括閱讀電子書、地圖導航、遵循食譜、向觀眾演示、掃描 QR/條形碼或使用語音或手勢控制（而不是觸控輸入，這是保持螢幕常亮的預設方式）的應用程式。

您可以透過呼叫 navigator.wakeLock.request() 這個基於 Promise 的方法來獲取一個 WakeLockSentinel 物件，如果平臺允許，該方法將解析。請求可能會因多種原因而被拒絕，包括系統設定（例如省電模式或電池電量低）或文件不活動或不可見。最好儲存對 sentinel 物件的引用，以便應用程式以後可以控制釋放。

sentinel 附加到底層系統喚醒鎖。它可以被系統釋放，例如當電池電量過低或文件不活動或不可見時。它也可以透過 WakeLockSentinel.release() 方法手動釋放。釋放後，WakeLockSentinel 將不再可用。如果需要螢幕喚醒鎖，應用程式將需要請求一個新的。

螢幕喚醒鎖 API 應透過改善可用性來保持螢幕常亮。最好在介面上顯示一些反饋，以表明喚醒鎖是否處於活動狀態，併為使用者提供一個停用它的選項。

介面

WakeLock

在應用程式需要執行時，防止裝置螢幕變暗或鎖定。

WakeLockSentinel

提供底層平臺喚醒鎖的控制代碼，如果被引用，可以手動釋放和重新獲取。透過呼叫 WakeLock.request 來獲取該物件的一個例項。

其他介面的擴充套件

Navigator.wakeLock 只讀

返回一個 WakeLock 物件例項，您可以透過它訪問所有其他功能。

Permissions-Policy: screen-wake-lock

對該 API 的訪問受 Permissions-Policy 指令 screen-wake-lock 的控制。請參閱下面的 安全注意事項。

示例

特性檢測

此程式碼檢查喚醒鎖支援並相應更新 UI。

if ("wakeLock" in navigator) {
  isSupported = true;
  statusElem.textContent = "Screen Wake Lock API supported!";
} else {
  wakeButton.disabled = true;
  statusElem.textContent = "Wake lock is not supported by this browser.";
}

請求喚醒鎖

以下示例演示瞭如何請求一個 WakeLockSentinel 物件。 WakeLock.request 方法基於 Promise，因此我們可以建立一個非同步函式，該函式進而更新 UI 以反映喚醒鎖已啟用。

// Create a reference for the Wake Lock.
let wakeLock = null;

// create an async function to request a wake lock
try {
  wakeLock = await navigator.wakeLock.request("screen");
  statusElem.textContent = "Wake Lock is active!";
} catch (err) {
  // The Wake Lock request has failed - usually system related, such as battery.
  statusElem.textContent = `${err.name}, ${err.message}`;
}

釋放喚醒鎖

以下示例展示瞭如何釋放先前獲取的喚醒鎖。

wakeLock.release().then(() => {
  wakeLock = null;
});

監聽喚醒鎖釋放

此示例在喚醒鎖因任何原因被釋放時更新 UI（例如，導航離開活動視窗/標籤頁）。

wakeLock.addEventListener("release", () => {
  // the wake lock has been released
  statusElem.textContent = "Wake Lock has been released";
});

重新獲取喚醒鎖

如果文件的可見性發生變化並且喚醒鎖被釋放，以下程式碼將重新獲取喚醒鎖。

document.addEventListener("visibilitychange", async () => {
  if (wakeLock !== null && document.visibilityState === "visible") {
    wakeLock = await navigator.wakeLock.request("screen");
  }
});

整合起來

您可以在 GitHub 上找到完整程式碼。 演示使用一個按鈕來獲取和釋放喚醒鎖，並相應地更新 UI。如果喚醒鎖因任何原因被自動釋放，UI 也會更新。有一個複選框，當被選中時，如果文件的可見性狀態發生變化並再次變得可見，它將自動重新獲取喚醒鎖。

效能注意事項

• 當用戶結束需要螢幕常亮的活動時，釋放螢幕喚醒鎖。例如，一個使用 QR 碼傳輸門票資訊的門票應用程式，在顯示 QR 碼時（以便成功掃描程式碼）可能會獲取螢幕喚醒鎖，但之後會釋放它。演示應用程式可能只在演示處於活動狀態時持有鎖，而在編輯演示時不持有。
• 如果您的應用程式正在執行長時間下載，請考慮使用後臺獲取。
• 如果您的應用程式正在從遠端伺服器同步資料，請考慮使用後臺同步。
• 只有活動文件才能獲取螢幕喚醒鎖，並且在文件變為非活動狀態時，先前獲取的鎖會自動釋放。因此，當文件變為活動狀態時（監聽 visibilitychange 事件），請務必在必要時重新獲取螢幕喚醒鎖。

安全注意事項

螢幕喚醒鎖 API 的訪問受 許可權策略指令 screen-wake-lock 控制。

使用 許可權策略時，screen-wake-lock 的預設允許列表是 self。這允許在同源巢狀框架中使用喚醒鎖，但阻止第三方內容使用喚醒鎖。透過伺服器首先設定 Permissions-Policy 標頭授予特定第三方來源許可權，可以啟用第三方使用。

Permissions-Policy: screen-wake-lock=(self b.example.com)

然後必須將 allow="screen-wake-lock" 屬性新增到該來源的 frame 容器元素。

<iframe src="https://b.example.com" allow="screen-wake-lock"></iframe>

瀏覽器也可能因為特定實現原因（例如使用者或平臺設定）而阻止在特定文件中鎖定螢幕。它們應該提供一些不顯眼的機制來告知使用者喚醒鎖何時處於活動狀態，併為使用者提供刪除應用程式螢幕鎖的能力。

可以使用 許可權 API 的 screen-wake-lock 許可權來測試螢幕鎖的使用許可權是 granted、denied 還是 prompt（需要使用者確認提示）。

規範

瀏覽器相容性

api.WakeLock

api.WakeLockSentinel

另見

• developer.chrome.com 上的“使用螢幕喚醒鎖 API 保持清醒”