chrome.webNavigation

Deskripsi

Gunakan chrome.webNavigation API untuk menerima notifikasi tentang status permintaan navigasi selama dalam perjalanan.

Izin

webNavigation

Semua metode dan peristiwa chrome.webNavigation mengharuskan Anda mendeklarasikan izin "webNavigation" dalam manifes ekstensi. Contoh:

{   "name": "My extension",   ...   "permissions": [     "webNavigation"   ],   ... } 

Konsep dan penggunaan

Urutan peristiwa

Untuk navigasi yang berhasil diselesaikan, peristiwa diaktifkan dalam urutan berikut:

onBeforeNavigate -> onCommitted -> [onDOMContentLoaded] -> onCompleted 

Error apa pun yang terjadi selama proses akan menghasilkan peristiwa onErrorOccurred. Untuk navigasi tertentu, tidak ada peristiwa lebih lanjut yang diaktifkan setelah onErrorOccurred.

Jika bingkai navigasi berisi sub-bingkai, onCommitted-nya akan dipicu sebelum onBeforeNavigate turunannya; sementara onCompleted dipicu setelah onCompleted semua turunannya.

Jika fragmen referensi frame diubah, peristiwa onReferenceFragmentUpdated akan diaktifkan. Peristiwa ini dapat dipicu kapan saja setelah onDOMContentLoaded, bahkan setelah onCompleted.

