對版面配置位移進行偵錯

瞭解如何找出及修正版面配置位移。

Katie Hempenius

本文第一部分將介紹用於偵錯版面配置位移的工具。 第二部分則討論 找出版面配置位移的原因

工具

版面配置 Instability API

Layout Instability API 是 用於測量和回報版面配置位移的瀏覽器機制。以下工具的所有工具 開發人員工具 (包括開發人員工具) 的偵錯版面配置 Layout Instability API。不過，直接使用 Layout Instability API 強大的偵錯工具。

注意： 只有 Chromium 瀏覽器支援 Layout Instability API。目前，尚無法測量非 Chromium 瀏覽器中的版面配置位移或偵錯。

用量

同樣的程式碼片段 累計版面配置位移 (CLS) 也可以測量 用來偵錯版面配置位移。下方的程式碼片段會記錄版面配置相關資訊 切換至控制台檢查這份記錄可提供相關資訊 顯示版面配置位移發生的時間、位置及方式。

let cls = 0;
new PerformanceObserver((entryList) => {
  for (const entry of entryList.getEntries()) {
    if (!entry.hadRecentInput) {
      cls += entry.value;
      console.log('Current CLS value:', cls, entry);
    }
  }
}).observe({type: 'layout-shift', buffered: true});

執行這個指令碼時，請注意下列事項：

• buffered: true 選項表示 PerformanceObserver 應檢查瀏覽器的效能項目 緩衝區 針對在觀察器發生前建立的效能項目 和初始化。因此，PerformanceObserver 會回報版面配置 轉換前後發生的位移。保留此項目 請務必留意版面配置位移的初始效果 反映的是報表待處理狀態，而非多方面突然發生 版面配置位移。
• 為避免影響效能，PerformanceObserver 會等到主要節點 執行緒閒置中，以回報版面配置位移。因此，隨著應用程式 主執行緒很忙碌，從版面配置開始時可能會有些許延遲 發生轉變及記錄在控制台時。
• 這個指令碼會忽略使用者輸入後 500 毫秒內發生的版面配置位移 因此不會計入 CLS

系統會使用下列兩個 API 組合回報版面配置位移相關資訊： LayoutShift 和 LayoutShiftAttribution。 存取 API如要進一步瞭解這些介面，請參閱 後續章節。

LayoutShift

每個版面配置位移都會使用 LayoutShift 介面回報。內容 如下所示：

duration: 0
entryType: "layout-shift"
hadRecentInput: false
lastInputTime: 0
name: ""
sources: (3) [LayoutShiftAttribution, LayoutShiftAttribution, LayoutShiftAttribution]
startTime: 11317.934999999125
value: 0.17508567530168798

上述項目表示在三個 DOM 元素發生變化的版面配置位移 位置。這個特定版面配置位移的版面配置位移分數為 0.175。

以下是與 LayoutShift 執行個體最相關的屬性 對版面配置位移進行偵錯：

屬性	說明
sources	sources 屬性會列出版面配置位移期間移動的 DOM 元素。這個陣列最多可包含五個來源。如果有超過五個元素受到版面配置位移影響，則會回報版面配置位移來源最大的五大 (評估依據為版面配置穩定性的影響程度) 來源。這項資訊是透過 LayoutShiftAttribution 介面回報 (詳情請參閱下方說明)。
value	value 屬性會回報特定版面配置位移的版面配置位移分數。
hadRecentInput	hadRecentInput 屬性會指出版面配置位移是否發生在使用者輸入內容的 500 毫秒內。
startTime	startTime 屬性會指出版面配置位移的時間。startTime 是以毫秒表示，評估時則是相對於啟動網頁載入的時間。
duration	duration 屬性一律會設為 0。這個屬性沿用自 PerformanceEntry 介面 (LayoutShift 介面會擴充 PerformanceEntry 介面)。不過，時間長度的概念不適用於版面配置位移事件，因此設為 0。如需 PerformanceEntry 介面的相關資訊，請參閱規格。

