Resource Timing API 文檔翻譯（未完）

187J3X1 發(fā)布于2019-08-21 11:40 / 3717人閱讀

摘要：本文檔的狀態(tài)簡介本節(jié)是非規(guī)范的。用戶延遲是應(yīng)用程序的重要基準(zhǔn)。雖然基于的機(jī)制可以為應(yīng)用程序中的用戶延遲測(cè)量提供全面的測(cè)試，但在許多情況下，它們無法提供完整的端到端延遲描述。本文檔介紹了接口，允許機(jī)制收集與文檔資源相關(guān)的完整時(shí)序信息。

原文鏈接：

Resource Timing Level 1

Resource Timing Level 1 W3C Candidate Recommendation 30 March 2017

This version:

https://www.w3.org/TR/2017/CR-resource-timing-1-20170330/

Latest published version:

https://www.w3.org/TR/resource-timing-1/

Latest editor"s draft:

https://w3c.github.io/resource-timing/

Implementation report:

https://w3c.github.io/test-results/resource-timing/all.html

Previous version:

https://www.w3.org/TR/2016/CR-resource-timing-1-20160721/

Editors:

Arvind Jain, Google Inc., arvind@google.com (Until December 2014)

Todd Reifsteck, Microsoft Corp., toddreif@microsoft.com

Jatinder Mann, Microsoft Corp., jmann@microsoft.com (Until February 2014)

Zhiheng Wang, Google Inc. (Until July 2012)

Anderson Quach, Microsoft Corp. (Until March 2011)

Repository:

We are on Github.

File a bug.

Commit history.

Mailing list:

public-web-perf@w3.org

Implementation:

Can I use Resource Timing?

Test Suite

Test Suite repository

摘要

該規(guī)范定義了一個(gè)接口，用于web應(yīng)用程序獲得一個(gè)文檔中完整的資源時(shí)序信息。

本文檔的狀態(tài)

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

Implementers are encouraged to look at the latest version of Resource Timing before implementing this Candidate Recommendation.

This specification uses DOMHighResTimeStamp and time origin from High Resolution Time Level 2 [HR-TIME-2]. These were also defined in High Resolution Time Level 1 but Level 2 provides more refined definitions.

This document was published by the Web Performance Working Group as a Candidate Recommendation. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-web-perf@w3.org (subscribe, archives) with [ResourceTiming] at the start of your email"s subject. W3C publishes a Candidate Recommendation to indicate that the document is believed to be stable and to encourage implementation by the developer community. This Candidate Recommendation is expected to advance to Proposed Recommendation no earlier than 27 April 2017. All comments are welcome.

Please see the Working Group"s implementation report.

Publication as a Candidate Recommendation does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of theW3C Patent Policy.

This document is governed by the 1 March 2017 W3C Process Document.

1. 簡介

本節(jié)是非規(guī)范的。

用戶延遲是web應(yīng)用程序的重要基準(zhǔn)。雖然基于JavaScript的機(jī)制可以為應(yīng)用程序中的用戶延遲測(cè)量提供全面的測(cè)試，但在許多情況下，它們無法提供完整的端到端延遲描述（picture？）。本文檔介紹了PerformanceResourceTiming接口，允許JavaScript機(jī)制收集與文檔資源相關(guān)的完整時(shí)序信息。Navigation Timing 2 [NAVIGATION-TIMING-2] 擴(kuò)展了本規(guī)范，以提供與導(dǎo)航相關(guān)聯(lián)的附加時(shí)序信息。

下面是一個(gè)簡單的例子，展示了如何計(jì)算出獲取一個(gè)資源所需的時(shí)間：

例 1

盡管這段腳本可以計(jì)算出獲取一個(gè)資源所需的時(shí)間，但是它不能分解到這其中的各個(gè)階段。而且，這種方式難以去計(jì)算標(biāo)記中的資源（Further, the script cannot easily measure the time it takes to fetch resources described in markup）。