Jika history API digunakan untuk mengubah status frame (misalnya, menggunakan history.pushState(), peristiwa onHistoryStateUpdated akan diaktifkan. Peristiwa ini dapat diaktifkan kapan saja setelah onDOMContentLoaded.

Jika navigasi memulihkan halaman dari Back Forward Cache, peristiwa onDOMContentLoaded tidak akan diaktifkan. Peristiwa tidak dipicu karena konten telah selesai dimuat saat halaman pertama kali dikunjungi.

Jika navigasi dipicu menggunakan Chrome Instan atau Halaman Instan, halaman yang dimuat sepenuhnya akan ditukar ke tab saat ini. Dalam hal ini, peristiwa onTabReplaced diaktifkan.

Hubungan dengan peristiwa webRequest

Tidak ada urutan yang ditentukan antara peristiwa webRequest API dan peristiwa webNavigation API. Kemungkinan peristiwa webRequest masih diterima untuk frame yang sudah memulai navigasi baru, atau navigasi hanya dilanjutkan setelah resource jaringan dimuat sepenuhnya.

Secara umum, peristiwa webNavigation terkait erat dengan status navigasi yang ditampilkan di UI, sedangkan peristiwa webRequest sesuai dengan status stack jaringan yang umumnya tidak transparan bagi pengguna.

ID Tab

Tidak semua tab navigasi sesuai dengan tab sebenarnya di UI Chrome, misalnya, tab yang sedang di-pra-render. Tab tersebut tidak dapat diakses menggunakan tabs API dan Anda juga tidak dapat meminta informasi tentang tab tersebut dengan memanggil webNavigation.getFrame() atau webNavigation.getAllFrames(). Setelah tab tersebut ditukar, peristiwa onTabReplaced akan diaktifkan dan tab tersebut dapat diakses melalui API ini.

Stempel waktu

Perlu diperhatikan bahwa beberapa keanehan teknis dalam penanganan proses Chrome yang berbeda oleh OS dapat menyebabkan jam menjadi tidak sinkron antara browser itu sendiri dan proses ekstensi. Artinya, properti timeStamp dari properti timeStamp peristiwa WebNavigation hanya dijamin konsisten secara internal. Membandingkan satu peristiwa dengan peristiwa lain akan memberi Anda selisih waktu yang benar di antara keduanya, tetapi membandingkannya dengan waktu saat ini di dalam ekstensi (menggunakan (new Date()).getTime(), misalnya) dapat memberikan hasil yang tidak terduga.

ID Frame

Frame dalam tab dapat diidentifikasi berdasarkan ID frame. ID frame dari frame utama selalu 0, ID frame turunan adalah angka positif. Setelah dokumen dibuat dalam frame, ID frame-nya tetap konstan selama masa aktif dokumen. Mulai Chrome 49, ID ini juga konstan selama masa aktif frame (di beberapa navigasi).

Karena sifat multi-proses Chrome, tab dapat menggunakan proses yang berbeda untuk merender sumber dan tujuan halaman web. Oleh karena itu, jika navigasi terjadi dalam proses baru, Anda mungkin menerima peristiwa dari halaman baru dan lama hingga navigasi baru dilakukan (yaitu peristiwa onCommitted dikirim untuk frame utama baru). Dengan kata lain, mungkin ada lebih dari satu urutan peristiwa webNavigation yang tertunda dengan frameId yang sama. Urutan dapat dibedakan dengan kunci processId.

Perhatikan juga bahwa selama pemuatan sementara, proses dapat dialihkan beberapa kali. Hal ini terjadi saat beban dialihkan ke situs lain. Dalam hal ini, Anda akan menerima peristiwa onBeforeNavigate dan onErrorOccurred berulang, hingga Anda menerima peristiwa onCommitted terakhir.

Konsep lain yang bermasalah dengan ekstensi adalah siklus proses frame. Frame menghosting dokumen (yang terkait dengan URL yang di-commit). Dokumen dapat berubah (misalnya dengan membuka halaman), tetapi frameId tidak akan berubah, sehingga sulit untuk mengaitkan bahwa sesuatu terjadi dalam dokumen tertentu hanya dengan frameId. Kami memperkenalkan konsep documentId yang merupakan ID unik per dokumen. Jika frame dinavigasi dan membuka dokumen baru, ID akan berubah. Kolom ini berguna untuk menentukan kapan halaman mengubah status siklus prosesnya (antara pra-render/aktif/di-cache) karena tetap sama.

Jenis dan penentu transisi

Peristiwa webNavigation onCommitted memiliki properti transitionType dan transitionQualifiers. Jenis transisi sama dengan yang digunakan dalam history API yang menjelaskan cara browser membuka URL tertentu ini. Selain itu, beberapa penentu transisi dapat ditampilkan yang selanjutnya menentukan navigasi.

Kualifikasi transisi berikut ada:

Penentu transisiDeskripsi
"client_redirect"Satu atau beberapa pengalihan yang disebabkan oleh tag refresh meta atau JavaScript di halaman terjadi selama navigasi.
"server_redirect"Satu atau beberapa pengalihan yang disebabkan oleh header HTTP yang dikirim dari server terjadi selama navigasi.
"forward_back"Pengguna menggunakan tombol Maju atau Kembali untuk memulai navigasi.
"from_address_bar"Pengguna memulai navigasi dari kolom URL (alias Omnibox).

Contoh

Untuk mencoba API ini, instal contoh webNavigation API dari repositori chrome-extension-samples.

Jenis

TransitionQualifier

Chrome 44+

Enum

"client_redirect"

"server_redirect"

"forward_back"

"from_address_bar"

TransitionType

Chrome 44+

Penyebab navigasi. Jenis transisi yang sama seperti yang ditentukan dalam History API digunakan. Jenis transisi ini sama dengan yang ditentukan dalam history API, kecuali dengan "start_page" sebagai pengganti "auto_toplevel" (untuk kompatibilitas mundur).

Enum

"link"

"diketik"

"auto_bookmark"

"auto_subframe"

"manual_subframe"

"dibuat"

"start_page"

"form_submit"

"reload"

"keyword"

"keyword_generated"

Metode

getAllFrames()

chrome.webNavigation.getAllFrames(
  details: object,
)
: Promise<object[] | undefined>

Mengambil informasi tentang semua frame tab tertentu.

Parameter

  • detail

    objek

    Informasi tentang tab untuk mengambil semua frame dari.

    • tabId

      angka

      ID tab.

Hasil

  • Promise<object[] | undefined>

    Chrome 93+

getFrame()

chrome.webNavigation.getFrame(
  details: object,
)
: Promise<object | undefined>

Mengambil informasi tentang frame yang diberikan. Frame mengacu pada <iframe> atau <frame> halaman web dan diidentifikasi oleh ID tab dan ID frame.

Parameter

  • detail

    objek

    Informasi tentang frame untuk mengambil informasi.

    • documentId

      string opsional

      Chrome 106+

      UUID dokumen. Jika frameId dan/atau tabId diberikan, keduanya akan divalidasi agar cocok dengan dokumen yang ditemukan berdasarkan ID dokumen yang diberikan.

    • frameId

      nomor opsional

      ID frame di tab tertentu.

    • processId

      nomor opsional

      Tidak digunakan lagi sejak Chrome 49

      Frame kini diidentifikasi secara unik berdasarkan ID tab dan ID frame-nya; ID proses tidak lagi diperlukan dan oleh karena itu diabaikan.

      ID proses yang menjalankan perender untuk tab ini.

    • tabId

      nomor opsional

      ID tab tempat frame berada.

Hasil

  • Promise<object | undefined>

    Chrome 93+

Acara

onBeforeNavigate

chrome.webNavigation.onBeforeNavigate.addListener(
  callback: function,
  filters?: object,
)

Diaktifkan saat navigasi akan terjadi.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti:

    (details: object) => void

    • detail

      objek

      • Chrome 106+

        Siklus proses dokumen.

      • frameId

        angka

        0 menunjukkan bahwa navigasi terjadi di jendela konten tab; nilai positif menunjukkan navigasi di subframe. ID frame bersifat unik untuk tab dan proses tertentu.

      • Chrome 106+

        Jenis frame tempat navigasi terjadi.

      • parentDocumentId

        string opsional

        Chrome 106+

        UUID dokumen induk yang memiliki frame ini. Atribut ini tidak disetel jika tidak ada induk.

      • parentFrameId

        angka

        ID frame induk, atau -1 jika ini adalah frame utama.

      • processId

        angka

        Tidak digunakan lagi sejak Chrome 50

        processId tidak lagi ditetapkan untuk peristiwa ini, karena proses yang akan merender dokumen yang dihasilkan tidak diketahui hingga onCommit.

        Nilai -1.

      • tabId

        angka

        ID tab tempat navigasi akan terjadi.

      • timeStamp

        angka

        Waktu saat browser akan memulai navigasi, dalam milidetik sejak epoch.

      • url

        string

  • filter

    objek opsional

    • Kondisi yang harus dipenuhi oleh URL yang dituju. Kolom 'schemes' dan 'ports' dari UrlFilter diabaikan untuk peristiwa ini.

onCommitted

chrome.webNavigation.onCommitted.addListener(
  callback: function,
  filters?: object,
)

Diaktifkan saat navigasi dilakukan. Dokumen (dan resource yang dirujuknya, seperti gambar dan subframe) mungkin masih didownload, tetapi setidaknya sebagian dokumen telah diterima dari server dan browser telah memutuskan untuk beralih ke dokumen baru.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti:

    (details: object) => void

    • detail

      objek

      • documentId

        string

        Chrome 106+

        UUID dokumen yang dimuat.

      • Chrome 106+

        Siklus proses dokumen.

      • frameId

        angka

        0 menunjukkan bahwa navigasi terjadi di jendela konten tab; nilai positif menunjukkan navigasi di subframe. ID frame bersifat unik dalam tab.

      • Chrome 106+

        Jenis frame tempat navigasi terjadi.

      • parentDocumentId

        string opsional

        Chrome 106+

        UUID dokumen induk yang memiliki frame ini. Atribut ini tidak disetel jika tidak ada induk.

      • parentFrameId

        angka

        Chrome 74+

        ID frame induk, atau -1 jika ini adalah frame utama.

      • processId

        angka

        ID proses yang menjalankan perender untuk frame ini.

      • tabId

        angka

        ID tab tempat navigasi terjadi.

      • timeStamp

        angka

        Waktu saat navigasi dilakukan, dalam milidetik sejak epoch.

      • transitionQualifiers

        Daftar penentu transisi.

      • transitionType

        Penyebab navigasi.

      • url

        string

  • filter

    objek opsional

    • Kondisi yang harus dipenuhi oleh URL yang dituju. Kolom 'schemes' dan 'ports' dari UrlFilter diabaikan untuk peristiwa ini.

onCompleted

chrome.webNavigation.onCompleted.addListener(
  callback: function,
  filters?: object,
)

Diaktifkan saat dokumen, termasuk resource yang dirujuknya, dimuat dan diinisialisasi sepenuhnya.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti:

    (details: object) => void

    • detail

      objek

      • documentId

        string

        Chrome 106+

        UUID dokumen yang dimuat.

      • Chrome 106+

        Siklus proses dokumen.

      • frameId

        angka

        0 menunjukkan bahwa navigasi terjadi di jendela konten tab; nilai positif menunjukkan navigasi di subframe. ID frame bersifat unik dalam tab.

      • Chrome 106+

        Jenis frame tempat navigasi terjadi.

      • parentDocumentId

        string opsional

        Chrome 106+

        UUID dokumen induk yang memiliki frame ini. Atribut ini tidak disetel jika tidak ada induk.

      • parentFrameId

        angka

        Chrome 74+

        ID frame induk, atau -1 jika ini adalah frame utama.

      • processId

        angka

        ID proses yang menjalankan perender untuk frame ini.

      • tabId

        angka

        ID tab tempat navigasi terjadi.

      • timeStamp

        angka

        Waktu saat dokumen selesai dimuat, dalam milidetik sejak epoch.

      • url

        string

  • filter

    objek opsional

    • Kondisi yang harus dipenuhi oleh URL yang dituju. Kolom 'schemes' dan 'ports' dari UrlFilter diabaikan untuk peristiwa ini.

onCreatedNavigationTarget

chrome.webNavigation.onCreatedNavigationTarget.addListener(
  callback: function,
  filters?: object,
)

Diaktifkan saat jendela baru, atau tab baru di jendela yang ada, dibuat untuk menghosting navigasi.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti:

    (details: object) => void

    • detail

      objek

      • sourceFrameId

        angka

        ID frame dengan sourceTabId tempat navigasi dipicu. 0 menunjukkan frame utama.

      • sourceProcessId

        angka

        ID proses yang menjalankan perender untuk frame sumber.

      • sourceTabId

        angka

        ID tab tempat navigasi dipicu.

      • tabId

        angka

        ID tab tempat URL dibuka

      • timeStamp

        angka

        Waktu saat browser akan membuat tampilan baru, dalam milidetik sejak epoch.

      • url

        string

        URL yang akan dibuka di jendela baru.

  • filter

    objek opsional

    • Kondisi yang harus dipenuhi oleh URL yang dituju. Kolom 'schemes' dan 'ports' dari UrlFilter diabaikan untuk peristiwa ini.

onDOMContentLoaded

chrome.webNavigation.onDOMContentLoaded.addListener(
  callback: function,
  filters?: object,
)

Diaktifkan saat DOM halaman dibuat sepenuhnya, tetapi resource yang dirujuk mungkin belum selesai dimuat.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti:

    (details: object) => void

    • detail

      objek

      • documentId

        string

        Chrome 106+

        UUID dokumen yang dimuat.

      • Chrome 106+

        Siklus proses dokumen.

      • frameId

        angka

        0 menunjukkan bahwa navigasi terjadi di jendela konten tab; nilai positif menunjukkan navigasi di subframe. ID frame bersifat unik dalam tab.

      • Chrome 106+

        Jenis frame tempat navigasi terjadi.

      • parentDocumentId

        string opsional

        Chrome 106+

        UUID dokumen induk yang memiliki frame ini. Atribut ini tidak disetel jika tidak ada induk.

      • parentFrameId

        angka

        Chrome 74+

        ID frame induk, atau -1 jika ini adalah frame utama.

      • processId

        angka

        ID proses yang menjalankan perender untuk frame ini.

      • tabId

        angka

        ID tab tempat navigasi terjadi.

      • timeStamp

        angka

        Waktu saat DOM halaman dibuat sepenuhnya, dalam milidetik sejak epoch.

      • url

        string

  • filter

    objek opsional

    • Kondisi yang harus dipenuhi oleh URL yang dituju. Kolom 'schemes' dan 'ports' dari UrlFilter diabaikan untuk peristiwa ini.

onErrorOccurred

chrome.webNavigation.onErrorOccurred.addListener(
  callback: function,
  filters?: object,
)

Diaktifkan saat terjadi error dan navigasi dibatalkan. Hal ini dapat terjadi jika terjadi error jaringan, atau pengguna membatalkan navigasi.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti:

    (details: object) => void

    • detail

      objek

      • documentId

        string

        Chrome 106+

        UUID dokumen yang dimuat.

      • Chrome 106+

        Siklus proses dokumen.

      • error

        string

        Deskripsi error.

      • frameId

        angka

        0 menunjukkan bahwa navigasi terjadi di jendela konten tab; nilai positif menunjukkan navigasi di subframe. ID frame bersifat unik dalam tab.

      • Chrome 106+

        Jenis frame tempat navigasi terjadi.

      • parentDocumentId

        string opsional

        Chrome 106+

        UUID dokumen induk yang memiliki frame ini. Atribut ini tidak disetel jika tidak ada induk.

      • parentFrameId

        angka

        Chrome 74+

        ID frame induk, atau -1 jika ini adalah frame utama.

      • processId

        angka

        Tidak digunakan lagi sejak Chrome 50

        ProcessId tidak lagi ditetapkan untuk acara ini.

        Nilai -1.

      • tabId

        angka

        ID tab tempat navigasi terjadi.

      • timeStamp

        angka

        Waktu saat terjadi error, dalam milidetik sejak epoch.

      • url

        string

  • filter

    objek opsional

    • Kondisi yang harus dipenuhi oleh URL yang dituju. Kolom 'schemes' dan 'ports' dari UrlFilter diabaikan untuk peristiwa ini.

onHistoryStateUpdated

chrome.webNavigation.onHistoryStateUpdated.addListener(
  callback: function,
  filters?: object,
)

Diaktifkan saat histori frame diperbarui ke URL baru. Semua acara mendatang untuk frame tersebut akan menggunakan URL yang diperbarui.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti:

    (details: object) => void

    • detail

      objek

      • documentId

        string

        Chrome 106+

        UUID dokumen yang dimuat.

      • Chrome 106+

        Siklus proses dokumen.

      • frameId

        angka

        0 menunjukkan bahwa navigasi terjadi di jendela konten tab; nilai positif menunjukkan navigasi di subframe. ID frame bersifat unik dalam tab.

      • Chrome 106+

        Jenis frame tempat navigasi terjadi.

      • parentDocumentId

        string opsional

        Chrome 106+

        UUID dokumen induk yang memiliki frame ini. Atribut ini tidak disetel jika tidak ada induk.

      • parentFrameId

        angka

        Chrome 74+

        ID frame induk, atau -1 jika ini adalah frame utama.

      • processId

        angka

        ID proses yang menjalankan perender untuk frame ini.

      • tabId

        angka

        ID tab tempat navigasi terjadi.

      • timeStamp

        angka

        Waktu saat navigasi dilakukan, dalam milidetik sejak epoch.

      • transitionQualifiers

        Daftar penentu transisi.

      • transitionType

        Penyebab navigasi.

      • url

        string

  • filter

    objek opsional

    • Kondisi yang harus dipenuhi oleh URL yang dituju. Kolom 'schemes' dan 'ports' dari UrlFilter diabaikan untuk peristiwa ini.

onReferenceFragmentUpdated

chrome.webNavigation.onReferenceFragmentUpdated.addListener(
  callback: function,
  filters?: object,
)

Diaktifkan saat fragmen referensi frame diperbarui. Semua acara mendatang untuk frame tersebut akan menggunakan URL yang diperbarui.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti:

    (details: object) => void

    • detail

      objek

      • documentId

        string

        Chrome 106+

        UUID dokumen yang dimuat.

      • Chrome 106+

        Siklus proses dokumen.

      • frameId

        angka

        0 menunjukkan bahwa navigasi terjadi di jendela konten tab; nilai positif menunjukkan navigasi di subframe. ID frame bersifat unik dalam tab.

      • Chrome 106+

        Jenis frame tempat navigasi terjadi.

      • parentDocumentId

        string opsional

        Chrome 106+

        UUID dokumen induk yang memiliki frame ini. Atribut ini tidak disetel jika tidak ada induk.

      • parentFrameId

        angka

        Chrome 74+

        ID frame induk, atau -1 jika ini adalah frame utama.

      • processId

        angka

        ID proses yang menjalankan perender untuk frame ini.

      • tabId

        angka

        ID tab tempat navigasi terjadi.

      • timeStamp

        angka

        Waktu saat navigasi dilakukan, dalam milidetik sejak epoch.

      • transitionQualifiers

        Daftar penentu transisi.

      • transitionType

        Penyebab navigasi.

      • url

        string

  • filter

    objek opsional

    • Kondisi yang harus dipenuhi oleh URL yang dituju. Kolom 'schemes' dan 'ports' dari UrlFilter diabaikan untuk peristiwa ini.

onTabReplaced

chrome.webNavigation.onTabReplaced.addListener(
  callback: function,
)

Diaktifkan saat konten tab diganti dengan tab lain (biasanya tab yang sebelumnya telah di-pra-render).

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti:

    (details: object) => void

    • detail

      objek

      • replacedTabId

        angka

        ID tab yang diganti.

      • tabId

        angka

        ID tab yang menggantikan tab lama.

      • timeStamp

        angka

        Waktu saat penggantian terjadi, dalam milidetik sejak epoch.