容器计时 API

1. 简介

容器计时 API 能够监测 DOM 中带注解的区段何时显示在屏幕上并 完成其初始绘制。开发者可以使用 containertiming 属性（类似于 Element Timing API 的 elementtiming）来标记 DOM 的子区段，并在该区段 第一次被绘制时接收性能条目。

此 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('Container painted:', entry.identifier,
                  'at', entry.startTime,
                  'size:', entry.size);
    }
  });
  observer.observe({ entryTypes: ["container"] });
</script>

3.1. 忽略子树

<div containertiming="foobar">
  <main>...</main>
  <!-- Aside updates won't trigger container timing events -->
  <aside containertiming-ignore>...</aside>
</div>

4. 术语

容器根是一个 具有 Element 且带有 containertiming 属性的元素。

被忽略的子树是一个 以带有 Element 和 containertiming-ignore> 属性的元素为根的子树。

已绘制区域是一个 区域（矩形集合），表示某个 容器根自首次 被观察以来所有已绘制部分的累积。

容器计时 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 Element? lastPaintedElement;
    readonly attribute Element? rootElement;
};

PerformanceContainerTiming includes PaintTimingMixin;

注： 用户代理需要维护 容器根记录映射，以确保已移除的内容不会 引入内存泄漏。特别是，它可以将条目的生命周期绑定到指向这些 Element 的弱指针，从而在这些 Element 被移除之后的某个时候对其进行清理。由于该映射不会暴露给 Web 开发者，因此这不会暴露垃圾收集计时。

6. 处理模型

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

6.1. 每文档状态

对于每个 Document， 用户代理必须维护一个 容器根记录映射，该映射将 容器根 Element 映射到 Container Timing Record 对象。

6.2. 对 Element 接口的扩展

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

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

partial interface Element {
    [CEReactions] attribute DOMString containertiming;
    [CEReactions] attribute DOMString? containertimingIgnore;
};

6.3. Container Timing Record

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

6.4. 注册容器根

当一个带有 [^containertiming^] 内容属性的 Element 被连接到文档时：

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

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

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

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

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

6.6. 发出容器计时条目

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

6.7. 获取父容器根 Element

6.8. 对容器计时有贡献

如果以下条件均为 true，则一个 Element 对某个容器根的容器计时有贡献：

• 它是该 容器根的后代。

• 它不在某个 被忽略的子树内。

• 它不在影子树中。

6.9. 获取容器根 Element

6.10. 可能更新最后的新绘制区域

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

6.11. 创建容器计时条目

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