屏幕唤醒锁 API

W3C 工作草案

关于本文档的更多详细信息
此版本：
https://www.w3.org/TR/2026/WD-screen-wake-lock-20260929/
最新发布版本：
https://www.w3.org/TR/screen-wake-lock/
最新编辑草案：
https://w3c.github.io/screen-wake-lock/
历史记录：
https://www.w3.org/standards/history/screen-wake-lock/
提交历史
测试套件：
https://wpt.live/screen-wake-lock/
实现报告：
https://www.w3.org/wiki/DAS/Implementations
编辑：
Kenneth Rohde Christiansen (英特尔公司)
Marcos Cáceres (苹果公司)
前编辑：
Raphael Kubo da Costa (英特尔 公司)
(Yandex)
(Yandex)
反馈：
GitHub w3c/screen-wake-lock (拉取请求, 新建议题, 开放议题)
质量保证负责人
Wanming Lin（英特尔）

Copyright © 2026 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.

摘要

本文档规定了一种允许 Web 应用请求 屏幕唤醒锁的 API。在适当的条件下，并且在获得允许的情况下， 屏幕唤醒锁可防止系统关闭设备的 屏幕。

本文档的状态

本节描述本文档 发布时的状态。当前 W3C 出版物列表以及本技术报告的最新修订版可在 以下 W3C 标准和草案 索引中找到。

实现者需要注意，本规范目前极其 不稳定。未参与 讨论的实现者会发现，本规范会在他们不知情的情况下以 不兼容的方式发生变化。 有意在本规范最终进入候选推荐标准 阶段之前实现本规范的供应商应订阅 GitHub 上的 仓库并参与讨论。

本文档由设备与传感器工作 组和Web 应用工作组作为 工作草案发布，并采用 推荐标准 流程。

作为 工作草案发布并不意味着获得 W3C 及其成员的认可。

本文档是一份草案，可能随时被其他 文档更新、取代或废弃。除将其视为 进行中的工作外，不宜引用本文档。

本文档由相关工作组制定，这些工作组 按照 W3C 专利 政策开展工作。 W3C 维护着 所有专利披露的公开列表 （设备与传感器工作组）以及 所有专利披露的公开列表 （Web 应用工作组）， 这些披露与 各工作组的交付成果有关；这些页面还包含 披露专利的说明。实际 知晓某项专利，并认为该专利包含 必要权利要求 的个人，必须按照 W3C 专利政策第 6 节披露相关信息。

本文档受 2025 年 8 月 18 日 W3C 流程文档约束。

1. 引言

本节是非规范性的。

现代操作系统通过实施积极的电源管理来延长电池续航时间， 这意味着，在用户停止活动后不久， 宿主设备就可能降低屏幕亮度、关闭 屏幕，甚至让 CPU 进入深度节能状态， 从而尽可能降低功耗。

虽然这有利于延长电池续航时间，但有时也会妨碍 某些使用场景，例如扫描条形码、阅读电子书、按照 食谱烹饪、向观众进行演示等。另请参阅 唤醒锁：使用场景。

唤醒锁通常会阻止某些事情发生，但用户代理 （以及底层操作系统）可能根据电池 状态（已连接外部电源、正在放电、电量低）限制唤醒锁的持续时间，甚至 在启用节能模式时不允许使用唤醒锁。

2. 唤醒锁

本规范定义了以下 唤醒锁 类型：

  1. 屏幕唤醒锁 可防止屏幕 关闭。只有可见文档才能获取屏幕唤醒 锁。

在此 API 中，唤醒锁类型 由 WakeLockType 枚举值表示。

注

其他规范可能定义不同的唤醒锁类型。

3. 策略控制

屏幕唤醒锁 API 定义了一个 由策略控制的功能， 由字符串 "screen-wake-lock" 标识。其 默认允许列表 为 'self'。

注

4. 权限和用户提示

[PERMISSIONS] API 为网站提供了一种统一的方式，用于向用户请求 权限并查询其已拥有的权限。

