總覽
「Performance」面板支援效能擴充 API,可在「Performance」時間軸中新增自訂資料。這可讓您將成效評估和事件直接以自訂音軌的形式,或在時間音軌中插入。如果您是使用自訂檢測功能的架構、程式庫和複雜應用程式的開發人員,這項功能可能會對您有所助益,可讓您更全面地瞭解效能。
這個 API 提供兩種不同的機制:
1. User Timings API (使用 performance.mark
和 performance.measure
)
這個 API 會運用現有的 User Timings API。它也會在瀏覽器的內部效能時間表中新增項目,方便進一步分析並整合其他效能工具。
2. console.timeStamp
API (針對 DevTools 擴充)
這個 API 提供高效能方法,可用於檢測應用程式,並將計時資料專門顯示在 DevTools 的「Performance」面板中。這項工具的設計可盡量減少執行階段的額外負擔,因此適合用於檢測熱門路徑和實際建構的應用程式。不會在瀏覽器的內部效能時間軸中新增項目。
主要功能與特色
這兩個 API 都提供以下功能:
- 自訂軌跡:在自訂軌跡和軌跡群組中新增項目。
- 項目:使用代表事件或評估項目的項目填入軌跡。
- 自訂顏色:顏色代碼項目,用於視覺區別。
主要差異和使用各 API 的時機:
- User Timings API (
performance.mark
、performance.measure
):- 在「Performance」面板和瀏覽器的內部效能時間軸上新增項目。
- 允許使用豐富的資料,包括工具提示和詳細屬性。
- 允許新增標記:使用視覺標記醒目顯示時間軸中的特定時刻。
- 適合用於詳細的效能分析,以及需要與其他成效工具整合的情況。
- 請在需要為每個項目儲存額外資料,且已使用 User Timings API 時使用。
console.timeStamp
API:- 僅將項目新增至「成效」面板。
- 提供更高效的效能,尤其是在實際工作環境中。
- 非常適合用於檢測熱門路徑和效能至關重要的程式碼。
- 無法新增工具提示或屬性等額外資料。
- 當效能負擔是主要考量,且您需要快速檢測程式碼時,請使用此選項。
使用 User Timings API 插入資料
如要插入自訂資料,請在 performance.mark
和 performance.measure
方法的 detail
屬性中加入 devtools
物件。這個 devtools
物件的結構會決定資料在「成效」面板中的顯示方式。
使用
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
}
使用 console.timeStamp
插入資料
擴充 console.timeStamp API,讓您在「Performance」面板中建立自訂計時項目,且不增加太多額外負擔。
console.timeStamp(label: string, start?: string, end?: string, trackName?: string, trackGroup?: string, color?: DevToolsColor);
label
:時間輸入項目的標籤。start
:先前記錄的時間戳記名稱 (使用console.timeStamp(timeStampName)
)。如果未定義,系統會使用目前時間。end
:先前記錄的時間戳記名稱。如果未定義,系統會使用目前的時間。trackName
:自訂軌道的名稱。trackGroup
:曲目群組的名稱。color
:項目的顏色。
在時間軸上查看資料
如要在時間軸上查看自訂資料,請在「成效」面板中依序開啟「設定」「擷取設定」>「擴充資料」。
歡迎前往這個示範頁面試用。開啟「擴充資料」,開始錄製效能資料,按一下示範頁面上的「新增 Corgi」,然後停止錄製。您會在追蹤記錄中看到自訂軌跡,其中包含事件,並在「摘要」分頁中顯示自訂工具提示和詳細資料。
程式碼範例
以下列舉幾個範例,說明如何使用 API 透過各項可用機制,將您自己的資料新增至「成效」面板。
User Timings API 範例:
在後續章節中,您可以參考程式碼範例,瞭解如何在效能時間軸中新增下列項目:
自訂曲目和項目
建立自訂追蹤,並填入項目,以便在自訂追蹤中以圖表呈現成效資料。例如:
// Mark used to represent the start of the image processing task
// The start time is defaulted to now
performance.mark("Image Processing Start");
// ... 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: "Image Processing Start",
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」軌道中產生下列標記,以及相關的工具提示文字和屬性:
console.timeStamp
API 範例:
// Record a start timestamp
console.timeStamp("start");
// Measure duration from start to now
console.timeStamp("measure 1", "start", undefined, "My Track", "My Group", "primary-light");
// Record an end timestamp
console.timeStamp("end");
// Measure duration from start to end
console.timeStamp("measure 2", "start", "end", "My Track", "My Group", "secondary-dark");
這會在成效時間軸中產生下列自訂追蹤項目: