---
title: 自定义时间测量API
slug: Web/API/User_Timing_API
translation_of: Web/API/User_Timing_API
---
<div>{{DefaultAPISidebar("自定义时间测量API")}}</div>

<p><strong><code>User Timing</code></strong>接口允许开发者在浏览器性能时间线中创建针对特定应用的 {{domxref("DOMHighResTimeStamp","时间戳")}}。有两种自定义时间测量事件类型："<code>mark</code>" {{domxref("PerformanceEntry.entryType","事件类型")}}和"<code>measure</code>" {{domxref("PerformanceEntry.entryType","事件类型")}}。</p>

<p><code><strong>mark</strong><font face="Arial, x-locale-body, sans-serif"><span style="background-color: #ffffff;">事件可以指定任意的名字并且可以在放在应用的任何位置，</span></font><strong>measure</strong></code>事件也可以指定为任意的名字，但是需要放在两个mark之间，所以它实际上是两个mark的中间点。</p>

<p>此文档提供了对<code>mark<font face="Arial, x-locale-body, sans-serif"><span style="background-color: #ffffff;">和</span></font></code><code>measure</code>{{domxref("PerformanceEntry.entryType","性能事件类型")}}的概览，包括四个拓展了{{domxref("Performance")}}接口的<code>User Timing</code>方法。 想要了解这两种性能事件类型和相关方法的更多详细内容和示例代码，请查阅<a href="/Web/API/User_Timing_API/Using_the_User_Timing_API">使用自定义时间测量API</a>。</p>

<h2 id="性能标记">性能<code>标记</code></h2>

<p>性能<code><strong>标记</strong></code>是一个由应用创建并指定名称的{{domxref("PerformanceEntry","性能条目")}}。这个标记是浏览器性能时间线上的一个{{domxref("DOMHighResTimeStamp","时间戳")}}。</p>

<h3 id="创建一个性能标记">创建一个性能<code>标记</code></h3>

<p>{{domxref("Performance.mark","performance.mark()")}}方法被用来创建一个性能标记。这个方法需要一个参数，标记的名称（例如<code>performance.mark("mark-1")</code>）。</p>

<p><code>标记的</code>{{domxref("PerformanceEntry","性能入口")}}包含以下属性值:</p>

<ul>
 <li>{{domxref("PerformanceEntry.entryType","entryType")}} - 设置为"<code>mark</code>".</li>
 <li>{{domxref("PerformanceEntry.name","name")}} - 设置为创建该标记时"<code>name</code>"参数传入的值</li>
 <li>{{domxref("PerformanceEntry.startTime","startTime")}} - 设置为<code>标记</code>被取消时的{{domxref("DOMHighResTimeStamp","时间戳")}}。</li>
 <li>{{domxref("PerformanceEntry.duration","duration")}} - 设置为"<code>0</code>" （一个没有时间间隔的标记）</li>
</ul>

<h3 id="检索一个性能标记">检索一个性能<code>标记</code></h3>

<p>{{domxref("Performance")}}接口有三个方法可以用来检索标记：</p>

<dl>
 <dt>{{domxref("Performance.getEntries","performance.getEntries()")}}</dt>
 <dd>返回性能时间线上的所有{{domxref("PerformanceEntry","性能条目")}}。通过筛选{{domxref("PerformanceEntry.entryType","entryType")}}属性为"<code>mark</code>"的条目来获取所有<code>标记</code>条目。</dd>
 <dt>{{domxref("Performance.getEntriesByType","performance.getEntriesByType(entryType)")}}</dt>
 <dd>返回性能事件线上具有指定<code>entryType</code>的{{domxref("PerformanceEntry","性能条目")}}，通过将<code>entryType</code>设置为"<code>mark</code>"来获取所有标记条目。</dd>
 <dt>{{domxref("Performance.getEntriesByName","performance.getEntriesByName(name, entryType)")}}</dt>
 <dd>返回性能时间线上具有指定<code>name</code>和<code>entryType</code>的{{domxref("PerformanceEntry","性能条目")}} 。将<code>entryType</code>设置为"<code>mark</code>"来获得所有的标记条目（通过指定<code>name</code>来检索更具体的条目)。</dd>
</dl>

<h3 id="移除性能标记">移除性能<code>标记</code></h3>

