對版面配置位移進行偵錯

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

Katie Hempenius

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

工具

版面配置 Instability API

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

用量

同樣的程式碼片段 累計版面配置位移 (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 執行個體最相關的屬性 對版面配置位移進行偵錯：

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，就表示 就會發現元素已移出檢視畫面。

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

示例 #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 與前端記錄工具搭配使用 讓您進一步瞭解這些問題的相關資訊退房日 範例：如何追蹤網頁上最大位移元素的程式碼。