requestIdleCallback()

摘要

本文档定义了一个 API，网页作者可用来协作调度后台任务，从而不会对同一事件循环中的其他高优先级任务（如输入处理、动画和帧合成）造成延迟。用户代理基于其对当前已调度任务、vsync 截止时间、用户交互等信息的了解，能够更好地判断何时可以运行后台任务而不引入用户可感知的延迟或动画/输入卡顿。因此，使用该 API 应能实现更合理的后台任务调度，使其在浏览器本应处于空闲的时机进行。

本节为非规范性内容。

网页通常希望在浏览器的事件循环中执行一些非关键的计算任务，但这些任务可能会占用较多时间。此类后台任务的例子包括记录分析数据、长时间的数据处理操作、客户端模板渲染以及对即将可见内容的预渲染。这些任务必须与其他时效性要求高的操作（如对输入的响应和基于脚本的动画）共享事件循环，例如通过requestAnimationFrame()实现的动画。这些后台任务通常通过setTimeout()来调度回调，在该时机内执行后台任务。

这种做法的一个缺点是，脚本作者无法告知用户代理某个setTimeout()回调是否为关键任务，还是可以推迟到浏览器空闲时执行。此外，用户代理也无法向回调提供关于它可以执行多长时间而不会延迟关键操作或造成动画、输入卡顿等用户可感知延迟的信息。因此，开发者通常的做法只是用一个很小的值调用setTimeout()，并在回调中执行最少的工作量，然后再次用setTimeout()调度后续工作。这种方法效率不高，因为为用户代理的事件循环频繁添加小任务会产生额外开销，并且依赖于用户代理在这些回调间穿插时效性工作，但由于用户代理无法准确预估每个回调的耗时，因此协调的难度较大。

本文档描述的 API 允许脚本作者请求用户代理在空闲时调度回调。用户代理会为回调传递一个截止时间，指示其预计还能保持空闲状态多久。页面作者可以利用截止时间确保这些后台任务不会影响对动画和输入等时延敏感事件的响应。

下面是使用该 API 实现后台任务的示例。

示例 1

<!DOCTYPE html>
<title>使用 requestIdleCallback 调度后台任务</title>
<script>
var requestId = 0;
var pointsTotal = 0;
var pointsInside = 0;

function piStep() {
  var r = 10;
  var x = Math.random() `*` r `*` 2 - r;
  var y = Math.random() `*` r `*` 2 - r;
  return (Math.pow(x, 2) + Math.pow(y, 2) < Math.pow(r, 2))
}
function refinePi(deadline) {
  while (deadline.timeRemaining() > 0) {
    if (piStep())
      pointsInside++;
    pointsTotal++;
  }
  currentEstimate = (4 `*` pointsInside / pointsTotal);
  textElement = document.getElementById("piEstimate");
  textElement.innerHTML="圆周率估算: " + currentEstimate;
  requestId = window.requestIdleCallback(refinePi);
}
function start() {
  requestId = window.requestIdleCallback(refinePi);
}
function stop() {
  if (requestId)
    window.cancelIdleCallback(requestId);
  requestId = 0;
}
</script>
<button onclick="start()">点击我开始！</button>
<button onclick="stop()">点击我停止！</button>
<div id="piEstimate">未开始</div>

本节为非规范性内容。

在某一帧的输入处理、渲染和合成完成后，用户代理的主线程通常会处于空闲状态，直到下一个帧开始、其他待执行任务达到可运行状态或收到用户输入。该规范提供了一种方式，可通过requestIdleCallback() API 在这些本应空闲的时间段调度回调执行。

通过requestIdleCallback() API 注册的回调，将在用户代理定义的空闲期内变为可运行状态。运行空闲回调时会传递一个对应当前空闲周期结束时间的截止时间。什么构成空闲期由用户代理定义，但预期这些时间段是浏览器判断为将保持空闲的期间。

空闲期的一个例子是活跃动画期间将某一帧提交到屏幕后到下一个帧开始处理之间的间隔，如图 1所示。活跃动画和屏幕刷新期间，这样的空闲期会频繁出现，但通常非常短（例如在 60Hz vsync 设备上小于 16 毫秒）。

Example of an inter-frame idle period. — 图 1 帧间空闲期示例

注意

Web 开发者应注意统计空闲回调期间所有操作的整体工作量。一些操作（如解析 promise 或触发页面布局）可能会导致回调结束后调度后续任务。在这种情况下，应用应在截止前主动让出，确保这些额外操作可在下一个帧截止前被执行。

另一种空闲期的例子是当用户代理处于空闲且没有屏幕刷新时。在这种情况下，用户代理可能没有即将到来的任务可以界定空闲周期的终止。为了避免在处理用户输入等不可预测任务时造成可感知的延迟，该类空闲周期的时长应被上限限制为50毫秒。一旦空闲期结束，在用户代理继续空闲时，可以再次安排新的空闲期，如图 2所示，使后台工作能在较长空闲阶段持续进行。

