Beschrijving
Gebruik de chrome.webNavigation API om meldingen te ontvangen over de status van navigatieverzoeken tijdens de vlucht.
Machtigingen
webNavigation Voor alle methoden en gebeurtenissen chrome.webNavigation moet u de machtiging "webNavigation" in het extensiemanifest declareren. Bijvoorbeeld:
{ "name": "My extension", ... "permissions": [ "webNavigation" ], ... } Begrippen en gebruik
Evenementvolgorde
Wanneer de navigatie succesvol is voltooid, worden gebeurtenissen in de volgende volgorde geactiveerd:
onBeforeNavigate -> onCommitted -> [onDOMContentLoaded] -> onCompleted Elke fout die tijdens het proces optreedt, resulteert in een onErrorOccurred -gebeurtenis. Voor een specifieke navigatie worden er na onErrorOccurred geen verdere gebeurtenissen geactiveerd.
Als een navigatieframe subframes bevat, wordt onCommitted geactiveerd vóór onBeforeNavigate van elk van zijn onderliggende frames, terwijl onCompleted wordt geactiveerd ná onCompleted van al zijn onderliggende frames.
Als het referentiefragment van een frame wordt gewijzigd, wordt de gebeurtenis onReferenceFragmentUpdated geactiveerd. Deze gebeurtenis kan op elk moment na onDOMContentLoaded worden geactiveerd, zelfs na onCompleted .
Als de geschiedenis-API wordt gebruikt om de status van een frame te wijzigen (bijvoorbeeld met behulp van history.pushState() , wordt de gebeurtenis onHistoryStateUpdated geactiveerd. Deze gebeurtenis kan op elk moment na onDOMContentLoaded worden geactiveerd.
Als een navigatie een pagina heeft hersteld vanuit de Back Forward Cache , wordt de gebeurtenis onDOMContentLoaded niet geactiveerd. De gebeurtenis wordt niet geactiveerd omdat de content al volledig geladen was toen de pagina voor het eerst werd bezocht.
Als een navigatie is geactiveerd via Chrome Instant of Instant Pages , wordt een volledig geladen pagina verplaatst naar het huidige tabblad. In dat geval wordt de gebeurtenis onTabReplaced geactiveerd.
Relatie tot webRequest-gebeurtenissen
Er is geen gedefinieerde volgorde tussen gebeurtenissen van de webRequest API en de gebeurtenissen van de webNavigation API. Het is mogelijk dat webRequest-gebeurtenissen nog steeds worden ontvangen voor frames die al een nieuwe navigatie hebben gestart, of dat een navigatie pas doorgaat nadat de netwerkbronnen volledig zijn geladen.
Over het algemeen zijn de webNavigation-gebeurtenissen nauw verbonden met de navigatiestatus die in de gebruikersinterface wordt weergegeven, terwijl de webRequest-gebeurtenissen overeenkomen met de status van de netwerkstack, die over het algemeen ondoorzichtig is voor de gebruiker.
Tabblad-ID's
Niet alle navigatietabbladen komen overeen met daadwerkelijke tabbladen in de gebruikersinterface van Chrome, bijvoorbeeld een tabblad dat vooraf wordt gerenderd. Dergelijke tabbladen zijn niet toegankelijk via de tabbladen-API en u kunt er ook geen informatie over opvragen door webNavigation.getFrame() of webNavigation.getAllFrames() aan te roepen. Zodra een dergelijk tabblad is verplaatst, wordt een onTabReplaced -gebeurtenis geactiveerd en worden ze toegankelijk via deze API's.
Tijdstempels
Het is belangrijk om te weten dat sommige technische eigenaardigheden in de manier waarop het besturingssysteem verschillende Chrome-processen afhandelt timeStamp ertoe kunnen leiden dat de klok scheefloopt tussen de browser zelf en extensieprocessen. Dit betekent dat de timeStamp eigenschap van de WebNavigation -gebeurtenis alleen intern consistent is. Het vergelijken van de ene gebeurtenis met de andere geeft u de juiste offset tussen beide, maar het vergelijken ervan met de huidige tijd binnen de extensie (bijvoorbeeld met behulp van (new Date()).getTime() ) kan onverwachte resultaten opleveren.
Frame-ID's
Frames binnen een tabblad kunnen worden geïdentificeerd aan de hand van een frame-ID. De frame-ID van het hoofdframe is altijd 0, de ID van subframes is een positief getal. Zodra een document in een frame is geconstrueerd, blijft de frame-ID constant gedurende de levensduur van het document. Vanaf Chrome 49 is deze ID ook constant gedurende de levensduur van het frame (over meerdere navigaties heen).
Vanwege het multiproceskarakter van Chrome kan een tabblad verschillende processen gebruiken om de bron en bestemming van een webpagina weer te geven. Als een navigatie in een nieuw proces plaatsvindt, ontvangt u daarom mogelijk gebeurtenissen van zowel de nieuwe als de oude pagina totdat de nieuwe navigatie is vastgelegd (d.w.z. de onCommitted gebeurtenis wordt verzonden voor het nieuwe hoofdframe). Met andere woorden, het is mogelijk dat er meer dan één reeks webNavigation-gebeurtenissen in behandeling is met dezelfde frameId . De reeksen kunnen worden onderscheiden door de processId sleutel.
Houd er ook rekening mee dat het proces tijdens een voorlopige laadprocedure meerdere keren kan worden omgeschakeld. Dit gebeurt wanneer de laadprocedure wordt omgeleid naar een andere site. In dat geval ontvangt u herhaaldelijk de gebeurtenissen onBeforeNavigate en onErrorOccurred , totdat u de laatste gebeurtenis onCommitted ontvangt.
Een ander concept dat problematisch is met extensies, is de levenscyclus van het frame. Een frame host een document (dat gekoppeld is aan een vastgelegde URL). Het document kan veranderen (bijvoorbeeld door te navigeren), maar de frame-ID niet. Het is daarom moeilijk om met alleen frame-ID's te associëren dat er iets in een specifiek document is gebeurd. We introduceren een document-ID , een unieke identificatie per document. Als er door een frame wordt genavigeerd en er een nieuw document wordt geopend, verandert de identificatie. Dit veld is handig om te bepalen wanneer pagina's hun levenscyclusstatus wijzigen (tussen prerender/actief/gecached), omdat deze hetzelfde blijft.
Overgangstypen en kwalificaties
De webNavigation onCommitted -gebeurtenis heeft een transitionType en een transitionQualifiers eigenschap. Het transitietype is hetzelfde als dat in de API voor geschiedenis, die beschrijft hoe de browser naar deze specifieke URL navigeert. Daarnaast kunnen verschillende transitiekwalificaties worden geretourneerd die de navigatie verder definiëren.
Er bestaan de volgende overgangskwalificaties:
| Overgangskwalificatie | Beschrijving |
|---|---|
| "client_redirect" | Tijdens de navigatie vonden een of meer omleidingen plaats die werden veroorzaakt door JavaScript of meta-refreshtags op de pagina. |
| "server_doorverwijzing" | Tijdens de navigatie hebben zich een of meer omleidingen voorgedaan die veroorzaakt werden door HTTP-headers die door de server werden verzonden. |
| "vooruit_terug" | De gebruiker heeft de knop Vooruit of Terug gebruikt om de navigatie te starten. |
| "van_adres_balk" | De gebruiker startte de navigatie via de adresbalk (ook wel Omnibox genoemd). |
Voorbeelden
Om deze API uit te proberen, installeert u het webNavigation API-voorbeeld uit de chrome-extension-samples repository.
Typen
TransitionQualifier
Enum
"client_redirect" "server_doorverwijzing" "vooruit_terug" "van_adres_balk"
TransitionType
Oorzaak van de navigatie. Dezelfde overgangstypen als gedefinieerd in de geschiedenis-API worden gebruikt. Dit zijn dezelfde overgangstypen als gedefinieerd in de geschiedenis-API, behalve dat "start_page" is gebruikt in plaats van "auto_toplevel" (voor achterwaartse compatibiliteit).
Enum
"link" "getypt" "auto_bladwijzer" "auto_subframe" "handmatig_subframe" "gegenereerd" "startpagina" "formulier_verzenden" "herladen" "trefwoord" "trefwoord_gegenereerd"
Methoden
getAllFrames()
chrome.webNavigation.getAllFrames(
details: object,
): Promise<object[] | undefined>
Haalt informatie op over alle frames van een bepaald tabblad.
Parameters
- details
voorwerp
Informatie over het tabblad waarvan u alle frames kunt ophalen.
- tabbladId
nummer
De ID van het tabblad.
Retourneren
Belofte<object[] | undefined>
Chroom 93+
getFrame()
chrome.webNavigation.getFrame(
details: object,
): Promise<object | undefined>
Haalt informatie op over het opgegeven frame. Een frame verwijst naar een <iframe> of een <frame> van een webpagina en wordt geïdentificeerd door een tabblad-ID en een frame-ID.
Parameters
- details
voorwerp
Informatie over het frame waarover u informatie wilt ophalen.
- document-ID
string optioneel
Chroom 106+De UUID van het document. Als de frameID en/of tabID worden opgegeven, wordt gevalideerd of deze overeenkomen met het document dat is gevonden met de opgegeven document-ID.
- frame-ID
nummer optioneel
De ID van het frame in het opgegeven tabblad.
- proces-ID
nummer optioneel
Verouderd sinds Chrome 49Frames worden nu op unieke wijze geïdentificeerd aan de hand van hun tabblad-ID en frame-ID. De proces-ID is niet langer nodig en wordt daarom genegeerd.
De ID van het proces dat de renderer voor dit tabblad uitvoert.
- tabbladId
nummer optioneel
De ID van het tabblad waarin het frame zich bevindt.
Retourneren
Belofte<object | undefined>
Chroom 93+
Evenementen
onBeforeNavigate
chrome.webNavigation.onBeforeNavigate.addListener(
callback: function,
filters?: object,
)
Wordt geactiveerd wanneer er een navigatie op het punt staat plaats te vinden.
Parameters
functie
De
callbackziet er als volgt uit:(details: object) => void
voorwerp
- Chroom 106+
De levenscyclus waarin het document zich bevindt.
nummer
0 geeft aan dat de navigatie plaatsvindt in het tabbladinhoudsvenster; een positieve waarde geeft aan dat de navigatie plaatsvindt in een subframe. Frame-ID's zijn uniek voor een bepaald tabblad en proces.
- Chroom 106+
Het type frame waarin de navigatie plaatsvond.
string optioneel
Chroom 106+Een UUID van het bovenliggende document dat eigenaar is van dit frame. Deze wordt niet ingesteld als er geen bovenliggend document is.
nummer
De ID van het bovenliggende frame, of
-1als dit het hoofdframe is.nummer
Verouderd sinds Chrome 50De processId is niet langer ingesteld voor deze gebeurtenis, omdat het proces dat het resulterende document zal renderen, pas bekend is bij onCommit.
De waarde van -1.
nummer
De ID van het tabblad waarin de navigatie gaat plaatsvinden.
nummer
Het tijdstip waarop de browser op het punt stond de navigatie te starten, in milliseconden sinds het tijdperk.
snaar
object optioneel
Voorwaarden waaraan de URL waarnaar wordt genavigeerd, moet voldoen. De velden 'schemes' en 'ports' van UrlFilter worden voor deze gebeurtenis genegeerd.
onCommitted
chrome.webNavigation.onCommitted.addListener(
callback: function,
filters?: object,
)
Wordt geactiveerd wanneer een navigatie wordt vastgelegd. Het document (en de bronnen waarnaar het verwijst, zoals afbeeldingen en subframes) worden mogelijk nog steeds gedownload, maar ten minste een deel van het document is ontvangen van de server en de browser heeft besloten over te schakelen naar het nieuwe document.
Parameters
- terugbellen
functie
De
callbackziet er als volgt uit:(details: object) => void
- details
voorwerp
- document-ID
snaar
Chroom 106+Een UUID van het geladen document.
- documentlevenscyclusChroom 106+
De levenscyclus waarin het document zich bevindt.
- frame-ID
nummer
0 geeft aan dat de navigatie plaatsvindt in het tabbladinhoudsvenster; een positieve waarde geeft aan dat de navigatie plaatsvindt in een subframe. Frame-ID's zijn uniek binnen een tabblad.
- frameTypeChroom 106+
Het type frame waarin de navigatie plaatsvond.
- ouderDocumentId
string optioneel
Chroom 106+Een UUID van het bovenliggende document dat eigenaar is van dit frame. Deze wordt niet ingesteld als er geen bovenliggend document is.
- ouderFrameId
nummer
Chroom 74+De ID van het bovenliggende frame, of
-1als dit het hoofdframe is. - proces-ID
nummer
De ID van het proces dat de renderer voor dit frame uitvoert.
- tabbladId
nummer
De ID van het tabblad waarin de navigatie plaatsvindt.
- tijdstempel
nummer
Het tijdstip waarop de navigatie is uitgevoerd, in milliseconden sinds het tijdperk.
- transitieKwalificaties
Een lijst met overgangskwalificaties.
- overgangstype
Oorzaak van de navigatie.
- url
snaar
- filters
object optioneel
- url
Voorwaarden waaraan de URL waarnaar wordt genavigeerd, moet voldoen. De velden 'schemes' en 'ports' van UrlFilter worden voor deze gebeurtenis genegeerd.
onCompleted
chrome.webNavigation.onCompleted.addListener(
callback: function,
filters?: object,
)
Wordt geactiveerd wanneer een document, inclusief de bronnen waarnaar het verwijst, volledig is geladen en geïnitialiseerd.
Parameters
- terugbellen
functie
De
callbackziet er als volgt uit:(details: object) => void
- details
voorwerp
- document-ID
snaar
Chroom 106+Een UUID van het geladen document.
- documentlevenscyclusChroom 106+
De levenscyclus waarin het document zich bevindt.
- frame-ID
nummer
0 geeft aan dat de navigatie plaatsvindt in het tabbladinhoudsvenster; een positieve waarde geeft aan dat de navigatie plaatsvindt in een subframe. Frame-ID's zijn uniek binnen een tabblad.
- frameTypeChroom 106+
Het type frame waarin de navigatie plaatsvond.
- ouderDocumentId
string optioneel
Chroom 106+Een UUID van het bovenliggende document dat eigenaar is van dit frame. Deze wordt niet ingesteld als er geen bovenliggend document is.
- ouderFrameId
nummer
Chroom 74+De ID van het bovenliggende frame, of
-1als dit het hoofdframe is. - proces-ID
nummer
De ID van het proces dat de renderer voor dit frame uitvoert.
- tabbladId
nummer
De ID van het tabblad waarin de navigatie plaatsvindt.
- tijdstempel
nummer
Het tijdstip waarop het document is geladen, in milliseconden sinds het tijdperk.
- url
snaar
- filters
object optioneel
- url
Voorwaarden waaraan de URL waarnaar wordt genavigeerd, moet voldoen. De velden 'schemes' en 'ports' van UrlFilter worden voor deze gebeurtenis genegeerd.
onCreatedNavigationTarget
chrome.webNavigation.onCreatedNavigationTarget.addListener(
callback: function,
filters?: object,
)
Wordt geactiveerd wanneer een nieuw venster of een nieuw tabblad in een bestaand venster wordt gemaakt om een navigatie te hosten.
Parameters
functie
De
callbackziet er als volgt uit:(details: object) => void
voorwerp
nummer
De ID van het frame met sourceTabId waarin de navigatie wordt geactiveerd. 0 geeft aan dat het om het hoofdframe gaat.
nummer
De ID van het proces dat de renderer voor het bronframe uitvoert.
nummer
De ID van het tabblad waarin de navigatie wordt geactiveerd.
nummer
De ID van het tabblad waarin de url is geopend
nummer
Het tijdstip waarop de browser op het punt stond een nieuwe weergave te creëren, in milliseconden sinds het tijdperk.
snaar
De URL die in het nieuwe venster geopend moet worden.
object optioneel
Voorwaarden waaraan de URL waarnaar wordt genavigeerd, moet voldoen. De velden 'schemes' en 'ports' van UrlFilter worden voor deze gebeurtenis genegeerd.
onDOMContentLoaded
chrome.webNavigation.onDOMContentLoaded.addListener(
callback: function,
filters?: object,
)
Wordt geactiveerd wanneer de DOM van de pagina volledig is opgebouwd, maar de bronnen waarnaar wordt verwezen, mogelijk niet volledig worden geladen.
Parameters
- terugbellen
functie
De
callbackziet er als volgt uit:(details: object) => void
- details
voorwerp
- document-ID
snaar
Chroom 106+Een UUID van het geladen document.
- documentlevenscyclusChroom 106+
De levenscyclus waarin het document zich bevindt.
- frame-ID
nummer
0 geeft aan dat de navigatie plaatsvindt in het tabbladinhoudsvenster; een positieve waarde geeft aan dat de navigatie plaatsvindt in een subframe. Frame-ID's zijn uniek binnen een tabblad.
- frameTypeChroom 106+
Het type frame waarin de navigatie plaatsvond.
- ouderDocumentId
string optioneel
Chroom 106+Een UUID van het bovenliggende document dat eigenaar is van dit frame. Deze wordt niet ingesteld als er geen bovenliggend document is.
- ouderFrameId
nummer
Chroom 74+De ID van het bovenliggende frame, of
-1als dit het hoofdframe is. - proces-ID
nummer
De ID van het proces dat de renderer voor dit frame uitvoert.
- tabbladId
nummer
De ID van het tabblad waarin de navigatie plaatsvindt.
- tijdstempel
nummer
Het tijdstip waarop de DOM van de pagina volledig is opgebouwd, in milliseconden sinds het tijdperk.
- url
snaar
- filters
object optioneel
- url
Voorwaarden waaraan de URL waarnaar wordt genavigeerd, moet voldoen. De velden 'schemes' en 'ports' van UrlFilter worden voor deze gebeurtenis genegeerd.
onErrorOccurred
chrome.webNavigation.onErrorOccurred.addListener(
callback: function,
filters?: object,
)
Wordt geactiveerd wanneer er een fout optreedt en de navigatie wordt afgebroken. Dit kan gebeuren als er een netwerkfout is opgetreden of als de gebruiker de navigatie heeft afgebroken.
Parameters
- terugbellen
functie
De
callbackziet er als volgt uit:(details: object) => void
- details
voorwerp
- document-ID
snaar
Chroom 106+Een UUID van het geladen document.
- documentlevenscyclusChroom 106+
De levenscyclus waarin het document zich bevindt.
- fout
snaar
De foutbeschrijving.
- frame-ID
nummer
0 geeft aan dat de navigatie plaatsvindt in het tabbladinhoudsvenster; een positieve waarde geeft aan dat de navigatie plaatsvindt in een subframe. Frame-ID's zijn uniek binnen een tabblad.
- frameTypeChroom 106+
Het type frame waarin de navigatie plaatsvond.
- ouderDocumentId
string optioneel
Chroom 106+Een UUID van het bovenliggende document dat eigenaar is van dit frame. Deze wordt niet ingesteld als er geen bovenliggend document is.
- ouderFrameId
nummer
Chroom 74+De ID van het bovenliggende frame, of
-1als dit het hoofdframe is. - proces-ID
nummer
Verouderd sinds Chrome 50De processId is niet langer ingesteld voor deze gebeurtenis.
De waarde van -1.
- tabbladId
nummer
De ID van het tabblad waarin de navigatie plaatsvindt.
- tijdstempel
nummer
Het tijdstip waarop de fout optrad, in milliseconden sinds het tijdperk.
- url
snaar
- filters
object optioneel
- url
Voorwaarden waaraan de URL waarnaar wordt genavigeerd, moet voldoen. De velden 'schemes' en 'ports' van UrlFilter worden voor deze gebeurtenis genegeerd.
onHistoryStateUpdated
chrome.webNavigation.onHistoryStateUpdated.addListener(
callback: function,
filters?: object,
)
Wordt geactiveerd wanneer de geschiedenis van het frame is bijgewerkt naar een nieuwe URL. Alle toekomstige gebeurtenissen voor dat frame gebruiken de bijgewerkte URL.
Parameters
- terugbellen
functie
De
callbackziet er als volgt uit:(details: object) => void
- details
voorwerp
- document-ID
snaar
Chroom 106+Een UUID van het geladen document.
- documentlevenscyclusChroom 106+
De levenscyclus waarin het document zich bevindt.
- frame-ID
nummer
0 geeft aan dat de navigatie plaatsvindt in het tabbladinhoudsvenster; een positieve waarde geeft aan dat de navigatie plaatsvindt in een subframe. Frame-ID's zijn uniek binnen een tabblad.
- frameTypeChroom 106+
Het type frame waarin de navigatie plaatsvond.
- ouderDocumentId
string optioneel
Chroom 106+Een UUID van het bovenliggende document dat eigenaar is van dit frame. Deze wordt niet ingesteld als er geen bovenliggend document is.
- ouderFrameId
nummer
Chroom 74+De ID van het bovenliggende frame, of
-1als dit het hoofdframe is. - proces-ID
nummer
De ID van het proces dat de renderer voor dit frame uitvoert.
- tabbladId
nummer
De ID van het tabblad waarin de navigatie plaatsvindt.
- tijdstempel
nummer
Het tijdstip waarop de navigatie is uitgevoerd, in milliseconden sinds het tijdperk.
- transitieKwalificaties
Een lijst met overgangskwalificaties.
- overgangstype
Oorzaak van de navigatie.
- url
snaar
- filters
object optioneel
- url
Voorwaarden waaraan de URL waarnaar wordt genavigeerd, moet voldoen. De velden 'schemes' en 'ports' van UrlFilter worden voor deze gebeurtenis genegeerd.
onReferenceFragmentUpdated
chrome.webNavigation.onReferenceFragmentUpdated.addListener(
callback: function,
filters?: object,
)
Wordt geactiveerd wanneer het referentiefragment van een frame wordt bijgewerkt. Alle toekomstige gebeurtenissen voor dat frame gebruiken de bijgewerkte URL.
Parameters
- terugbellen
functie
De
callbackziet er als volgt uit:(details: object) => void
- details
voorwerp
- document-ID
snaar
Chroom 106+Een UUID van het geladen document.
- documentlevenscyclusChroom 106+
De levenscyclus waarin het document zich bevindt.
- frame-ID
nummer
0 geeft aan dat de navigatie plaatsvindt in het tabbladinhoudsvenster; een positieve waarde geeft aan dat de navigatie plaatsvindt in een subframe. Frame-ID's zijn uniek binnen een tabblad.
- frameTypeChroom 106+
Het type frame waarin de navigatie plaatsvond.
- ouderDocumentId
string optioneel
Chroom 106+Een UUID van het bovenliggende document dat eigenaar is van dit frame. Deze wordt niet ingesteld als er geen bovenliggend document is.
- ouderFrameId
nummer
Chroom 74+De ID van het bovenliggende frame, of
-1als dit het hoofdframe is. - proces-ID
nummer
De ID van het proces dat de renderer voor dit frame uitvoert.
- tabbladId
nummer
De ID van het tabblad waarin de navigatie plaatsvindt.
- tijdstempel
nummer
Het tijdstip waarop de navigatie is uitgevoerd, in milliseconden sinds het tijdperk.
- transitieKwalificaties
Een lijst met overgangskwalificaties.
- overgangstype
Oorzaak van de navigatie.
- url
snaar
- filters
object optioneel
- url
Voorwaarden waaraan de URL waarnaar wordt genavigeerd, moet voldoen. De velden 'schemes' en 'ports' van UrlFilter worden voor deze gebeurtenis genegeerd.
onTabReplaced
chrome.webNavigation.onTabReplaced.addListener(
callback: function,
)
Wordt geactiveerd wanneer de inhoud van het tabblad wordt vervangen door een ander (meestal eerder gerenderd) tabblad.
Parameters
- terugbellen
functie
De
callbackziet er als volgt uit:(details: object) => void
- details
voorwerp
- vervangenTabId
nummer
De ID van het tabblad dat is vervangen.
- tabbladId
nummer
De ID van het tabblad dat het oude tabblad heeft vervangen.
- tijdstempel
nummer
Het tijdstip waarop de vervanging plaatsvond, in milliseconden sinds het tijdperk.