屏幕唤醒锁 API

大多数设备默认情况下会在指定时间后关闭屏幕，以延长硬件的寿命。现代设备这样做是为了节省电池电量。虽然这是一个有用的功能，但一些应用程序需要屏幕保持唤醒状态才能发挥其最大作用。

屏幕唤醒锁 API 阻止屏幕关闭、变暗或锁定。它允许对可见（活动）文档获取平台屏幕唤醒锁，从而提供简单的平台级解决方案。

有很多用例需要保持屏幕亮着，包括阅读电子书、地图导航、查看食谱、向观众展示、扫描二维码/条形码，以及使用语音或手势控制而不是触控输入的应用程序（默认保持屏幕亮着的方式）。

您可以通过调用WakeLockSentinel 对象来获取一个navigator.wakeLock.request() Promise -based 方法，如果平台允许，该方法会解析。请求可能会因多种原因被拒绝，包括系统设置（例如省电模式或电池电量不足）或文档未处于活动状态或可见状态。良好的做法是存储对哨兵对象的引用，以便应用程序以后可以控制释放。

哨兵附加到底层系统唤醒锁。如果电池电量过低或文档未处于活动状态或可见状态，它可能会被系统释放。它也可以通过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 -based 的，因此我们可以创建一个异步函数，该函数反过来更新 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 也会更新。有一个复选框，当选中时，如果文档的可见性状态发生更改并再次变为可见，它将自动重新获取唤醒锁。

• 当用户结束需要始终开启屏幕的活动时，释放屏幕唤醒锁。例如，一个使用二维码传输票务信息的购票应用程序，可以在显示二维码时获取屏幕唤醒锁（以便成功扫描二维码），但之后释放。一个演示应用程序可能只在演示处于活动状态时保持锁住，而在编辑演示时不会保持锁住。
• 如果您的应用程序正在执行长时间运行的下载，请考虑使用后台获取。
• 如果您的应用程序正在从远程服务器同步数据，请考虑使用后台同步。
• 只有活动文档才能获取屏幕唤醒锁，以前获取的锁会在文档变为非活动状态时自动释放。因此，请确保在文档变为活动状态时重新获取屏幕唤醒锁（监听visibilitychange 事件）。

对屏幕唤醒锁 API 的访问受权限策略 指令screen-wake-lock 的控制。

使用权限策略 时，screen-wake-lock 的默认允许列表为 self。这允许在同源嵌套框架中使用唤醒锁，但阻止第三方内容使用锁。服务器可以通过首先设置 Permissions-Policy 标头来授予特定第三方来源的权限，从而启用第三方使用。

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

然后必须将 allow="screen-wake-lock" 属性添加到来自该来源的框架容器元素中

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

浏览器也可能出于特定于实现的原因阻止特定文档中的屏幕锁，例如用户或平台设置。他们应该提供一些不显眼的机制来通知用户何时唤醒锁处于活动状态，并为用户提供删除应用程序的屏幕锁的能力。

权限 API screen-wake-lock 权限可用于测试对使用屏幕锁的访问权限是 granted、denied 还是 prompt（需要用户确认提示）。

• 使用屏幕唤醒锁 API 保持唤醒状态
• Glitch 上的屏幕唤醒锁 API 演示