Example of an idle period when there are no pending frame updates. — 图 2 没有待处理帧更新时的空闲期示例

在一个空闲周期内，用户代理会以FIFO顺序执行空闲回调，直到空闲期结束或没有剩余可运行回调为止。因此，用户代理并不保证在单个空闲周期内会全部执行当前已登记的空闲回调。剩余的空闲任务将在下一个空闲周期变为可运行状态。

注意

为获得最佳性能，建议开发者移除无意义的回调（如 requestAnimationFrame、setTimeout 等），不要让这类回调持续触发并等待事件响应，而是在事件实际到来时再调度。这种模式能提升整体效率，同时让用户代理有机会安排最长达50毫秒的长空闲回调，从而高效地执行大块后台任务。

仅在当前空闲周期开始前登记的空闲任务，才有资格在该周期内运行。因此，如果空闲回调期间又注册了另一个requestIdleCallback()回调，这个后注册的回调不会在当前空闲周期被执行。这样，空闲回调可在无法在截止前完成任务时，重新登记自身以便在下一个空闲周期继续运行——即便于实现如下示例中的代码模式，而不会因为空闲周期太短导致多次重复执行：

示例 2

function doWork(deadline) {
  if (deadline.timeRemaining() <= 5) {
    // 这个任务超过5ms，所以等待我们
    // 被分配到足够长的空闲周期时再执行。
    requestIdleCallback(doWork);
    return;
  }
  // 执行工作……
}

下一个空闲周期开始时，新登记的空闲回调会被追加到可运行回调队列末尾，从而确保重新登记的回调以轮询形式被执行——先前任务的回调重新登记前，其他回调也能获得运行机会。

注意

本规范的未来版本可能允许其它调度策略。例如，在同一空闲周期内调度回调、调度到存在至少X毫秒空闲时间的周期等等。目前规范仅支持调度到下一个空闲周期，届时回调可执行逻辑或再次重新登记到下一空闲周期。

当用户代理判断网页处于非用户可见状态时，可以限制空闲周期以降低设备能耗，例如只每10秒触发一次空闲周期而非持续触发。

需要注意的是，在页面负载较高时用户代理未必能分配任何空闲CPU时间。因此，用户代理不调度任何空闲期完全是合理的，结果是通过requestIdleCallback()API登记的回调可能会无限期延后。对于希望优先使用空闲期、但又希望限定最长等待时间的开发者，可以在requestIdleCallback()的options参数提供timeout属性；如果在指定超时前没运行回调，则会将其入队执行。

注意

50毫秒的最大截止时间来源于相关研究 [RESPONSETIME]，结果显示人类大多会认为100毫秒内响应为瞬时反馈。将空闲回调截止时间限制为50毫秒，即使用户输入刚好在空闲任务开始后发生，用户代理仍有50毫秒响应时间，不会让用户感觉到滞后。

下方 IDL 片段中的 partial interface 用于在 Window 对象上暴露 requestIdleCallback() 操作。

WebIDLpartial interface Window {
  unsigned long requestIdleCallback(IdleRequestCallback callback, optional IdleRequestOptions options = {});
  undefined cancelIdleCallback(unsigned long handle);
};

dictionary IdleRequestOptions {
  unsigned long timeout;
};

[Exposed=Window] interface IdleDeadline {
  DOMHighResTimeStamp timeRemaining();
  readonly attribute boolean didTimeout;
};

callback IdleRequestCallback = undefined (IdleDeadline deadline);

每个 Window 都有：

一个空闲请求回调列表。该列表必须初始为空，且其中每个条目都通过一个编号标识，该编号在该Window对象的生命周期内必须唯一。
一个可运行空闲回调列表。该列表必须初始为空，且其中每个条目都通过一个编号标识，该编号在该Window对象的生命周期内必须唯一。
一个空闲回调标识符，其为数字，必须初始为零。

当以指定的IdleRequestCallback 及可选IdleRequestOptions 调用 requestIdleCallback(callback, options) 时，用户代理必须执行如下步骤：

令window为当前的Window 对象。
将window的空闲回调标识符加一。
令handle为window当前的空闲回调标识符值。
将callback以handle进行关联，并推送到window的空闲请求回调列表末尾。
返回handle，然后异步继续运行本算法。

注意

下述步骤会并行运行，并在指定timeout属性时，排队一个类似setTimeout()的定时器。从此，空闲回调与超时回调将互相竞争并彼此取消——例如若空闲回调先被调度，则取消超时，反之亦然。
若options中存在timeout属性且为正值：
1. 等待timeout毫秒。
2. 等待本算法所有timeout加上其发起时间先于当前请求的实例均已完成。
3. 可选：再等待一段用户代理自定义的时长。
  
  注意
  
  此举意在允许用户代理按需对超时进行填充，以优化设备的功耗。例如某些处理器存在低功耗模式，定时器粒度降低；在此类平台上，用户代理可以降低定时器速率，无须一直维持高精度，从而节省耗电。
4. 在与 idle-task 任务源关联的队列中排队一个任务，该任务执行调用空闲回调超时算法，传递handle和window为参数。

