對版面配置位移進行偵錯

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

Katie Hempenius
Katie Hempenius
X

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

工具

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 例項中與版面配置位移偵錯作業最相關的屬性：

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

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

開發人員工具「Event Log」分頁，顯示版面配置位移的螢幕截圖

如要進一步瞭解如何使用「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 搭配您偏好的前端記錄工具，收集這些問題的更多資訊。請參閱追蹤網頁上最大偏移元素的程式碼範例。