使用 Screen Wake Lock API 不锁定屏幕

Screen Wake Lock 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 用例

RioRun 是由 The Guardian 开发的 Web 应用，是绝佳的用例（但已不再可用）。该应用会带您沿着 2016 年奥运会马拉松赛的路线，进行一场虚拟的音频里约之旅。如果没有唤醒锁定，用户的屏幕会在导览播放期间频繁关闭，导致导览难以使用。

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

  • 一款食谱应用，可在您烤蛋糕或做晚餐时让屏幕保持开启状态
  • 让屏幕保持开启状态直到条形码被扫描的登机牌或票券应用
  • 一种可让屏幕持续开启的 kiosk 式应用
  • 一款基于网络的演示文稿应用，可在演示期间让屏幕保持开启状态

当前状态

步骤 状态
1. 创建铺垫消息 不适用
2. 创建规范的初始草稿 完成
3. 收集反馈并迭代设计 完成
4. 来源试用 完成
5. 启动 完成

使用 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 的属性，用于指示是否已释放哨兵。其值最初为 false，在分派 "release" 事件后会更改为 true。此属性可帮助 Web 开发者了解锁定何时已释放，以免他们手动跟踪此信息。Chrome 87 及更高版本均提供此功能。

屏幕唤醒锁定生命周期

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

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

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

document.addEventListener('visibilitychange', handleVisibilityChange);

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

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

在向应用添加屏幕唤醒锁定之前，请考虑是否可以使用以下替代解决方案来解决您的用例：

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

演示

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

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

您可以使用操作系统的任务管理器查看是否有应用阻止计算机进入休眠状态。以下视频显示了 macOS Activity Monitor，其中显示 Chrome 有一个处于活动状态的屏幕唤醒锁，可让系统保持唤醒状态。

反馈

Web 平台孵化器社区组 (WICG) 和 Chrome 团队希望了解您对 Screen Wake Lock API 的看法和使用体验。

请向我们说明 API 设计

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

报告实现方面的问题

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

  • 请访问 https://new.crbug.com 提交 bug。请务必提供尽可能详细的信息，提供重现 bug 的简单说明，并将组件设置为 Blink>WakeLock。故障非常适合分享快速轻松的重现步骤。

表示对 API 的支持

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

实用链接

致谢

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