chrome.webNavigation

Description

Utilisez l'API chrome.webNavigation pour recevoir des notifications sur l'état des requêtes de navigation en cours.

Autorisations

webNavigation

Toutes les méthodes et tous les événements chrome.webNavigation nécessitent que vous déclariez l'autorisation "webNavigation" dans le fichier manifeste de l'extension. Exemple :

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

Concepts et utilisation

Ordre de l'événement

Lorsqu'une navigation est effectuée avec succès, les événements sont déclenchés dans l'ordre suivant :

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

Toute erreur survenant au cours du processus entraîne un événement onErrorOccurred. Pour une navigation spécifique, aucun autre événement n'est déclenché après onErrorOccurred.

Si un frame de navigation contient des sous-frames, son onCommitted est déclenché avant le onBeforeNavigate de l'un de ses enfants, tandis que onCompleted est déclenché après le onCompleted de tous ses enfants.

Si le fragment de référence d'un frame est modifié, un événement onReferenceFragmentUpdated est déclenché. Cet événement peut se déclencher à tout moment après onDOMContentLoaded, même après onCompleted.

Si l'API History est utilisée pour modifier l'état d'un frame (par exemple, à l'aide de history.pushState()), un événement onHistoryStateUpdated est déclenché. Cet événement peut se déclencher à tout moment après onDOMContentLoaded.

Si une navigation restaure une page à partir du cache amélioré, l'événement onDOMContentLoaded ne se déclenche pas. L'événement n'est pas déclenché, car le contenu a déjà été chargé lors de la première visite de la page.

Si une navigation a été déclenchée à l'aide de Chrome Instant ou des pages instantanées, une page entièrement chargée est insérée dans l'onglet actuel. Dans ce cas, un événement onTabReplaced est déclenché.

Relation avec les événements webRequest

Il n'existe pas d'ordre défini entre les événements de l'API webRequest et ceux de l'API webNavigation. Il est possible que des événements webRequest soient toujours reçus pour des frames qui ont déjà commencé une nouvelle navigation, ou qu'une navigation ne se poursuive qu'une fois que les ressources réseau sont entièrement chargées.

En général, les événements webNavigation sont étroitement liés à l'état de navigation affiché dans l'UI, tandis que les événements webRequest correspondent à l'état de la pile réseau, qui est généralement opaque pour l'utilisateur.

ID d'onglet

Tous les onglets de navigation ne correspondent pas à des onglets réels dans l'UI de Chrome (par exemple, un onglet en cours de prérendu). Vous ne pouvez pas accéder à ces onglets à l'aide de l'API Tabs, ni demander d'informations à leur sujet en appelant webNavigation.getFrame() ou webNavigation.getAllFrames(). Une fois un tel onglet inséré, un événement onTabReplaced est déclenché et il devient accessible via ces API.

Codes temporels

Il est important de noter que certaines bizarreries techniques dans la gestion des processus Chrome distincts par l'OS peuvent entraîner un décalage de l'horloge entre le navigateur lui-même et les processus d'extension. Cela signifie que la propriété timeStamp de la propriété timeStamp de l'événement WebNavigation n'est garantie d'être cohérente qu'en interne. Comparer un événement à un autre vous donnera le décalage correct entre eux, mais les comparer à l'heure actuelle dans l'extension (à l'aide de (new Date()).getTime(), par exemple) peut donner des résultats inattendus.

ID de frames

Les frames d'un onglet peuvent être identifiés par un ID de frame. L'ID du frame principal est toujours 0, tandis que celui des frames enfants est un nombre positif. Une fois qu'un document est construit dans un frame, son ID de frame reste constant pendant toute la durée de vie du document. Depuis Chrome 49, cet ID est également constant pendant toute la durée de vie du frame (pour plusieurs navigations).

En raison de la nature multiprocessus de Chrome, un onglet peut utiliser différents processus pour afficher la source et la destination d'une page Web. Par conséquent, si une navigation a lieu dans un nouveau processus, vous pouvez recevoir des événements à la fois de l'ancienne et de la nouvelle page jusqu'à ce que la nouvelle navigation soit validée (c'est-à-dire que l'événement onCommitted est envoyé pour le nouveau frame principal). En d'autres termes, il est possible d'avoir plusieurs séquences d'événements webNavigation en attente avec le même frameId. Les séquences peuvent être distinguées par la clé processId.

