chrome.webNavigation

Description

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

Autorisations

webNavigation

L'ensemble des méthodes et é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 des événements

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

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

Toute erreur qui se produit pendant le processus entraîne un événement onErrorOccurred. Pour une navigation, aucun autre événement n'est déclenché après onErrorOccurred.

Si un cadre de navigation contient des sous-cadres, son onCommitted est déclenché avant les images onBeforeNavigate; tandis que onCompleted est déclenché après toutes les onCompleted de ses enfants.

Si le fragment de référence d'un frame est modifié, un événement onReferenceFragmentUpdated est déclenché. Ce 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 L'événement onHistoryStateUpdated est déclenché. Cet événement peut se déclencher à tout moment après le onDOMContentLoaded.

Si une navigation a restauré une page à partir du cache amélioré, l'événement onDOMContentLoaded ne se déclenchera pas. L'événement n'est pas déclenché, car le chargement du contenu est déjà terminé lorsque la page a été consultée pour la première fois.

Si la navigation a été déclenchée par la fonctionnalité Chrome Instantané ou les pages instantanées, une page dans l'onglet actif. Dans ce cas, un événement onTabReplaced est déclenché.

Relation avec les événements webRequest

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

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

ID des onglets

Tous les onglets de navigation ne correspondent pas à des onglets réels dans l'interface utilisateur de Chrome, par exemple un onglet en cours prérendus. Ces onglets ne sont pas accessibles à l'aide de l'API Tabs et vous ne pouvez pas demander d'informations. à leur sujet en appelant webNavigation.getFrame() ou webNavigation.getAllFrames(). Une fois qu'un tel onglet sont échangées, un événement onTabReplaced est déclenché, et ils deviennent accessibles via ces API.

Codes temporels

Il est important de noter que certaines anomalies techniques dans la gestion par le système d'exploitation de différentes 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 cohérents en interne. Comparer un événement à un autre vous permet d'obtenir le décalage correct entre elles, mais en les comparant à l'heure actuelle dans l'extension (en utilisant (new Date()).getTime(), par exemple) peuvent donner des résultats inattendus.

ID de frame

Les frames dans un onglet peuvent être identifiés par un identifiant de frame. L'ID du frame principal est toujours 0, L'ID des frames enfants est un nombre positif. Une fois qu'un document est créé dans un cadre, son ID de cadre reste constante pendant toute la durée de vie du document. À partir de Chrome 49, cet ID est également constant pour la durée de vie du cadre (sur plusieurs navigations).

En raison de la nature multiprocessus de Chrome, différents processus peuvent être appliqués à un onglet 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 de la nouvelle et de l'ancienne page jusqu'à ce que la nouvelle navigation soit validée (par exemple, l'événement onCommitted est envoyé pour le nouveau frame principal). En d'autres termes, il est possible d'avoir plus plusieurs séquences en attente d'événements webNavigation avec le même frameId. Les séquences peuvent être distinguée par la clé processId.

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

Un autre concept qui pose problème avec les extensions est le cycle de vie cadre. Un cadre héberge un document (associé à une URL validée). Le document peut changer (en naviguant, par exemple), mais pas frameId. Il qu'un événement s'est produit dans un document spécifique frameIds uniquement. Nous ajoutons le concept de documentId. qui est un identifiant unique pour chaque document. Si l'utilisateur parcourt un cadre et qu'il ouvre un l'identifiant sera modifié. Ce champ est utile pour déterminer Lorsque l'état du cycle de vie des pages change (entre prérendu, actif ou mis en cache) car elle reste la même.

Types de transition et qualificatifs

L'événement webNavigation onCommitted comporte un transitionType et un transitionQualifiers . Le type de transition est le même que celui utilisé dans l'API History, qui décrit comment le j'ai accédé à cette URL. En outre, plusieurs qualificatifs de transition peuvent être renvoyés qui définissent plus précisément la navigation.

Les qualificatifs de transition suivants existent:

Qualificatif de transitionDescription
"client_redirect"Une ou plusieurs redirections liées à des balises JavaScript ou Meta refresh sur la page se sont produites pendant la navigation.
"server_redirect"Une ou plusieurs redirections causées par les en-têtes HTTP envoyés depuis le serveur se sont produites pendant la navigation.
"forward_back" (Transférer)L'utilisateur a utilisé le bouton Avant ou Retour pour lancer la navigation.
"from_address_bar"L'utilisateur a lancé la navigation à partir de la barre d'adresse (également appelée "omnibox").

Exemples

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

Types

TransitionQualifier

Chrome 44 ou version ultérieure

Énumération

"client_redirect"

"server_redirect"

"forward_back"

"from_address_bar"

TransitionType

Chrome 44 ou version ultérieure

Cause de la navigation. Les types de transition 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 des raisons de rétrocompatibilité).

Énumération

"lien"

"typed"

"auto_bookmark"

"auto_subframe"

"manual_subframe"

"generated"

"start_page"

"form_submit"

"recharger"

"mot clé"

"keyword_generated"

Méthodes

getAllFrames()

Promesse 
chrome.webNavigation.getAllFrames(
  details: object,
  callback?: function,
)

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

Paramètres

  • détails

    objet

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

    • tabId

      Nombre

      ID de l'onglet.

  • rappel

    function facultatif

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

    (details?: object[]) => void

    • détails

      objet[] facultatif

      Liste de frames dans l'onglet donné, null si l'ID d'onglet spécifié est incorrect.

      • documentId

        chaîne

        Chrome 106 et versions ultérieures

        Un UUID du document chargé.

      • documentLifecycle

        DocumentLifecycle

        Chrome 106 ou version ultérieure

        Cycle de vie du document.

      • errorOccurred

        booléen

        "True" si la dernière navigation dans ce frame a été interrompue par une erreur, c'est-à-dire si l'événement onErrorOccurred a été déclenché.

      • frameId

        Nombre

        Identifiant du frame. 0 indique qu'il s'agit du frame principal ; une valeur positive indique l'identifiant d'un sous-cadre.

      • frameType

        FrameType

        Chrome 106 et versions ultérieures

        Type de cadre dans lequel la navigation a eu lieu.

      • parentDocumentId

        chaîne facultatif

        Chrome 106 et versions ultérieures

        Un UUID du document parent propriétaire de ce cadre. Cette valeur n'est pas définie en l'absence de parent.

      • parentFrameId

        Nombre

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

      • processId

        Nombre

        ID du processus qui exécute le moteur de rendu pour cette image.

      • url

        chaîne

        URL actuellement associée à ce cadre.

Renvoie

  • Promise<object[] | indéfini>

    Chrome 93 ou version ultérieure

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

getFrame()

Promesse 
chrome.webNavigation.getFrame(
  details: object,
  callback?: function,
)

Récupère des informations sur la trame donnée. Un frame fait référence à un