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,
});

規範

瀏覽器相容性