用户 代理 可以 拒绝唤醒锁， 该锁属于 特定的 唤醒锁类型，且面向特定的 Document；拒绝理由可以是任何 特定于实现的原因，例如平台设置或用户 偏好。

建议 用户代理以某种不打扰用户的形式显示 通知，在唤醒锁处于活动状态时告知用户，同时 为用户提供 阻止 正在进行的操作的方式，或者 仅关闭 该通知。

4.1 "screen-wake-lock" 强大功能

"screen-wake-lock" 强大功能 启用 本规范定义的能力。

4.2 权限算法

"screen-wake-lock" 强大功能 定义了一个 权限撤销 算法。要调用 屏幕 唤醒锁权限撤销算法，运行以下步骤：

  1. 令 document 为 当前全局对象 的 关联 Document。
  2. 令 lockList 为 document.[[ActiveLocks]]["screen"]。
  3. 逐一处理 lock，其取自 lockList：
    1. 运行 释放唤醒锁，传入 document、lock 和 "screen"。

5. 概念

用作 任务源 的是下述定义；它适用于 任务，即本 规范中提及的任务：屏幕唤醒锁任务源。

术语 平台 唤醒锁 指平台接口， 用户代理通过与其交互来查询状态，以及获取和 释放唤醒锁。

平台唤醒锁 可以由底层平台定义 （例如，在原生唤醒锁框架中），也可以由具有 直接硬件控制能力的用户代理定义。

6. 对 Document 接口的扩展

6.1 内部槽

内部槽 初始值 描述
[[ActiveLocks]] 一个 有序映射，将 唤醒锁类型 映射到空 列表。 一个 有序映射，将 唤醒锁 类型 映射到一个 列表，其中包含 WakeLockSentinel 对象，这些对象关联 于 此 Document。

7. 对 Navigator 接口的扩展 

WebIDL[SecureContext]
partial interface Navigator {
  [SameObject] readonly attribute WakeLock wakeLock;
};

8. WakeLock 接口

WakeLock 接口允许文档获取 屏幕唤醒锁。 

WebIDL[SecureContext, Exposed=(Window)]
interface WakeLock {
  Promise<WakeLockSentinel> request(optional WakeLockType type = "screen");
};

8.1 request() 方法

request(type) 方法的步骤如下：

  1. 令 document 为 this 的 相关全局对象 的 关联 Document。
  2. 如果 document 不是 完全活动的，则返回 一个被拒绝的 promise，拒绝原因为一个 "NotAllowedError" DOMException。
  3. 如果 document 不被 允许使用 此 由策略控制的功能，其名称为 "screen-wake-lock"，则返回 一个被拒绝的 promise，拒绝原因为一个 "NotAllowedError" DOMException。
  4. 如果 用户代理 拒绝唤醒锁，该锁的类型为 type，且面向 document，则返回 一个被拒绝的 promise，拒绝原因为一个 "NotAllowedError" DOMException。
  5. 如果 document 的 可见性状态 为 "hidden"，则返回 一个被拒绝的 promise，拒绝原因为一个 "NotAllowedError" DOMException。
  6. 令 promise 为 一个 新的 promise。
  7. 运行以下步骤，执行方式为 并行：
    1. 令 state 为以下操作的结果：请求 使用权限，目标为 "screen-wake-lock"。
    2. 如果 state 为 "denied"，则：
      1. 将一个全局任务排入队列，任务源为 屏幕唤醒 锁任务 源，给定 document 的 相关全局对象， 以拒绝 promise，拒绝原因为一个 "NotAllowedError" DOMException。
      2. 中止这些步骤。
    3. 将一个全局任务排入队列，任务源为 屏幕唤醒锁任务 源，给定 document 的 相关全局对象，以 运行以下步骤：
      1. 如果 document 不是 完全活动的，则：
        1. 拒绝 promise，拒绝原因为一个 "NotAllowedError" DOMException。
        2. 中止这些步骤。
      2. 如果 document 的 可见性状态 为 "hidden"，则：
        1. 拒绝 promise，拒绝原因为一个 "NotAllowedError" DOMException。
        2. 中止这些步骤。
      3. 如果 document.[[ActiveLocks]]["screen"] 为空，则执行 以下步骤，执行方式为 并行 执行：
        1. 调用 获取 唤醒锁，传入 "screen"。
          注
      4. 令 lock 为一个新的 WakeLockSentinel 对象，其 type 属性设置为 type。
      5. 追加 lock 到 document.[[ActiveLocks]]["screen"]。
      6. 将 promise 兑现为 lock。
  8. 返回 promise。