Notez également que lors d'un chargement provisoire, le processus peut être modifié plusieurs fois. Cela se produit lorsque la charge est redirigée vers un autre site. Dans ce cas, vous recevrez des événements onBeforeNavigate et onErrorOccurred à plusieurs reprises, jusqu'à ce que vous receviez l'événement onCommitted final.

Un autre concept problématique avec les extensions est le cycle de vie du frame. Un frame héberge un document (associé à une URL validée). Le document peut changer (par exemple, en naviguant), mais le frameId ne changera pas. Il est donc difficile d'associer un événement survenu dans un document spécifique à un frameId. Nous introduisons le concept de documentId, qui est un identifiant unique par document. Si un frame est parcouru et ouvre un nouveau document, l'identifiant change. Ce champ est utile pour déterminer quand les pages changent d'état de cycle de vie (entre prérendu/actif/mis en cache), car il reste le même.

Types et qualificatifs de transition

L'événement webNavigation onCommitted comporte une propriété transitionType et une propriété transitionQualifiers. Le type de transition est le même que celui utilisé dans l'API History, qui décrit comment le navigateur a accédé à cette URL spécifique. De plus, plusieurs qualificateurs de transition peuvent être renvoyés pour définir plus précisément la navigation.

Voici les qualificatifs de transition disponibles :

Qualificatif de transitionDescription
"client_redirect"Une ou plusieurs redirections provoquées par des balises JavaScript ou méta-actualisation sur la page se sont produites lors de la navigation.
"server_redirect"Une ou plusieurs redirections provoquées par des en-têtes HTTP envoyés par le serveur se sont produites lors de la navigation.
"forward_back"L'utilisateur a utilisé le bouton "Suivant" ou "Précédent" pour lancer la navigation.
"from_address_bar"L'utilisateur a lancé la navigation depuis la barre d'adresse (également appelée Omnibox).

Exemples

Pour essayer cette API, installez l'exemple d'API webNavigation à partir du dépôt chrome-extension-samples.

Types

TransitionQualifier

Chrome 44 et versions ultérieures

Énumération

"client_redirect"

"server_redirect"

"forward_back"

"from_address_bar"

TransitionType

Chrome 44 et versions ultérieures

Cause de la navigation. Les mêmes types de transitions que ceux définis dans l'API History sont utilisés. Il s'agit des mêmes types de transition que ceux définis dans l'API History, sauf que "start_page" remplace "auto_toplevel" (pour la rétrocompatibilité).

Énumération

"link"

"typed"

"auto_bookmark"

"auto_subframe"

"manual_subframe"

"generated"

"start_page"

"form_submit"

"reload"

"keyword"

"keyword_generated"

Méthodes

getAllFrames()

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

Récupère des informations sur tous les cadres d'un onglet donné.

Paramètres

  • détails

    objet

    Informations sur l'onglet à partir duquel récupérer toutes les frames.

    • tabId

      Total

      ID de l'onglet.

Renvoie

  • Promise<object[] | undefined>

    Chrome 93 et versions ultérieures

getFrame()

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

Récupère des informations sur le frame indiqué. Un frame fait référence à un <iframe> ou à un <frame> d'une page Web. Il est identifié par un ID d'onglet et un ID de frame.

Paramètres

  • détails

    objet

    Informations sur le frame pour lequel récupérer des informations.

    • documentId

      chaîne facultative

      Chrome 106 et versions ultérieures

      UUID du document. Si les frameId et/ou tabId sont fournis, ils seront validés pour correspondre au document trouvé par l'ID de document fourni.

    • frameId

      number facultatif

      ID du frame dans l'onglet donné.

    • processId

      number facultatif

      Obsolète depuis Chrome 49

      Les cadres sont désormais identifiés de manière unique par leur ID d'onglet et leur ID de cadre. L'ID de processus n'est plus nécessaire et est donc ignoré.

      ID du processus qui exécute le moteur de rendu pour cet onglet.

    • tabId

      number facultatif

      ID de l'onglet dans lequel se trouve le frame.

Renvoie

  • Promise<object | undefined>

    Chrome 93 et versions ultérieures

Événements

onBeforeNavigate

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

Déclenché lorsqu'une navigation est sur le point de se produire.

