Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

使用可擴充的 API 自訂效能資料

Andrés Olivares

Sofia Emelianova

總覽

想深入瞭解應用程式效能，而不只是瀏覽器內建指標嗎？您現在可以直接將自己的成效資料匯入「Performance」面板的時間軸。無論您是需要以視覺化方式呈現內部程序的架構作者、追蹤程式碼影響的程式庫開發人員，還是使用自訂檢測建構複雜應用程式，效能擴充性 API 都能提供工具，協助您全面瞭解幕後運作情形。

只要插入自訂測量結果和事件，就能在熟悉的「Performance」面板中建立自訂視覺化圖表。想像一下，您可以同時查看框架的元件生命週期事件和標準瀏覽器成效指標，或追蹤自訂顯示引擎的執行流程，並與瀏覽器的轉譯管道完美同步。

這個 API 提供兩種方法：

1. console.timeStamp API (DevTools 擴充功能)

這個 API 提供高效能方法，可檢測應用程式並將時間資料顯示在開發人員工具的「效能」面板中。這項工具的設計可盡量減少執行階段負擔，因此適合用於檢測熱路徑和正式版建構。不會在瀏覽器的內部效能時間軸中新增項目。

2. 使用者載入時間 API (使用 performance.mark 和 performance.measure)

這項 API 會運用現有的 User Timings API。此外，這項 API 也會在瀏覽器的內部效能時間軸中新增項目，以便進一步分析及整合其他效能工具。

「效能」面板中自訂軌跡的顯示方式範例。

主要優點

這兩個 API 都提供：

自訂追蹤：新增專屬追蹤和追蹤群組，呈現程式碼的獨特效能。
項目：在這些軌跡中填入項目，清楚標示重要事件或特定作業的時間長度。
自訂顏色：使用顏色標記，一眼就能區分不同類型的活動或測量結果。

根據需求選擇合適的 API：

console.timeStamp API：
- 檢測對效能的影響是主要考量，尤其是在正式版建構中。
- 您需要快速有效的方法來標記時間長度或事件，而不需額外的中繼資料。
- 您只需要在「效能」面板中以圖表呈現資料。
使用者載入時間 API (performance.mark、performance.measure)：
- 如果需要為每個項目儲存額外資料，且已使用使用者載入時間 API，請使用這個方法。
- 您需要將多媒體資料 (工具提示、詳細屬性) 與效能項目建立關聯。
- 你想加入視覺標記，突顯特定時刻。
- 您不僅需要在開發人員工具中提供資料，也需要在瀏覽器的內部效能時間軸中提供資料，以進行更廣泛的分析或其他工具。
- 您已熟悉或正在使用 User Timings API。

使用 `console.timeStamp` 插入資料

擴充 console.timeStamp API，即可在「效能」面板中建立自訂時間記錄項目，且負擔極小，尤其是在開發人員工具未記錄追蹤記錄時。

console.timeStamp(label: string, start?: string|number, end?: string|number, trackName?: string, trackGroup?: string, color?: DevToolsColor);

label：

時間記錄的標籤。
start (選用)：
- 如果定義為字串：先前記錄的時間戳記名稱 (使用 console.timeStamp(timeStampName))。
- 如果定義為數字：相對於 Performance.timeOrigin 的時間戳記 (以毫秒為單位，例如使用 performance.now() 取得)，代表計時項目的開始時間。
- 如未定義，系統會使用目前時間做為開始時間。
end：
- 如果定義為字串：先前記錄的時間戳記名稱。
- 如果定義為數字：相對於 Performance.timeOrigin 的時間戳記 (以毫秒為單位，例如使用 performance.now() 取得)，代表計時項目的結束時間。
- 如未定義，則會以目前時間做為結束時間。
trackName：

自訂曲目名稱。
trackGroup：

音軌群組的名稱。
color：

項目的顏色。

使用 User Timings API 插入資料

如要插入自訂資料，請在 performance.mark 和 performance.measure 方法的 detail 屬性中加入 devtools 物件。這個 devtools 物件的結構會決定資料在「Performance」面板中的顯示方式。

使用 performance.mark 記錄即時事件或時間軸中的時間戳記。你可以標記特定作業的開始或結束時間，或是任何沒有時間長度的感興趣點。在 detail 屬性中加入 devtools 物件時，「Performance」面板會在「Timings」軌跡中顯示自訂標記。
使用 performance.measure 測量工作或程序的持續時間。在 detail 屬性中加入 devtools 物件後，「效能」面板會在時間軸的自訂軌中顯示自訂測量項目。如果您使用 performance.mark 做為參考點來建立 performance.measure，則不必在 performance.mark 呼叫中加入 devtools 物件。