注意： Web Vitals 擴充功能可將版面配置位移資訊記錄到控制台。如要啟用這項功能，請前往 [選項] > 控制台記錄功能。

LayoutShiftAttribution

LayoutShiftAttribution 介面說明單一 DOM 的單一位移 元素。如果多個元素在版面配置位移期間位移，sources 屬性包含多個項目。

舉例來說，下列 JSON 對應到一個來源的版面配置位移： <div id='banner'> DOM 元素從 y: 76 向下移動到 y:246。

// ...
  "sources": [
    {
      "node": "div#banner",
      "previousRect": {
        "x": 311,
        "y": 76,
        "width": 4,
        "height": 18,
        "top": 76,
        "right": 315,
        "bottom": 94,
        "left": 311
      },
      "currentRect": {
        "x": 311,
        "y": 246,
        "width": 4,
        "height": 18,
        "top": 246,
        "right": 315,
        "bottom": 264,
        "left": 311
      }
    }
  ]

node 屬性會識別位移的 HTML 元素。懸停在此項目 屬性會醒目顯示對應的網頁元素。

previousRect 和 currentRect 屬性則會回報 節點。

• x 和 y 座標會回報 X 座標和 y 座標 個別
• width 和 height 屬性會分別回報寬度和高度 該元素的屬性。
• top、right、bottom 和 left 屬性會回報 x 或 y 對應元素指定邊緣的座標值。在其他 則 top 的值等於 y；bottom 的值等於 y+height。

如果 previousRect 的所有屬性都設為 0，表示該元素 切換至視圖如果 currentRect 的所有屬性都設為 0，就表示 就會發現元素已移出檢視畫面。

注意： Layout Instability API 目前不會忽略已移動但由於其他元素置於這些元素之前無法顯示的元素。使用 display: none、visibility: hidden 或 opacity: 0，以免需要先對部分元素執行版面配置，以便向使用者顯示。

解讀這些輸出內容時最重要的須知事項之一 列為來源元素是在 版面配置位移。然而，這些元素也可能是 與「根本原因」有關版面配置不穩定以下列舉幾個例子。

示例 #1

這個版面配置位移是由一個來源回報：元素 B。不過， 這種版面配置位移的根本原因是元素 A 的大小變更。

範例 #2

這個範例中的版面配置位移是由兩個來源回報：元素 A 和元素 B這個版面配置位移的根本原因是 元素 A。

範例 #3

在這個範例中，版面配置位移是由元素 B 回報。 變更元素 B 的位置導致版面配置位移。

範例 4

雖然元素 B 的大小會改變，但這個範例中沒有版面配置位移。

觀看觀看示範，瞭解 Layout Instability API 如何回報 DOM 變更情形。

開發人員工具

效能面板

開發人員工具「Performance」面板的「Experience」窗格會顯示 在特定效能追蹤期間發生的版面配置位移，即使發生了這些變化也不成問題 在使用者進行互動的 500 毫秒內，因此不會計入 CLS。 將滑鼠遊標懸停在「體驗」面板中的特定版面配置位移 受影響的 DOM 元素

如要查看版面配置位移的詳細資訊，請點選版面配置位移，然後 開啟「Summary」導覽匣。元素尺寸有變更 採用 [width, height] 格式；清單中會列出元素位置的變更 使用 [x,y] 格式。「Had 最近輸入」屬性會指出 版面配置位移發生在使用者互動後的 500 毫秒內。

如要瞭解版面配置位移的持續時間，請開啟「Event Log」(事件記錄) 分頁標籤。 您也可以查看 「Experience」(體驗) 窗格，顯示紅色版面配置 Shift 矩形的長度。

注意： 版面配置位移的時間長度不會影響版面配置位移分數。

如要進一步瞭解如何使用效能面板，請參閱效能 分析 參考資料。

醒目顯示版面配置位移區域

醒目顯示版面配置位移區域，能有效達到 快速一覽版面配置位移的位置和時間 發生的時間

