chrome.webNavigation (original) (raw)

Zum Hauptinhalt springen

• Docs

  • Übersicht
  • Jetzt starten
  • Entwickeln
  • Anleitungen
  • KI
  • Referenzen
  • Beispiele
  • Chrome Web Store

• Fallstudien

• Blog

• Neu in Chrome

• Manifest V3

• ➡ Manifest V2

• accessibilityFeatures

• action

• alarms

• audio

• bookmarks

• browsingData

• certificateProvider

• commands

• contentSettings

• contextMenus

• cookies

• debugger

• declarativeContent

• declarativeNetRequest

• desktopCapture

• devtools.inspectedWindow

• devtools.network

• devtools.panels

• devtools.performance

• devtools.recorder

• dns

• documentScan

• dom

• downloads

• enterprise.deviceAttributes

• enterprise.hardwarePlatform

• enterprise.login

• enterprise.networkingAttributes

• enterprise.platformKeys

• events

• extension

• extensionTypes

• fileBrowserHandler

• fileSystemProvider

• fontSettings

• gcm

• history

• i18n

• identity

• idle

• input.ime

• instanceID

• loginState

• management

• notifications

• offscreen

• omnibox

• pageCapture

• permissions

• platformKeys

• power

• printerProvider

• printing

• printingMetrics

• privacy

• processes

• proxy

• readingList

• runtime

• scripting

• search

• sessions

• sidePanel

• storage

• system.cpu

• system.display

• system.memory

• system.storage

• systemLog

• tabCapture

• tabGroups

• tabs

• topSites

• tts

• ttsEngine

• types

• userScripts

• vpnProvider

• wallpaper

• webAuthenticationProxy

• webNavigation

• webRequest

• windows

chrome.webNavigation

Beschreibung

Mit der chrome.webNavigation API können Sie Benachrichtigungen zum Status von Navigationsanfragen erhalten, während diese bearbeitet werden.

Berechtigungen

webNavigation

Für alle chrome.webNavigation-Methoden und ‑Ereignisse müssen Sie die Berechtigung "webNavigation" im Erweiterungsmanifest deklarieren. Beispiel:

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

Konzepte und Verwendung

Ereignisreihenfolge

Bei einer erfolgreich abgeschlossenen Navigation werden Ereignisse in der folgenden Reihenfolge ausgelöst:

onBeforeNavigate -> onCommitted -> [onDOMContentLoaded] -> onCompleted

Jeder Fehler, der während des Vorgangs auftritt, führt zu einem onErrorOccurred-Ereignis. Für eine bestimmte Navigation werden nach onErrorOccurred keine weiteren Ereignisse ausgelöst.

Wenn ein Navigationsframe untergeordnete Frames enthält, wird sein onCommitted vor dem onBeforeNavigate seiner untergeordneten Elemente ausgelöst. onCompleted wird nach dem onCompleted aller untergeordneten Elemente ausgelöst.

Wenn das Referenzfragment eines Frames geändert wird, wird ein onReferenceFragmentUpdated-Ereignis ausgelöst. Dieses Ereignis kann jederzeit nach onDOMContentLoaded ausgelöst werden, auch nach onCompleted.

Wenn die History API verwendet wird, um den Status eines Frames zu ändern (z.B. mit history.pushState()), wird ein onHistoryStateUpdated-Ereignis ausgelöst. Dieses Ereignis kann jederzeit nach onDOMContentLoaded ausgelöst werden.

Wenn bei einer Navigation eine Seite aus dem Back-Forward-Cache wiederhergestellt wurde, wird das onDOMContentLoaded-Ereignis nicht ausgelöst. Das Ereignis wird nicht ausgelöst, weil die Inhalte bereits geladen wurden, als die Seite zum ersten Mal aufgerufen wurde.

Wenn eine Navigation über Chrome Instant oder Instant Pages ausgelöst wurde, wird eine vollständig geladene Seite in den aktuellen Tab eingefügt. In diesem Fall wird ein onTabReplaced-Ereignis ausgelöst.

Beziehung zu webRequest-Ereignissen

