使用者時序 - Web API | MDN

什麼是使用者時序？

瀏覽器會為你提供某些資訊（稱為效能條目），並將其新增到瀏覽器的效能時間軸中。例如，這包括資源時序 API 提供的條目，它們用於確定獲取影像等資源所需的時間。

然而，瀏覽器無法確定你的應用程式內部發生了什麼。例如，當用戶點選按鈕或在你應用程式中執行特定任務時，沒有高精度效能測量。使用者時序 API 是瀏覽器效能時間軸的擴充套件，它幫助你測量和記錄應用程式特有的效能資料。

與呼叫 Date.now() 或 performance.now() 相比，使用此 API 的優勢在於你可以為標記命名，並且它能與效能工具很好地整合。瀏覽器的開發者工具可以在“效能”面板中顯示效能標記，並且它還能與 PerformanceObserver 物件等其他效能 API 一起使用。

新增效能標記

要開始測量應用程式功能效能的第一步，你需要為程式碼中的重要位置新增命名的效能標記。理想情況下，你應該遍歷程式碼庫，確定關鍵路徑和你希望確保其能夠快速執行的重要任務。

performance.mark() 方法用於建立 PerformanceMark。該方法接受一個引數，即標記的 name，如下例所示。

// Place at a location in the code that starts login
performance.mark("login-started");

// Place at a location in the code that finishes login
performance.mark("login-finished");

如果 name 引數不夠，mark() 可以透過一個選項物件進行配置，你可以在其中將額外資訊放入 detail 屬性中，該屬性可以是任何型別。如果需要，你還可以設定一個不同的 startTime。在下面的程式碼中，startTime 被設定為 12.5，並且透過 detail 提供了額外資訊，例如使用的 HTML 元素。

performance.mark("login-started", {
  startTime: 12.5,
  detail: { htmlElement: myElement.id },
});

測量標記之間的時間

現在你已經在應用程式中添加了標記，可以測量它們之間的時間了。

Performance.measure() 方法用於建立 PerformanceMeasure 物件。它接受一個 name 引數（用於標識測量值）以及兩個標記 start 和 end，它將在此之間進行測量。下面的示例建立了一個 "login-duration" 測量，並測量了登入過程的開始到結束之間的時間。

該物件隨後有一個 duration 屬性，它會為你計算結束標記時間戳減去開始標記時間戳。例如，你可以記錄此值或將其傳送到某個分析端點。

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

console.log(loginMeasure.duration);

Performance.measure() 方法也可以透過選項物件進行配置，因此你可以進行更高階的測量或使用 detail 屬性提供額外資訊。

例如，你可以使用 click 事件中的 event.timestamp 屬性，確切瞭解使用者何時點選了登入按鈕，並將其測量到 UI 更新的時間點，也就是這裡的 "login-finished" 標記。

loginButton.addEventListener("click", (clickEvent) => {
  fetch(loginURL).then((data) => {
    renderLoggedInUser(data);

    const marker = performance.mark("login-finished");

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

觀察效能測量

獲取自定義效能測量通知的首選方法是使用 PerformanceObserver 物件。效能觀察器允許你被動地訂閱效能標記和測量值的發生。

function perfObserver(list, observer) {
  list.getEntries().forEach((entry) => {
    if (entry.entryType === "mark") {
      console.log(`${entry.name}'s startTime: ${entry.startTime}`);
    }
    if (entry.entryType === "measure") {
      console.log(`${entry.name}'s duration: ${entry.duration}`);
    }
  });
}
const observer = new PerformanceObserver(perfObserver);
observer.observe({ entryTypes: ["measure", "mark"] });

更多資訊，請參閱 PerformanceObserver。

檢索標記和測量

瀏覽器的效能時間軸中有許多不同的效能條目。有些由瀏覽器新增，有些則可能由你新增，例如上面示例中的登入標記和測量值。

要在單個時間點檢索效能標記和測量值，Performance 介面提供了三個方法，如下所示。

注意： 以下方法不會通知你新的效能標記；你只會獲得在呼叫這些方法時已建立的標記。有關使用 PerformanceObserver 接收新指標可用通知的資訊，請參閱上面的觀察效能測量部分。通常，使用效能觀察器是獲取效能標記和測量值的首選方法。

performance.getEntries() 方法獲取所有效能條目。你可以根據需要進行過濾。

const entries = performance.getEntries();
entries.forEach((entry) => {
  if (entry.entryType === "mark") {
    console.log(`${entry.name}'s startTime: ${entry.startTime}`);
  }
  if (entry.entryType === "measure") {
    console.log(`${entry.name}'s duration: ${entry.duration}`);
  }
});

performance.getEntriesByType(entryType) 方法會按型別過濾條目。

const marks = performance.getEntriesByType("mark");
marks.forEach((entry) => {
  console.log(`${entry.name}'s startTime: ${entry.startTime}`);
});

const measures = performance.getEntriesByType("measure");
measures.forEach((entry) => {
  console.log(`${entry.name}'s duration: ${entry.duration}`);
});

performance.getEntriesByName(name, entryType) 方法允許你按名稱獲取特定的標記或測量值。

// Log all marks named "debug-marks"
const debugMarks = performance.getEntriesByName("debug-mark", "mark");
debugMarks.forEach((entry) => {
  console.log(`${entry.name}'s startTime: ${entry.startTime}`);
});

移除標記和測量

要清理所有效能標記或測量值，或僅清理特定條目，可以使用以下方法：

// Clear all marks
performance.clearMarks();

// Removes the marker with the name "myMarker"
performance.clearMarks("myMarker");

// Clear all measures
performance.clearMeasures();

// Removes the measure with the name "myMeasure"
performance.clearMeasures("myMeasure");