往返快取 notRestoredReasons API

找出哪些瀏覽項目無法使用 bfcache 的瀏覽方式以及原因。

Chris Mills

在 PerformanceNavigationTiming 類別中加入 notRestoredReasons 屬性後，系統會回報文件中出現的影格是否遭到禁止使用 bfcache 瀏覽導覽，以及相關原因。開發人員可運用這項資訊，找出需要更新以便與 bfcache 相容的網頁，藉此提升網站效能。

目前狀態

步驟 狀態
1. 建立說明 完成
2. 建立規格的初始草稿 Not started
3. 收集意見回饋並改進設計 進行中
4. 來源試用 已開始
5. 推出 Not started

試用 bfcache notRestoredReasons API

自 109 版起，bfcache notRestoredReasons API 在 Chromium 中提供來源試用。如需這項功能的最新發布時間表，請造訪 ChromeStatus.com 功能頁面 (如要瞭解版本發布日期，請參閱 Chrome 發展藍圖)。

歡迎註冊來源試用，並在實驗中使用 bfcache notRestoredReasons API。請參閱「參加來源試用」，瞭解註冊後如何使用權杖。

概念和用法

新式瀏覽器為記錄導覽提供了最佳化功能，稱為往返快取 (bfcache)。當使用者返回先前造訪過的網頁時，可立即載入。基於各種原因，有些網頁可能會遭到封鎖，而無法進入 bfcache 或將其移除。這是因為，有些網頁必須符合規格要求，有些則與瀏覽器實作的具體有關。

過去，開發人員無法得知相關欄位無法使用 bfcache 的原因，不過已有 Chrome 開發工具進行測試。為啟用欄位監控功能，已擴充 PerformanceNavigationTiming 類別並納入 notRestoredReasons 屬性。這樣會傳回一個物件，其中包含文件中所有影格的相關資訊：

  • 而 id 和 name 等詳細資料，有助於在 HTML 中識別。
  • 對方是否無法使用 bfcache。

  • 他們無法使用 bfcache 的原因。

    這讓開發人員能採取行動，使這些網頁與 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 屬性會傳回具有以下結構的物件，代表頂層頁框的封鎖狀態：

{
  blocked: true,
  children: [],
  id: "",
  name: "",
  reasons: [ "Internal Error", "Unload handler" ],
  src: "",
  url: "a.com"
}

屬性如下：

blocked
布林值，指定到達網頁是否無法使用 bfcache (true) 功能 (false)。
children
這個物件陣列代表頂層頁框內嵌任何頁框的封鎖狀態。每個物件都具有與父項物件相同的結構，因此，物件內部可以以遞迴方式呈現任意數量的嵌入式頁框。如果影格沒有子項，陣列將顯示空白。
id
代表影格 id 屬性值的字串 (例如 <iframe id="foo" src="...">)。如果頁框沒有 id，則值會是空字串。
name
代表影格 name 屬性值的字串 (例如 <iframe name="bar" src="...">)。如果頁框沒有 name，則值會是空字串。
reasons
每個字串陣列，代表瀏覽頁面無法使用 bfcache 的原因。導致封鎖的原因有很多種，詳情請參閱下方的「封鎖原因」一節。
src
代表影格來源路徑的字串 (例如 <iframe src="b.html">)。如果頁框沒有 src，則值為空白字串。
url
字串，代表所瀏覽網頁的網址。

針對不代表記錄導覽的 PerformanceNavigationTiming 物件，notRestoredReasons 屬性會傳回 null。這有助於判斷 bfcache 是否與特定導覽無關，而不是不支援 notRestoredReasons，在此情況下，會傳回 undefined。

回報相同來源影格中的 Bfcache 封鎖

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

例如：

{
  blocked: false,
  children: [
    { url: "a.com", src: "b.a.com", id: "b", name: "b", blocked: false, reasons: [], children: [] },
    { url: "a.com", src: "c.a.com", id: "c", name: "c", blocked: true, reasons: [ "BroadcastChannel" ], children: [] },
    { url: "a.com", src: "d.a.com", id: "d", name: "d", blocked: false, reasons: [], children: [] }
  ],
  id: "",
  name: "",
  reasons: [],
  src: "",
  url:"a.com"
}

回報跨來源影格中的 Bfcache 封鎖

