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 保持清醒”