Paramètres

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    (details: object) => void

    • détails

      objet

      • Chrome 106 et versions ultérieures

        Cycle de vie du document.

      • frameId

        Total

        La valeur 0 indique que la navigation a lieu dans la fenêtre de contenu de l'onglet, tandis qu'une valeur positive indique une navigation dans un sous-frame. Les ID de frame sont uniques pour un onglet et un processus donnés.

      • Chrome 106 et versions ultérieures

        Type de frame dans lequel la navigation a eu lieu.

      • parentDocumentId

        chaîne facultative

        Chrome 106 et versions ultérieures

        UUID du document parent propriétaire de ce frame. Cette valeur n'est pas définie s'il n'y a pas de parent.

      • parentFrameId

        Total

        ID du frame parent ou -1 s'il s'agit du frame principal.

      • processId

        Total

        Obsolète depuis Chrome 50

        L'ID de processus n'est plus défini pour cet événement, car le processus qui affichera le document résultant n'est connu qu'après onCommit.

        Valeur -1.

      • tabId

        Total

        ID de l'onglet dans lequel la navigation est sur le point de se produire.

      • timeStamp

        Total

        Heure à laquelle le navigateur était sur le point de commencer la navigation, en millisecondes depuis l'epoch.

      • url

        chaîne

  • filtres

    object facultatif

    • Conditions que l'URL vers laquelle l'utilisateur est redirigé doit remplir. Les champs "schemes" et "ports" de UrlFilter sont ignorés pour cet événement.

onCommitted

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

Déclenché lorsqu'une navigation est validée. Le document (et les ressources auxquelles il fait référence, telles que les images et les sous-frames) est peut-être toujours en cours de téléchargement, mais au moins une partie du document a été reçue du serveur et le navigateur a décidé de passer au nouveau document.

Paramètres

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    (details: object) => void

    • détails

      objet

      • documentId

        chaîne

        Chrome 106 et versions ultérieures

        UUID du document chargé.

      • Chrome 106 et versions ultérieures

        Cycle de vie du document.

      • frameId

        Total

        La valeur 0 indique que la navigation a lieu dans la fenêtre de contenu de l'onglet, tandis qu'une valeur positive indique une navigation dans un sous-frame. Les ID de frame sont uniques dans un onglet.

      • Chrome 106 et versions ultérieures

        Type de frame dans lequel la navigation a eu lieu.

      • parentDocumentId

        chaîne facultative

        Chrome 106 et versions ultérieures

        UUID du document parent propriétaire de ce frame. Cette valeur n'est pas définie s'il n'y a pas de parent.

      • parentFrameId

        Total

        Chrome 74 et versions ultérieures

        ID du frame parent ou -1 s'il s'agit du frame principal.

      • processId

        Total

        ID du processus qui exécute le moteur de rendu pour ce frame.

      • tabId

        Total

        ID de l'onglet dans lequel la navigation a lieu.

      • timeStamp

        Total

        Heure à laquelle la navigation a été validée, en millisecondes depuis l'epoch.

      • transitionQualifiers

        TransitionQualifier[]

        Liste des qualificatifs de transition.

      • transitionType

        TransitionType

        Cause de la navigation.

      • url

        chaîne

  • filtres

    object facultatif

    • Conditions que l'URL vers laquelle l'utilisateur est redirigé doit remplir. Les champs "schemes" et "ports" de UrlFilter sont ignorés pour cet événement.

onCompleted

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

Déclenché lorsqu'un document, y compris les ressources auxquelles il fait référence, est entièrement chargé et initialisé.

Paramètres

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    (details: object) => void

    • détails

      objet

      • documentId

        chaîne

        Chrome 106 et versions ultérieures

        UUID du document chargé.

      • Chrome 106 et versions ultérieures

        Cycle de vie du document.

      • frameId

        Total

        La valeur 0 indique que la navigation a lieu dans la fenêtre de contenu de l'onglet, tandis qu'une valeur positive indique une navigation dans un sous-frame. Les ID de frame sont uniques dans un onglet.

      • Chrome 106 et versions ultérieures

        Type de frame dans lequel la navigation a eu lieu.

      • parentDocumentId

        chaîne facultative

        Chrome 106 et versions ultérieures

        UUID du document parent propriétaire de ce frame. Cette valeur n'est pas définie s'il n'y a pas de parent.

      • parentFrameId

        Total

        Chrome 74 et versions ultérieures

        ID du frame parent ou -1 s'il s'agit du frame principal.

      • processId

        Total

        ID du processus qui exécute le moteur de rendu pour ce frame.

      • tabId

        Total

        ID de l'onglet dans lequel la navigation a lieu.

      • timeStamp

        Total

        Heure à laquelle le document a fini de se charger, en millisecondes depuis l'epoch.

      • url

        chaîne

  • filtres

    object facultatif

    • Conditions que l'URL vers laquelle l'utilisateur est redirigé doit remplir. Les champs "schemes" et "ports" de UrlFilter sont ignorés pour cet événement.