如要在開發人員工具中啟用版面配置位移區域，請依序前往「設定」>「設定」更多工具 > 轉譯 >版面配置位移區域，然後重新整理您要偵錯的頁面。 版面配置位移的區域會短暫以紫色醒目顯示。

找出版面配置位移原因的思維流程

您可以透過下列步驟找出版面配置位移的原因 無論版面配置位移發生的時間或方式為何。您可以視需求 補充運用運作中的 Lighthouse — 不過請記住，Lighthouse 可以 只識別初始頁面載入期間發生的版面配置位移。於 此外，Lighthouse 也會針對版面配置的部分原因提供建議 移動幅度—例如沒有明確寬度和高度的圖片元素。

找出版面配置位移的原因

版面配置位移可能是下列事件造成：

• DOM 元素位置變更
• DOM 元素尺寸異動
• 插入或移除 DOM 元素
• 觸發版面配置的動畫

具體來說，位移元素前方的 DOM 元素會 最有可能引發「引發」事件的元素版面配置位移。因此 調查版面配置位移發生的原因：

• 上述元素的位置或尺寸是否有變化？
• 是否在位移元素之前插入或移除 DOM 元素？
• 移位元素的位置是否明確變更？

如果上述元素不會導致版面配置位移，請在下方進行搜尋 考量到其他先前和鄰近元素

此外，版面配置位移的方向和距離也能提供提示 根本原因舉例來說，如果向下變動幅度較大，通常表示廣告活動 插入 DOM 元素時，版面配置位移通常為 1 px 或 2 px，通常表示 衝突 CSS 樣式的應用，或 網頁字型。

在這個範例中，字型替換會導致網頁元素向上移動五像素。

這些是最常造成版面配置位移的具體行為 事件：

元素位置變更 (不屬於其他元素移動)

造成這類變更的原因通常包括：

• 延遲載入或覆寫先前宣告的樣式的樣式表。
• 動畫和轉場效果。

元素尺寸異動

造成這類變更的原因通常包括：

• 延遲載入或覆寫先前宣告的樣式的樣式表。
• 不含 width 和 height 屬性的圖片和 iframe 會在之後載入 對方的「版位」。
• 不含 width 或 height 屬性的文字區塊，會在 文字已轉譯完成

插入或移除 DOM 元素

這通常是由以下原因造成：

• 插入廣告和其他第三方嵌入項目。
• 插入橫幅、快訊和互動視窗。
• 會在上方載入額外內容的無限捲動和其他使用者體驗模式 。

觸發版面配置的動畫

部分動畫效果可能會觸發 版面配置。常見的 例如 DOM 元素為「動畫」增加屬性 例如 top 或 left，而不是使用 CSS 的 transform敬上 資源。請參閱「如何建立高效能 CSS 動畫」一文 瞭解詳情

重現版面配置位移

您無法修正無法重現的版面配置位移。最簡單而最簡單的方式之一 最有效的方法能幫助您進一步瞭解網站版面配置 穩定性需要 5 到 10 分鐘的時間，才能與你的網站互動 觸發版面配置位移。執行這項作業時，請勿關閉主控台，並使用 Layout Instability API ：用於回報版面配置位移。

如要找出版面配置位移，請考慮重複執行這項練習，例如： 不同的裝置和連線速度尤其是採用 連線速度可讓您更輕鬆掌握版面配置位移。此外， 您可以使用 debugger 陳述式更輕鬆地逐步完成版面配置 轉變。

new PerformanceObserver((entryList) => {
  for (const entry of entryList.getEntries()) {
    if (!entry.hadRecentInput) {
      cls += entry.value;
      debugger;
      console.log('Current CLS value:', cls, entry);
    }
  }
}).observe({type: 'layout-shift', buffered: true});

最後，針對在開發過程中無法重現的版面配置問題，請考慮 將 Layout Instability API 與前端記錄工具搭配使用 讓您進一步瞭解這些問題的相關資訊退房日 範例：如何追蹤網頁上最大位移元素的程式碼。