Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add a performance entry type for visibility state changes #8206

Merged
merged 1 commit into from
Apr 27, 2023
Merged

Add a performance entry type for visibility state changes #8206

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
81 changes: 81 additions & 0 deletions source
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2717,6 +2717,21 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/resource-timing/#dfn-mark-resource-timing">Mark resource timing</dfn></li>
</ul>

<dt>Performance Timeline</dt>

<dd>
<p>The following terms are defined in <cite>Performance Timeline</cite>: <ref spec=PERFORMANCETIMELINE></p>

<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/performance-timeline/#dom-performanceentry"><code>PerformanceEntry</code></dfn> and its
<dfn data-x="PerformanceEntry-name" data-x-href="https://w3c.github.io/performance-timeline/#dom-performanceentry-name"><code>name</code></dfn>,
<dfn data-x="PerformanceEntry-entryType" data-x-href="https://w3c.github.io/performance-timeline/#dom-performanceentry-entrytype"><code>entryType</code></dfn>,
<dfn data-x="PerformanceEntry-startTime" data-x-href="https://w3c.github.io/performance-timeline/#dom-performanceentry-starttime"><code>startTime</code></dfn>, and
<dfn data-x="PerformanceEntry-duration" data-x-href="https://w3c.github.io/performance-timeline/#dom-performanceentry-duration"><code>duration</code></dfn> attributes.</li>

<li><dfn data-x-href="https://w3c.github.io/performance-timeline/#queue-a-performanceentry">Queue a performance entry</dfn></li>
</ul>
</dd>

<dt>Long Tasks</dt>
Expand Down Expand Up @@ -76637,6 +76652,14 @@ END:VCARD</pre>
<li><p>Set <var>document</var>'s <span>visibility state</span> to
<var>visibilityState</var>.</p></li>

<li><p><span data-x="queue a performance entry">Queue</span> a new
<code>VisibilityStateEntry</code> whose
<span data-x="VisibilityStateEntry-state">visibility state</span> is
<var>visibilityState</var> and whose <span
data-x="VisibilityStateEntry-timestamp">timestamp</span> is
the <span>current high resolution time</span> given <var>document</var>'s
<span>relevant global object</span>.</p>

<li><p>Run the <span>screen orientation change steps</span> with <var>document</var>. <ref
spec=SCREENORIENTATION></p></li>

Expand All @@ -76657,6 +76680,56 @@ END:VCARD</pre>
initialized to true.</p></li>
</ol>

<h4>The <code>VisibilityStateEntry</code> interface</h4>

<p>The <code>VisibilityStateEntry</code> interface exposes visibility changes to the document,
from the moment the document becomes active.</p>

<div class="example">For example, this allows JavaScript code in the page to examine correlation
between visibility changes and paint timing:

<pre><code class="js">function wasHiddenBeforeFirstContentfulPaint() {
const fcpEntry = performance.getEntriesByName("first-contentful-paint")[0];
const visibilityStateEntries = performance.getEntriesByType("visibility-state");
return visibilityStateEntries.some(e =>
e.startTime &lt; fcpEntry.startTime &&
e.name === "hidden");
}</code></pre>
</div>

<p class="note">Since hiding a page can cause throttling of rendering and other user-agent
operations, it is common to use visibility changes as an indication that such throttling has
occurred. However, other things could also cause throttling in different browsers, such as
long periods of inactivity.</p>

<pre><code class="idl">[Exposed=(Window)]
interface <dfn interface>VisibilityStateEntry</dfn> : <span>PerformanceEntry</span> {
readonly attribute DOMString <span data-x="VisibilityStateEntry-name">name</span>; // shadows inherited <span data-x="PerformanceEntry-name">name</span>
readonly attribute DOMString <span data-x="VisibilityStateEntry-entryType">entryType</span>; // shadows inherited <span data-x="PerformanceEntry-entryType">entryType</span>
readonly attribute DOMHighResTimeStamp <span data-x="VisibilityStateEntry-startTime">startTime</span>; // shadows inherited <span data-x="PerformanceEntry-startTime">startTime</span>
readonly attribute unsigned long <span data-x="VisibilityStateEntry-duration">duration</span>; // shadows inherited <span data-x="PerformanceEntry-duration">duration</span>
};</code></pre>

<p>The <code>VisibilityStateEntry</code> has an associated
<span><code>DOMHighResTimeStamp</code></span>
<dfn data-x="VisibilityStateEntry-timestamp">timestamp</dfn>.</p>

<p>The <code>VisibilityStateEntry</code> has an associated "<code data-x="">visible</code>" or
"<code data-x="">hidden</code>" <dfn
data-x="VisibilityStateEntry-state">visibility state</dfn>.</p>

<p>The <dfn data-x="VisibilityStateEntry-name"><code>name</code></dfn> getter steps are to return
<span>this</span>'s <span data-x="VisibilityStateEntry-state">visibility state</span>.</p>

<p>The <dfn data-x="VisibilityStateEntry-entryType"><code>entryType</code></dfn> getter steps are to return
"<code data-x="">visibility-state</code>".</p>

<p>The <dfn data-x="VisibilityStateEntry-startTime"><code>startTime</code></dfn> getter steps are to return
<span>this</span>'s <span data-x="VisibilityStateEntry-timestamp">timestamp</span>.</p>

<p>The <dfn data-x="VisibilityStateEntry-duration"><code>duration</code></dfn> getter steps are to return
zero.</p>


<h3>Inert subtrees</h3>

Expand Down Expand Up @@ -94929,6 +95002,11 @@ location.href = '#foo';</code></pre>
<span>node navigable</span>'s <span data-x="nav-traversable">traversable navigable</span>'s
<span>system visibility state</span>.</p></li>

<li><p><span data-x="queue a performance entry">Queue</span> a new
<code>VisibilityStateEntry</code> whose <span data-x="VisibilityStateEntry-state">visibility
state</span> is <var>document</var>'s <span>visibility state</span> and whose <span
data-x="VisibilityStateEntry-timestamp">timestamp</span> is zero.</p></li>

<li><p>Set <var>window</var>'s <span>relevant settings object</span>'s <span
data-x="concept-environment-execution-ready-flag">execution ready flag</span>.</p></li>
</ol>
Expand Down Expand Up @@ -133509,6 +133587,9 @@ INSERT INTERFACES HERE
<dt id="refsPDF">[PDF]</dt>
<dd>(Non-normative) <cite><a href="https://www.adobe.com/content/dam/Adobe/en/devnet/acrobat/pdfs/PDF32000_2008.pdf">Document management &mdash; Portable document format &mdash; Part 1: PDF</a></cite>. ISO.</dd>

<dt id="refsPERFORMANCETIMELINE">[PERFORMANCETIMELINE]</dt>
<dd><cite><a href="https://w3c.github.io/performance-timeline/">Performance Timeline</a></cite>, N. Peña Moreno, W3C.</dd>

<dt id="refsPERMISSIONSPOLICY">[PERMISSIONSPOLICY]</dt>
<dd><cite><a href="https://w3c.github.io/webappsec-feature-policy/">Permissions Policy</a></cite>, I. Clelland, W3C.</dd>

Expand Down