useWakeLock

响应式屏幕唤醒锁 API，防止屏幕变暗或锁定。

useWakeLock 封装了 Screen Wake Lock API，防止应用活动期间设备屏幕变暗或锁定。它返回一个包含 isSupported、isActive（当前是否持有唤醒锁）、request（在页面可见时获取锁，页面隐藏时延迟）、forceRequest（无论可见性如何都获取锁）和 release 的对象。可通过选项提供请求、释放和错误事件的回调。

使用场景

  • 在视频播放、演示或食谱展示期间保持屏幕常亮
  • 在长时间任务（如文件上传或实时监控仪表板）期间防止屏幕锁定
  • 构建必须始终保持显示开启的 Kiosk 模式应用

注意事项

  • SSR 安全：在服务端渲染期间返回 isSupported: false 和 isActive: false 以及空操作函数。服务端不会访问 navigator.wakeLock。
  • 页面可见性：标准的 request 方法会延迟唤醒锁获取直到页面变为可见。需要时使用 forceRequest 绕过此安全检查。
  • 自动释放：当页面变为隐藏（切换标签页、最小化）时，浏览器会自动释放唤醒锁。如果之前处于活动状态，当页面重新变为可见时 hook 会重新获取锁。

Usage

Live Editor
function Demo() {
  const { isSupported, isActive, request, forceRequest, release } = useWakeLock({
    onRequest: () => console.log("唤醒锁已获取"),
    onRelease: () => console.log("唤醒锁已释放"),
    onError: (e) => console.error("唤醒锁错误:", e),
  });

  if (!isSupported) {
    return <div>您的浏览器不支持 Wake Lock API。</div>;
  }

  return (
    <div>
      <div style={{ marginBottom: 16 }}>
        唤醒锁: <b>{isActive ? "已激活" : "未激活"}</b>
      </div>
      <div>
        <button type="button" onClick={request}>
          请求
        </button>
        <button
          type="button"
          onClick={forceRequest}
          style={{ margin: "0 8px" }}
        >
          强制请求
        </button>
        <button type="button" onClick={release}>
          释放
        </button>
      </div>
    </div>
  );
};
Result

API

useWakeLock

Returns

UseWakeLockReturn: 包含以下元素的对象：

  • isSupported：浏览器是否支持 Wake Lock API。
  • isActive：当前是否持有唤醒锁。
  • request：请求唤醒锁（页面可见时立即请求，不可见时延迟到可见时请求）。
  • forceRequest：强制请求唤醒锁，无论页面是否可见。
  • release：释放唤醒锁。

Arguments

参数名描述类型默认值
options可选参数UseWakeLockOptions | undefined-

UseWakeLockOptions

参数名描述类型默认值
onRequest请求成功时的回调() => void-
onRelease释放时的回调() => void-
onError发生错误时的回调(error: Error) => void-

UseWakeLockReturn

参数名描述类型默认值
isSupported浏览器是否支持 Wake Lock APIboolean (必填)-
isActive当前是否持有唤醒锁boolean (必填)-
request请求唤醒锁() => Promise<void> (必填)-
forceRequest强制请求唤醒锁，无论页面是否可见() => Promise<void> (必填)-
release释放唤醒锁() => Promise<void> (必填)-