<p>想要从性能事件线上移除一个特定标记，调用<code>performance.clearMarks(name)</code>，<code>name</code>是想要移除的标记的名称。如果这个方法被调用时没有传入任何参数，那么性能时间线上所有标记类型的条目都会被移除。</p>

<h2 id="性能测量">性能<code>测量</code></h2>

<p><code><strong>measure</strong></code>事件同样由程序指定名称，但是它被放在两个标记之间因此实际上是两个标记间的中间点。</p>

<h3 id="创建一个性能测量">创建一个性能<code>测量</code></h3>

<p><code>测量</code>通过调用<code>performance.measure(measureName, startMarkName, endMarkName)</code>来创建，<code>measureName</code>指定了该测量的名称，<code>startMarkName</code>和<code>endMarkName</code>分别指定了性能时间线上该测量前后的两个标记的名称。</p>

<p><code>测量</code>{{domxref("PerformanceEntry","性能条目")}}包含以下属性值:</p>

<ul>
 <li>{{domxref("PerformanceEntry.entryType","entryType")}} - 设置为"<code>measure</code>".</li>
 <li>{{domxref("PerformanceEntry.name","name")}} - 设置为测量被创建时"<code>name</code>"参数给定的值</li>
 <li>{{domxref("PerformanceEntry.startTime","startTime")}} - 设置为<code>measure()</code>被调用时的 {{domxref("DOMHighResTimeStamp","时间戳")}}。</li>
 <li>{{domxref("PerformanceEntry.duration","duration")}} - 设置为该测量间隔{{domxref("DOMHighResTimeStamp")}}（即结束标记时间戳减去开始标记时间戳的差值)。</li>
</ul>

<h3 id="检索性能测量">检索性能<code>测量</code></h3>

<p>{{domxref("Performance")}}接口有三个方法可以检索一个测量：</p>

<dl>
 <dt>{{domxref("Performance.getEntries","performance.getEntries()")}}</dt>
 <dd>返回性能时间线上所有的{{domxref("PerformanceEntry","性能条目")}}。通过筛选{{domxref("PerformanceEntry.entryType","entryType")}}属性为"<code>measure</code>"的条目来获取所有<code>测量</code>条目。</dd>
 <dt>{{domxref("Performance.getEntriesByType","performance.getEntriesByType(entryType)")}}</dt>
 <dd>返回性能事件线上指定<code>entryType</code>的{{domxref("PerformanceEntry","性能条目")}}，通过将<code>entryType</code>设置为"<code>measure</code>"来获取所有的测量条目。</dd>
 <dt>{{domxref("Performance.getEntriesByName","performance.getEntriesByName(name, entryType)")}}</dt>
 <dd>返回性能时间线上具有指定 <code>name</code>和<code>entryType</code>的{{domxref("PerformanceEntry","性能项目")}}，将<code>entryType</code>设置为"<code>measure</code>"来获取所有测量条目（通过指定<code>name</code>参数来检索更具体的条目)。</dd>
</dl>

<h3 id="移除性能测量">移除性能<code>测量</code></h3>

<p>想要从性能时间线上移除一个测量，调用<code>performance.clearMeasures(name)</code>，<code>name</code> 是要移除的测量的名称。如果该方法被调用时没有传入任何参数，那么性能时间线上所有的测量都会被移除。</p>

<h2 id="互操作性">互操作性</h2>

<p>如{{domxref("Performance")}}接口的<a href="/Web/API/Performance#Browser_compatibility">浏览器兼容性</a>表所示，<code>User Timing</code> 方法被大多数桌面和移动浏览器（唯一的例外是桌面Safari和移动版Safari，<a href="https://developer.apple.com/safari/technology-preview/release-notes/#r24">Safari Technology Preview 24已经支持该方法</a>)。</p>

<p>想要测试你的浏览器是否支持该API，运行<code><a href="https://mdn.github.io/dom-examples/performance-apis/perf-api-support.html">perf-api-support</a></code>程序。</p>

<h2 id="相关内容">相关内容</h2>

<ul>
 <li><a href="https://w3c.github.io/user-timing/">User Timing Standard</a>; W3C Editor's Draft</li>
 <li><a href="http://caniuse.com/#search=user-timing">CanIUse data</a></li>
 <li><a href="http://siusin.github.io/perf-timing-primer/">A Primer for Web Performance Timing APIs</a>; Xiaoqian Wu; W3C Editor's Draft</li>
</ul>