绘制计时

1. 简介

本节为非规范性内容。

Web 浏览器的主要作用之一是将 HTML、CSS 和图片资源转化为用户屏幕上的像素。衡量网页性能通常涉及测量完成这些任务（即将文本或图片内容渲染到屏幕）所需的时间。虽然有许多不同的方法可以利用这些计时信息来评判页面性能或加载体验，但所有这些方法本质上都依赖于统一的时间测量方式。

本文件是一个基础规范，规定了如何作为通用机制测量绘制计时（Paint Timing）。在此基础上，定义了“首次绘制（First Paint）”和“首次内容绘制（First Contentful Paint）”等指标。其它具体的绘制测量实例可能由其他文档进一步规定。

具体而言，本规范涵盖：

测量图片解码并准备绘制的时间
测量元素被绘制的时间
测量已绘制元素的尺寸
判断绘制元素是否包含可见内容

1.1. 首次绘制与首次内容绘制

“加载”并非单一时刻——它是一种体验，没有任何单一指标能够完全描述。加载体验过程中有多个时刻会影响用户对“快”或“慢”的感知。

首次绘制（FP）是这些关键时刻中的第一个，紧随其后的是首次内容绘制（FCP）。这些指标标记了浏览器渲染特定文档的时间点。对用户来说，这很重要，因为它回答了“页面是不是开始有动静了？”这一问题。

两者的主要区别在于：FP 标志着浏览器首次为特定文档渲染任何内容的时刻；而 FCP 标志着浏览器首次从 DOM 渲染出图片或文本内容的时刻。

1.2. 用法示例

const observer = new PerformanceObserver(function(list) {
    const perfEntries = list.getEntries();
    for (const perfEntry of perfEntries) {
        // 处理条目
        // 上报分析和监控
        // ...
    }
});

// 注册观察者以获取绘制计时通知
observer.observe({entryTypes: ["paint"]});

2. 术语

绘制（Paint）：当用户代理将渲染树转换为屏幕上的像素时，即执行了“绘制”（或“渲染”）。正式地讲，当用户代理执行了事件循环中的更新渲染步骤时，视为已“渲染”文档。

注意：渲染管线非常复杂，时间戳应为用户代理在该管线中能够记录到的最新时间戳（尽力而为）。通常建议此 API 采用提交帧给操作系统用于显示的时间。

当以下条件全部满足时，生成内容伪元素为可绘制伪元素：

该伪元素的 used visibility 属性值为 visible。
伪元素的 used opacity 大于零。
伪元素生成了一个非空的 box。

当以下条件全部满足时，CSS 图像 img 为有内容的图像（contentful image）：

img 为url 值。
img 是可用的。

当DOMString 至少包含一个非文档空白字符的字符时，视为非空（non-empty）。

当以下任一条件满足时，元素 target 为有内容（contentful）：

target 有一个文本节点子节点，表示非空文本，并且该节点的使用不透明度大于零。

注：这涵盖了排版伪元素会覆盖文本节点不透明度的情况。
target 是一个替换元素，表示一个可用的图像。
target 有一个 background-image，它是一个有内容的图像，并且其使用的 background-size 的宽度和高度值均非零。
target 有一个 border-image-source，它是一个有内容的图像，并且其使用的 border-image-width 具有非零值。
target 是一个 canvas ，其上下文模式被设置为除 none 之外的任何值。
target 是一个 video 元素，它表示其海报帧或第一个视频帧，并且该帧可用。
target 是一个具有已渲染后代的 SVG 元素。
target 是一个 input 元素，具有一个非空的 value 属性。
target 是一个起源元素，对应一个可绘制的伪元素，该伪元素表示一个有内容的图像或非空文本。

当下列之一成立时，元素为可计时（timing-eligible）：

一个 img 表示有内容图像的元素。
一个 image 位于 svg 元素内的元素。
一个具有video 元素，其具有一个海报帧。
一个元素具有一个background-image，它是一个有内容图像。
一个文本节点。

要计算可绘制包围矩形（paintable bounding rect），请对元素 target执行以下步骤：

令 boundingRect 为在 target 上运行 getBoundingClientRect() 的结果。
用文档的滚动区域剪裁 boundingRect。
返回 boundingRect。

注意：被 overflow: scroll 或 overflow: hidden 包含的元素，其可绘制包围矩形不会被裁剪，因为这两种情况下元素都可以通过滚动变为可见。

当以下条件全部满足时，元素 el 为可绘制（paintable）：

el 正在被渲染。
el 的使用 visibility 为 visible。
el 及其所有祖先的使用不透明度均大于零。

注：可能存在 paintable 元素对用户不可见的情况，例如文本与其背景颜色相同的情况。为了计算首次内容绘制，这些元素仍会被视为可绘制的。
el 的可绘制边界矩形与滚动区域相交，该滚动区域属于文档。