`devtools` 個物件

這些類型定義了不同擴充功能的 devtools 物件結構：

type DevToolsColor =
  "primary" | "primary-light" | "primary-dark" |
  "secondary" | "secondary-light" | "secondary-dark" |
  "tertiary" | "tertiary-light" | "tertiary-dark" |
  "error";

interface ExtensionTrackEntryPayload {
  dataType?: "track-entry"; // Defaults to "track-entry"
  color?: DevToolsColor;    // Defaults to "primary"
  track: string;            // Required: Name of the custom track
  trackGroup?: string;      // Optional: Group for organizing tracks
  properties?: [string, string][]; // Key-value pairs for detailed view
  tooltipText?: string;     // Short description for tooltip
}

interface ExtensionMarkerPayload {
  dataType: "marker";       // Required: Identifies as a marker
  color?: DevToolsColor;    // Defaults to "primary"
  properties?: [string, string][]; // Key-value pairs for detailed view
  tooltipText?: string;     // Short description for tooltip
}

在時間軸中查看資料

如要在時間軸中查看自訂資料，請在「效能」面板中，確認已開啟設定：依序點選「設定」「擷取設定」 >「check_box」「顯示自訂軌跡」。

「效能」面板「擷取設定」中的「顯示自訂軌跡」核取方塊。

歡迎前往這個示範頁面試用。開始錄製效能，在示範頁面上按一下「Add new Corgi」，然後停止錄製。您會在追蹤記錄中看到自訂軌跡，其中包含附有自訂工具提示的事件、「摘要」分頁中的詳細資料，以及追蹤記錄摘要中的自訂軌跡群組摘要。

程式碼範例

以下舉例說明如何使用 API，透過各種可用機制將自己的資料新增至「Performance」面板。

`console.timeStamp` API 範例：

// Take a start timestamp
const start = performance.now();

// Measure duration from start to now
console.timeStamp("measure 1", start, undefined, "My Track", "My Group", "primary-light");

// Take an end timestamp
const end = performance.now();

// Measure duration from start to end
console.timeStamp("measure 2", start, end, "My Track", "My Group", "secondary-dark");

這會在成效時間軸中產生下列自訂軌跡項目：

使用 console.timeStamp API 新增自訂項目的自訂追蹤記錄。

使用者載入時間 API 範例：

在接下來的章節中，我們將透過程式碼範例，說明如何將下列項目新增至效能時間軸：

自訂軌道和時間軸項目
「時間」軌的標記

自訂測試群組和項目

建立自訂軌，並填入項目，即可在自訂軌中以視覺化方式呈現成效資料。例如：

// Mark used to represent the start of the image processing task
// The start time is defaulted to now
const imageProcessinTimeStart = performance.now();

// ... later in your code

// Track entry representing the completion of image processing
// with additional details and a tooltip
// The start time is a marker from earlier
// The end time is defaulted to now
performance.measure("Image Processing Complete", {
  start: imageProcessinTimeStart,
  detail: {
    devtools: {
      dataType: "track-entry",
      track: "Image Processing Tasks",
      trackGroup: "My Tracks", // Group related tracks together
      color: "tertiary-dark",
      properties: [
        ["Filter Type", "Gaussian Blur"],
        ["Resize Dimensions", "500x300"]
      ],
      tooltipText: "Image processed successfully"
    }
  }
});

這會在效能時間軸中產生下列自訂軌跡項目，以及工具提示文字和屬性：

效能時間軸中的自訂追蹤。

標記

使用橫跨所有軌道的自訂標記，在時間軸中醒目顯示特定搜尋點。例如：

// Marker indicating when the processed image was uploaded
performance.mark("Image Upload", {
  detail: {
    devtools: {
      dataType: "marker",
      color: "secondary",
      properties: [
        ["Image Size", "2.5MB"],
        ["Upload Destination", "Cloud Storage"]
      ],
      tooltipText: "Processed image uploaded"
    }
  }
});

這會在「Timings」軌跡中產生下列標記，以及工具提示文字和屬性：

「時間」軌中的自訂標記。

使用可擴充的 API 自訂效能資料 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

總覽