webNavigation

Fügen Sie Ereignis-Listener für die verschiedenen Phasen einer Navigation hinzu. Eine Navigation besteht aus einem Frame im Browser, der von einer URL zu einer anderen wechselt, üblicherweise (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: Navigationen führen normalerweise dazu, dass der Browser Webanfragen stellt, aber die webRequest-API beschäftigt sich eher mit der unteren Ebene der HTTP-Schicht, während die webNavigation-API sich mehr mit der Ansicht vom Browser-UI selbst beschäftigt.

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

Darstellung des primären Ablaufs und zusätzlicher Abläufe, wie unten beschrieben.

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, 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 ausgelöst, wenn die Ziel-URL eines der Muster erfüllt.

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

Um diese API zu nutzen, 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 zu einem Übergang.

Funktionen

webNavigation.getFrame()

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

webNavigation.getAllFrames()

Gibt bei Angabe einer Tab-ID Informationen über alle enthaltenen Frames zurück.

Ereignisse

webNavigation.onBeforeNavigate

Wird ausgelöst, wenn der Browser kurz davor ist, ein Navigationsevent zu starten.

webNavigation.onCommitted

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

webNavigation.onDOMContentLoaded

Wird ausgelöst, wenn das DOMContentLoaded-Ereignis in 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-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 bestehenden Fenster erstellt wird, 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 Fragment-Identifier einer 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 verwendet, um die in der Adressleiste des Browsers angezeigte URL zu aktualisieren.

Browser-Kompatibilität

Beispielerweiterungen

Hinweis: Diese API basiert auf Chromiums chrome.webNavigation-API. Diese Dokumentation ist abgeleitet von web_navigation.json im Chromium-Code.