onCreatedNavigationTarget

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

Déclenché lorsqu'une nouvelle fenêtre ou un nouvel onglet dans une fenêtre existante est créé pour héberger une navigation.

Paramètres

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    (details: object) => void

    • détails

      objet

      • sourceFrameId

        Total

        ID du frame avec sourceTabId dans lequel la navigation est déclenchée. 0 indique le frame principal.

      • sourceProcessId

        Total

        ID du processus qui exécute le moteur de rendu pour le frame source.

      • sourceTabId

        Total

        ID de l'onglet dans lequel la navigation est déclenchée.

      • tabId

        Total

        ID de l'onglet dans lequel l'URL est ouverte

      • timeStamp

        Total

        Heure à laquelle le navigateur était sur le point de créer une vue (en millisecondes depuis l'epoch).

      • url

        chaîne

        URL à ouvrir dans la nouvelle fenêtre.

  • filtres

    object facultatif

    • Conditions que l'URL vers laquelle l'utilisateur est redirigé doit remplir. Les champs "schemes" et "ports" de UrlFilter sont ignorés pour cet événement.

onDOMContentLoaded

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

Déclenché lorsque le DOM de la page est entièrement construit, mais que les ressources référencées ne sont pas encore chargées.

Paramètres

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    (details: object) => void

    • détails

      objet

      • documentId

        chaîne

        Chrome 106 et versions ultérieures

        UUID du document chargé.

      • Chrome 106 et versions ultérieures

        Cycle de vie du document.

      • frameId

        Total

        La valeur 0 indique que la navigation a lieu dans la fenêtre de contenu de l'onglet, tandis qu'une valeur positive indique une navigation dans un sous-frame. Les ID de frame sont uniques dans un onglet.

      • Chrome 106 et versions ultérieures

        Type de frame dans lequel la navigation a eu lieu.

      • parentDocumentId

        chaîne facultative

        Chrome 106 et versions ultérieures

        UUID du document parent propriétaire de ce frame. Cette valeur n'est pas définie s'il n'y a pas de parent.

      • parentFrameId

        Total

        Chrome 74 et versions ultérieures

        ID du frame parent ou -1 s'il s'agit du frame principal.

      • processId

        Total

        ID du processus qui exécute le moteur de rendu pour ce frame.

      • tabId

        Total

        ID de l'onglet dans lequel la navigation a lieu.

      • timeStamp

        Total

        Heure à laquelle le DOM de la page a été entièrement construit, en millisecondes depuis l'epoch.

      • url

        chaîne

  • filtres

    object facultatif

    • Conditions que l'URL vers laquelle l'utilisateur est redirigé doit remplir. Les champs "schemes" et "ports" de UrlFilter sont ignorés pour cet événement.

onErrorOccurred

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

Déclenché lorsqu'une erreur se produit et que la navigation est abandonnée. Cela peut se produire en cas d'erreur réseau ou si l'utilisateur a interrompu la navigation.

Paramètres

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    (details: object) => void

    • détails

      objet

      • documentId

        chaîne

        Chrome 106 et versions ultérieures

        UUID du document chargé.

      • Chrome 106 et versions ultérieures

        Cycle de vie du document.

      • erreur

        chaîne

        Description de l'erreur.

      • frameId

        Total

        La valeur 0 indique que la navigation a lieu dans la fenêtre de contenu de l'onglet, tandis qu'une valeur positive indique une navigation dans un sous-frame. Les ID de frame sont uniques dans un onglet.

      • Chrome 106 et versions ultérieures

        Type de frame dans lequel la navigation a eu lieu.

      • parentDocumentId

        chaîne facultative

        Chrome 106 et versions ultérieures

        UUID du document parent propriétaire de ce frame. Cette valeur n'est pas définie s'il n'y a pas de parent.

      • parentFrameId

        Total

        Chrome 74 et versions ultérieures

        ID du frame parent ou -1 s'il s'agit du frame principal.

      • processId

        Total

        Obsolète depuis Chrome 50

        Le processId n'est plus défini pour cet événement.

        Valeur -1.

      • tabId

        Total

        ID de l'onglet dans lequel la navigation a lieu.

      • timeStamp

        Total

        Heure à laquelle l'erreur s'est produite, en millisecondes depuis l'epoch.

      • url

        chaîne

  • filtres

    object facultatif

    • Conditions que l'URL vers laquelle l'utilisateur est redirigé doit remplir. Les champs "schemes" et "ports" de UrlFilter sont ignorés pour cet événement.

onHistoryStateUpdated

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

Déclenché lorsque l'historique du frame a été mis à jour vers une nouvelle URL. Tous les futurs événements de ce frame utiliseront l'URL mise à jour.

Paramètres

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    (details: object) => void

    • détails

      objet

      • documentId

        chaîne

        Chrome 106 et versions ultérieures

        UUID du document chargé.

      • Chrome 106 et versions ultérieures

        Cycle de vie du document.

      • frameId

        Total

        La valeur 0 indique que la navigation a lieu dans la fenêtre de contenu de l'onglet, tandis qu'une valeur positive indique une navigation dans un sous-frame. Les ID de frame sont uniques dans un onglet.

      • Chrome 106 et versions ultérieures

        Type de frame dans lequel la navigation a eu lieu.

      • parentDocumentId

        chaîne facultative

        Chrome 106 et versions ultérieures

        UUID du document parent propriétaire de ce frame. Cette valeur n'est pas définie s'il n'y a pas de parent.

      • parentFrameId

        Total

        Chrome 74 et versions ultérieures

        ID du frame parent ou -1 s'il s'agit du frame principal.

      • processId

        Total

        ID du processus qui exécute le moteur de rendu pour ce frame.

      • tabId

        Total

        ID de l'onglet dans lequel la navigation a lieu.

      • timeStamp

        Total

        Heure à laquelle la navigation a été validée, en millisecondes depuis l'epoch.

      • transitionQualifiers

        TransitionQualifier[]

        Liste des qualificatifs de transition.

      • transitionType

        TransitionType

        Cause de la navigation.

      • url

        chaîne

  • filtres

    object facultatif

    • Conditions que l'URL vers laquelle l'utilisateur est redirigé doit remplir. Les champs "schemes" et "ports" de UrlFilter sont ignorés pour cet événement.

onReferenceFragmentUpdated

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

Déclenché lorsque le fragment de référence d'un frame a été mis à jour. Tous les futurs événements de ce frame utiliseront l'URL mise à jour.

Paramètres

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    (details: object) => void

    • détails

      objet

      • documentId

        chaîne

        Chrome 106 et versions ultérieures

        UUID du document chargé.

      • Chrome 106 et versions ultérieures

        Cycle de vie du document.

      • frameId

        Total

        La valeur 0 indique que la navigation a lieu dans la fenêtre de contenu de l'onglet, tandis qu'une valeur positive indique une navigation dans un sous-frame. Les ID de frame sont uniques dans un onglet.

      • Chrome 106 et versions ultérieures

        Type de frame dans lequel la navigation a eu lieu.

      • parentDocumentId

        chaîne facultative

        Chrome 106 et versions ultérieures

        UUID du document parent propriétaire de ce frame. Cette valeur n'est pas définie s'il n'y a pas de parent.

      • parentFrameId

        Total

        Chrome 74 et versions ultérieures

        ID du frame parent ou -1 s'il s'agit du frame principal.

      • processId

        Total

        ID du processus qui exécute le moteur de rendu pour ce frame.

      • tabId

        Total

        ID de l'onglet dans lequel la navigation a lieu.

      • timeStamp

        Total

        Heure à laquelle la navigation a été validée, en millisecondes depuis l'epoch.

      • transitionQualifiers

        TransitionQualifier[]

        Liste des qualificatifs de transition.

      • transitionType

        TransitionType

        Cause de la navigation.

      • url

        chaîne

  • filtres

    object facultatif

    • Conditions que l'URL vers laquelle l'utilisateur est redirigé doit remplir. Les champs "schemes" et "ports" de UrlFilter sont ignorés pour cet événement.

onTabReplaced

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

Déclenché lorsque le contenu de l'onglet est remplacé par un autre onglet (généralement prérendu).

Paramètres

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    (details: object) => void

    • détails

      objet

      • replacedTabId

        Total

        ID de l'onglet remplacé.

      • tabId

        Total

        ID de l'onglet qui a remplacé l'ancien.

      • timeStamp

        Total

        Heure à laquelle le remplacement a eu lieu, en millisecondes depuis l'epoch.