browser.webNavigation

Descrizione

Autorizzazioni

Tutti i metodi e gli eventi browser.webNavigation richiedono la dichiarazione dell'autorizzazione "webNavigation" nel manifest dell'estensione. Ad esempio:

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

Concetti e utilizzo

Ordine dell'evento

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 le ore onDOMContentLoaded, anche dopo le ore 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 le ore 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 quando la pagina è stata visitata per la prima volta.

Se una navigazione è stata attivata utilizzando Chrome Instant o Instant Pages, una pagina completamente caricata viene scambiata con la scheda corrente. In questo caso, viene attivato un evento onTabReplaced.

Relazione con gli eventi webRequest

Non è definito un ordine 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à completamente cariche.

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 è generalmente opaco per l'utente.

ID scheda

Non tutte le schede di navigazione corrispondono a schede effettive nell'interfaccia utente di Chrome, ad esempio una scheda di cui è stato eseguito il rendering preliminare. Queste schede non sono accessibili tramite l'API Tabs e non puoi richiedere informazioni su di esse chiamando webNavigation.getFrame() o webNavigation.getAllFrames(). Una volta sostituita una scheda, viene attivato un evento onTabReplaced e le schede diventano accessibili tramite queste API.

Timestamp

È importante notare che alcune stranezze tecniche nella gestione dei 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 della proprietà timeStamp dell'evento WebNavigation è garantita solo per essere coerente internamente. Il confronto tra un evento e un altro ti darà l'offset corretto tra i due, ma il confronto con l'ora corrente all'interno dell'estensione (utilizzando (new Date()).getTime(), ad esempio) 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 costruito un documento in un frame, il suo ID frame rimane costante per tutta la durata del documento. A partire da Chrome 49, questo ID è costante anche per l'intera durata del frame (in 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 la navigazione avviene in un nuovo processo, potresti ricevere eventi sia dalla pagina nuova che da quella precedente finché la nuova navigazione non viene eseguita (ovvero finché non 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 dal tasto processId.

Tieni presente inoltre che durante un caricamento provvisorio la procedura potrebbe essere cambiata più volte. Ciò accade quando il carico viene reindirizzato a un altro sito. In questo caso, riceverai eventi onBeforeNavigate e onErrorOccurred ripetuti, finché 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 di commit). Il documento può cambiare (ad esempio tramite navigazione), ma l'frameId non cambia, quindi è difficile associare un evento in un documento specifico solo agli frameId. Stiamo introducendo il concetto di documentId, che è un identificatore univoco per documento. Se viene spostato un frame e viene aperto un nuovo documento, l'identificatore cambierà. Questo campo è utile per determinare quando le pagine cambiano il loro stato del ciclo di vita (tra prerendering/attivo/memorizzato nella cache) perché rimane invariato.

Tipi di transizione e qualificatori

L'evento webNavigation onCommitted ha una proprietà transitionType e una 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: