绘制计时

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 拥有文本节点子节点，且该文本节点为非空文本，且节点的used opacity 大于零。

注意：覆盖文本节点透明度的排版伪元素也包含在此情形。
target 为表示可用图像的可替换元素。
target 拥有 background-image，其为有内容的图像，且其used background-size 宽高皆大于零。
target 为 canvas 且其上下文模式（context mode）不为 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 的 used visibility 属性为 visible。
el 及其所有祖先的 used opacity 大于零。

注意：存在某些情况下，paintable 元素对用户来说不可见，例如文本颜色与其背景色相同的情况。但对于计算首次内容绘制而言，这些元素仍然被视为 paintable。
el 的 paintable bounding rect 和文档的滚动区域相交。

注意：这覆盖了元素被缩放为零尺寸、display: none、或 display: contents 并且内容解析为空矩形等情况。

注意：一般来说，如果一个元素在视口内，或由于滚动/缩放有可能出现在视口内，则它是 paintable。

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

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

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

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

3. Paint Timing 混入

本节是非规范性的。

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. 标记绘制计时

当需要针对 mark paint timing（标记绘制时序），并以文档（Document） document 作为输入时，执行以下步骤：

如果 document 的浏览上下文不具备绘制时序资格，则返回。
令 paintTimingInfo 为一个新的绘制时序信息（paint timing info），其渲染更新结束时间为 document 的相关全局对象上的当前高精度时间。
令 paintedImages 为一个新的有序集合（ordered set）。
令 paintedTextNodes 为一个新的有序集合。
对于 doc 的待渲染图片列表中的每个 record：
1. 如果 record 的请求可用且已准备好被绘制，则执行以下步骤：
  1. 将 record 追加到 paintedImages。
  2. 从 doc 的待渲染图片列表中移除 record。
对于 doc 的所有后代中的每个 Element element：
1. 如果 element 已包含于 doc 的已绘制文本元素集合（set of elements with rendered text），则继续。
2. 如果 element 的所有权文本节点集合为空，则继续。
3. 将 element 追加到 doc 的已绘制文本元素集合。
4. 将 element 追加到 paintedTextNodes。
令 reportedPaints 为 document 的已报告绘制集合。
令 frameTimingInfo 为 document 的当前帧时序信息（current frame timing info）。
将 document 的当前帧时序信息设为 null。
令 flushPaintTimings 为以下步骤：
1. 如果 reportedPaints 不包含 "first-paint"，且用户代理配置为标记首次绘制，则基于 document、"first-paint" 和 paintTimingInfo 报告绘制时序。
  
  注意：首次绘制不包括默认背景绘制，但包括非默认背景绘制。
  
  此处应改为规范性注记。
2. 如果 document 应报告首次内容绘制，则：
  1. 以 document、"first-contentful-paint" 和 paintTimingInfo 调用报告绘制时序。
  注意：父 frame 不应感知其子 iframe 的绘制事件，反之亦然。这意味着仅包含 iframes 的 frame 会标记首次绘制（因包含了 iframe 的外包框），但不会标记首次内容绘制。
  
  注意：并不保证文档一定会标记 "first-paint" 或 "first-contentful-paint"。一个完全空白的文档可能永远不会标记首次绘制，而只包含非内容元素的文档可能永远不会标记首次内容绘制。
  
  注意：是否标记首次绘制是可选的。实现绘制时序的 user-agent 至少应标记首次内容绘制。
3. 以 document、paintTimingInfo、paintedImages 和 paintedTextNodes 调用报告最大内容绘制（largest contentful paint）。
4. 以 document、paintTimingInfo、paintedImages 和 paintedTextNodes 调用报告元素绘制（element timing）。
5. 如果 frameTimingInfo 非 null，则以 document、frameTimingInfo 和 paintTimingInfo 调用排入长动画帧条目队列（queue a long animation frame entry）。
如果 user-agent 不支持实现自定义的呈现时间，则调用 flushPaintTimings 并返回。
按以下步骤并行运行：
1. 等待实现自定义的某个时刻，直到当前帧已向用户呈现为止。
2. 将 paintTimingInfo 的实现自定义的呈现时间设为 document 的相关全局对象上的当前高精度时间。
3. 如果 document 的跨源隔离能力为 false，则：
  1. 将 paintTimingInfo 的实现自定义的呈现时间粗化为下一个 4 毫秒的倍数或更粗粒度。
  2. 等待，直到当前高精度时间为 paintTimingInfo 的实现自定义的呈现时间。
4. 以 document 的相关全局对象为参数，向 performance timeline 任务源排队一个全局任务，用于执行 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 索引

问题索引

绘制计时

摘要

文档状态

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 索引

问题索引

3.1. `PaintTimingMixin` 接口

4. `PerformancePaintTiming` 接口