Es gibt keine definierte Reihenfolge zwischen Ereignissen der webRequest API und Ereignissen der webNavigation API. Es ist möglich, dass webRequest-Ereignisse weiterhin für Frames empfangen werden, in denen bereits eine neue Navigation gestartet wurde, oder dass eine Navigation erst erfolgt, nachdem die Netzwerkressourcen vollständig geladen wurden.

Im Allgemeinen stehen die webNavigation-Ereignisse in engem Zusammenhang mit dem Navigationsstatus, der in der Benutzeroberfläche angezeigt wird, während die webRequest-Ereignisse dem Status des Netzwerk-Stacks entsprechen, der für den Nutzer in der Regel nicht sichtbar ist.

Tab-IDs

Nicht alle Navigations-Tabs entsprechen tatsächlichen Tabs in der Chrome-Benutzeroberfläche, z. B. ein Tab, der vorgerendert wird. Auf solche Tabs kann nicht über die Tabs API zugegriffen werden. Außerdem können Sie keine Informationen dazu anfordern, indem Sie webNavigation.getFrame() oder webNavigation.getAllFrames() aufrufen. Sobald ein solcher Tab eingefügt wird, wird ein onTabReplaced-Ereignis ausgelöst und die Tabs sind über diese APIs zugänglich.

Zeitstempel

Es ist wichtig zu beachten, dass einige technische Besonderheiten bei der Verarbeitung von separaten Chrome-Prozessen im Betriebssystem dazu führen können, dass die Uhrzeit zwischen dem Browser selbst und den Erweiterungsprozessen abweicht. Das bedeutet, dass die timeStamp-Property der WebNavigation-Ereignis-timeStamp-Property nur intern konsistent ist. Wenn Sie ein Ereignis mit einem anderen Ereignis vergleichen, erhalten Sie die richtige Differenz zwischen den beiden Ereignissen. Wenn Sie sie jedoch mit der aktuellen Zeit in der Erweiterung vergleichen (z. B. mit (new Date()).getTime()), kann das zu unerwarteten Ergebnissen führen.

Frame-IDs

Frames auf einem Tab können anhand einer Frame-ID identifiziert werden. Die Frame-ID des Hauptframes ist immer 0, die ID von untergeordneten Frames ist eine positive Zahl. Sobald ein Dokument in einem Frame erstellt wurde, bleibt seine Frame-ID während der gesamten Lebensdauer des Dokuments konstant. Ab Chrome 49 ist diese ID auch für die Lebensdauer des Frames konstant (über mehrere Navigationsvorgänge hinweg).

Aufgrund der Multi-Prozess-Architektur von Chrome kann es sein, dass für das Rendern von Quelle und Ziel einer Webseite unterschiedliche Prozesse verwendet werden. Wenn also eine Navigation in einem neuen Prozess stattfindet, erhalten Sie möglicherweise Ereignisse sowohl von der neuen als auch von der alten Seite, bis die neue Navigation übernommen wird (d.h. das onCommitted-Ereignis für den neuen Hauptframe gesendet wird). Mit anderen Worten: Es kann mehr als eine ausstehende Sequenz von webNavigation-Ereignissen mit derselben frameId geben. Die Sequenzen können durch die processId-Taste unterschieden werden.

Beachten Sie außerdem, dass der Prozess während eines vorläufigen Ladevorgangs mehrmals umgeschaltet werden kann. Das passiert, wenn die Last auf eine andere Website umgeleitet wird. In diesem Fall erhalten Sie wiederholt die Ereignisse onBeforeNavigate und onErrorOccurred, bis Sie das endgültige Ereignis onCommitted erhalten.

Ein weiteres Konzept, das bei Erweiterungen problematisch ist, ist der Lebenszyklus des Frames. In einem Frame wird ein Dokument gehostet, das mit einer festgeschriebenen URL verknüpft ist. Das Dokument kann sich ändern (z. B. durch Navigation), die frameId jedoch nicht. Daher ist es schwierig, ein Ereignis in einem bestimmten Dokument nur mit frameIds zu verknüpfen. Wir führen das Konzept einer documentId ein, die eine eindeutige Kennung pro Dokument ist. Wenn ein Frame aufgerufen wird und ein neues Dokument geöffnet wird, ändert sich die Kennung. Dieses Feld ist nützlich, um zu ermitteln, wann Seiten ihren Lebenszyklusstatus ändern (zwischen „Vorrendern“, „Aktiv“ und „Im Cache“), da es gleich bleibt.

Übergangstypen und Qualifizierer

Das webNavigation-Ereignis onCommitted hat die Attribute transitionType und transitionQualifiers. Der Übergangstyp ist derselbe wie in der History API und beschreibt, wie der Browser zu dieser bestimmten URL navigiert ist. Außerdem können mehrere Übergangsqualifizierer zurückgegeben werden, die die Navigation weiter definieren.

Es gibt die folgenden Übergangsqualifizierer:

Beispiele

Wenn Sie diese API ausprobieren möchten, installieren Sie das webNavigation API-Beispiel aus dem Repository chrome-extension-samples.

Typen

TransitionQualifier

Enum

"client_redirect"

"server_redirect"

"forward_back"

"from_address_bar"

TransitionType

Ursache der Navigation. Es werden dieselben Übergangstypen wie in der History API verwendet. Dies sind dieselben Übergangstypen wie in der History API definiert, nur dass "start_page" anstelle von "auto_toplevel" verwendet wird (zur Abwärtskompatibilität).

Enum

„link“

"typed"

"auto_bookmark"

"auto_subframe"

"manual_subframe"

"generated"

"start_page"

"form_submit"

"reload"

"keyword"

"keyword_generated"

Methoden

getAllFrames()

chrome.webNavigation.getAllFrames(
  details: object,
): Promise<object[] | undefined>

Ruft Informationen zu allen Frames eines bestimmten Tabs ab.

Parameter

• Informationen zum Tab, von dem alle Frames abgerufen werden sollen.
  • Die ID des Tabs.

Ausgabe

• Promise<object[] | undefined>

getFrame()

chrome.webNavigation.getFrame(
  details: object,
): Promise<object | undefined>

Ruft Informationen zum angegebenen Frame ab. Ein Frame bezieht sich auf ein oder ein einer Webseite und wird durch eine Tab-ID und eine Frame-ID identifiziert.

Parameter

• Informationen zum Frame, zu dem Informationen abgerufen werden sollen.
  • documentId
    String optional
    Die UUID des Dokuments. Wenn die frameId und/oder tabId angegeben werden, werden sie validiert, um mit dem Dokument übereinzustimmen, das anhand der angegebenen Dokument-ID gefunden wurde.
  • Die ID des Frames auf dem angegebenen Tab.
  • processId
    number optional
    Seit Chrome 49 nicht mehr unterstützt
    Frames werden jetzt eindeutig über ihre Tab-ID und Frame-ID identifiziert. Die Prozess-ID ist nicht mehr erforderlich und wird daher ignoriert.
    Die ID des Prozesses, der den Renderer für diesen Tab ausführt.
  • Die ID des Tabs, auf dem sich der Frame befindet.

Ausgabe

• Promise<object | undefined>

Ereignisse

onBeforeNavigate

chrome.webNavigation.onBeforeNavigate.addListener(
  callback: function,
  filters?: object,
)

Wird ausgelöst, wenn eine Navigation bevorsteht.

Parameter

• Der Parameter callback sieht so aus:
  (details: object) => void
  • • Die Lebenszyklusphase des Dokuments.
      • Der Wert 0 gibt an, dass die Navigation im Tab-Inhaltsfenster erfolgt. Ein positiver Wert gibt an, dass die Navigation in einem Unterframe erfolgt. Frame-IDs sind für einen bestimmten Tab und Prozess eindeutig.
      • Der Typ des Frames, in dem die Navigation stattgefunden hat.
      • parentDocumentId
        String optional
        Eine UUID des übergeordneten Dokuments, das diesen Frame enthält. Dieser Wert wird nicht festgelegt, wenn es kein übergeordnetes Element gibt.
      • Die ID des übergeordneten Frames oder -1, wenn dies der Hauptframe ist.
      • Seit Chrome 50 eingestellt
        Die processId wird für dieses Ereignis nicht mehr festgelegt, da der Prozess, der das resultierende Dokument rendert, erst bei onCommit bekannt ist.
        Der Wert -1.
      • Die ID des Tabs, auf dem die Navigation stattfinden soll.
      • Die Zeit, zu der der Browser mit der Navigation beginnen wollte, in Millisekunden seit der Epoche.
