對版面配置位移進行偵錯

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

Katie Hempenius

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

工具

Layout 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 介面。以下各節將詳細說明每個介面。

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，表示該元素已從檢視畫面移出。

解讀這些輸出內容時，最重要的一點是，列為「sources」的元素，就是在版面配置變動期間移動的元素。不過，這些元素可能只間接與版面配置不穩定的「根本原因」相關。以下列舉幾個例子。

示例 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」(體驗) 窗格中查看紅色版面配置位移矩形的長度，近似版面配置位移的時間長度。

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

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

如果想快速掌握頁面上版面配置位移的位置和時機，醒目顯示版面配置位移區域是相當實用的技術。

如要在開發人員工具中啟用版面配置位移區域，請依序前往「Settings」>「More Tools」>「Rendering」>「Layout Shift Regions」，然後重新整理您要偵錯的頁面。版面配置位移區域會以紫色標示。

找出版面配置位移原因的思考過程

無論版面配置位移何時發生，或如何發生位移，您都可以透過下列步驟找出版面配置位移的原因。這些步驟可以透過執行中的 Lighthouse 補足，但請注意，Lighthouse 只能辨識初始頁面載入期間發生的版面配置位移。此外，Lighthouse 也只能針對導致版面配置位移的某些原因提供建議，例如沒有明確寬度和高度的圖片元素。

找出版面配置位移的原因

下列事件可能會導致版面配置偏移：

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

特別是，緊靠在位移元素之前的 DOM 元素，就是最有可能導致「造成」版面配置位移的元素。因此，在調查版面配置位移發生的原因時，會考量以下因素：

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

如果前置元素並未造成版面配置偏移，請繼續搜尋，並考量其他前置元素和附近元素。

此外，版面配置位移的方向和距離也能提供根本原因的相關提示。舉例來說，向下移動的幅度越大，通常表示插入了 DOM 元素；而版面配置的移動幅度為 1 或 2 像素時，通常表示套用了相衝突的 CSS 樣式，或是載入及套用網頁字型。

以下列舉幾個最常導致版面配置位移事件的特定行為：

元素位置的變更 (非因其他元素的移動而變更)

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

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

元素尺寸異動

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

• 延遲載入或覆寫先前宣告的樣式的樣式表。
• 圖片和 iframe 沒有 width 和 height 屬性，且在「插槽」算繪後載入。
• 沒有 width 或 height 屬性的文字區塊，會在文字轉譯後替換字型。

插入或移除 DOM 元素

這通常是因為：

• 插入廣告和其他第三方嵌入內容。
• 插入橫幅、快訊和互動視窗。
• 無限捲動和其他 UX 模式，會在現有內容上方載入額外內容。

觸發版面配置的動畫

部分動畫效果可以觸發版面配置。常見的例子是，以遞增方式 (例如 top 或 left) 來「動畫」DOM 元素，而不使用 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 搭配您偏好的前端記錄工具，收集這些問題的更多資訊。請參閱追蹤網頁上最大偏移元素的程式碼範例。