使用 Screen Wake Lock API 不锁定屏幕

当应用需要持续运行时，屏幕唤醒锁定 API 可防止设备屏幕变暗或锁定。

Pete LePage

Thomas Steiner

什么是 Screen Wake Lock API？

为避免消耗电池电量，大多数设备在处于空闲状态时会快速进入休眠模式。虽然大多数情况下这样做都没什么问题，但有些应用需要保持屏幕唤醒状态才能完成工作。例如，显示食谱步骤的烹饪应用，或者使用设备运动 API 进行输入的 Ball Puzzle 等游戏。

Screen Wake Lock API 提供了一种防止设备屏幕变暗和锁定的方法。借助此功能，您可以打造新的体验，而在此之前，这些体验需要使用特定于平台的应用。

Screen Wake Lock API 可减少对可能耗电的权宜之计的需求。它解决了旧版 API 的缺点，旧版 API 仅限于保持屏幕开启，并且存在许多安全和隐私问题。

Screen Wake Lock API 的建议用例

由 The Guardian 开发的 Web 应用 RioRun 就是一个完美的用例（不过该应用已不再提供）。这款应用会带您进行里约热内卢的虚拟音频导览，沿着 2016 年奥运会马拉松的路线游览。 如果没有唤醒锁定，用户在导览播放期间屏幕会频繁关闭，导致难以使用。

当然，还有许多其他用例：

• 一款可在您烘焙蛋糕或烹饪晚餐时保持屏幕常亮的食谱应用
• 一种登机牌或票券应用，可使屏幕保持开启状态，直到条形码被扫描
• 可让屏幕持续保持开启状态的信息亭式应用
• 一款基于网络的演示应用，可在演示期间保持屏幕开启状态

当前状态

使用 Screen Wake Lock API

唤醒锁定类型

Screen Wake Lock API 目前仅提供一种唤醒锁定类型：screen。

screen 唤醒锁定

screen唤醒锁定可防止设备屏幕关闭，以便用户查看屏幕上显示的信息。

获取屏幕唤醒锁定

如需请求屏幕唤醒锁定，您需要调用返回 WakeLockSentinel 对象的 navigator.wakeLock.request() 方法。您需要将所需的唤醒锁定类型作为参数传递给此方法，目前仅限于 'screen'，因此是可选的。浏览器可能会因各种原因（例如，电池电量过低）拒绝该请求，因此最好将该调用封装在 try…catch 语句中。如果失败，异常的消息将包含更多详细信息。

释放屏幕唤醒锁定

您还需要一种释放屏幕唤醒锁的方法，这可以通过调用 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 的属性，用于指示是否已发布 Sentinel。 其值最初为 false，并在调度 "release" 事件后更改为 true。此属性可帮助 Web 开发者了解锁何时已释放，这样他们就不需要手动跟踪此信息。 自 Chrome 87 起提供。

屏幕唤醒锁定的生命周期

当您使用屏幕唤醒锁定演示时，您会注意到屏幕唤醒锁定对页面可见性很敏感。这意味着，当您最小化标签页或窗口，或者切换到未启用屏幕唤醒锁定的标签页或窗口时，系统会自动释放屏幕唤醒锁定。

如需重新获取屏幕唤醒锁定，请监听 visibilitychange 事件，并在发生该事件时请求新的屏幕唤醒锁定：

const handleVisibilityChange = async () => {
  if (wakeLock !== null && document.visibilityState === 'visible') {
    await requestWakeLock();
  }
};

document.addEventListener('visibilitychange', handleVisibilityChange);

最大限度减少对系统资源的影响

您是否应在应用中使用屏幕唤醒锁定？ 所采用的方法取决于应用的需求。无论如何，您都应该为应用使用尽可能轻量的方法，以便最大限度减少应用对系统资源的影响。

在为应用添加屏幕唤醒锁定之前，请考虑您的使用情形是否可以通过以下某种替代解决方案来解决：

• 如果您的应用执行长时间运行的下载，请考虑使用后台提取。
• 如果您的应用同步来自外部服务器的数据，请考虑使用后台同步。

演示

查看屏幕唤醒锁定演示和演示源代码。 请注意，当您切换标签页或应用时，屏幕唤醒锁定会自动释放。

操作系统任务管理器中的屏幕唤醒锁定

您可以使用操作系统的任务管理器来查看是否有应用阻止计算机进入睡眠状态。以下视频显示了 macOS Activity Monitor，其中指示 Chrome 具有可使系统保持唤醒状态的有效屏幕唤醒锁定。

反馈

Web Platform Incubator Community Group (WICG) 和 Chrome 团队希望了解您对 Screen Wake Lock API 的想法和使用体验。

介绍 API 设计

API 是否存在未按预期运行的情况？或者，是否缺少您需要实现想法的方法或属性？

• 在 Screen Wake Lock API GitHub 代码库中提交规范问题，或在现有问题中添加您的想法。

报告实现方面的问题

您是否发现 Chrome 的实现存在 bug？还是实现与规范不同？

• 请访问 https://new.crbug.com 提交 bug。请务必尽可能详细地说明问题，提供重现 bug 的简单说明，并将组件设置为 Blink>WakeLock。

显示对 API 的支持

您是否打算使用 Screen Wake Lock API？您的公开支持有助于 Chrome 团队确定功能的优先级，并向其他浏览器供应商展示支持这些功能的重要性。

• 在 WICG Discourse 帖子中分享您计划如何使用该 API。
• 发送一条推文给 @ChromiumDev，使用 ##WakeLock 主题标签，告诉我们您在何处以及如何使用它。

实用链接

• 规范 候选建议 | 编辑草稿
• Screen Wake Lock 演示 | Screen Wake Lock 演示源代码
• 跟踪 bug
• ChromeStatus.com 条目
• 试用 Wake Lock API
• Blink 组件：Blink>WakeLock

致谢

主打图片，由 Kate Stone Matheson 在 Unsplash 上提供。 任务管理器视频由 Henry Lim 提供。