资源计时

本节是非规范性的。

由非 null 客户端获取的资源请求会作为 PerformanceResourceTiming 对象包含在客户端的全局对象的性能时间轴中，除非在获取过程中被排除在时间轴之外。从 HTTP 缓存中检索的资源会作为 PerformanceResourceTiming 对象包含在性能时间轴中。已启动获取但稍后中止（例如由于网络错误）的资源会作为PerformanceResourceTiming 对象包含在性能时间轴中，并带有其开始和结束计时。

示例：

• 如果将相同的规范 URL 用作两个 HTML IMG 元素的 src 属性，则由第一个 HTML IMG 元素启动的资源的获取将作为 PerformanceResourceTiming 对象包含在性能时间轴中。用户代理可能不会为第二个 HTML IMG 元素重新请求该 URL，而是使用它为第一个 HTML IMG 元素启动的现有下载。在这种情况下，第一个 IMG 元素对资源的获取将是性能时间轴中的唯一一次出现。
• 如果通过脚本更改 HTML IMG 元素的 src 属性，则原始资源的获取以及新 URL 的获取都将作为 PerformanceResourceTiming 对象包含在性能时间轴中。
• 如果通过标记添加 HTML IFRAME 元素而未指定 src 属性，则用户代理可能会为该 IFRAME 加载 about:blank 文档。如果稍后通过脚本动态更改 src 属性，则用户代理可能会为该 IFRAME 获取新的 URL 资源。在这种情况下，只有新 URL 的获取才会作为 PerformanceResourceTiming 对象包含在性能时间轴中。
• 如果为相同的规范 URL 生成两次 XMLHttpRequest，则资源的两次获取都将作为 PerformanceResourceTiming 对象包含在性能时间轴中。这是因为第二个 XMLHttpRequest 对资源的获取无法重用为第一个 XMLHttpRequest 发出的下载。
• 如果在页面上包含 HTML IFRAME 元素，则只有由 IFRAME src 属性请求的资源才会作为 PerformanceResourceTiming 对象包含在性能时间轴中。由 IFRAME 文档请求的子资源将包含在 IFRAME 文档的性能时间轴中，而不是父文档的性能时间轴中。
• 如果 HTML IMG 元素的源是 data: URI [RFC2397]，则此资源不会作为 PerformanceResourceTiming 对象包含在性能时间轴中。PerformanceResourceTiming 条目仅针对 http(s) 资源报告。
• 如果由于网络错误（例如 DNS、TCP 或 TLS 错误）而中止了资源获取，则该获取将作为 PerformanceResourceTiming 对象包含在性能时间轴中，并且仅设置 startTime、fetchStart、duration 和 responseEnd。
• 如果由于未能满足获取前提条件（例如混合内容、CORS 限制、CSP 策略等）而中止了资源获取，则此资源不会作为 PerformanceResourceTiming 对象包含在性能时间轴中。

WebIDL[Exposed=(Window,Worker)]
interface PerformanceResourceTiming : PerformanceEntry {
    readonly attribute DOMString initiatorType;
    readonly attribute DOMString deliveryType;
    readonly attribute ByteString nextHopProtocol;
    readonly attribute DOMHighResTimeStamp workerStart;
    readonly attribute DOMHighResTimeStamp redirectStart;
    readonly attribute DOMHighResTimeStamp redirectEnd;
    readonly attribute DOMHighResTimeStamp fetchStart;
    readonly attribute DOMHighResTimeStamp domainLookupStart;
    readonly attribute DOMHighResTimeStamp domainLookupEnd;
    readonly attribute DOMHighResTimeStamp connectStart;
    readonly attribute DOMHighResTimeStamp connectEnd;
    readonly attribute DOMHighResTimeStamp secureConnectionStart;
    readonly attribute DOMHighResTimeStamp requestStart;
    readonly attribute DOMHighResTimeStamp finalResponseHeadersStart;
    readonly attribute DOMHighResTimeStamp firstInterimResponseStart;
    readonly attribute DOMHighResTimeStamp responseStart;
    readonly attribute DOMHighResTimeStamp responseEnd;
    readonly attribute unsigned long long  transferSize;
    readonly attribute unsigned long long  encodedBodySize;
    readonly attribute unsigned long long  decodedBodySize;
    readonly attribute unsigned short responseStatus;
    readonly attribute RenderBlockingStatusType renderBlockingStatus;
    readonly attribute DOMString contentType;
    readonly attribute DOMString contentEncoding;
    [Default] object toJSON();
};

