往返快取 notRestoredReasons API

找出哪些導覽因 bfcache 而遭到封鎖,以及原因。

notRestoredReasons 屬性已新增至 PerformanceNavigationTiming 類別,可回報文件中的頁框是否在導覽時遭禁止使用 bfcache,以及原因。開發人員可以利用這項資訊,找出需要更新的網頁,使其與 bfcache 相容,進而提升網站效能。

目前狀態

notRestoredReasons API 已從 Chrome 123 版推出,並逐步開放使用。

概念和用途

新式瀏覽器提供往返快取 (bfcache) 功能,可最佳化瀏覽記錄。這樣一來,使用者返回先前造訪過的網頁時,就能立即載入網頁。網頁可能因各種原因而無法進入 bfcache,或在 bfcache 中遭到移除,部分原因與規格有關,部分原因則與瀏覽器實作有關。

先前,開發人員無法在實際環境中找出網頁無法使用 bfcache 的原因,但可以在 Chrome 開發人員工具中進行測試。為了在欄位中啟用監控功能,PerformanceNavigationTiming 類別已擴充,納入 notRestoredReasons 屬性。這會傳回一個物件,其中包含頂層框架和文件中所有 iframe 的相關資訊:

  • 無法使用 bfcache 的原因。
  • id 和 name 等詳細資料,有助於識別 HTML 中的 iframe。

    這樣一來,開發人員就能採取行動,讓這些網頁與 bfcache 相容,進而提升網站效能。

範例

您可以從 Performance.getEntriesByType() 和 PerformanceObserver 等功能取得 PerformanceNavigationTiming 執行個體。

舉例來說,您可以叫用下列函式,傳回效能時間軸中的所有 PerformanceNavigationTiming 物件,並記錄其 notRestoredReasons:

function returnNRR() {
  const navEntries = performance.getEntriesByType("navigation");
  for (let< i = 0; i  navEntries.length; i++) {
    console.log(`Navigation entry ${i}`);
    let navEntry = navEntries[i];
    console.log(navEntry.notRestoredReasons);
  }
}

如果是歷史記錄導覽,PerformanceNavigationTiming.notRestoredReasons 屬性會傳回具有下列結構的物件,代表頂層框架的封鎖狀態:

{
  children: [],
  id: null,
  name: null,
  reasons: [
    {"reason", "unload-listener"}
  ],
  src: null,
  url: "https://www.example.com/page/"
}

屬性如下:

children
物件陣列,代表嵌入頂層框架的任何同源框架的封鎖狀態。每個物件的結構都與父項物件相同,因此物件內可以遞迴方式表示任意數量的內嵌頁框層級。如果頁框沒有子項,陣列會是空的。
id
代表頁框 id 屬性值的字串 (例如 <iframe id="foo" src="...">)。如果頁框沒有 id,值會是 null。頂層頁面為 null。
name
代表頁框 name 屬性值的字串 (例如 <iframe name="bar" src="...">)。如果頁框沒有 name,值會是空字串。頂層頁面為 null。
reasons
字串陣列,每個字串代表瀏覽的網頁無法使用 bfcache 的原因。造成封鎖的原因有很多,詳情請參閱「封鎖原因」一節。
src
代表頁框來源路徑的字串 (例如 <iframe src="b.html">)。如果頁框沒有 src,值會是空白字串。頂層頁面為 null。
url
代表導覽頁面/iframe 網址的字串。

如果 PerformanceNavigationTiming 物件不代表歷史記錄導覽,notRestoredReasons 屬性會傳回 null。

請注意,如果沒有封鎖原因,notRestoredReasons 也會傳回 null,因此這個值為 null 並不代表是否使用了 bfcache。這項資訊請使用 event.persisted 屬性。

回報同源頁框中的往返快取封鎖情形

如果網頁嵌入了同源頁框,傳回的 notRestoredReasons 值會在 children 屬性中包含一個物件,代表每個嵌入頁框的封鎖狀態。

例如:

{
  children: [
    {
      children: [],
      id: "iframe-id",
      name: "iframe-name",
      reasons: [],
      src: "./index.html",
      url: "https://www.example.com/"
    },
    {
      children: [],
      id: "iframe-id2",
      name: "iframe-name2",
      reasons: [
        {"reason": "unload-listener"}
      ],
      src: "./unload-examples.html",
      url: "https://www.example.com/unload-examples.html"
    },
  ],
  id: null,
  name: null,
  reasons: [],
  src: null,
  url:"https://www.example.com"
}

回報跨源頁框中的 bfcache 封鎖情形

如果網頁嵌入跨源頁框,我們會限制分享的相關資訊量,避免跨源資訊外洩。我們只會納入外部網頁已知的資訊,以及跨源子樹是否封鎖 bfcache。我們不會提供任何封鎖原因,或子樹狀結構較低層級的相關資訊 (即使某些子層級屬於相同來源)。

例如:

{
  children: [
    {
      children: [],
      id: "iframe-id",
      name: "iframe-name",
      reasons: [],
      src: "./index.html",
      url: "https://www.example2.com/"
    }
  ],
  id: null,
  name: null,
  reasons: [
        {"reason": "masked"}
  ],
  src: null,
  url:"https://www.example.com"
}

對於所有跨源 iframe,我們會針對 iframe 的 reasons 值回報 null,而頂層頁框則會顯示 "masked" 的原因。請注意,"masked" 也可能用於使用者代理程式特定原因,因此不一定表示 iframe 有問題。

如要進一步瞭解安全性和隱私權注意事項,請參閱說明文件的「安全性和隱私權」一節。

封鎖原因

如前所述,造成封鎖的原因有很多:

以下列舉一些無法使用 bfcache 的常見原因:

  • unload-listener:網頁註冊了 unload 處理常式,導致某些瀏覽器無法使用 bfcache。請注意,自 Chrome 155 起,Chrome 不會再發出這個原因,除非網站已重新啟用 unload 事件。詳 hip 請參閱「淘汰 unload 事件」。
  • response-cache-control-no-store:網頁使用 no-store 做為 cache-control 值。
  • related-active-contents:這個頁面是從另一個頁面開啟 (使用「複製分頁」),且該頁面仍含有這個頁面的參照內容。

意見回饋

Chromium 團隊想瞭解您使用 bfcache notRestoredReasons API 的體驗。

說明 API 設計

API 是否有任何部分未如預期運作?還是缺少實作構想所需的方法或屬性?對安全性模型有任何疑問或意見嗎?在對應的 GitHub 存放區中回報規格問題,或在現有問題中加入您的想法。

回報導入問題

您是否發現 Chromium 實作有錯誤?還是實作方式與規格不同?在 Issue Tracker 中回報錯誤。請務必盡可能提供詳細資訊、重現問題的操作說明,並將元件指定為 UI > Browser > Navigation > BFCache。

表示對 API 的支持

您是否打算使用 bfcache notRestoredReasons API?您的公開支持有助於 Chromium 團隊優先處理功能,並向其他瀏覽器供應商展示支援這些功能的重要性。

請傳送推文至 @ChromiumDev,並加上主題標記 #NotRestoredReasons,告訴我們您在何處以及如何使用這項功能。

實用連結