為了滿足用戶體驗(yàn)的完整信息的需要，本文檔介紹了 PerformanceResourceTiming 接口。此接口允許JavaScript機(jī)制（mechanisms？？？）在應(yīng)用程序中提供完整的客戶端延遲測(cè)量。使用此接口，可以修改前面的示例來測(cè)量用戶感知的資源加載時(shí)間。

以下腳本計(jì)算獲取頁面中每個(gè)資源所需的時(shí)間，即使是在標(biāo)記中定義的資源。This example assumes that this page is hosted on https://www.w3.org. One could further measure the amount of time it takes in every phase of fetching a resource with the PerformanceResourceTiming interface.此示例假定此頁面托管在https://www.w3.org上。可以使用PerformanceResourceTiming接口獲取資源在每個(gè)階段所花費(fèi)的時(shí)間。

例 2

2. 一致性（Conformance）

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words may, must, must not, and should are to be interpreted as described in [RFC2119].

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Some conformance requirements are phrased as requirements on attributes, methods or objects. Such requirements are to be interpreted as requirements on user agents.

Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)

The IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [WebIDL]

3. 術(shù)語（Terminology）

The construction "a Foo object", where Foo is actually an interface, is sometimes used instead of the more accurate "an object implementing the interface Foo".

The term DOM is used to refer to the API set made available to scripts in Web applications, and does not necessarily imply the existence of an actual Document object or of any other Node objects as defined in the DOM specification. [DOM]

A DOM attribute is said to be getting when its value is being retrieved (such as by author script), and is said to be setting when a new value is assigned to it.

The term JavaScript is used to refer to ECMA262, rather than the official term ECMAScript, since the term JavaScript is more widely known. [ECMA-262]