9. WakeLockSentinel 接口 

WebIDL[SecureContext, Exposed=(Window)]
interface WakeLockSentinel : EventTarget {
  readonly attribute boolean released;
  readonly attribute WakeLockType type;
  Promise<undefined> release();
  attribute EventHandler onrelease;
};

WakeLockSentinel 对象提供一个句柄，指向 平台唤醒 锁，并持续持有该句柄，直到它被手动释放， 或直到底层 平台唤醒锁 被释放。它的 存在使 平台唤醒锁 保持活动状态，该锁属于给定的 唤醒锁 类型；而释放所有 WakeLockSentinel 实例，若这些实例属于 给定的 唤醒锁类型，则会导致底层 平台唤醒 锁 被释放。

注

9.1 内部槽

WakeLockSentinel 实例在创建时具有 以下 内部 槽：

内部槽 初始值 描述（非规范性）
[[Released]] false 给定的 WakeLockSentinel 是否已被释放。

9.2 released 属性

released 获取器的步骤是返回 this.[[Released]]。

注

9.3 type 属性

type 获取器的步骤是返回 this 的 唤醒锁类型。

9.4 release() 方法

release() 方法的步骤 如下：

  1. 如果 this 的 [[Released]] 为 false， 则运行 释放唤醒锁，其中 lock 设置 为 this，且 type 设置为以下 属性的值： this 的 type 属性。
  2. 返回 一个已兑现的 promise，兑现值为 undefined。

9.5 onrelease 属性

onrelease 属性是一个 事件处理器 IDL 属性，对应 "onrelease" 事件 处理器，其 事件处理器事件类型 为 "release"。

它用于通知脚本，给定的 WakeLockSentinel 对象的句柄已被释放，原因可能是 release() 方法被 调用，也可能是 唤醒锁被 用户代理 释放。

注
注

9.6 垃圾回收

当 WakeLockSentinel 对象 注册了一个或多个事件监听器， 用于 "release"，并且该 WakeLockSentinel 对象尚未被 释放时，必须 存在一个强引用，起点为 Window 对象，即 WakeLockSentinel 对象的构造函数被调用时所来自的对象， 终点为 WakeLockSentinel 对象本身。

当存在一个由 WakeLockSentinel 对象排入队列的任务，且其任务源为 屏幕唤醒锁任务源 时，必须 存在一个强引用， 起点为 Window 对象，即 WakeLockSentinel 对象的 构造函数被调用时所来自的对象，终点为该 WakeLockSentinel 对象。

10. WakeLockType 枚举

为了描述唤醒锁类型，本规范 定义了以下枚举来表示 唤醒锁类型： 

WebIDLenum WakeLockType { "screen" };
screen
屏幕唤醒锁 类型。

11. 管理唤醒锁

本节同等且独立地适用于每种 唤醒锁类型， 除非明确提及某种特定的 唤醒锁类型 才另作处理。

用户 代理 获取唤醒 锁 的方式是请求底层操作系统应用该 锁。不检查向底层 操作系统发出的请求可能产生的返回值。换言之，用户代理 必须 将唤醒锁的获取视为 仅具有建议性。

反之，用户代理 释放唤醒锁 的方式是请求底层操作系统不再应用该 唤醒锁。只有向操作系统发出的请求 成功时，才认为该锁已被释放。

唤醒锁是 适用的，当且仅当 操作系统的状态允许应用该锁（例如， 电池电量充足）。

屏幕唤醒锁 不得 为 适用的，从 用户手动关闭屏幕开始，直到屏幕 再次开启为止。

注

11.1 自动释放唤醒锁

用户代理可以随时 释放唤醒锁。例如， 当：

11.2 处理文档失去完全活动状态

当一个 Document document 不再是 完全活动的 时，用户代理必须运行以下 步骤：

  1. 逐一处理 lock，其取自 document.[[ActiveLocks]]["screen"]：
    1. 运行 释放唤醒锁，传入 document、lock 和 "screen"。

11.3 处理文档失去可见性

本规范定义了以下 页面可见性更改步骤，给定 可见性状态 state 和 document：

  1. 如果 state 不是 "hidden"，则中止这些步骤。
  2. 逐一处理 lock，其取自 document.[[ActiveLocks]]["screen"]：
    1. 运行 释放唤醒锁，传入 document、lock 和 "screen"。

11.4 获取唤醒锁算法

要 获取 唤醒锁，给定 type， 运行以下步骤：

  1. 如果类型为 type 的唤醒锁不是 适用的，则中止 这些步骤。
  2. 请求底层操作系统 获取唤醒 锁，其类型为 type。

11.5 释放唤醒锁算法

要 释放 唤醒锁，给定 document、 lock 和 type，运行以下 步骤：

  1. 如果 document.[[ActiveLocks]][type] 不 包含 lock，则中止这些步骤。
  2. 移除 lock，从 document.[[ActiveLocks]][type] 中。
  3. 如果 document.[[ActiveLocks]][type] 为空，则运行以下步骤，执行方式为 并行：
    1. 请求底层操作系统 释放唤醒 锁，其类型为 type，并令 success 为 true，如果 操作成功；否则为 false。
    2. 如果 success 为 true，且 type 为 "screen"，则运行 以下步骤：
      1. 重置特定于平台的无活动计时器，该计时器到期后 屏幕才会真正关闭。
      注
  4. 将 lock 的 [[Released]] 设置为 true。
  5. 触发一个事件，名称为 "release"，目标为 lock。

12. 安全注意事项

屏幕唤醒锁可能使设备的各个组件，尤其是 显示屏，以高于未使用唤醒锁时的 功耗运行。这可能造成不良影响，例如阻止 设备自动锁定，以及加快电池电量消耗。 电池电量消耗加快对移动设备尤其值得关注， 因为它们往往无法随时使用固定电源。 电池电量在意料之外的时间完全耗尽，可能导致 用户无法拨打或接听电话，也无法使用网络服务， 包括紧急呼叫服务。

实现 可以 忽略屏幕唤醒锁请求，例如， 在电池电量较低，或者用户已将设备置于 节能模式时。

13. 隐私注意事项

建议 用户代理提供某种用户界面或指示器， 让用户知道屏幕唤醒锁何时处于活动状态。提供 这样的用户界面有助于最终用户识别某个 Web 应用是否对设备的能耗产生负面影响，并允许 他们在希望时采取行动。

14. 示例

本节是非规范性的。

示例 1：获取和释放屏幕唤醒锁 
function tryKeepScreenAlive(minutes) {
  navigator.wakeLock.request("screen").then(lock => {
    setTimeout(() => lock.release(), minutes * 60 * 1000);
  });
}

tryKeepScreenAlive(10);

此示例允许用户通过点击复选框请求 屏幕唤醒锁，但会在唤醒锁 状态发生变化时更新复选框的选中状态：

示例 2 
const checkbox = document.createElement("input");
checkbox.setAttribute("type", "checkbox");
document.body.appendChild(checkbox);

const sentinel = await navigator.wakeLock.request("screen");
checkbox.checked = !sentinel.released;
sentinel.onrelease = () => checkbox.checked = !sentinel.released;

在此示例中，两个不同的唤醒锁请求被创建， 并独立释放：

示例 3 
let lock1 = await navigator.wakeLock.request("screen");
let lock2 = await navigator.wakeLock.request("screen");

lock1.release();
lock2.release();

15. 符合性

除了标记为非规范性的章节外，本规范中的所有编写指南、图表、示例和注释 也都是非规范性的。本规范中的其余内容均为规范性的。

本文档中的关键词 可以（MAY）、必须（MUST）、不得（MUST NOT） 和 建议（RECOMMENDED） 应按照以下文档中的描述解释： BCP 14 [RFC2119] [RFC8174]， 当且仅当它们以此处所示的全 大写形式出现时。

本规范为单一产品定义符合性标准： 用户代理，其实现本规范包含的接口。

A. 致谢

本节是非规范性的。

我们衷心感谢 Mounir Lamouri、Sergey Konstantinov、Matvey Larionov、Dominique Hazael-Massieux、Domenic Denicola、Thomas Steiner、Anne van Kesteren 为这项 工作作出的贡献。

B. 变更

本节是非规范性的。

本节记录自先前发布版本以来的变更。

B.1 自 2017 年 12 月 14 日候选推荐标准以来的变更

C. 索引

C.1 本规范定义的 术语

C.2 通过引用定义的术语

D. IDL 索引

WebIDL[SecureContext]
partial interface Navigator {
  [SameObject] readonly attribute WakeLock wakeLock;
};

[SecureContext, Exposed=(Window)]
interface WakeLock {
  Promise<WakeLockSentinel> request(optional WakeLockType type = "screen");
};

[SecureContext, Exposed=(Window)]
interface WakeLockSentinel : EventTarget {
  readonly attribute boolean released;
  readonly attribute WakeLockType type;
  Promise<undefined> release();
  attribute EventHandler onrelease;
};

enum WakeLockType { "screen" };

E. 参考文献

E.1 规范性参考文献

[dom]
DOM 标准. Anne van Kesteren. WHATWG. 现行标准. URL: https://dom.spec.whatwg.org/
[ECMASCRIPT]
ECMAScript 语言规范. Ecma 国际. URL: https://tc39.es/ecma262/multipage/
[html]
HTML 标准. Anne van Kesteren; Domenic Denicola; Dominic Farolino; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. 现行 标准. URL: https://html.spec.whatwg.org/multipage/
[infra]
Infra 标准. Anne van Kesteren; Domenic Denicola. WHATWG. 现行标准. URL: https://infra.spec.whatwg.org/
[PERMISSIONS]
权限. Marcos Caceres; Mike Taylor. W3C. 2025 年 10 月 6 日. W3C 工作草案. URL: https://www.w3.org/TR/permissions/
[PERMISSIONS-POLICY]
权限策略. Ian Clelland; Ari Chivukula. W3C. 2026 年 9 月 22 日. W3C 工作草案. URL: https://www.w3.org/TR/permissions-policy-1/
[RFC2119]
RFC 中用于表示 需求级别的关键词. S. Bradner. IETF. 1997 年 3 月. 当前最佳实践. URL: https://www.rfc-editor.org/info/rfc2119/
[RFC8174]
RFC 2119 关键词中大写与小写的歧义. B. Leiba. IETF. 2017 年 5 月. 当前最佳实践. URL: https://www.rfc-editor.org/info/rfc8174/
[WEBIDL]
Web IDL 标准. Edgar Chen; Timothy Gu. WHATWG. 现行标准. URL: https://webidl.spec.whatwg.org/

E.2 资料性参考文献

[wake-lock-use-cases]
唤醒锁：使用场景. Marcos Caceres; Natasha Rooney; Dominique Hazaël-Massieux. W3C. 2014 年 8 月 14 日. W3C 工作组说明. URL: https://www.w3.org/TR/wake-lock-use-cases/