MDN Web API 教程：深入理解 Screen Wake Lock API

什么是 Screen Wake Lock API

Screen Wake Lock API 是现代浏览器提供的一套 Web API，它允许网页应用在需要持续运行时阻止设备屏幕自动变暗或锁定。这个 API 特别适用于那些需要用户长时间与屏幕交互的应用场景。

核心概念与应用场景

为什么需要屏幕唤醒锁

现代设备为了节省电量和延长硬件寿命，通常会在无操作一段时间后自动关闭或调暗屏幕。然而，某些应用场景下：

• 电子书阅读应用需要保持屏幕常亮
• 导航应用在驾驶过程中需要持续显示路线
• 烹饪应用在跟随食谱时需要屏幕保持开启
• 演示文稿展示时需要防止屏幕关闭
• 使用语音或手势控制而非触摸操作的应用

在这些情况下，Screen Wake Lock API 就能派上用场。

工作原理

该 API 通过 navigator.wakeLock.request() 方法返回一个 WakeLockSentinel 对象，这个对象代表系统级别的唤醒锁。当获得这个锁后，屏幕将保持亮起状态，直到：

1. 应用主动释放锁
2. 文档变为非活动或不可见状态
3. 设备电量过低
4. 用户手动锁定设备

API 接口详解

主要接口

1. WakeLock 接口

   • 提供请求屏幕唤醒锁的能力
   • 通过 navigator.wakeLock 访问

2. WakeLockSentinel 接口

   • 表示一个具体的唤醒锁实例
   • 提供 release() 方法手动释放锁
   • 可以监听 release 事件

扩展接口

• Navigator.wakeLock 只读属性
  • 返回 WakeLock 对象实例
  • 是所有功能的主要入口点

实战示例

基础使用流程

// 1. 检查浏览器支持
if ("wakeLock" in navigator) {
  console.log("Screen Wake Lock API 支持");
} else {
  console.log("当前浏览器不支持此API");
}

// 2. 请求唤醒锁
let wakeLock = null;

async function requestWakeLock() {
  try {
    wakeLock = await navigator.wakeLock.request("screen");
    console.log("唤醒锁已激活");
    
    // 3. 监听锁释放
    wakeLock.addEventListener("release", () => {
      console.log("唤醒锁已被释放");
    });
  } catch (err) {
    console.error(`获取唤醒锁失败: ${err.message}`);
  }
}

// 4. 释放唤醒锁
function releaseWakeLock() {
  if (wakeLock) {
    wakeLock.release();
    wakeLock = null;
  }
}

处理页面可见性变化

当用户切换标签页或最小化浏览器时，唤醒锁会自动释放。我们可以监听页面可见性变化，在页面重新可见时重新获取锁：

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

最佳实践与注意事项

性能优化建议

1. 及时释放：在不再需要时立即释放唤醒锁，比如当用户完成阅读或导航到达目的地后。

2. 合理使用：避免长时间持有唤醒锁，考虑使用后台任务替代方案：

   • 长时间下载：使用 Background Fetch API
   • 数据同步：使用 Background Sync API

3. 用户体验：

   • 在UI上明确显示当前唤醒锁状态
   • 提供用户手动关闭唤醒锁的选项

安全考虑

1. 权限策略：

   • 默认情况下，只有同源页面可以使用此API
   • 如需在iframe中使用，需要设置 Permissions-Policy 头部和 allow 属性

2. 浏览器限制：

   • 浏览器可能因用户设置或平台限制阻止唤醒锁
   • 浏览器应提供可视化提示表明唤醒锁处于活动状态

兼容性与规范

Screen Wake Lock API 目前处于标准化过程中，各浏览器厂商正在逐步实现。开发者在使用前应：

1. 检查浏览器兼容性
2. 提供优雅降级方案
3. 考虑使用特性检测

总结

Screen Wake Lock API 为Web应用提供了控制设备屏幕状态的能力，极大提升了特定场景下的用户体验。开发者应当合理使用这一API，遵循最佳实践，在提供便利功能的同时兼顾设备性能和电量消耗。

通过本文的介绍，你应该已经掌握了Screen Wake Lock API的核心概念、使用方法和注意事项，可以在你的Web应用中合理实现屏幕保持亮起的功能了。