Halaman ini diterjemahkan oleh Cloud Translation API.

Back-forward cache notRestoreReasons API

Temukan navigasi yang diblokir agar tidak menggunakan bfcache, dan alasannya.

Chris Mills

Barry Pollard

Properti notRestoredReasons, yang ditambahkan ke class PerformanceNavigationTiming, melaporkan informasi tentang apakah frame yang ada dalam dokumen diblokir agar tidak menggunakan bfcache pada navigasi, dan alasannya. Developer dapat menggunakan informasi ini untuk mengidentifikasi halaman yang memerlukan pembaruan agar kompatibel dengan bfcache, sehingga meningkatkan performa situs.

Status saat ini

notRestoredReasons API telah diluncurkan dari Chrome 123 dan akan diluncurkan secara bertahap.

Konsep dan penggunaan

Browser modern menyediakan fitur pengoptimalan untuk navigasi histori yang disebut back/forward cache (bfcache). Hal ini memungkinkan pengalaman pemuatan instan saat pengguna kembali ke halaman yang telah mereka kunjungi. Halaman dapat diblokir agar tidak masuk ke bfcache atau dikeluarkan saat dalam bfcache karena berbagai alasan, beberapa diperlukan oleh spesifikasi dan beberapa khusus untuk implementasi browser.

Sebelumnya, tidak ada cara bagi developer untuk mengetahui alasan halaman mereka diblokir agar tidak dapat menggunakan bfcache di kolom, meskipun ada pengujian di alat dev Chrome. Untuk mengaktifkan pemantauan di kolom, class PerformanceNavigationTiming telah diperluas untuk menyertakan properti notRestoredReasons. Tindakan ini akan menampilkan objek yang berisi informasi terkait di frame bagian atas dan semua iframe yang ada dalam dokumen:

Alasan mereka diblokir agar tidak dapat menggunakan bfcache.
Detail seperti frame id dan name, untuk membantu mengidentifikasi iframe di HTML.

Hal ini memungkinkan developer mengambil tindakan untuk membuat halaman tersebut kompatibel dengan bfcache, sehingga meningkatkan performa situs.

Contoh

Instance PerformanceNavigationTiming dapat diperoleh dari fitur seperti Performance.getEntriesByType() dan PerformanceObserver.

Misalnya, Anda dapat memanggil fungsi berikut untuk menampilkan semua objek PerformanceNavigationTiming yang ada di linimasa performa dan mencatat notRestoredReasons-nya dalam log:

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);
  }
}

Untuk navigasi histori, properti PerformanceNavigationTiming.notRestoredReasons menampilkan objek dengan struktur berikut, yang mewakili status diblokir dari frame tingkat atas:

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

Propertinya adalah sebagai berikut:

children: Array objek yang mewakili status diblokir dari frame origin yang sama yang disematkan dalam frame level atas. Setiap objek memiliki struktur yang sama dengan objek induk — dengan cara ini, berapa pun level frame tersemat dapat direpresentasikan di dalam objek secara rekursif. Jika frame tidak memiliki turunan, array akan kosong.
id: String yang mewakili nilai atribut id frame (misalnya, <iframe id="foo" src="...">). Jika frame tidak memiliki id, nilainya akan menjadi null. Untuk halaman tingkat atas, nilainya adalah null.
name: String yang mewakili nilai atribut name frame (misalnya, <iframe name="bar" src="...">). Jika frame tidak memiliki name, nilai akan berupa string kosong. Untuk halaman tingkat atas, nilainya adalah null.
reasons: Array string yang masing-masing mewakili alasan halaman yang dibuka diblokir agar tidak menggunakan bfcache. Ada berbagai alasan mengapa pemblokiran dapat terjadi. Lihat bagian Alasan pemblokiran untuk detail selengkapnya.
src: String yang mewakili jalur ke sumber frame (misalnya, <iframe src="b.html">). Jika frame tidak memiliki src, nilainya akan berupa string kosong. Untuk halaman tingkat atas, nilainya adalah null.
url: String yang mewakili URL halaman/iframe yang dibuka.