一个 PerformanceResourceTiming 具有一个关联的 DOMString 发起者类型。

一个 PerformanceResourceTiming 具有一个关联的 DOMString 交付类型。

一个 PerformanceResourceTiming 具有一个关联的 DOMString 请求的 URL。

一个 PerformanceResourceTiming 具有一个关联的 DOMString 缓存模式 （空字符串、“local”或“validated”）。

一个 PerformanceResourceTiming 有一个关联的 获取计时信息 计时信息。

一个 PerformanceResourceTiming 有一个关联的 响应体信息 资源信息。

一个 PerformanceResourceTiming 具有一个关联的 状态 响应状态。

一个 PerformanceResourceTiming 具有一个关联的 RenderBlockingStatusType 渲染阻塞状态。

当调用 toJSON 时，为 PerformanceResourceTiming 运行默认 toJSON 步骤。

initiatorType getter 步骤是为 this 返回发起者类型。

deliveryType getter 步骤是为 this 返回交付类型。

workerStart getter 步骤是为 this 的 计时信息的 最终 service worker 启动时间和 this 的相关全局对象转换获取时间戳。更多信息请参见 HTTP 获取。

redirectStart getter 步骤是为 this 的 计时信息的 重定向开始时间和 this 的相关全局对象转换获取时间戳。更多信息请参见 HTTP 重定向获取。

redirectEnd getter 步骤是为 this 的 计时信息的 重定向结束时间和 this 的相关全局对象转换获取时间戳。更多信息请参见 HTTP 重定向获取。

fetchStart getter 步骤是为 this 的 计时信息的 重定向后开始时间和 this 的相关全局对象转换获取时间戳。更多信息请参见 HTTP 获取。

domainLookupStart getter 步骤是为 this 的 计时信息的 最终连接计时信息的 域名查找开始时间和 this 的相关全局对象转换获取时间戳。更多信息请参见记录连接计时信息。

domainLookupEnd getter 步骤是为 this 的 计时信息的 最终连接计时信息的 域名查找结束时间和 this 的相关全局对象转换获取时间戳。更多信息请参见记录连接计时信息。

connectStart getter 步骤是为 this 的 计时信息的 最终连接计时信息的 连接开始时间和 this 的相关全局对象转换获取时间戳。更多信息请参见记录连接计时信息。

connectEnd getter 步骤是为 this 的 计时信息的 最终连接计时信息的 连接结束时间和 this 的相关全局对象转换获取时间戳。更多信息请参见记录连接计时信息。

secureConnectionStart getter 步骤是为 this 的 计时信息的 最终连接计时信息的 安全连接开始时间和 this 的相关全局对象转换获取时间戳。更多信息请参见记录连接计时信息。

nextHopProtocol getter 步骤是同构解码 this 的 计时信息的 最终连接计时信息的 ALPN 协商协议。更多信息请参见记录连接计时信息。

requestStart getter 步骤是为 this 的 计时信息的 最终网络请求开始时间和 this 的相关全局对象转换获取时间戳。更多信息请参见 HTTP 获取。

firstInterimResponseStart getter 步骤是为 this 的 计时信息的 第一个临时网络响应开始时间和 this 的相关全局对象转换获取时间戳。更多信息请参见 HTTP 获取。

finalResponseHeadersStart getter 步骤是为 this 的 计时信息的 最终网络响应开始时间和 this 的相关全局对象转换获取时间戳。更多信息请参见 HTTP 获取。

responseStart getter 步骤是返回 this 的 firstInterimResponseStart（如果不为 0）；否则返回 this 的 finalResponseHeadersStart。

responseEnd getter 步骤是为 this 的 计时信息的 结束时间和 this 的相关全局对象转换获取时间戳。更多信息请参见 获取。

