browser.webNavigation

Beschreibung

Berechtigungen

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

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

Konzepte und Nutzung

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 navigierender Frame untergeordnete Frames enthält, wird sein onCommitted vor dem onBeforeNavigate seiner untergeordneten Frames ausgelöst. onCompleted wird nach dem onCompleted aller untergeordneten Frames 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 mit 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).

Da Chrome mehrere Prozesse verwendet, kann es sein, dass für die Darstellung 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 bestätigt 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 über die processId-Taste unterschieden werden.

Beachten Sie auch, 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 sich der Lebenszyklusstatus von Seiten ändert (zwischen Vorrendern/Aktiv/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 hat. 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.

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

chrome.webNavigation.getFrame