Skip to main content

Screen Wake Lock API - 提供了防止设备调暗或锁定屏幕的方法

Screen Wake Lock API（屏幕唤醒锁定 API）提供了一种在应用程序需要继续运行时防止设备调暗或锁定屏幕的方法。

概念和用法​

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

Screen Wake Lock API 可防止屏幕关闭、变暗或锁定。它允许一个简单的基于平台的解决方案，到目前为止，这只能通过变通的方式来实现，而变通的方式有可能很耗电。只有可见 (活动) 文档才能获取屏幕唤醒锁定。

保持屏幕打开的用例很多，包括阅读电子书、地图导航、查看菜谱、向观众演示、扫描二维码 / 条形码或使用语音或手势控制等非触觉输入（默认保持屏幕常亮的默认方式）的应用程序。

您通过调用 基于 Promise 的 Navigator.wakeLock.request() 方法来获取 WakeLockSentinel 对象。该方法将在平台允许的情况下进行解析。请求可能会因多种原因被拒绝，包括系统设置（例如省电模式或电池电量低），或文档未激活，或文档不可见。

哨兵对象会附加到底层系统唤醒锁上。如果电池电量太低或文档不活动或不可见，系统可以再次释放它。也可以通过 WakeLockSentinel.Release() 方法手动释放。存储哨兵对象以稍后控制释放，并在需要时重新获取锁是一种很好的做法。

应该使用 Screen Wake Lock API 来保持屏幕打开以提高可用性。 最好在界面上显示一些反馈，以显示唤醒锁定是否处于活动状态，以及用户可以根据需要禁用它的方法。

功能策略集成​

唤屏锁定接口的访问权限由功能策略的 SCREEN-WAKE-LOCK 指令控制。具体使用方法请参考使用 Feature Policy]。

Screen Wake Lock API 接口​

WakeLock​

WakeLock 接口可在应用程序需要继续运行时防止设备屏幕变暗或锁定。

WakeLockSentinel​

提供底层平台唤醒锁的句柄。可以手动释放和重新获取。通过调用 WakeLock.request 可以获取该对象的实例。

返回一个 WakeLock 对象实例，从中可以访问所有其他功能。

实例​

功能检测​

此代码检查唤醒锁支持，并相应地更新 UI。

if ('wakeLock' in navigator) {
  isSupported = true;
  statusElem.textContent = '支持屏幕唤醒锁定 API！';
} else {
  wakeButton.disabled = true;
  statusElem.textContent = '此浏览器不支持唤醒锁定。';
}

请求唤醒锁定​

以下实例演示如何请求 WakeLockSentinel 对象。WakeLock.request 方法基于 Promise，因此我们可以创建一个异步函数，该函数进而更新 UI 以反映唤醒锁处于活动状态。

WakeLock.request 方法是基于 Promise 的，因此我们可以创建一个异步函数，进而更新 UI 以反映唤醒锁处于活动状态。

The WakeLock.request method is Promise-based and so we can create an asynchronous function, which in turn updates the UI to reflect the wake lock is active.

// 创建唤醒锁的引用。
let wakeLock = null;

//创建异步函数以请求唤醒锁定
try {
  wakeLock = await navigator.wakeLock.request('screen');
  statusElem.textContent = '唤醒锁处于激活状态！';
} catch (err) {
  // 唤醒锁定请求失败 - 通常与系统有关，如电池。
  statusElem.textContent = `${err.name}, ${err.message}`;
}

释放唤醒锁定​

以下实例显示如何释放先前获取的唤醒锁。

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

侦听唤醒锁定释放​

如果唤醒锁因任何原因 (如离开活动窗口 / 选项卡) 被释放，此实例将更新 UI。

wakeLock.addEventListener('release', () => {
  // 唤醒锁已被释放
  statusElem.textContent = '唤醒锁已被释放';
});

重新获取唤醒锁​

如果文档的可见性发生变化，并且释放了唤醒锁，下面的代码将重新获取唤醒锁。

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

把它们放在一起​

您可以在 GitHub 上找到完整的代码。该演示使用一个按钮来获取唤醒锁并释放它，从而更新 UI。如果出于任何原因自动释放唤醒锁定，则 UI 也会更新。有一个复选框被选中后，如果文档的可见性状态更改并再次变为可见，它将自动重新获取唤醒锁定。

性能注意事项​

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

功能策略集成​

屏幕唤醒锁定接口的访问权限由功能策略 的 SCREEN-WAKE-LOCK 指令控制。具体使用方法请参考使用功能策略。

规范​

规范
Screen Wake Lock API

桌面浏览器兼容性​

特性ChromeEdgeFirefoxInternet ExplorerOperaSafari
基础支持8484不支持不支持70不支持
request8484不支持不支持70不支持

移动浏览器兼容性​

特性AndroidChrome for AndroidEdge mobileFirefox for AndroidIE mobileOpera AndroidiOS Safari
基础支持8484未知不支持未知60不支持
request8484未知不支持未知60不支持

相关链接​