encodedBodySize getter 步骤是返回 this 的 资源信息的 编码大小。

decodedBodySize getter 步骤是返回 this 的 资源信息的 解码大小。

transferSize getter 的步骤是：

1. 如果 this 的 缓存模式是“local”，则返回 0。

2. 如果 this 的 缓存模式是“validated”，则返回 300。

3. 返回 this 的 响应体信息的 编码大小加 300。

   注意

   添加到 transferSize 的常量数字取代了公开 HTTP 标头的总字节大小，因为这可能会暴露某些 cookie 的存在。请参见此问题。

responseStatus getter 步骤是返回 this 的 响应状态。

contentType getter 步骤是返回 this 的 资源信息的 内容类型。

contentEncoding getter 的步骤是返回 此对象的资源信息的内容编码。

renderBlockingStatus getter 步骤是如果 this 的 计时信息的 渲染阻塞为 true，则返回 blocking；否则返回 non-blocking。

WebIDLenum RenderBlockingStatusType {
                "blocking",
                "non-blocking"
            };

用户代理 可以 限制多少资源作为 PerformanceResourceTiming 对象包含在 性能时间线 中 [PERFORMANCE-TIMELINE-2]。此部分扩展了 Performance 接口，以允许控制存储的 PerformanceResourceTiming 对象的数量。

推荐的 PerformanceResourceTiming 对象的最小数量是 250，尽管此数量可能会由用户代理更改。 可以调用 setResourceTimingBufferSize 来请求更改此限制。

每个 ECMAScript 全局环境 都有：

• 一个 资源计时缓冲区大小限制，最初应为 250 或更大。
• 一个 资源计时缓冲区当前大小，最初为 0。
• 一个 资源计时缓冲区已满事件挂起标志，最初为 false。
• 一个 资源计时次要缓冲区当前大小，最初为 0。
• 一个 资源计时次要缓冲区，用于存储最初为空的 PerformanceResourceTiming 对象。

WebIDLpartial interface Performance {
          undefined clearResourceTimings ();
          undefined setResourceTimingBufferSize (unsigned long maxSize);
          attribute EventHandler onresourcetimingbufferfull;
        };

Performance 接口定义在 [HR-TIME] 中。

clearResourceTimings 方法运行以下步骤：

1. 删除 PerformanceResourceTiming 对象在 性能条目缓冲区 中的所有实例。
2. 将 资源计时缓冲区当前大小 设置为 0。

setResourceTimingBufferSize 方法运行以下步骤：

1. 将 资源计时缓冲区大小限制 设置为 maxSize 参数。如果 maxSize 参数小于 资源计时缓冲区当前大小，则不从 性能条目缓冲区 中删除任何 PerformanceResourceTiming 对象。

onresourcetimingbufferfull 是 resourcetimingbufferfull 事件的事件处理程序，描述如下。

要检查 是否可以添加资源计时条目，请执行以下步骤：

1. 如果 资源计时缓冲区当前大小 小于 资源计时缓冲区大小限制，则返回 true。
2. 返回 false。

要 添加 PerformanceResourceTiming 条目 new entry 到 性能条目缓冲区 中，请执行以下步骤：

1. 如果 是否可以添加资源计时条目 返回 true 且 资源计时缓冲区已满事件挂起标志 为 false，请执行以下子步骤：
   1. 将 new entry 添加到 性能条目缓冲区。
   2. 将 资源计时缓冲区当前大小 增加 1。
   3. 返回。
2. 如果 资源计时缓冲区已满事件挂起标志 为 false，请执行以下子步骤：
   1. 将 资源计时缓冲区已满事件挂起标志 设置为 true。
   2. 排队任务 到 性能时间线任务源，运行 触发缓冲区已满事件。
3. 将 new entry 添加到 资源计时次要缓冲区 中。
4. 将 资源计时次要缓冲区当前大小 增加 1。

要 复制次要缓冲区，请执行以下步骤：

