webNavigation

Fügen Sie Ereignislistener für die verschiedenen Phasen einer Navigation hinzu. Eine Navigation besteht aus einem Frame im Browser, der von einer URL zu einer anderen wechselt, normalerweise (aber nicht immer) als Reaktion auf eine Benutzeraktion wie das Klicken auf einen Link oder das Eingeben einer URL in die Adressleiste.

Vergleich mit der webRequest API: Navigationen führen normalerweise dazu, dass der Browser Webanfragen durchführt, aber die webRequest-API bezieht sich auf die niederschwelligere Sicht von der HTTP-Schicht, während die webNavigation-API sich mehr auf die Sicht der Browser-Benutzeroberfläche konzentriert.

Jedes Ereignis entspricht einem bestimmten Stadium der Navigation. Die Reihenfolge der Ereignisse ist wie folgt:

Visualisierung des primären Ablaufs und der unten beschriebenen zusätzlichen Abläufe.

Jede Navigation ist ein URL-Übergang in einem bestimmten Browser-Frame. Der Browser-Frame wird durch eine Tab-ID und eine Frame-ID identifiziert. Der Frame kann der oberste Browsing-Kontext im Tab sein oder ein verschachtelter Browsing-Kontext sein, der als iframe implementiert ist.

Jeder addListener()-Aufruf eines Ereignisses akzeptiert einen optionalen Filterparameter. Der Filter gibt ein oder mehrere URL-Muster an, und das Ereignis wird dann nur für Navigationen ausgelöst, bei denen die Ziel-URL mit einem der Muster übereinstimmt.

Dem onCommitted-Ereignislistener werden zwei zusätzliche Eigenschaften übergeben: ein TransitionType, das die Ursache der Navigation anzeigt (zum Beispiel, weil der Benutzer auf einen Link geklickt hat oder ein Lesezeichen ausgewählt hat), und ein TransitionQualifier, das zusätzliche Informationen über die Navigation liefert.

Um diese API zu verwenden, benötigen Sie die "webNavigation" Berechtigung.

Typen

webNavigation.TransitionType

Ursache der Navigation: zum Beispiel, der Benutzer hat auf einen Link geklickt, eine Adresse eingegeben oder ein Lesezeichen ausgewählt.

webNavigation.TransitionQualifier

Zusätzliche Informationen über einen Übergang.

Funktionen

webNavigation.getFrame()

Ruft Informationen über einen bestimmten Frame ab. Ein Frame kann der oberste Frame in einem Tab oder ein verschachtelter iframe sein und wird eindeutig durch eine Tab-ID und eine Frame-ID identifiziert.

webNavigation.getAllFrames()

Angesichts einer Tab-ID ruft Informationen über alle enthaltenen Frames ab.

Ereignisse

webNavigation.onBeforeNavigate

Wird ausgelöst, wenn der Browser dabei ist, ein Navigationsereignis zu starten.

webNavigation.onCommitted

Wird ausgelöst, wenn eine Navigation festgeschrieben wird. Mindestens ein Teil des neuen Dokuments wurde vom Server empfangen, und der Browser hat beschlossen, zum neuen Dokument zu wechseln.

webNavigation.onDOMContentLoaded

Wird ausgelöst, wenn das DOMContentLoaded Ereignis auf der Seite ausgelöst wird.

webNavigation.onCompleted

Wird ausgelöst, wenn ein Dokument, einschließlich der von ihm referenzierten Ressourcen, vollständig geladen und initialisiert wurde. Dies entspricht dem DOM-Event load.

webNavigation.onErrorOccurred

Wird ausgelöst, wenn ein Fehler auftritt und die Navigation abgebrochen wird. Dies kann passieren, wenn entweder ein Netzwerkfehler auftrat oder der Benutzer die Navigation abgebrochen hat.

webNavigation.onCreatedNavigationTarget

Wird ausgelöst, wenn ein neues Fenster oder ein neuer Tab in einem vorhandenen Fenster erstellt wird, um eine Navigation zu hosten: beispielsweise, wenn der Benutzer einen Link in einem neuen Tab öffnet.

webNavigation.onReferenceFragmentUpdated

Wird ausgelöst, wenn der Fragment-Identifikator einer Seite geändert wird.

webNavigation.onTabReplaced

Wird ausgelöst, wenn der Inhalt des Tabs durch einen anderen (normalerweise zuvor vorgerenderten) Tab ersetzt wird.

webNavigation.onHistoryStateUpdated

Wird ausgelöst, wenn die Seite die history API (2011) verwendet, um die in der Browser-Adressleiste angezeigte URL zu aktualisieren.

Browser-Kompatibilität

Beispielerweiterungen

Hinweis: Diese API basiert auf der chrome.webNavigation API von Chromium. Diese Dokumentation stammt aus web_navigation.json im Chromium-Code.