Deskripsi
Gunakan chrome.webNavigation
API untuk menerima notifikasi terkait status permintaan navigasi yang sedang berlangsung.
Izin
webNavigation
Manifes
Semua metode dan peristiwa chrome.webNavigation
mengharuskan Anda mendeklarasikan izin "webNavigation" dalam manifes ekstensi. Contoh:
{
"name": "My extension",
...
"permissions": [
"webNavigation"
],
...
}
Urutan peristiwa
Untuk navigasi yang berhasil diselesaikan, peristiwa akan diaktifkan dalam urutan berikut:
onBeforeNavigate -> onCommitted -> [onDOMContentLoaded] -> onCompleted
Setiap error yang terjadi selama proses akan menghasilkan peristiwa onErrorOccurred
. Untuk navigasi
tertentu, tidak ada peristiwa lebih lanjut yang diaktifkan setelah onErrorOccurred
.
Jika frame navigasi berisi subframe, onCommitted
-nya akan diaktifkan sebelum onBeforeNavigate
turunannya; sedangkan onCompleted
akan diaktifkan setelah semua onCompleted
turunannya.
Jika fragmen referensi frame diubah, peristiwa onReferenceFragmentUpdated
akan diaktifkan. Peristiwa
ini dapat diaktifkan kapan saja setelah onDOMContentLoaded
, bahkan setelah onCompleted
.
Jika API histori 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 Cache Back Forward, peristiwa onDOMContentLoaded
tidak akan diaktifkan. Peristiwa ini tidak diaktifkan karena konten sudah selesai dimuat saat halaman pertama kali dikunjungi.
Jika navigasi dipicu melalui Chrome Instan atau Halaman Instan, halaman yang dimuat sepenuhnya
akan ditukar ke tab saat ini. Dalam hal ini, peristiwa onTabReplaced
akan diaktifkan.
Hubungan dengan peristiwa webRequest
Tidak ada pengurutan yang ditentukan antara peristiwa webRequest API dan peristiwa webNavigation API. Ada kemungkinan bahwa peristiwa webRequest masih diterima untuk frame yang telah memulai navigasi baru, atau navigasi hanya dilanjutkan setelah resource jaringan sudah 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 buram bagi pengguna.
ID tab
Tidak semua tab navigasi sesuai dengan tab sebenarnya di UI Chrome, misalnya tab yang sedang
dirender sebelumnya. Tab tersebut tidak dapat diakses melalui API tab. Anda juga tidak dapat meminta informasi
tentang tab tersebut melalui webNavigation.getFrame
atau webNavigation.getAllFrames
. Setelah tab tersebut ditukar, peristiwa onTabReplaced
akan diaktifkan dan dapat diakses melalui API ini.
Stempel waktu
Penting untuk diperhatikan bahwa beberapa ketidaksesuaian teknis dalam penanganan proses Chrome yang berbeda oleh OS dapat menyebabkan jam menjadi tidak tepat antara browser itu sendiri dan proses ekstensi. Artinya, properti timeStamp
peristiwa WebNavigation hanya dijamin konsisten secara internal. Membandingkan satu peristiwa dengan peristiwa lain akan memberi Anda offset yang benar di antara peristiwa tersebut, tetapi membandingkannya dengan waktu saat ini dalam ekstensi (misalnya melalui (new Date()).getTime()
) dapat memberikan hasil yang tidak diharapkan.
ID Frame
Frame dalam tab dapat diidentifikasi dengan ID frame. ID frame utama selalu 0, ID frame turunan adalah angka positif. Setelah dokumen dibuat dalam frame, ID frame-nya akan tetap konstan selama masa aktif dokumen tersebut. Mulai Chrome 49, ID ini juga konstan selama masa aktif frame (di beberapa navigasi).
Karena sifat multiproses Chrome, tab mungkin menggunakan proses yang berbeda untuk merender sumber
dan tujuan halaman web. Oleh karena itu, jika navigasi berlangsung dalam proses baru, Anda mungkin
menerima peristiwa dari halaman baru dan lama hingga navigasi baru di-commit (yaitu
peristiwa onCommitted
dikirim untuk frame utama baru). Dengan kata lain, Anda dapat memiliki lebih dari satu urutan peristiwa webNavigation yang tertunda dengan frameId
yang sama. Urutan dapat
dibedakan dengan kunci processId
.
Perhatikan juga bahwa selama pemuatan sementara, prosesnya mungkin diganti beberapa kali. Hal ini terjadi saat beban dialihkan ke situs lain. Dalam hal ini, Anda akan menerima peristiwa onBeforeNavigate
dan onErrorOccurred
berulang, sampai Anda menerima peristiwa onCommitted
akhir.
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 menavigasi) tetapi frameId tidak akan berubah, sehingga sulit untuk mengaitkan sesuatu yang terjadi dalam dokumen tertentu hanya dengan frameIds. Kami memperkenalkan konsep documentId yang merupakan ID unik per dokumen. Jika sebuah frame dinavigasi dan membuka dokumen baru, ID akan berubah. Kolom ini berguna untuk menentukan kapan halaman mengubah status siklus prosesnya (antara pra-rendering/aktif/cache) karena tetap sama.
Jenis dan penentu transisi
Peristiwa onCommitted
webNavigation API memiliki properti transitionType
dan transitionQualifiers
. Jenis transisi sama dengan yang digunakan dalam API histori yang menjelaskan cara
browser membuka URL khusus ini. Selain itu, beberapa penentu transisi dapat
ditampilkan yang menentukan navigasi lebih lanjut.
Terdapat penentu transisi berikut:
Penentu transisi | Deskripsi |
---|---|
"client_redirect" | Satu atau beberapa pengalihan yang disebabkan oleh tag JavaScript atau refresh meta di halaman terjadi selama navigasi. |
"server_redirect" | Satu atau beberapa pengalihan yang disebabkan oleh header HTTP yang dikirim dari server terjadi selama navigasi. |
"maju_kembali" | Pengguna menggunakan tombol Maju atau Mundur untuk memulai navigasi. |
"from_address_bar" | Pengguna memulai navigasi dari bilah alamat (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. Menggunakan jenis transisi yang sama seperti yang ditentukan dalam API histori. Ini adalah jenis transisi yang sama seperti yang ditentukan dalam API histori, kecuali dengan "start_page"
sebagai pengganti "auto_toplevel"
(untuk kompatibilitas mundur).
Enum
"link"
"auto_bookmark"
"auto_subframe"
"manual_subframe"
"start_page"
"form_submit"
"keyword_generated"
Metode
getAllFrames()
chrome.webNavigation.getAllFrames(
details: object,
callback?: function,
)
Mengambil informasi tentang semua frame dari tab tertentu.
Parameter
-
detail
objek
Informasi tentang tab tempat mengambil semua frame.
-
tabId
angka
ID tab.
-
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:(details?: object[]) => void
-
detail
object[] opsional
Daftar frame di tab yang diberikan, null jika ID tab yang ditentukan tidak valid.
-
documentId
string
Chrome 106+UUID dokumen yang dimuat.
-
documentLifecycleChrome 106+
Siklus proses tempat dokumen berada.
-
errorOccurred
boolean
True jika navigasi terakhir dalam frame ini terganggu oleh error, yaitu peristiwa onErrorOccurred diaktifkan.
-
frameId
angka
ID bingkai. 0 menunjukkan bahwa ini adalah {i>frame<i} utama; nilai positif menunjukkan ID subframe.
-
frameTypeChrome 106+
Jenis frame tempat navigasi terjadi.
-
parentDocumentId
string opsional
Chrome 106+UUID dokumen induk yang memiliki frame ini. Ini tidak disetel jika tidak ada induk.
-
parentFrameId
angka
ID frame induk, atau
-1
jika ini adalah frame utama. -
processId
angka
ID proses yang menjalankan perender untuk frame ini.
-
url
string
URL yang saat ini terkait dengan frame ini.
-
-
Hasil
-
Promise<object[] | undefined>
Chrome 93 dan yang lebih baruPromise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.
getFrame()
chrome.webNavigation.getFrame(
details: object,
callback?: function,
)
Mengambil informasi tentang frame yang diberikan. Bingkai mengacu pada <iframe> atau <frame> dari laman web dan diidentifikasi oleh ID tab dan ID bingkai.
Parameter
-
detail
objek
Informasi tentang {i>frame<i} yang informasinya akan diambil.
-
documentId
string opsional
Chrome 106+UUID dokumen. Jika frameId dan/atau tabId diberikan, keduanya akan divalidasi agar cocok dengan dokumen yang ditemukan oleh ID dokumen yang diberikan.
-
frameId
nomor opsional
ID frame di tab yang ditentukan.
-
processId
nomor opsional
Tidak digunakan lagi sejak Chrome 49Frame kini diidentifikasi secara unik oleh ID tab dan ID frame-nya; ID proses tidak lagi diperlukan dan karenanya diabaikan.
ID proses yang menjalankan perender untuk tab ini.
-
tabId
nomor opsional
ID tab tempat bingkai berada.
-
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:(details?: object) => void
-
detail
objek opsional
Informasi tentang frame yang diminta, null jika ID frame dan/atau ID tab yang ditentukan tidak valid.
-
documentId
string
Chrome 106+UUID dokumen yang dimuat.
-
documentLifecycleChrome 106+
Siklus proses tempat dokumen berada.
-
errorOccurred
boolean
True jika navigasi terakhir dalam frame ini terganggu oleh error, yaitu peristiwa onErrorOccurred diaktifkan.
-
frameTypeChrome 106+
Jenis frame tempat navigasi terjadi.
-
parentDocumentId
string opsional
Chrome 106+UUID dokumen induk yang memiliki frame ini. Ini tidak disetel jika tidak ada induk.
-
parentFrameId
angka
ID frame induk, atau
-1
jika ini adalah frame utama. -
url
string
URL yang saat ini terkait dengan frame ini, jika frame yang diidentifikasi oleh frameId ada pada satu titik di tab yang ditentukan. Fakta bahwa URL terkait dengan frameId tertentu tidak berarti bahwa frame yang sesuai masih ada.
-
-
Hasil
-
Promise<object | undefined>
Chrome 93 dan yang lebih baruPromise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.
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 tempat dokumen berada.
-
angka
0 menunjukkan 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. 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 akan dinavigasi. Kolom 'skema' dan 'port' UrlFilter diabaikan untuk peristiwa ini.
-
onCommitted
chrome.webNavigation.onCommitted.addListener(
callback: function,
filters?: object,
)
Diaktifkan saat navigasi di-commit. Dokumen (dan resource yang dirujuknya, seperti gambar dan subframe) mungkin masih dapat 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 tempat dokumen berada.
-
frameId
angka
0 menunjukkan navigasi terjadi di jendela konten tab; nilai positif menunjukkan navigasi di subframe. ID Frame bersifat unik di dalam tab.
-
frameTypeChrome 106+
Jenis frame tempat navigasi terjadi.
-
parentDocumentId
string opsional
Chrome 106+UUID dokumen induk yang memiliki frame ini. Ini tidak disetel jika tidak ada induk.
-
parentFrameId
angka
Chrome 74 dan yang lebih baruID 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 di-commit, dalam milidetik sejak epoch.
-
transitionQualifiers
Daftar penentu transisi.
-
transitionType
Penyebab navigasi.
-
url
string
-
-
-
filter
objek opsional
-
url
Kondisi yang harus dipenuhi oleh URL yang akan dinavigasi. Kolom 'skema' dan 'port' 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 tempat dokumen berada.
-
frameId
angka
0 menunjukkan navigasi terjadi di jendela konten tab; nilai positif menunjukkan navigasi di subframe. ID Frame bersifat unik di dalam tab.
-
frameTypeChrome 106+
Jenis frame tempat navigasi terjadi.
-
parentDocumentId
string opsional
Chrome 106+UUID dokumen induk yang memiliki frame ini. Ini tidak disetel jika tidak ada induk.
-
parentFrameId
angka
Chrome 74 dan yang lebih baruID 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 akan dinavigasi. Kolom 'skema' dan 'port' 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 bingkai dengan sourceTabId tempat navigasi dipicu. 0 menunjukkan {i>frame<i} 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 akan dinavigasi. Kolom 'skema' dan 'port' UrlFilter diabaikan untuk peristiwa ini.
-
onDOMContentLoaded
chrome.webNavigation.onDOMContentLoaded.addListener(
callback: function,
filters?: object,
)
Diaktifkan saat DOM halaman sepenuhnya dibuat, tetapi resource yang direferensikan mungkin tidak 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 tempat dokumen berada.
-
frameId
angka
0 menunjukkan navigasi terjadi di jendela konten tab; nilai positif menunjukkan navigasi di subframe. ID Frame bersifat unik di dalam tab.
-
frameTypeChrome 106+
Jenis frame tempat navigasi terjadi.
-
parentDocumentId
string opsional
Chrome 106+UUID dokumen induk yang memiliki frame ini. Ini tidak disetel jika tidak ada induk.
-
parentFrameId
angka
Chrome 74 dan yang lebih baruID 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 sepenuhnya dibuat, dalam milidetik sejak epoch.
-
url
string
-
-
-
filter
objek opsional
-
url
Kondisi yang harus dipenuhi oleh URL yang akan dinavigasi. Kolom 'skema' dan 'port' UrlFilter diabaikan untuk peristiwa ini.
-
onErrorOccurred
chrome.webNavigation.onErrorOccurred.addListener(
callback: function,
filters?: object,
)
Diaktifkan jika 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 tempat dokumen berada.
-
error
string
Deskripsi error.
-
frameId
angka
0 menunjukkan navigasi terjadi di jendela konten tab; nilai positif menunjukkan navigasi di subframe. ID Frame bersifat unik di dalam tab.
-
frameTypeChrome 106+
Jenis frame tempat navigasi terjadi.
-
parentDocumentId
string opsional
Chrome 106+UUID dokumen induk yang memiliki frame ini. Ini tidak disetel jika tidak ada induk.
-
parentFrameId
angka
Chrome 74 dan yang lebih baruID frame induk, atau
-1
jika ini adalah frame utama. -
processId
angka
Tidak digunakan lagi sejak Chrome 50processId tidak lagi ditetapkan untuk peristiwa ini.
Nilai -1.
-
tabId
angka
ID tab tempat navigasi terjadi.
-
timeStamp
angka
Waktu terjadinya error, dalam milidetik sejak epoch.
-
url
string
-
-
-
filter
objek opsional
-
url
Kondisi yang harus dipenuhi oleh URL yang akan dinavigasi. Kolom 'skema' dan 'port' UrlFilter diabaikan untuk peristiwa ini.
-
onHistoryStateUpdated
chrome.webNavigation.onHistoryStateUpdated.addListener(
callback: function,
filters?: object,
)
Diaktifkan saat histori frame diperbarui ke URL baru. Semua peristiwa mendatang untuk bingkai 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 tempat dokumen berada.
-
frameId
angka
0 menunjukkan navigasi terjadi di jendela konten tab; nilai positif menunjukkan navigasi di subframe. ID Frame bersifat unik di dalam tab.
-
frameTypeChrome 106+
Jenis frame tempat navigasi terjadi.
-
parentDocumentId
string opsional
Chrome 106+UUID dokumen induk yang memiliki frame ini. Ini tidak disetel jika tidak ada induk.
-
parentFrameId
angka
Chrome 74 dan yang lebih baruID 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 di-commit, dalam milidetik sejak epoch.
-
transitionQualifiers
Daftar penentu transisi.
-
transitionType
Penyebab navigasi.
-
url
string
-
-
-
filter
objek opsional
-
url
Kondisi yang harus dipenuhi oleh URL yang akan dinavigasi. Kolom 'skema' dan 'port' UrlFilter diabaikan untuk peristiwa ini.
-
onReferenceFragmentUpdated
chrome.webNavigation.onReferenceFragmentUpdated.addListener(
callback: function,
filters?: object,
)
Diaktifkan saat fragmen referensi frame diperbarui. Semua peristiwa mendatang untuk bingkai 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 tempat dokumen berada.
-
frameId
angka
0 menunjukkan navigasi terjadi di jendela konten tab; nilai positif menunjukkan navigasi di subframe. ID Frame bersifat unik di dalam tab.
-
frameTypeChrome 106+
Jenis frame tempat navigasi terjadi.
-
parentDocumentId
string opsional
Chrome 106+UUID dokumen induk yang memiliki frame ini. Ini tidak disetel jika tidak ada induk.
-
parentFrameId
angka
Chrome 74 dan yang lebih baruID 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 di-commit, dalam milidetik sejak epoch.
-
transitionQualifiers
Daftar penentu transisi.
-
transitionType
Penyebab navigasi.
-
url
string
-
-
-
filter
objek opsional
-
url
Kondisi yang harus dipenuhi oleh URL yang akan dinavigasi. Kolom 'skema' dan 'port' UrlFilter diabaikan untuk peristiwa ini.
-
onTabReplaced
chrome.webNavigation.onTabReplaced.addListener(
callback: function,
)
Diaktifkan jika konten tab diganti dengan tab lain (biasanya telah dipra-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.
-
-