注意

requestIdleCallback() 仅调度单个回调，并在单个空闲周期执行。如果回调未能在指定deadline前完成其工作，则应再次调用requestIdleCallback()（可在回调中发起），以调度新的后续回调，并立即退出以将控制权归还事件循环。

cancelIdleCallback() 方法用于取消此前登记的空闲回调。当调用 cancelIdleCallback(handle) 时，用户代理必须执行如下步骤：

令window为当前Window 对象。
在window的空闲请求回调列表或可运行空闲回调列表中查找与handle相关联的条目。
若存在该条目，则从window的空闲请求回调列表和可运行空闲回调列表中均移除此条目。

注意

cancelIdleCallback() 可能针对window的空闲请求回调列表或可运行空闲回调列表中的一个条目被调用。无论哪种情况，该条目都应被移除，使回调不会被执行。

每个IdleDeadline都有一个关联的获取截止时间算法，返回DOMHighResTimeStamp ，表示该截止时间的绝对毫秒时间。截止时间初始为零。

在 IdleDeadline对象上调用timeRemaining() 方法时，必须返回截止前剩余时长，类型为DOMHighResTimeStamp；该值应能满足测量需求同时避免计时攻击——详见 [HR-TIME] 的“隐私与安全”章节。其值按以下步骤计算：

令now为DOMHighResTimeStamp，表示当前高精度时间（毫秒）。
令deadline为调用IdleDeadline的获取截止时间算法的结果。
令timeRemaining为deadline减now。
如timeRemaining为负，则置为0。
返回timeRemaining。

每个 IdleDeadline都有关联的超时标记，其初始值为 false。 didTimeout getter 必须返回超时标记的值。

注意

调用空闲回调超时算法将超时标记设为 true，以表明该回调因超过登记时提供的 IdleRequestOptions的 timeout 属性而在非空闲周期执行。

为 Window window 和 getDeadline（一个返回 DOMHighResTimeStamp 的算法）启动空闲期：

注意

该算法由事件循环处理模型判断事件循环处于空闲时调用。

用户代理可选地认为空闲期应当延迟时，直接返回本算法。

注意

为允许用户代理根据需要延迟空闲期的启动以优化设备电源。例如，若 Document 的 visibility state 为 "hidden" ，则用户代理可限制空闲期的生成，例如每 10 秒 1 次以优化电源消耗。
令 pending_list 为 window 的空闲请求回调列表。
令 run_list 为 window 的可运行空闲回调列表。
将 pending_list 中所有条目按顺序追加到 run_list 末尾。
清空 pending_list。
在与 idle-task 任务源关联的队列中排队一个任务，该任务执行调用空闲回调算法，参数为 window 和 getDeadline。

注意

当��时刻到截止时间的这段时间称为空闲期。对于任意 Window，同一时刻仅有一个空闲期处于激活状态。若用户代理判断不再空闲则空闲期可提前结束，此时新空闲期需等待到达 deadline 后才能重新开始。

为 Window window 和 getDeadline（返回 DOMHighResTimeStamp 的算法），调用空闲回调算法：

若用户代理因新调度的高优先级工作判断应提前结束空闲期，则直接返回本算法。
令 now 为当前时间。
若 now 小于 getDeadline 的结果，且 window 的可运行空闲回调列表非空：
1. 从 window 的可运行空闲回调列表弹出最上方的 callback。
2. 令 deadlineArg 为新建 IdleDeadline，其获取截止时间算法为 getDeadline。
3. 调用 callback，传递 « deadlineArg » 和 "report"。
4. 若 window 的可运行空闲回调列表非空，则排队一个任务，执行本调用空闲回调算法，参数为 getDeadline 和 window，并返回本算法

注意

即使 deadline 未到，用户代理也可在第 1 步直接返回以提前终止空闲期。例如判断更高优先级的任务已可运行时。

调用空闲回调超时算法：

令 callback 为在 window 的空闲请求回调列表或可运行空闲回调列表中与传递进来的 handle 相关联的条目。
若 callback 不为 undefined：
1. 从 window 的空闲请求回调列表和可运行空闲回调列表中移除 callback。
2. 令 now 为当前时间。
3. 令 deadlineArg 为新建 IdleDeadline。将获取截止时间算法设为返回 now，并将超时标记设为 true。
4. 调用 callback，传递 « deadlineArg » 和 "report"。

`requestIdleCallback()`

后台任务的协作式调度

摘要

本文档状态

1. 介绍

2. 空闲期

3. 一致性

4. `Window` 接口扩展

4.1 `requestIdleCallback()` 方法

4.2 `cancelIdleCallback()` 方法

4.3 `IdleDeadline` 接口

5. 处理过程

5.1 启动空闲期算法

5.2 调用空闲回调算法

5.3 调用空闲回调超时算法

6. 隐私注意事项

7. 安全性注意事项

A. 致谢

B. 参考文献

B.1 规范性参考文献

B.2 资料性参考文献