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 transisi | Deskripsi |
---|---|
"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
Enum
"client_redirect"
"server_redirect"
"forward_back"
"from_address_bar"
TransitionType
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 49Frame 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
-
fungsi
Parameter
callback
terlihat seperti:(details: object) => void
-
objek
- Chrome 106+
Siklus proses dokumen.
-
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.
-
string opsional
Chrome 106+UUID dokumen induk yang memiliki frame ini. Atribut ini tidak disetel jika tidak ada induk.
-
angka
ID frame induk, atau
-1
jika ini adalah frame utama. -
angka
Tidak digunakan lagi sejak Chrome 50processId tidak lagi ditetapkan untuk peristiwa ini, karena proses yang akan merender dokumen yang dihasilkan tidak diketahui hingga onCommit.
Nilai -1.
-
angka
ID tab tempat navigasi akan terjadi.
-
angka
Waktu saat browser akan memulai navigasi, dalam milidetik sejak epoch.
-
string
-
-
-
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.
- documentLifecycleChrome 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.
- frameTypeChrome 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
- url
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.
- documentLifecycleChrome 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.
- frameTypeChrome 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
- url
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
-
fungsi
Parameter
callback
terlihat seperti:(details: object) => void
-
objek
-
angka
ID frame dengan sourceTabId tempat navigasi dipicu. 0 menunjukkan frame utama.
-
angka
ID proses yang menjalankan perender untuk frame sumber.
-
angka
ID tab tempat navigasi dipicu.
-
angka
ID tab tempat URL dibuka
-
angka
Waktu saat browser akan membuat tampilan baru, dalam milidetik sejak epoch.
-
string
URL yang akan dibuka di jendela baru.
-
-
-
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.
- documentLifecycleChrome 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.
- frameTypeChrome 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
- url
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.
- documentLifecycleChrome 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.
- frameTypeChrome 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 50ProcessId 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
- url
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.
- documentLifecycleChrome 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.
- frameTypeChrome 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
- url
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.
- documentLifecycleChrome 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.
- frameTypeChrome 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
- url
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.
-
-