注：这涵盖了元素被缩放为零大小、具有 display: none，或者具有 display: contents 且其内容解析为空矩形的情况。

注：一般而言，元素如果位于视口内，或者通过滚动或缩放可能进入视口，则它是可绘制的。

首次绘制条目包含一个 DOMHighResTimeStamp ，用于报告用户代理在导航后首次渲染的时间。这不包括默认背景绘制，但包括非默认背景绘制以及一个可绘制 iframe 的包围盒。这是开发者在页面加载过程中关注的第一个关键时刻——用户代理开始渲染页面的时刻。

当以下任一条件满足时，浏览上下文 ctx 为可绘制计时（paint-timing eligible）：

ctx 是顶级浏览上下文。
ctx 是嵌套浏览上下文，且用户代理已配置 ctx 上报绘制计时。

注意：这允许用户代理选择性地为部分 frame 启用绘制计时，例如主 frame，以及（如有需要）为某些子 frame 启用。例如，用户代理可决定为跨域 iframe 禁用绘制计时，因为某些场景下其计时可能泄露主 frame 信息。

3. Paint Timing 混入

本节是非规范性的。

The PaintTimingMixin 接口公开与渲染周期相关的时间戳。它包含在扩展 PerformanceEntry 的平台对象中，具体包括 PerformanceElementTiming、 LargestContentfulPaint、 PerformanceEventTiming、 PerformancePaintTiming 和 PerformanceLongAnimationFrameTiming。

paintTime 属性表示更新渲染循环结束时的时间戳，而 presentationTime 表示帧呈现给用户时的特定实现时间戳。在 HTML 标准中从更新渲染调用的标记 paint timing 算法会填充这两个属性。

依赖于绘制时序的条目中的属性，比如 LargestContentfulPaint 的 renderTime （以及它的 startTime），通常返回默认绘制时间戳而不是具体的某个时间戳，这样可以不受 presentationTime 这种具体实现细节的影响。

3.1. `PaintTimingMixin` 接口

[Exposed=Window]
interface mixin PaintTimingMixin {
    readonly attribute DOMHighResTimeStamp paintTime;
    readonly attribute DOMHighResTimeStamp? presentationTime;
};

包含 PaintTimingMixin 接口混入的对象具有一个关联的 paint timing 信息（null 或 paint timing 信息）。

paint timing 信息是一个结构体。它具有以下条目：

渲染更新结束时间: 一个 DOMHighResTimeStamp
实现自定义的呈现时间: Null 或一个 DOMHighResTimeStamp

paintTime 属性的 getter 步骤是返回 this 的 paint timing 信息的渲染更新结束时间。

presentationTime 属性的 getter 步骤（如果存在）是返回 this 的 paint timing 信息的实现定义的呈现时间。

获取默认 paint 时间戳的步骤，对于 paint timing 信息 paintTimingInfo，返回 paintTimingInfo 的实现定义的呈现时间（如果非 null），否则返回 paintTimingInfo 的渲染更新结束时间。

4. `PerformancePaintTiming` 接口

[Exposed=Window]
interface PerformancePaintTiming : PerformanceEntry {
    [Default] object toJSON();
};
PerformancePaintTiming includes PaintTimingMixin;

PerformancePaintTiming 扩展了 PerformanceEntry 接口的以下属性：

name 属性的 getter 必须返回一个 DOMString ，用于最小帧归因。name 的可能值有：
- "first-paint"：用于首次绘制
- "first-contentful-paint"：用于首次内容绘制
entryType 属性的 getter 必须返回 "paint"。
startTime 属性的 getter 必须返回一个 DOMHighResTimeStamp ，表示绘制发生的时刻。
duration 属性的 getter 必须返回 0。
当调用 toJSON 时，需对 PerformancePaintTiming 运行默认 toJSON 步骤。

注意：实现 PerformancePaintTiming 的用户代理需要在某个全局对象的 "paint" 被包含在 supportedEntryTypes 中，且该对象的浏览上下文是绘制时机可用的。这允许开发者检测某个浏览上下文是否支持绘制时机。

5. 处理模型

5.1. 关联图片请求

每个 Element 都有一个关联图片请求，它是一个图片请求或 null，初始为 null。

当某个 Element element 的处理模型为以下类型： HTMLImageElement、 SVGImageElement，或 HTMLVideoElement 创建新的图片资源（例如用于显示图片或海报图片）， element 的关联图片请求会被设置为所创建图片资源的图片请求。

注意：每一个从 URL 获取且 scheme 等于 "data" 的图片资源，都有一个关联的图片请求，它不会被抓取但仍需要被加载。此请求可以作为 Element 的关联图片请求。

注意：当前描述较为模糊，因为未指定具体算法。当相关处理模型更统一后，可进一步严格化。

每个 Element 都有一个关联背景图片请求列表，初始为空数组。当 Element element 的样式需要新的图片资源（用于显示为背景图片），由新资源创建的图片请求会被添加到 element 的关联背景图片请求列表中。

注意：一个 Element 可以有多个图片请求，例如其 background-image 属性有多个值。例如下例中，一个 background-image 属性会产生四个图片请求，这些请求都会被下述算法记录和报告。

<!DOCTYPE html>
<style>
div {
  background-image: url(https://images.example/background1.png),
                    url(https://images.example/background2.png);
}
</style>
<div></div>
<div></div>

5.2. 记录绘制计时

待处理图片记录是一个结构体，包含以下项：

element，一个 Element
request，一个图片请求（image request）
loadTime, DOMHighResTimeStamp

每个 Element 都有一个拥有的文本节点集合（set of owned text nodes），为Text 节点组成的有序集合，初始为空。

每个 Document 都有一个已上报绘制集合（set of previously reported paints），为字符串的有序集合，初始为空。

每个 Document 都有一个待渲染图片列表（images pending rendering），为待处理图片记录（pending image record）的列表，初始为空。

每个 Document 都有一个已渲染文本元素集合（set of elements with rendered text），为Element的有序集合，初始为空。

5.2.1. 对 CSS 规范的修改

每当 Element element 的关联背景图片请求（associated background image requests）中的某个图片请求（image request）变为完全可用时，执行处理已加载完成图片（process an image that finished loading）算法，参数为 element 和该图片请求。

5.2.2. 对 HTML 规范的修改

当 Element element 的关联图片请求（associated image request）变为完全可用时，执行处理已加载完成图片算法，参数为 element 及其关联图片请求。

当用户代理首次绘制 Text 节点 text 时，应执行以下步骤：

如果由于字体处于字体阻塞期（font block period），text 不会被绘制，则返回。
令 element 为确定 text 包含块（containing block）的 Element。
将 text 添加到 element 的拥有的文本节点集合中。

5.2.3. 处理已加载完成图片

要处理已加载完成图片（process an image that finished loading），给定 Element element 和图片请求 imageRequest，按如下步骤：

令 root 为 element 的根节点（root）。
若 root 不是 Document，则返回。
令 now 为 element 的相关全局对象（relevant global object）下的当前高精度时间。
令 record 为待处理图片记录，其 element 为 element，request 为 imageRequest，loadTime 为 now。
将 record 添加到 root 的待渲染图片列表中。

5.3. 上报绘制计时

5.3.1. 首次内容绘制

若要判断文档 document 是否应报告首次内容绘制，请执行以下步骤：

如果 document 的已报告绘制集合包含 "first-contentful-paint"，则返回 false。
如果 document 至少包含一个同时为可绘制且有内容的元素，则返回 true。
否则，返回 false。

5.3.2. 标记绘制计时

当被要求根据作为输入的标记绘制时间，并给定一个 Document document 时，执行以下步骤：

如果文档的浏览上下文不符合绘制计时条件，则返回。
令 paintTimingInfo 为一个新的绘制计时信息，其渲染更新结束时间为以 document 的当前高精度时间，并给定 document 的相关全局对象。
令 paintedImages 为一个新的有序集合
令 paintedTextNodes 为一个新的有序集合
对于 doc 的待渲染图像列表中的每个 record：
1. 如果 record 的请求处于可用状态且已准备好绘制，则执行以下步骤：
  1. 将 record 追加到 paintedImages。
  2. 从 doc 的待渲染图像列表中移除 record。
对于 Element element，它是 doc 的后代之一：
1. 如果 element 包含在 doc 的包含已渲染文本的元素集合中，则继续。
2. 如果 element 的拥有的文本节点集合为空，则继续。
3. 追加 element 到 doc 的包含已渲染文本的元素集合中。
4. 将 element 追加到 paintedTextNodes 中。
令 reportedPaints 为 document 的先前已报告的绘制集合。
令 frameTimingInfo 为 document 的当前帧计时信息。
将 document 的当前帧计时信息设置为 null。
令 flushPaintTimings 为以下步骤：
1. 如果 reportedPaints 不包含 "first-paint"，且用户代理已配置为标记首次绘制，则报告绘制计时，并给定 document、 "first-paint" 和 paintTimingInfo。
  
  注意：首次绘制不包括默认背景绘制，但包括非默认背景绘制。
  
  这应当改为规范性注释。
2. 如果 document 应报告首次内容绘制，则：
  1. 报告绘制计时，并给定 document、"first-contentful-paint" 和 paintTimingInfo。
  注意：父框架不应感知来自其子 iframe 的绘制事件，反之亦然。这意味着仅包含 iframe 的框架会有首次绘制（由于可绘制 iframe 的包围盒），但不会有首次内容绘制。
  
  注意：文档不保证会标记 "first-paint" 或 "first-contentful-paint"。一个完全空白的文档可能永远不会标记首次绘制，而一个文档如果只包含不属于有内容的元素，则可能永远不会标记首次内容绘制。
  
  注意：标记首次绘制是可选的。实现绘制计时的用户代理至少应标记首次内容绘制。
3. 报告最大内容绘制，并给定 document、paintTimingInfo、 paintedImages 和 paintedTextNodes。
4. 报告元素计时，并给定 document、paintTimingInfo、 paintedImages 和 paintedTextNodes。
5. 如果 frameTimingInfo 不为 null，则将长动画帧条目加入队列，并给定 document、frameTimingInfo 和 paintTimingInfo。
如果用户代理不支持实现定义的呈现时间，则调用 flushPaintTimings 并返回。
并行执行以下步骤：
1. 等待至实现定义的时间，此时当前帧已呈现给用户。
2. 将 paintTimingInfo 的实现定义的呈现时间设置为当前高精度时间，并给定 document 的相关全局对象。
3. 如果 document 的跨源隔离能力为 false，则：
  1. 将 paintTimingInfo 的实现定义的呈现时间粗化到下一个 4 毫秒的倍数，或更粗的精度。
  2. 等待直到当前高精度时间等于 paintTimingInfo 的实现定义的呈现时间。
4. 在排入一个全局任务到性能时间线任务源，并给定 document 的相关全局对象，以运行 flushPaintTimings。

5.3.3. 上报绘制计时

要根据参数 document、paintType 和绘制计时信息（paint timing info） paintTimingInfo 执行上报绘制计时，请执行以下步骤：

创建一个新的 PerformancePaintTiming 对象 newEntry，位于 document 的相关 realm，并按如下设置其属性：
1. 设置 newEntry 的 name 属性为 paintType。
2. 设置 newEntry 的 entryType 属性为 "paint"。
3. 设置 newEntry 的 startTime 属性为默认绘制时间戳（default paint timestamp），参数为 paintTimingInfo。
4. 设置 newEntry 的 duration 属性为 0。
设置 newEntry 的绘制计时信息（paint timing info）为 paintTimingInfo。
将 newEntry 加入队列到 document 的相关 realm。
将 paintType 添加到 document 的已上报绘制集合中。

5.4. 通用算法

5.4.1. 对绘制计时暴露

要判断一个元素（Element） element 是否为绘制时序公开，给定一个文档（Document）或 null document，请执行以下步骤：

如果 element 未连接，返回 false。
如果 document 为 null，则令 document 为 element 的相关设置对象（relevant settings object）的相关全局对象的关联文档。
如果 document 不是完全激活，返回 false。
如果 element 的根节点不等于 document，返回 false。
返回 true。

6. 致谢

特别感谢所有贡献者，他们的技术意见和建议促使本规范不断完善。

绘制计时

摘要

文档状态

1. 简介

1.1. 首次绘制与首次内容绘制

1.2. 用法示例

2. 术语

3. Paint Timing 混入

3.1. `PaintTimingMixin` 接口

4. `PerformancePaintTiming` 接口

5. 处理模型

5.1. 关联图片请求

5.2. 记录绘制计时

5.2.1. 对 CSS 规范的修改

5.2.2. 对 HTML 规范的修改

5.2.3. 处理已加载完成图片

5.3. 上报绘制计时

5.3.1. 首次内容绘制

5.3.2. 标记绘制计时

5.3.3. 上报绘制计时

5.4. 通用算法

5.4.1. 对绘制计时暴露

6. 致谢

一致性

文档约定

符合规范的算法

索引

本规范定义的术语

引用定义的术语

参考文献

规范性引用

补充性引用

IDL 索引

Issues Index

绘制计时

摘要

文档状态

1. 简介

1.1. 首次绘制与首次内容绘制

1.2. 用法示例

2. 术语

3. Paint Timing 混入

3.1. PaintTimingMixin 接口

4. PerformancePaintTiming 接口

5. 处理模型

5.1. 关联图片请求

5.2. 记录绘制计时

5.2.1. 对 CSS 规范的修改

5.2.2. 对 HTML 规范的修改

5.2.3. 处理已加载完成图片

5.3. 上报绘制计时

5.3.1. 首次内容绘制

5.3.2. 标记绘制计时

5.3.3. 上报绘制计时

5.4. 通用算法

5.4.1. 对绘制计时暴露

6. 致谢

一致性

文档约定

符合规范的算法

索引

本规范定义的术语

引用定义的术语

参考文献

规范性引用

补充性引用

IDL 索引

Issues Index

3.1. `PaintTimingMixin` 接口

4. `PerformancePaintTiming` 接口