• • Bedingungen, die die URL erfüllen muss, zu der navigiert wird. Die Felder „schemes“ und „ports“ von UrlFilter werden für dieses Ereignis ignoriert.

onCommitted

chrome.webNavigation.onCommitted.addListener(
  callback: function,
  filters?: object,
)

Wird ausgelöst, wenn eine Navigation abgeschlossen ist. Das Dokument (und die darin referenzierten Ressourcen wie Bilder und Unterframes) werden möglicherweise noch heruntergeladen, aber zumindest ein Teil des Dokuments wurde vom Server empfangen und der Browser hat sich entschieden, zum neuen Dokument zu wechseln.

Parameter

• Der Parameter callback sieht so aus:
  (details: object) => void
  • • Die UUID des geladenen Dokuments.
      • Die Lebenszyklusphase des Dokuments.
      • Der Wert 0 gibt an, dass die Navigation im Tab-Inhaltsfenster erfolgt. Ein positiver Wert gibt an, dass die Navigation in einem Unterframe erfolgt. Frame-IDs sind innerhalb eines Tabs eindeutig.
      • Der Typ des Frames, in dem die Navigation stattgefunden hat.
      • parentDocumentId
        String optional
        Eine UUID des übergeordneten Dokuments, das diesen Frame enthält. Dieser Wert wird nicht festgelegt, wenn es kein übergeordnetes Element gibt.
      • Die ID des übergeordneten Frames oder -1, wenn dies der Hauptframe ist.
      • Die ID des Prozesses, der den Renderer für diesen Frame ausführt.
      • Die ID des Tabs, auf dem die Navigation erfolgt.
      • Die Zeit, zu der die Navigation bestätigt wurde, in Millisekunden seit der Epoche.
      • Eine Liste der Übergangsqualifizierer.
      • Ursache der Navigation.
• • Bedingungen, die die URL erfüllen muss, zu der navigiert wird. Die Felder „schemes“ und „ports“ von UrlFilter werden für dieses Ereignis ignoriert.

onCompleted

chrome.webNavigation.onCompleted.addListener(
  callback: function,
  filters?: object,
)

Wird ausgelöst, wenn ein Dokument, einschließlich der Ressourcen, auf die es verweist, vollständig geladen und initialisiert wurde.

Parameter

• Der Parameter callback sieht so aus:
  (details: object) => void
  • • Die UUID des geladenen Dokuments.
      • Die Lebenszyklusphase des Dokuments.
      • Der Wert 0 gibt an, dass die Navigation im Tab-Inhaltsfenster erfolgt. Ein positiver Wert gibt an, dass die Navigation in einem Unterframe erfolgt. Frame-IDs sind innerhalb eines Tabs eindeutig.
      • Der Typ des Frames, in dem die Navigation stattgefunden hat.
      • parentDocumentId
        String optional
        Eine UUID des übergeordneten Dokuments, das diesen Frame enthält. Dieser Wert wird nicht festgelegt, wenn es kein übergeordnetes Element gibt.
      • Die ID des übergeordneten Frames oder -1, wenn dies der Hauptframe ist.
      • Die ID des Prozesses, der den Renderer für diesen Frame ausführt.
      • Die ID des Tabs, auf dem die Navigation erfolgt.
      • Die Zeit, zu der das Laden des Dokuments abgeschlossen wurde, in Millisekunden seit der Epoche.
• • Bedingungen, die die URL erfüllen muss, zu der navigiert wird. Die Felder „schemes“ und „ports“ von UrlFilter werden für dieses Ereignis ignoriert.

onCreatedNavigationTarget

chrome.webNavigation.onCreatedNavigationTarget.addListener(
  callback: function,
  filters?: object,
)