The term resource is used to refer to elements and any other user-initiated fetches throughout this specification. For example, a resource could originate from XMLHttpRequest objects [[XMLHttpRequest], HTML elements [HTML51] such as iframe, img, script, object, embed, and link with the link type of stylesheet, and SVG elements [SVG11] such as svg.

The term cross-origin is used to mean non same origin.

The term current document refers to the document associated with the Window object"s newest Document object.

Throughout this work, all time values are measured in milliseconds since the start of navigation of the document [HR-TIME-2]. For example, the start of navigation of the document occurs at time 0.

The term current time refers to the number of milliseconds since the start of navigation of the document until the current moment in time.

NOTE

This definition of time is based on the High Resolution Time specification [HR-TIME-2] and is different from the definition of time used in the Navigation Timing specification [NAVIGATION-TIMING], where time is measured in milliseconds since midnight of January 1, 1970 (UTC).

4. Resource Timing 4.1 Introduction

This section is non-normative.

The PerformanceResourceTiming interface facilitates timing measurement of downloadable resources. For example, this interface is available for XMLHttpRequest objects [XHR], HTML elements [HTML51] such as iframe,img, script, object, embed, and link with the link type of stylesheet, and SVG elements [SVG11] such as svg.

4.2 Resources Included in the PerformanceResourceTiming Interface

All resources fetched by the current browsing [HTML51] or worker [WORKERS] context"s must be included as PerformanceResourceTiming objects in the Performance Timeline of the relevant context, without violating the origin policy. Resources that are retrieved from relevant application caches or local resources must be included as PerformanceResourceTiming objects in the Performance Timeline [PERFORMANCE-TIMELINE-2].

Aborted requests or requests that don"t return a response may be included as PerformanceResourceTiming objects in the Performance Timeline of the relevant context.

NOTE

Future versions of this specification could require the inclusion of aborted requests or requests that don"t return a response (see issue 12).

NOTE

Implementers should be aware of Issue 27: Same-origin policy & observing no-cors fetches.

The rest of this section is non-normative.

Examples:

If the same canonical URL is used as the src attribute of two HTML IMG elements, the fetch of the resource initiated by the first HTML IMG element should be included as a PerformanceResourceTiming object in the Performance Timeline. The user agent might not re-request the URL for the second HTML IMG element, instead using the existing download it initiated for the first HTML IMG element. In this case, the fetch of the resource by the first IMG element would be the only occurrence in the Performance Timeline.

If the src attribute of a HTML IMG element is changed via script, both the fetch of the original resource as well as the fetch of the new URL would be included as PerformanceResourceTiming objects in the Performance Timeline.

If an HTML IFRAME element is added via markup without specifying a src attribute, the user agent may load the about:blank document for the IFRAME. If at a later time the src attribute is changed dynamically via script, the user agent may fetch the new URL resource for the IFRAME. In this case, only the fetch of the new URL would be included as a PerformanceResourceTiming object in the Performance Timeline.

If an XMLHttpRequest is generated twice for the same canonical URL, both fetches of the resource would be included as a PerformanceResourceTiming object in the Performance Timeline. This is because the fetchof the resource for the second XMLHttpRequest cannot reuse the download issued for the first XMLHttpRequest.

If an HTML IFRAME element is included on the page, then only the resource requested by IFRAME src attribute is included as a PerformanceResourceTiming object in the Performance Timeline. Sub-resources requested by the IFRAME document will be included in the IFRAME document"s Performance Timeline and not the parent document"s Performance Timeline.

If an HTML IMG element has a data: URI as its source [RFC2397], then this resource will not be included as a PerformanceResourceTiming object in the Performance Timeline. By definition data: URI contains embedded data and does not require a fetch.

If a resource fetch was aborted due to a networking error (e.g. DNS, TCP, or TLS error), then the fetch would be included as a PerformanceResourceTiming object in the Performance Timeline with initialized attribute values up to the point of failure - e.g. a TCP handshake error should report DNS timestamps for the request, and so on.

If a resource fetch is aborted because it failed a fetch precondition (e.g. mixed content, CORS restriction, CSP policy, etc), then this resource will not be included as a PerformanceResourceTiming object in the Performance Timeline.

4.3 The PerformanceResourceTiming Interface

The PerformanceResourceTiming interface participates in the Performance Timeline and extends the following attributes of the PerformanceEntry interface:

name

This attribute must return the resolved URL of the requested resource. This attribute must not change even if the fetch redirected to a different URL.

entryType

The entryType attribute must return the DOMString "resource".

startTime

The startTime attribute must return a DOMHighResTimeStamp [HR-TIME-2] with the time immediately before the user agent starts to queue the resource for fetching. If there are HTTP redirects or equivalentwhen fetching the resource, and if all the redirects or equivalent are from the same origin as the current document or the timing allow check algorithm passes, this attribute must return the same value as redirectStart. Otherwise, this attribute must return the same value as fetchStart.

duration

The duration attribute must return a DOMHighResTimeStamp equal to the difference between responseEnd and startTime, respectively.

[Exposed=(Window)]
interface PerformanceResourceTiming : PerformanceEntry {
    readonly attribute DOMString           initiatorType;
    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 responseStart;
    readonly attribute DOMHighResTimeStamp responseEnd;
    serializer = {inherit, attribute};
};

On getting, the initiatorType attribute must return one of the following DOMString:

The same value as the localName of that element [DOM], if the initiator is an element.

"css", if the initiator is a CSS resource downloaded by the url() syntax [CSS-SYNTAX-3], such as @import url() or background: url().

"xmlhttprequest", if the initiator is an XMLHttpRequest object [XHR].

On getting, the redirectStart attribute must return as follows:

The time immediately before the user agent starts to fetch the resource that initiates the redirect, if there are HTTP redirects or equivalent when fetching the resource and all the redirects or equivalent pass the timing allow check algorithm.

zero, otherwise.

On getting, the redirectEnd attribute must return as follows:

The time immediately after receiving the last byte of the response of the last redirect, if there are HTTP redirects or equivalent when fetching the resource and all the redirects or equivalent pass the timing allow check algorithm.

zero, otherwise.

On getting, the fetchStart attribute must return as follows:

The time immediately before the user agent starts to fetch the final resource in the redirection, if there are HTTP redirects or equivalent.

The time immediately before the user agent starts to fetch the resource otherwise.

On getting, the domainLookupStart attribute must return as follows: