refresh date: 2026-09-25 robots: noindex
Descrizione
Utilizza l'API chrome.webNavigation per ricevere notifiche sullo stato delle richieste di navigazione in corso.
Autorizzazioni
webNavigationManifest
Tutti i metodi e gli eventi chrome.webNavigation richiedono la dichiarazione dell'autorizzazione "webNavigation" nel manifest dell'estensione. Ad esempio:
{
"name": "My extension",
...
"permissions": [
"webNavigation"
],
...
}
Ordine degli eventi
Per una navigazione completata correttamente, gli eventi vengono attivati nel seguente ordine:
onBeforeNavigate -> onCommitted -> [onDOMContentLoaded] -> onCompleted
Qualsiasi errore che si verifica durante il processo genera un evento onErrorOccurred. Per una navigazione specifica, non vengono attivati altri eventi dopo onErrorOccurred.
Se un frame di navigazione contiene frame secondari, il relativo onCommitted viene attivato prima di qualsiasi onBeforeNavigate dei relativi elementi secondari, mentre onCompleted viene attivato dopo tutti i onCompleted dei relativi elementi secondari.
Se il frammento di riferimento di un frame viene modificato, viene attivato un evento onReferenceFragmentUpdated. Questo
evento può essere attivato in qualsiasi momento dopo onDOMContentLoaded, anche dopo onCompleted.
Se l'API History viene utilizzata per modificare lo stato di un frame (ad es. utilizzando history.pushState()), viene attivato un evento onHistoryStateUpdated. Questo evento può essere attivato in qualsiasi momento dopo il giorno onDOMContentLoaded.
Se una navigazione ha ripristinato una pagina dalla cache back-forward, l'evento onDOMContentLoaded non verrà attivato. L'evento non viene attivato perché il caricamento dei contenuti è già stato completato alla prima visita della pagina.
Se la navigazione è stata attivata tramite Chrome Instant o Pagine istantanee, una pagina completamente caricata viene scambiata con la scheda corrente. In questo caso, viene attivato un evento onTabReplaced.
Relazione con gli eventi webRequest
Non esiste un ordine definito tra gli eventi dell'API webRequest e gli eventi dell'API webNavigation. È possibile che gli eventi webRequest vengano ancora ricevuti per i frame che hanno già avviato una nuova navigazione o che una navigazione proceda solo dopo che le risorse di rete sono già state caricate completamente.
In generale, gli eventi webNavigation sono strettamente correlati allo stato di navigazione visualizzato nell'interfaccia utente, mentre gli eventi webRequest corrispondono allo stato dello stack di rete, che in genere è opaco per l'utente.
ID schede
Non tutte le schede di navigazione corrispondono a schede effettive nell'interfaccia utente di Chrome, ad esempio una scheda di cui è in corso il prerendering. Queste schede non sono accessibili tramite l'API Tabs e non puoi richiedere informazioni
su di esse tramite webNavigation.getFrame o webNavigation.getAllFrames. Una volta scambiata una scheda di questo tipo, viene attivato un evento onTabReplaced e la scheda diventa accessibile tramite queste API.
Timestamp
È importante notare che alcune anomalie tecniche nella gestione di processi Chrome distinti da parte del sistema operativo possono causare una discrepanza dell'orologio tra il browser stesso e i processi delle estensioni. Ciò significa che la proprietà timeStamp degli eventi di WebNavigation è garantita solo per essere coerente internamente. Il confronto di un evento con un altro ti darà l'offset corretto tra i due, ma il confronto con l'ora corrente all'interno dell'estensione (ad esempio tramite (new Date()).getTime()) potrebbe dare risultati imprevisti.
ID frame
I frame all'interno di una scheda possono essere identificati da un ID frame. L'ID frame del frame principale è sempre 0, mentre l'ID dei frame secondari è un numero positivo. Una volta creato un documento in un frame, il relativo ID frame rimane costante per tutta la durata del documento. A partire da Chrome 49, questo ID è anche costante per la durata del frame (tra più navigazioni).
A causa della natura multiprocesso di Chrome, una scheda potrebbe utilizzare processi diversi per eseguire il rendering dell'origine e della destinazione di una pagina web. Pertanto, se una navigazione avviene in un nuovo processo, potresti ricevere eventi sia dalla nuova che dalla vecchia pagina fino a quando non viene eseguito il commit della nuova navigazione (ovvero viene inviato l'evento onCommitted per il nuovo frame principale). In altre parole, è possibile avere più di una sequenza in attesa di eventi webNavigation con lo stesso frameId. Le sequenze possono essere
distinte dalla chiave processId.
Tieni presente inoltre che durante un caricamento provvisorio il processo potrebbe essere cambiato più volte. Questo accade quando il carico viene reindirizzato a un sito diverso. In questo caso, riceverai eventi onBeforeNavigate e onErrorOccurred ripetuti fino a quando non riceverai l'evento onCommitted finale.
Un altro concetto problematico con le estensioni è il ciclo di vita del frame. Un frame ospita un documento (associato a un URL sottoposto a commit). Il documento può cambiare (ad esempio tramite la navigazione), ma il frameId non cambia, quindi è difficile associare un evento a un documento specifico solo con i frameId. Stiamo introducendo il concetto di documentId, che è un identificatore univoco per documento. Se un frame viene esplorato e apre un nuovo documento, l'identificatore cambia. Questo campo è utile per determinare quando le pagine cambiano lo stato del ciclo di vita (tra prerendering/attivo/memorizzato nella cache) perché rimane invariato.
Tipi di transizione e qualificatori
L'evento onCommitted dell'API webNavigation ha una proprietà transitionType e una proprietà transitionQualifiers. Il tipo di transizione è lo stesso utilizzato nell'API History che descrive in che modo il browser ha raggiunto questo URL specifico. Inoltre, possono essere restituiti diversi qualificatori di transizione che definiscono ulteriormente la navigazione.
Esistono i seguenti qualificatori di transizione:
| Qualificatore di transizione | Descrizione |
|---|---|
| "client_redirect" | Durante la navigazione si sono verificati uno o più reindirizzamenti causati da JavaScript o da tag meta refresh nella pagina. |
| "server_redirect" | Durante la navigazione si sono verificati uno o più reindirizzamenti causati da intestazioni HTTP inviate dal server. |
| "forward_back" | L'utente ha utilizzato il pulsante Avanti o Indietro per avviare la navigazione. |
| "from_address_bar" | L'utente ha avviato la navigazione dalla barra degli indirizzi (nota anche come omnibox). |
Esempi
Per provare questa API, installa l'esempio di API webNavigation dal repository chrome-extension-samples.
Tipi
TransitionQualifier
Enum
"client_redirect"
"server_redirect"
"forward_back"
"from_address_bar"
TransitionType
Causa della navigazione. Vengono utilizzati gli stessi tipi di transizione definiti nell'API History. Questi sono gli stessi tipi di transizione definiti nell'API History, ad eccezione di "start_page" al posto di "auto_toplevel" (per la compatibilità con le versioni precedenti).
Enum
"link"
"typed"
"auto_bookmark"
"auto_subframe"
"manual_subframe"
"generated"
"start_page"
"form_submit"
"reload"
"keyword"
"keyword_generated"
Metodi
getAllFrames()
chrome.webNavigation.getAllFrames(
details: object,
callback?: function,
): Promise<object[] | undefined>
Recupera le informazioni su tutti i frame di una determinata scheda.
Parametri
-
dettagli
oggetto
Informazioni sulla scheda da cui recuperare tutti i frame.
-
tabId
numero
L'ID della scheda.
-
-
callback
funzione elemento facoltativo
Il parametro
callbackha il seguente aspetto:(details?: object[]) => void
-
dettagli
object[] facoltativo
Un elenco di frame nella scheda specificata, null se l'ID della scheda specificata non è valido.
-
documentId
stringa
Chrome 106 e versioni successiveUn UUID del documento caricato.
-
documentLifecycleChrome 106 e versioni successive
Il ciclo di vita in cui si trova il documento.
-
errorOccurred
booleano
True se l'ultima navigazione in questo frame è stata interrotta da un errore, ovvero se è stato attivato l'evento onErrorOccurred.
-
frameId
numero
L'ID del frame. 0 indica che si tratta del frame principale; un valore positivo indica l'ID di un frame secondario.
-
frameTypeChrome 106 e versioni successive
Il tipo di frame in cui si è verificata la navigazione.
-
parentDocumentId
stringa facoltativa
Chrome 106 e versioni successiveUn UUID del documento principale proprietario di questo frame. Questo valore non viene impostato se non esiste un elemento principale.
-
parentFrameId
numero
L'ID del frame principale o
-1se si tratta del frame principale. -
processId
numero
L'ID del processo che esegue il renderer per questo frame.
-
url
stringa
L'URL attualmente associato a questo frame.
-
-
Resi
-
Promise<object[] | undefined>
Chrome 93 e versioni successiveLe promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.
getFrame()
chrome.webNavigation.getFrame(
details: object,
callback?: function,
): Promise<object | undefined>
Recupera le informazioni sul frame specificato. Un frame si riferisce a un <iframe> o a un <frame> di una pagina web ed è identificato da un ID scheda e un ID frame.
Parametri
-
dettagli
oggetto
Informazioni sul frame di cui recuperare le informazioni.
-
documentId
stringa facoltativa
Chrome 106 e versioni successiveL'UUID del documento. Se vengono forniti frameId e/o tabId, verranno convalidati in modo che corrispondano al documento trovato tramite l'ID documento fornito.
-
frameId
number optional
L'ID del frame nella scheda specificata.
-
processId
number optional
Ritirato da Chrome 49I frame sono ora identificati in modo univoco dal relativo ID scheda e ID frame; l'ID di processo non è più necessario e viene quindi ignorato.
L'ID del processo che esegue il renderer per questa scheda.
-
tabId
number optional
L'ID della scheda in cui si trova il frame.
-
-
callback
funzione elemento facoltativo
Il parametro
callbackha il seguente aspetto:(details?: object) => void
-
dettagli
object facoltativo
Informazioni sul frame richiesto, null se l'ID frame e/o l'ID scheda specificati non sono validi.
-
documentId
stringa
Chrome 106 e versioni successiveUn UUID del documento caricato.
-
documentLifecycleChrome 106 e versioni successive
Il ciclo di vita in cui si trova il documento.
-
errorOccurred
booleano
True se l'ultima navigazione in questo frame è stata interrotta da un errore, ovvero se è stato attivato l'evento onErrorOccurred.
-
frameTypeChrome 106 e versioni successive
Il tipo di frame in cui si è verificata la navigazione.
-
parentDocumentId
stringa facoltativa
Chrome 106 e versioni successiveUn UUID del documento principale proprietario di questo frame. Questo valore non viene impostato se non esiste un elemento principale.
-
parentFrameId
numero
L'ID del frame principale o
-1se si tratta del frame principale. -
url
stringa
L'URL attualmente associato a questo frame, se il frame identificato da frameId esisteva in un determinato momento nella scheda specificata. Il fatto che un URL sia associato a un determinato frameId non implica che il frame corrispondente esista ancora.
-
-
Resi
-
Promise<object | undefined>
Chrome 93 e versioni successiveLe promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.
Eventi
onBeforeNavigate
chrome.webNavigation.onBeforeNavigate.addListener(
callback: function,
filters?: object,
)
Attivato quando sta per verificarsi una navigazione.
Parametri
-
funzione
Il parametro
callbackha il seguente aspetto:(details: object) => void
-
oggetto
-
Chrome 106 e versioni successive
Il ciclo di vita in cui si trova il documento.
-
numero
0 indica che la navigazione avviene nella finestra dei contenuti della scheda; un valore positivo indica la navigazione in un frame secondario. Gli ID frame sono univoci per una determinata scheda e un determinato processo.
-
Chrome 106 e versioni successive
Il tipo di frame in cui si è verificata la navigazione.
-
stringa facoltativa
Chrome 106 e versioni successiveUn UUID del documento principale proprietario di questo frame. Questo valore non viene impostato se non esiste un elemento principale.
-
numero
L'ID del frame principale o
-1se si tratta del frame principale. -
numero
Ritirato da Chrome 50Il processId non è più impostato per questo evento, poiché il processo che eseguirà il rendering del documento risultante non è noto fino a onCommit.
Il valore -1.
-
numero
L'ID della scheda in cui sta per avvenire la navigazione.
-
numero
L'ora in cui il browser stava per avviare la navigazione, in millisecondi dall'epoca.
-
stringa
-
-
-
object facoltativo
-
Condizioni che l'URL di destinazione deve soddisfare.
-
onCommitted
chrome.webNavigation.onCommitted.addListener(
callback: function,
filters?: object,
)
Attivato quando viene eseguito il commit di una navigazione. Il documento (e le risorse a cui fa riferimento, come immagini e frame secondari) potrebbe essere ancora in fase di download, ma almeno una parte del documento è stata ricevuta dal server e il browser ha deciso di passare al nuovo documento.
Parametri
-
callback
funzione
Il parametro
callbackha il seguente aspetto:(details: object) => void
-
dettagli
oggetto
-
documentId
stringa
Chrome 106 e versioni successiveUn UUID del documento caricato.
-
documentLifecycleChrome 106 e versioni successive
Il ciclo di vita in cui si trova il documento.
-
frameId
numero
0 indica che la navigazione avviene nella finestra dei contenuti della scheda; un valore positivo indica la navigazione in un frame secondario. Gli ID frame sono univoci all'interno di una scheda.
-
frameTypeChrome 106 e versioni successive
Il tipo di frame in cui si è verificata la navigazione.
-
parentDocumentId
stringa facoltativa
Chrome 106 e versioni successiveUn UUID del documento principale proprietario di questo frame. Questo valore non viene impostato se non esiste un elemento principale.
-
parentFrameId
numero
Chrome 74 e versioni successiveL'ID del frame principale o
-1se si tratta del frame principale. -
processId
numero
L'ID del processo che esegue il renderer per questo frame.
-
tabId
numero
L'ID della scheda in cui avviene la navigazione.
-
timeStamp
numero
L'ora in cui è stato eseguito il commit della navigazione, in millisecondi dall'epoca.
-
transitionQualifiers
Un elenco di qualificatori di transizione.
-
transitionType
Causa della navigazione.
-
url
stringa
-
-
-
filtri
object facoltativo
-
url
Condizioni che l'URL di destinazione deve soddisfare.
-
onCompleted
chrome.webNavigation.onCompleted.addListener(
callback: function,
filters?: object,
)
Attivato quando un documento, incluse le risorse a cui fa riferimento, viene caricato e inizializzato completamente.
Parametri
-
callback
funzione
Il parametro
callbackha il seguente aspetto:(details: object) => void
-
dettagli
oggetto
-
documentId
stringa
Chrome 106 e versioni successiveUn UUID del documento caricato.
-
documentLifecycleChrome 106 e versioni successive
Il ciclo di vita in cui si trova il documento.
-
frameId
numero
0 indica che la navigazione avviene nella finestra dei contenuti della scheda; un valore positivo indica la navigazione in un frame secondario. Gli ID frame sono univoci all'interno di una scheda.
-
frameTypeChrome 106 e versioni successive
Il tipo di frame in cui si è verificata la navigazione.
-
parentDocumentId
stringa facoltativa
Chrome 106 e versioni successiveUn UUID del documento principale proprietario di questo frame. Questo valore non viene impostato se non esiste un elemento principale.
-
parentFrameId
numero
Chrome 74 e versioni successiveL'ID del frame principale o
-1se si tratta del frame principale. -
processId
numero
L'ID del processo che esegue il renderer per questo frame.
-
tabId
numero
L'ID della scheda in cui avviene la navigazione.
-
timeStamp
numero
L'ora in cui è stato completato il caricamento del documento, in millisecondi dall'epoca.
-
url
stringa
-
-
-
filtri
object facoltativo
-
url
Condizioni che l'URL di destinazione deve soddisfare.
-
onCreatedNavigationTarget
chrome.webNavigation.onCreatedNavigationTarget.addListener(
callback: function,
filters?: object,
)
Attivato quando viene creata una nuova finestra o una nuova scheda in una finestra esistente per ospitare una navigazione.
Parametri
-
funzione
Il parametro
callbackha il seguente aspetto:(details: object) => void
-
oggetto
-
numero
L'ID del frame con sourceTabId in cui viene attivata la navigazione. 0 indica il frame principale.
-
numero
L'ID del processo che esegue il renderer per il frame di origine.
-
numero
L'ID della scheda in cui viene attivata la navigazione.
-
numero
L'ID della scheda in cui viene aperto l'URL
-
numero
Il momento in cui il browser stava per creare una nuova visualizzazione, in millisecondi dall'epoca.
-
stringa
L'URL da aprire nella nuova finestra.
-
-
-
object facoltativo
-
Condizioni che l'URL di destinazione deve soddisfare.
-
onDOMContentLoaded
chrome.webNavigation.onDOMContentLoaded.addListener(
callback: function,
filters?: object,
)
Attivato quando il DOM della pagina è completamente costruito, ma il caricamento delle risorse di riferimento potrebbe non essere completato.
Parametri
-
callback
funzione
Il parametro
callbackha il seguente aspetto:(details: object) => void
-
dettagli
oggetto
-
documentId
stringa
Chrome 106 e versioni successiveUn UUID del documento caricato.
-
documentLifecycleChrome 106 e versioni successive
Il ciclo di vita in cui si trova il documento.
-
frameId
numero
0 indica che la navigazione avviene nella finestra dei contenuti della scheda; un valore positivo indica la navigazione in un frame secondario. Gli ID frame sono univoci all'interno di una scheda.
-
frameTypeChrome 106 e versioni successive
Il tipo di frame in cui si è verificata la navigazione.
-
parentDocumentId
stringa facoltativa
Chrome 106 e versioni successiveUn UUID del documento principale proprietario di questo frame. Questo valore non viene impostato se non esiste un elemento principale.
-
parentFrameId
numero
Chrome 74 e versioni successiveL'ID del frame principale o
-1se si tratta del frame principale. -
processId
numero
L'ID del processo che esegue il renderer per questo frame.
-
tabId
numero
L'ID della scheda in cui avviene la navigazione.
-
timeStamp
numero
Il momento in cui il DOM della pagina è stato completamente costruito, in millisecondi dall'epoca.
-
url
stringa
-
-
-
filtri
object facoltativo
-
url
Condizioni che l'URL di destinazione deve soddisfare.
-
onErrorOccurred
chrome.webNavigation.onErrorOccurred.addListener(
callback: function,
filters?: object,
)
Attivato quando si verifica un errore e la navigazione viene interrotta. Ciò può accadere se si è verificato un errore di rete o se l'utente ha interrotto la navigazione.
Parametri
-
callback
funzione
Il parametro
callbackha il seguente aspetto:(details: object) => void
-
dettagli
oggetto
-
documentId
stringa
Chrome 106 e versioni successiveUn UUID del documento caricato.
-
documentLifecycleChrome 106 e versioni successive
Il ciclo di vita in cui si trova il documento.
-
errore
stringa
La descrizione dell'errore.
-
frameId
numero
0 indica che la navigazione avviene nella finestra dei contenuti della scheda; un valore positivo indica la navigazione in un frame secondario. Gli ID frame sono univoci all'interno di una scheda.
-
frameTypeChrome 106 e versioni successive
Il tipo di frame in cui si è verificata la navigazione.
-
parentDocumentId
stringa facoltativa
Chrome 106 e versioni successiveUn UUID del documento principale proprietario di questo frame. Questo valore non viene impostato se non esiste un elemento principale.
-
parentFrameId
numero
Chrome 74 e versioni successiveL'ID del frame principale o
-1se si tratta del frame principale. -
processId
numero
Ritirato da Chrome 50Il campo processId non è più impostato per questo evento.
Il valore -1.
-
tabId
numero
L'ID della scheda in cui avviene la navigazione.
-
timeStamp
numero
L'ora in cui si è verificato l'errore, in millisecondi dall'epoca.
-
url
stringa
-
-
-
filtri
object facoltativo
-
url
Condizioni che l'URL di destinazione deve soddisfare.
-
onHistoryStateUpdated
chrome.webNavigation.onHistoryStateUpdated.addListener(
callback: function,
filters?: object,
)
Attivato quando la cronologia del frame è stata aggiornata a un nuovo URL. Tutti gli eventi futuri per quel frame utilizzeranno l'URL aggiornato.
Parametri
-
callback
funzione
Il parametro
callbackha il seguente aspetto:(details: object) => void
-
dettagli
oggetto
-
documentId
stringa
Chrome 106 e versioni successiveUn UUID del documento caricato.
-
documentLifecycleChrome 106 e versioni successive
Il ciclo di vita in cui si trova il documento.
-
frameId
numero
0 indica che la navigazione avviene nella finestra dei contenuti della scheda; un valore positivo indica la navigazione in un frame secondario. Gli ID frame sono univoci all'interno di una scheda.
-
frameTypeChrome 106 e versioni successive
Il tipo di frame in cui si è verificata la navigazione.
-
parentDocumentId
stringa facoltativa
Chrome 106 e versioni successiveUn UUID del documento principale proprietario di questo frame. Questo valore non viene impostato se non esiste un elemento principale.
-
parentFrameId
numero
Chrome 74 e versioni successiveL'ID del frame principale o
-1se si tratta del frame principale. -
processId
numero
L'ID del processo che esegue il renderer per questo frame.
-
tabId
numero
L'ID della scheda in cui avviene la navigazione.
-
timeStamp
numero
L'ora in cui è stato eseguito il commit della navigazione, in millisecondi dall'epoca.
-
transitionQualifiers
Un elenco di qualificatori di transizione.
-
transitionType
Causa della navigazione.
-
url
stringa
-
-
-
filtri
object facoltativo
-
url
Condizioni che l'URL di destinazione deve soddisfare.
-
onReferenceFragmentUpdated
chrome.webNavigation.onReferenceFragmentUpdated.addListener(
callback: function,
filters?: object,
)
Attivato quando il frammento di riferimento di un frame è stato aggiornato. Tutti gli eventi futuri per quel frame utilizzeranno l'URL aggiornato.
Parametri
-
callback
funzione
Il parametro
callbackha il seguente aspetto:(details: object) => void
-
dettagli
oggetto
-
documentId
stringa
Chrome 106 e versioni successiveUn UUID del documento caricato.
-
documentLifecycleChrome 106 e versioni successive
Il ciclo di vita in cui si trova il documento.
-
frameId
numero
0 indica che la navigazione avviene nella finestra dei contenuti della scheda; un valore positivo indica la navigazione in un frame secondario. Gli ID frame sono univoci all'interno di una scheda.
-
frameTypeChrome 106 e versioni successive
Il tipo di frame in cui si è verificata la navigazione.
-
parentDocumentId
stringa facoltativa
Chrome 106 e versioni successiveUn UUID del documento principale proprietario di questo frame. Questo valore non viene impostato se non esiste un elemento principale.
-
parentFrameId
numero
Chrome 74 e versioni successiveL'ID del frame principale o
-1se si tratta del frame principale. -
processId
numero
L'ID del processo che esegue il renderer per questo frame.
-
tabId
numero
L'ID della scheda in cui avviene la navigazione.
-
timeStamp
numero
L'ora in cui è stato eseguito il commit della navigazione, in millisecondi dall'epoca.
-
transitionQualifiers
Un elenco di qualificatori di transizione.
-
transitionType
Causa della navigazione.
-
url
stringa
-
-
-
filtri
object facoltativo
-
url
Condizioni che l'URL di destinazione deve soddisfare.
-
onTabReplaced
chrome.webNavigation.onTabReplaced.addListener(
callback: function,
)
Attivato quando i contenuti della scheda vengono sostituiti da un'altra scheda (di solito con prerendering precedente).
Parametri
-
callback
funzione
Il parametro
callbackha il seguente aspetto:(details: object) => void
-
dettagli
oggetto
-
replacedTabId
numero
L'ID della scheda sostituita.
-
tabId
numero
L'ID della scheda che ha sostituito la scheda precedente.
-
timeStamp
numero
L'ora in cui è avvenuta la sostituzione, in millisecondi dall'epoca.
-
-