Performance: measure() 方法

语法

measure(measureName)
measure(measureName, startMark)
measure(measureName, startMark, endMark)
measure(measureName, measureOptions)
measure(measureName, measureOptions, endMark)

如果仅指定了 measureName，则开始时戳设置为零，结束时戳（用于计算持续时间）将是 Performance.now() 返回的值。

您可以使用字符串来标识 PerformanceMark 对象作为开始和结束标记。

要仅提供 endMark，您需要提供一个空的 measureOptions 对象：performance.measure("myMeasure", {}, "myEndMarker")。

参数

measureName

一个代表测量名称的字符串。

measureOptions 可选

一个可能包含测量选项的对象。

detail 可选

要包含在测量中的任意元数据。默认为 null。必须是 结构克隆 的。

start 可选

用作开始时间的时间戳 (DOMHighResTimeStamp)，或者命名 PerformanceMark 以用于开始时间的字符串。

如果这是一个命名 PerformanceMark 的字符串，则它的定义方式与 startMark 相同。

duration 可选

开始标记和结束标记之间的时间（以毫秒为单位）。如果省略，则默认为 performance.now()；即自上下文创建以来经过的时间。如果提供了此参数，则必须同时指定 start 或 end，但不能同时指定两者。

end 可选

用作结束时间的时间戳 (DOMHighResTimeStamp)，或者命名 PerformanceMark 以用于结束时间的字符串。

如果这是一个命名 PerformanceMark 的字符串，则它的定义方式与 endMark 相同。

startMark 可选

一个在性能时间轴中命名 PerformanceMark 的字符串。此标记的 PerformanceEntry.startTime 属性将用于计算测量值。

endMark 可选

一个在性能时间轴中命名 PerformanceMark 的字符串。此标记的 PerformanceEntry.startTime 属性将用于计算测量值。如果要传递此参数，则必须同时传递 startMark 或一个空的 measureOptions 对象。

返回值

已创建的 PerformanceMeasure 条目。

返回的测量将具有以下属性值：

• entryType - 设置为 "measure"。

• name - 设置为 name 参数。

• startTime - 设置为：

  • 如果 measureOptions.start 中指定了时间戳，则为 timestamp。
  • 如果 measureOptions.start 或 startMark 中指定了开始标记的时间戳，则为该 timestamp。
  • 如果未指定 measureOptions.start，则根据 measureOptions.end 和 measureOptions.duration 计算的时间戳。
  • 如果未指定且无法从其他值确定，则为 0。

• duration - 设置为 DOMHighResTimeStamp，这是通过从结束时戳中减去 startTime 计算出的测量持续时间。

  结束时戳为以下之一：

  • 如果 measureOptions.end 中指定了时间戳，则为 timestamp。
  • 如果 measureOptions.end 或 endMark 中指定了结束标记的时间戳，则为该 timestamp。
  • 如果未指定 measureOptions.end，则根据 measureOptions.start 和 measureOptions.duration 计算的时间戳。
  • 如果没有指定结束标记或无法从其他值确定，则为 Performance.now() 返回的值。

• detail - 设置为 measureOptions 中传递的值。

异常

TypeError

在开始、结束或持续时间可能不明确的任何情况下，都可能引发此错误：

• 同时指定了 endMark 和 measureOptions。
• measureOptions 指定了 duration，但未指定 start 或 end。
• measureOptions 指定了 start、end 和 duration。

SyntaxError DOMException

命名的标记不存在。

• 使用 endMark 或 measureOptions.end 指定了结束标记，但在性能缓冲区中没有同名 PerformanceMark。
• 使用 endMark 或 measureOptions.end 指定了结束标记，但它无法转换为匹配 PerformanceTiming 接口中的只读属性。
• 使用 startMark 或 measureOptions.start 指定了开始标记，但在性能缓冲区中没有同名 PerformanceMark。
• 使用 startMark 或 measureOptions.start 指定了开始标记，但它无法转换为匹配 PerformanceTiming 接口中的只读属性。

DataCloneError DOMException

measureOptions.detail 的值为非 null，并且无法使用 HTML“StructuredSerialize”算法进行序列化。

RangeError

measureOptions.detail 的值为非 null，并且在使用 HTML“StructuredSerialize”算法进行序列化时无法分配内存。

示例

测量命名标记之间的持续时间

给定您自己的两个标记 "login-started" 和 "login-finished"，您可以创建一个名为 "login-duration" 的测量，如下例所示。返回的 PerformanceMeasure 对象将提供一个 duration 属性，告诉您两个标记之间经过的时间。

const loginMeasure = performance.measure(
  "login-duration",
  "login-started",
  "login-finished",
);
console.log(loginMeasure.duration);

使用自定义开始和结束时间测量持续时间

为了进行更高级的测量，您可以传递 measureOptions 参数。例如，您可以使用 click 事件 的 event.timeStamp 属性作为开始时间。

performance.measure("login-click", {
  start: myClickEvent.timeStamp,
  end: myMarker.startTime,
});

提供额外的测量细节

您可以使用 details 属性提供任何类型的额外信息。例如，您可能想记录点击了哪个 HTML 元素。

performance.measure("login-click", {
  detail: { htmlElement: myElement.id },
  start: myClickEvent.timeStamp,
  end: myMarker.startTime,
});

规范

浏览器兼容性