如果網頁內嵌跨來源頁框，我們會限制分享的資訊量，以免跨來源資訊外洩。我們只會納入外部網頁已知的資訊，以及跨來源子樹狀結構是否封鎖快取。我們不會納入任何封鎖原因或子樹狀結構中較低層級的資訊 (即使有些子層級的來源相同也一樣)。

例如：

{
  blocked: false,
  children: [
    { url: "a.com", src: "c.a.com", id: "c", name: "c", blocked: true, reasons: [ "ScreenReader" ], children: [] },
    /* cross-origin frame */
    { url: "", src: "b.com", id: "d", name: "d", blocked: true, reasons: [], children: [] }
  ],
  id: "",
  name: "",
  reasons: [],
  src: "",
  url:"a.com"
}

如果有多個跨來源頁框導致封鎖原因，我們會隨機選取一個跨來源 iframe，並回報該 iframe 是否封鎖快取。針對其餘影格，我們會回報 blocked 值的 null。這麼做是為了防止不肖人士在非由您控制的網站上推測使用者狀態的相關資訊，方法是將多個第三方頁框嵌入同一個網頁，然後比較每個網站的封鎖資訊。

{
  blocked: false,
  children: [
    /* cross-origin frames */
    {url: "", src: "b.com", id: "b", name: "b", blocked: null, reasons: [], children: []},
    {url: "", src: "c.com", id: "c", name: "c", blocked: true, reasons: [], children: []},
    {url: "", src: "d.com", id: "d", name: "d", blocked: null, reasons: [], children: []}
  ]
  id: "",
  name: "",
  reasons: [],
  src: "",
  url:"a.com"
}

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

封鎖原因

如前所述，封鎖情況有很多種，我們彙整了一份簡易的試算表，當中列出所有原因字串，並說明這些原因所代表的意義。

以下列出幾個主要原因供您參考：

  • Circumstantial：這是指封鎖原因，與開發人員的網頁程式碼沒有直接關聯。舉例來說，相關元件當機、載入程序發生錯誤、網頁處於無法快取的狀態、因記憶體不足而停用 bfcache，或是 Service Worker 網頁做出會導致系統不予快取的頁面。
  • Extensions：發生幾個不同原因的訊息與擴充功能相關。一般來說，我們會將許多不同的原因合併為「擴充功能」原因。我們會故意散播擴充功能相關的封鎖原因，因為我們不希望透露太多資訊，說明使用者已安裝哪些擴充功能、目前在網頁上使用的擴充功能、目前使用的擴充功能等等。
  • PageSupportNeeded：開發人員程式碼使用的網路平台功能不會進行 bfcache 封鎖，但目前設定使用 bfcache 封鎖。舉例來說，網頁目前具有內含已註冊事件監聽器的 BroadcastChannel 或開放式 IndexedDB 連線。或者，網頁已註冊 unload 處理常式，目前禁止某些瀏覽器使用 bfcache。
  • SupportPending：開發人員的程式碼使用了會拒絕 bfcache 的網頁平台功能，例如 Web Serial API、Web Authentication API、File System Access API 或 Media Session API。或者網頁使用了 Cache-Control: no-store，目前禁止部分瀏覽器使用快取功能。如果外部工具 (例如螢幕閱讀器或 Chrome 密碼管理工具) 位於網頁本身外，也會回報這類工具是否阻擋了快取。

意見回饋：

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

告訴我們 API 設計

有什麼 API 功能不如您預期嗎？或者您需要實作提案的方法或屬性嗎？對於安全性模型有任何疑問或意見嗎？在對應的 [GitHub 存放區][feedback] 上提交規格問題，或將您的想法新增至現有問題中。

回報導入問題

你在 Chromium 的實作方式中發現錯誤嗎？或者，實作項目是否與規格不同？ 前往 new.crbug.com 回報錯誤。請務必盡可能提供詳細資料、重現簡易操作說明，並將元件指定為 UI > Browser > Navigation > bfcache。Glitch 適合用來快速分享簡單快速的提案，

展現對 API 的支援

您打算使用 bfcache notRestoredReasons API 嗎？您的公開支援可協助 Chromium 團隊決定功能的優先順序，以及向其他瀏覽器廠商說明這項功能有多重要。

請使用主題標記 #NotRestoredReasons 將 Tweet 訊息傳送至 @ChromiumDev，並告訴我們您的使用地點和方式。

實用連結