容器计时 API

1. 简介

Container Timing API 可用于监测 DOM 中已标注的部分何时显示在屏幕上并 完成其初始绘制。开发者可以使用 containerTiming 属性标记 DOM 的子部分（类似于 Element Timing API 的 elementtiming），并在该部分 首次完成绘制时接收性能条目。

此 API 允许开发者测量页面中各类组件的计时。随着开发者 越来越多地将应用组织成组件，对应用或网页的 子区段进行性能测量的需求也在增长。

与 Element Timing 不同，渲染器无法知道 DOM 的某个区段何时已经完成 绘制（可能还会有未来的变化、用于新图像的异步请求、加载缓慢的按钮等）， 因此此 API 会在发生更新时，以 PerformanceEntry 对象的形式发出候选项。

2. 动机

开发者希望测量 DOM 子区段何时被绘制，例如表格、小部件或其他 组件，以便跟踪绘制时间并将其提交给分析系统。当前的 Web API 无法充分 支持这一点：

• Element Timing 所能支持的内容有限，不能用于整个 区段。

• 最大内容绘制（LCP）不足以用于计时页面特定部分 何时加载完成。

• 用户空间 polyfill 存在显著缺点，例如：

  • 需要在绘制前标记元素（这需要服务端更改或阻塞 渲染）

  • 需要 MutationObserver 来捕获新注入的元素

  • 需要在文档头部运行，从而增加首次绘制时间

  • 与浏览器内建 2D 引擎相比，在矩形跟踪方面可能效率更低

Web 作者比任何人都更了解自己的领域，并希望以其用户或组织能够理解的方式 传达自身内容块的性能（例如 “首次推文时间”）。

2.1. 生命周期

但是，一旦某个区域已被绘制，随后对同一区域的绘制将不会生成新的条目。

一旦用户滚动页面或与页面进行交互，就不会再记录后续绘制，也不会生成新的条目 。

3. 用法示例

下面的示例演示如何注册一个容器根并观察其绘制计时。

<div containertiming="foobar">
  <main>...</main>
  <aside>...</aside>
</div>

<script>
  const observer = new PerformanceObserver((list) => {
    let perfEntries = list.getEntries();
    for (const entry of perfEntries) {
      console.log('容器已绘制：', entry.identifier,
                  '时间', entry.startTime,
                  '大小：', entry.size);
    }
  });
  observer.observe({ entryTypes: ["container"] });
</script>

3.1. 忽略子树

<div containertiming="foobar">
  <main>...</main>
  <!-- aside 的更新不会触发容器计时事件 -->
  <aside containertimingignore>...</aside>
</div>

4. 术语

容器根是一个 具有 HTMLElement 的 containerTiming 属性。

被忽略的子树是一个 以具有 HTMLElement 的 containerTimingIgnore 属性的元素为根的子树。

已绘制区域是一个 区域（矩形的集合），表示自首次 观察以来容器根所有已绘制部分的累积，以 CSS 像素表示。已绘制区域维护在视口坐标空间中。如果 容器根元素发生移动 （例如，由于布局变化或 moveBefore()）， 之前累积的矩形不会进行调整——该区域会继续在视口坐标中扩展。

容器计时 API提供有关容器根何时绘制到屏幕上的计时信息。

5. PerformanceContainerTiming 接口

[Exposed=Window]
interface PerformanceContainerTiming : PerformanceEntry {
    readonly attribute DOMString identifier;
    readonly attribute DOMRectReadOnly intersectionRect;
    readonly attribute unsigned long long size;
    readonly attribute DOMHighResTimeStamp firstRenderTime;
    readonly attribute HTMLElement? lastPaintedElement;
    readonly attribute HTMLElement? rootElement;

    [Default] object toJSON();
};

PerformanceContainerTiming includes PaintTimingMixin;

注： intersectionRect 的 坐标和 size 均以 CSS 像素表示（对于 size，则为 CSS 像素的平方）， 这与绘制 区域的坐标空间以及交叉矩形算法所生成的单位一致。

注： 用户代理需要维护容器根记录映射，以使被移除的内容不会 引入内存泄漏。具体而言，它可以将条目的生命周期与指向这些 HTMLElement 的弱指针相关联， 以便在这些 HTMLElement 被移除后的某个时间清理它们。由于该映射不会暴露给 Web 开发者，因此这不会暴露垃圾回收的时机。

6. 处理模型

注： 实现容器计时 API 的用户代理 需要在 supportedEntryTypes 中为 Window 上下文包含 "container"。 这允许开发者检测对容器计时的支持。

6.1. 每文档状态

对于每个 Document， 用户代理必须维护一个 容器根记录映射，它将 容器根 HTMLElement 映射到 容器计时记录对象。

6.2. 对 DOM 规范的修改

一旦 [DOM] 规范完成修改，本节将被移除。

我们按如下方式修改 事件分派算法。

紧接在步骤 1 之后，我们添加以下步骤：

1. 如果 target 的 相关全局对象是一个 Window 对象，并且 event 的 isTrusted 为 true：

   1. 如果 event 的 type 为 scroll，则将 target 的 相关全局对象的 已分派滚动事件设置为 true。

   2. 如果 event 的 type 是 keydown、mousedown、pointerdown 或 click 之一，则将 target 的 相关全局对象的 已分派输入事件设置为 true。

6.3. 对 HTMLElement 接口的扩展

一旦 [DOM] 规范完成修改，本节将被移除。

我们按如下方式扩展 HTMLElement 接口：

partial interface HTMLElement {
    [CEReactions, Reflect] attribute DOMString containerTiming;
    [CEReactions, Reflect] attribute boolean containerTimingIgnore;
};

6.4. 容器计时记录

本规范定义了处理模型所使用的内部数据结构：

6.5. 注册容器根

当一个带有 HTMLElement 的 containerTiming 内容属性连接到文档时：

1. 用户代理必须将该元素注册为一个 容器根。

2. 用户代理必须为该 已绘制区域初始化一个空的 容器根。

3. 用户代理必须跟踪该 容器根子树内的所有绘制操作，但排除任何 忽略的子树。

6.6. 移除 containertiming 属性

注：如果随后又将 containerTiming 属性重新添加到同一元素，则会在下一次绘制时创建一个新的 容器计时记录。 已绘制区域会从头开始——不会保留先前的绘制数据。

6.7. 断开容器根

注：如果该元素重新连接到文档 时仍具有 containerTiming 属性，则会将其视为一次新的 容器根注册。一个新的 容器计时记录将在 下一次绘制时创建，并具有一个全新的 已绘制区域。

6.8. 处理用于容器计时的元素绘制

注：对于每个进行绘制的图像或文本 节点，都会调用此算法。交叉矩形应使用 交叉矩形算法计算，其中以该元素作为 目标、以视口作为根，并与可视视口相交。对于文本节点，交叉 矩形是包含 拥有的文本节点集合中所有文本节点边框盒的最小矩形，并与可视视口相交。

注：容器计时旨在测量内容的 初始渲染。一旦用户滚动页面或与文档交互，就不再记录 绘制，因为这些绘制很可能是滚动或交互的结果（例如，内容 被滚动到视图中或通过点击显示），而不是页面加载的结果。当前 帧中已经待处理的条目仍会被发出。

6.9. 发出容器计时条目

注：与其他一些可能针对每个已绘制元素发出 多个条目的绘制计时 API 不同，容器计时会为每个 容器根累积已绘制区域，并且每个 容器根每帧最多发出一个 PerformanceContainerTiming 条目。这种批处理方法效率更高，并提供 容器绘制状态的整体视图。

6.10. 获取父容器根 Element

6.11. 计入容器计时

如果以下所有条件均为 true，则一个 HTMLElement 会计入一个 容器根的容器计时：

• 它是该 容器根的后代。

• 它不位于一个 忽略的子树中。

• 它不位于影子树中。

6.12. 获取容器根 Element

6.13. 可能更新最后新增绘制区域

注：lastPaintedElement 是在单个渲染帧中贡献了最大新增绘制区域的元素。这避免了 对实现特定绘制顺序的依赖。lastPaintedElement 旨在作为调试辅助工具，帮助开发者调查大型或复杂 容器根（例如 表格）上的更新由什么驱动，而不是作为其自身独立的性能指标。lastNewPaintedAreaSize 会在 条目发出后重置，以便每一帧的比较都从头开始。

注：此算法会报告已绘制 区域的任何变化，而不考虑其大小。即使已绘制区域只有 1 像素的变化，也会导致一个新的 PerformanceContainerTiming 条目被排入队列。希望过滤掉较小变化的开发者可以通过比较 size 在各条目之间的值来实现。

6.14. 创建容器计时条目

7. 安全与隐私考量

7.1. 跨源限制

该 API 遵守跨源边界：

• 属于跨源 iframe 的元素不会暴露给父框架。

• 除非开发者通过 postMessage 显式传递，否则计时信息不会跨越框架边界。

7.2. 信息暴露

此 API 提供的大多数信息都已经可以通过现有 API 进行估算：

• Element Timing 会返回图像和文本的首次渲染时间。

• Paint Timing API 提供相关时间戳。

• 这些 API 的组合可以近似容器计时信息，尽管效率较低。

该 API 不会暴露：

• 渲染引擎的内部实现细节

• 开发者尚无权访问的元素相关信息

• 比现有 Performance API 已可用粒度更细的计时信息

7.3. 计时攻击

该 API 使用 DOMHighResTimeStamp， 出于安全目的，它可能受到分辨率限制，这与其他 Performance API 一致。

7.4. 隐私考量

该 API 不会：

• 支持跨站点跟踪用户

• 暴露浏览历史

• 提供超出站点通过脚本执行已经能够访问的用户行为信息

8. 致谢

非常感谢以下人士提供的宝贵反馈和建议：

• Barry Pollard

• Michael Mocny

• Scott Haseley

• Sergey Chernyshev

• Bas Schouten