Untuk objek PerformanceNavigationTiming yang tidak merepresentasikan navigasi histori, properti notRestoredReasons akan menampilkan null.

Perhatikan bahwa notRestoredReasons juga menampilkan null jika tidak ada alasan pemblokiran, jadi ini adalah null bukan indikator bahwa bfcache telah atau tidak digunakan. Untuk itu, Anda harus menggunakan properti event.persisted.

Melaporkan pemblokiran bfcache dalam frame origin yang sama

Jika halaman memiliki frame asal yang sama yang disematkan, nilai notRestoredReasons yang ditampilkan akan berisi objek di dalam properti children yang mewakili status diblokir dari setiap frame tersemat.

Contoh:

{
  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"
}

Melaporkan pemblokiran bfcache dalam frame lintas origin

Jika suatu halaman memiliki frame lintas origin yang disematkan, kami membatasi jumlah informasi yang dibagikan tentang frame tersebut untuk menghindari kebocoran informasi lintas origin. Kami hanya menyertakan informasi yang sudah diketahui oleh halaman luar, dan apakah subtree lintas origin memblokir bfcache atau tidak. Kami tidak menyertakan alasan pemblokiran atau informasi tentang tingkat subhierarki yang lebih rendah (meskipun jika beberapa subtingkat berasal dari asal yang sama).

Contoh:

{
  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"
}

Untuk semua iframe lintas origin, kami melaporkan null untuk nilai reasons untuk frame, dan frame tingkat atas akan menunjukkan alasan "masked". Perlu diketahui bahwa "masked" juga dapat digunakan untuk alasan khusus agen pengguna, sehingga mungkin tidak selalu menunjukkan masalah dalam iframe.

Lihat bagian Keamanan dan privasi dalam penjelasan untuk mengetahui detail selengkapnya tentang pertimbangan keamanan dan privasi.

Alasan pemblokiran

Seperti yang kami katakan sebelumnya, ada berbagai alasan mengapa pemblokiran dapat terjadi:

Berikut adalah contoh beberapa alasan paling umum bfcache tidak dapat digunakan:

unload-listener: halaman mendaftarkan pengendali unload, yang mencegah penggunaan bfcache di browser tertentu. Lihat Menghentikan penggunaan peristiwa penghapusan muatan untuk informasi selengkapnya.
response-cache-control-no-store: Halaman menggunakan no-store sebagai nilai cache-control.
related-active-contents: Halaman dibuka dari halaman lain (baik menggunakan "tab duplikat") yang masih memiliki referensi ke halaman ini.

Masukan

Tim Chromium ingin mengetahui pengalaman Anda dengan bfcache notRestoredReasons API.

Beri tahu kami tentang desain API

Apakah ada sesuatu terkait API yang tidak berfungsi seperti yang Anda harapkan? Atau apakah ada metode atau properti yang hilang yang diperlukan untuk menerapkan ide Anda? Ada pertanyaan atau komentar tentang model keamanan? Ajukan masalah spesifikasi di repo GitHub yang sesuai, atau tambahkan pendapat Anda ke masalah yang sudah ada.

Laporkan masalah terkait penerapan

Apakah Anda menemukan bug pada implementasi Chromium? Atau apakah implementasinya berbeda dengan spesifikasi? Laporkan bug di issue tracker kami. Pastikan untuk menyertakan detail sebanyak mungkin, petunjuk sederhana untuk mereproduksi, dan tentukan komponen sebagai UI > Browser > Navigation > BFCache. Glitch sangat cocok untuk membagikan repro dengan cepat dan mudah.

Menunjukkan dukungan untuk API

Anda berencana menggunakan bfcache notRestoredReasons API? Dukungan publik Anda membantu tim Chromium memprioritaskan fitur dan menunjukkan kepada vendor browser lain betapa pentingnya mendukung mereka.

Kirim tweet ke @ChromiumDev menggunakan hashtag #NotRestoredReasons dan beri tahu kami tempat dan cara Anda menggunakannya.