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.

Verglichen mit der webRequest API: Navigationsvorgänge führen normalerweise dazu, dass der Browser Webanfragen stellt, aber die webRequest API ist mit der tieferliegenden Ansicht von der HTTP-Ebene befasst, während die webNavigation API sich mehr mit der Ansicht von der Browser-Benutzeroberfläche selbst befasst.

Jedes Ereignis entspricht einer bestimmten Phase in der Navigation. Die Reihenfolge der Ereignisse ist wie folgt:

Visualisierung des primären Flusses und zusätzlicher Flüsse, die unten beschrieben werden.

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 oder ein eingebetteter Browsing-Kontext, der als <iframe> implementiert ist, sein.

Der addListener()-Aufruf jedes 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 eines der Muster erfüllt.

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

Um diese API zu verwenden, müssen Sie die Berechtigung "webNavigation" haben permission.

Typen

webNavigation.TransitionType

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

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 eingebetteter <iframe> sein und wird eindeutig durch eine Tab-ID und eine Frame-ID identifiziert.

webNavigation.getAllFrames()

Gibt bei Vorliegen einer Tab-ID Informationen über alle enthaltenen Frames aus.

Ereignisse

webNavigation.onBeforeNavigate

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

webNavigation.onCommitted

Wird ausgelöst, wenn eine Navigation festgesetzt 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 ist. Dies entspricht dem DOM load-Ereignis.

webNavigation.onErrorOccurred

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

webNavigation.onCreatedNavigationTarget

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

webNavigation.onReferenceFragmentUpdated

Wird ausgelöst, wenn sich der Fragmentbezeichner für eine Seite ändert.

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 hat, um die in der Adressleiste des Browsers angezeigte URL zu aktualisieren.

Browser-Kompatibilität

BCD tables only load in the browser

Beispielerweiterungen

Hinweis: Diese API basiert auf der chrome.webNavigation API von Chromium. Diese Dokumentation leitet sich von web_navigation.json im Chromium-Code ab.