1. 当 资源计时次要缓冲区 非空时，并且 是否可以添加资源计时条目 返回 true，请运行以下子步骤：
   1. 将 entry 设置为最旧的 PerformanceResourceTiming 在 资源计时次要缓冲区 中。
   2. 将 entry 添加到 性能条目缓冲区 的末尾。
   3. 将 资源计时缓冲区当前大小 增加 1。
   4. 将 entry 从 资源计时次要缓冲区 中移除。
   5. 将 资源计时次要缓冲区当前大小 减少 1。

要 触发缓冲区已满事件，请执行以下步骤：

1. 当 资源计时次要缓冲区 非空时，请运行以下子步骤：
   1. 将 number of excess entries before 设置为 资源计时次要缓冲区当前大小。
   2. 如果可以添加资源计时条目返回 false，则在 Performance 对象上触发一个名为 resourcetimingbufferfull 的事件。
   3. 运行 复制次要缓冲区。
   4. 将 number of excess entries after 设置为 资源计时次要缓冲区当前大小。
   5. 如果 number of excess entries before 小于等于 number of excess entries after，则从 资源计时次要缓冲区 中移除所有条目， 将 资源计时次要缓冲区当前大小 设置为 0，并中止这些步骤。
2. 将 资源计时缓冲区已满事件挂起标志 设置为 false。
   注

   这意味着，如果 resourcetimingbufferfull 事件处理程序没有比它向缓冲区添加的资源腾出更多空间， 则多余的条目将从缓冲区中丢弃。开发者应该确保 resourcetimingbufferfull 事件处理程序调用 clearResourceTimings 或足够扩展缓冲区（通过调用 setResourceTimingBufferSize）。

服务器端应用程序可以返回 Timing-Allow-Origin HTTP 响应头，以允许用户代理完全向指定的文档源公开那些由于跨域限制而设置为零的属性值。

本节是非规范性的。

下图说明了 PerformanceResourceTiming 接口定义的计时属性。在获取跨域资源时，括号中的属性可能不可用。用户代理可能会在计时之间执行内部处理，这允许计时之间存在非规范性间隔。

要标记资源计时，给定一个 获取计时信息 timingInfo、一个 DOMString requestedURL、一个 DOMString initiatorType、一个全局对象 global、一个字符串 cacheMode、一个 响应体信息 bodyInfo、一个 状态 responseStatus 以及一个可选的字符串 deliveryType（默认为空字符串），请执行以下步骤：

1. 在 global 的领域中创建一个 PerformanceResourceTiming 对象 entry。
2. 给定 initiatorType、requestedURL、timingInfo、cacheMode、bodyInfo、responseStatus 和 deliveryType，为 entry 设置资源计时条目。
3. 排队 entry。
4. 将 entry 添加到 global 的性能条目缓冲区。

要为 PerformanceResourceTiming entry 设置资源计时条目，给定 DOMString initiatorType、DOMString requestedURL、获取计时信息 timingInfo、一个 DOMString cacheMode、一个 响应体信息 bodyInfo、一个 状态 responseStatus 以及一个可选的 DOMString deliveryType（默认为空字符串），请执行以下步骤：

1. 断言 cacheMode 为空字符串、"local" 或 "validated"。
2. 令 global 为 entry 的相关全局对象。
3. 初始化 entry，给定转换 timingInfo 的开始时间（给定 global）、"resource"、requestedURL 以及转换 timingInfo 的结束时间（给定 global）的结果。
4. 将 entry 的发起者类型设置为 initiatorType。
5. 将 entry 的请求的 URL 设置为 requestedURL。
6. 将 entry 的计时信息设置为 timingInfo。
7. 将 entry 的响应体信息设置为 bodyInfo。
8. 将 entry 的缓存模式设置为 cacheMode。
9. 将 entry 的响应状态设置为 responseStatus。
10. 如果 deliveryType 为空字符串且 cacheMode 不为空，则将 deliveryType 设置为 "cache"。
11. 将 entry 的交付类型设置为 deliveryType。

要转换获取时间戳，给定 DOMHighResTimeStamp ts 和全局对象 global，请执行以下操作：

1. 如果 ts 为零，则返回零。
2. 否则，返回给定 ts 和 global 的相对高精度粗略时间。