Wird ausgelöst, wenn ein neues Fenster oder ein neuer Tab in einem vorhandenen Fenster erstellt wird, um eine Navigation zu hosten.

Parameter

• Der Parameter callback sieht so aus:
  (details: object) => void
  • • Die ID des Frames mit „sourceTabId“, in dem die Navigation ausgelöst wird. 0 gibt den Hauptframe an.
      • Die ID des Prozesses, der den Renderer für den Quellframe ausführt.
      • Die ID des Tabs, auf dem die Navigation ausgelöst wird.
      • Die ID des Tabs, in dem die URL geöffnet wird
      • Der Zeitpunkt, zu dem der Browser eine neue Ansicht erstellen wollte, in Millisekunden seit der Epoche.
      • Die URL, die im neuen Fenster geöffnet werden soll.
• • Bedingungen, die die URL erfüllen muss, zu der navigiert wird. Die Felder „schemes“ und „ports“ von UrlFilter werden für dieses Ereignis ignoriert.

onDOMContentLoaded

chrome.webNavigation.onDOMContentLoaded.addListener(
  callback: function,
  filters?: object,
)

Wird ausgelöst, wenn das DOM der Seite vollständig erstellt wurde, die referenzierten Ressourcen jedoch möglicherweise noch nicht vollständig geladen wurden.

Parameter

• Der Parameter callback sieht so aus:
  (details: object) => void
  • • Die UUID des geladenen Dokuments.
      • Die Lebenszyklusphase des Dokuments.
      • Der Wert 0 gibt an, dass die Navigation im Tab-Inhaltsfenster erfolgt. Ein positiver Wert gibt an, dass die Navigation in einem Unterframe erfolgt. Frame-IDs sind innerhalb eines Tabs eindeutig.
      • Der Typ des Frames, in dem die Navigation stattgefunden hat.
      • parentDocumentId
        String optional
        Eine UUID des übergeordneten Dokuments, das diesen Frame enthält. Dieser Wert wird nicht festgelegt, wenn es kein übergeordnetes Element gibt.
      • Die ID des übergeordneten Frames oder -1, wenn dies der Hauptframe ist.
      • Die ID des Prozesses, der den Renderer für diesen Frame ausführt.
      • Die ID des Tabs, auf dem die Navigation erfolgt.
      • Die Zeit, zu der das DOM der Seite vollständig erstellt wurde, in Millisekunden seit der Epoche.
• • Bedingungen, die die URL erfüllen muss, zu der navigiert wird. Die Felder „schemes“ und „ports“ von UrlFilter werden für dieses Ereignis ignoriert.

onErrorOccurred

chrome.webNavigation.onErrorOccurred.addListener(
  callback: function,
  filters?: object,
)

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

Parameter

• Der Parameter callback sieht so aus:
  (details: object) => void
  • • Die UUID des geladenen Dokuments.
      • Die Lebenszyklusphase des Dokuments.
      • Die Fehlerbeschreibung.
      • Der Wert 0 gibt an, dass die Navigation im Tab-Inhaltsfenster erfolgt. Ein positiver Wert gibt an, dass die Navigation in einem Unterframe erfolgt. Frame-IDs sind innerhalb eines Tabs eindeutig.
      • Der Typ des Frames, in dem die Navigation stattgefunden hat.
      • parentDocumentId
        String optional
        Eine UUID des übergeordneten Dokuments, das diesen Frame enthält. Dieser Wert wird nicht festgelegt, wenn es kein übergeordnetes Element gibt.
      • Die ID des übergeordneten Frames oder -1, wenn dies der Hauptframe ist.
      • Seit Chrome 50 eingestellt
        Die processId ist für dieses Ereignis nicht mehr festgelegt.
        Der Wert -1.
      • Die ID des Tabs, auf dem die Navigation erfolgt.
      • Der Zeitpunkt, zu dem der Fehler aufgetreten ist, in Millisekunden seit der Epoche.
• • Bedingungen, die die URL erfüllen muss, zu der navigiert wird. Die Felder „schemes“ und „ports“ von UrlFilter werden für dieses Ereignis ignoriert.

onHistoryStateUpdated

chrome.webNavigation.onHistoryStateUpdated.addListener(
  callback: function,
  filters?: object,
)

Wird ausgelöst, wenn der Verlauf des Frames auf eine neue URL aktualisiert wurde. Für alle zukünftigen Ereignisse für diesen Frame wird die aktualisierte URL verwendet.

Parameter

• Der Parameter callback sieht so aus:
  (details: object) => void
  • • Die UUID des geladenen Dokuments.
      • Die Lebenszyklusphase des Dokuments.
      • Der Wert 0 gibt an, dass die Navigation im Tab-Inhaltsfenster erfolgt. Ein positiver Wert gibt an, dass die Navigation in einem Unterframe erfolgt. Frame-IDs sind innerhalb eines Tabs eindeutig.
      • Der Typ des Frames, in dem die Navigation stattgefunden hat.
      • parentDocumentId
        String optional
        Eine UUID des übergeordneten Dokuments, das diesen Frame enthält. Dieser Wert wird nicht festgelegt, wenn es kein übergeordnetes Element gibt.
      • Die ID des übergeordneten Frames oder -1, wenn dies der Hauptframe ist.
      • Die ID des Prozesses, der den Renderer für diesen Frame ausführt.
      • Die ID des Tabs, auf dem die Navigation erfolgt.
      • Die Zeit, zu der die Navigation bestätigt wurde, in Millisekunden seit der Epoche.
      • Eine Liste der Übergangsqualifizierer.
      • Ursache der Navigation.
• • Bedingungen, die die URL erfüllen muss, zu der navigiert wird. Die Felder „schemes“ und „ports“ von UrlFilter werden für dieses Ereignis ignoriert.

onReferenceFragmentUpdated

chrome.webNavigation.onReferenceFragmentUpdated.addListener(
  callback: function,
  filters?: object,
)

Wird ausgelöst, wenn das Referenzfragment eines Frames aktualisiert wurde. Für alle zukünftigen Ereignisse für diesen Frame wird die aktualisierte URL verwendet.

Parameter

• Der Parameter callback sieht so aus:
  (details: object) => void
  • • Die UUID des geladenen Dokuments.
      • Die Lebenszyklusphase des Dokuments.
      • Der Wert 0 gibt an, dass die Navigation im Tab-Inhaltsfenster erfolgt. Ein positiver Wert gibt an, dass die Navigation in einem Unterframe erfolgt. Frame-IDs sind innerhalb eines Tabs eindeutig.
      • Der Typ des Frames, in dem die Navigation stattgefunden hat.
      • parentDocumentId
        String optional
        Eine UUID des übergeordneten Dokuments, das diesen Frame enthält. Dieser Wert wird nicht festgelegt, wenn es kein übergeordnetes Element gibt.
      • Die ID des übergeordneten Frames oder -1, wenn dies der Hauptframe ist.
      • Die ID des Prozesses, der den Renderer für diesen Frame ausführt.
      • Die ID des Tabs, auf dem die Navigation erfolgt.
      • Die Zeit, zu der die Navigation bestätigt wurde, in Millisekunden seit der Epoche.
      • Eine Liste der Übergangsqualifizierer.
      • Ursache der Navigation.
• • Bedingungen, die die URL erfüllen muss, zu der navigiert wird. Die Felder „schemes“ und „ports“ von UrlFilter werden für dieses Ereignis ignoriert.

onTabReplaced

chrome.webNavigation.onTabReplaced.addListener(
  callback: function,
)

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

Parameter

• Der Parameter callback sieht so aus:
  (details: object) => void
  • • Die ID des Tabs, der ersetzt wurde.
      • Die ID des Tabs, der den alten Tab ersetzt hat.
      • Die Zeit, zu der der Ersatz erfolgte, in Millisekunden seit der Epoche.

Sofern nicht anders angegeben, sind die Inhalte dieser Seite unter der Creative Commons Attribution 4.0 License und Codebeispiele unter der Apache 2.0 License lizenziert. Weitere Informationen finden Sie in den Websiterichtlinien von Google Developers. Java ist eine eingetragene Marke von Oracle und/oder seinen Partnern.

Zuletzt aktualisiert: 2025-09-11 (UTC).