chrome.history

Description

Utilisez l'API chrome.history pour interagir avec l'enregistrement des pages visitées du navigateur. Vous pouvez ajouter, supprimer et rechercher des URL dans l'historique du navigateur. Pour remplacer la page d'historique par votre propre version, consultez Remplacer les pages.

Autorisations

history

Fichier manifeste

Vous devez déclarer l'"historique" l'autorisation dans le fichier manifeste de l'extension d'utiliser l'API History. Exemple :

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

Types de transition

L'API History utilise un type de transition pour décrire la manière dont le navigateur a accédé à une URL spécifique. lors d'une visite en particulier. Par exemple, si un utilisateur visite une page en cliquant sur un lien figurant sur une autre page, le le type de transition est "link".

Le tableau suivant décrit chaque type de transition.

Type de transitionDescription
"typed"L'utilisateur a obtenu cette page en saisissant son URL dans la barre d'adresse. Également utilisé pour d'autres actions de navigation explicites. Consultez également l'article Généré : cet attribut est utilisé lorsque l'utilisateur a sélectionné une option qui ne ressemblant pas du tout à une URL.
"auto_bookmark"L'utilisateur a accédé à cette page via une suggestion dans l'interface utilisateur, par exemple via un élément de menu.
"auto_subframe"Navigation dans un sous-cadre. Il s'agit de tout contenu chargé automatiquement dans un frame de niveau inférieur. Par exemple, si une page est composée de plusieurs cadres contenant des annonces, ces URL d'annonces comportent ce type de transition. L'internaute peut même ne pas se rendre compte que le contenu de ces pages est un cadre distinct et ne se soucie donc pas de l'URL (voir aussi manual_subframe).
"manual_subframe"Pour les navigations de sous-frame qui sont explicitement demandées par l'utilisateur et qui génèrent de nouvelles entrées de navigation dans la liste précédente/suivante. Une trame explicitement demandée est probablement plus importante qu'une trame chargée automatiquement car l'utilisateur se soucie probablement du fait que la trame demandée ait été chargée.
"généré"L'utilisateur a accédé à cette page en saisissant une entrée dans la barre d'adresse et en sélectionnant une entrée qui ne ressemblait pas à une URL. Par exemple, une correspondance peut être l'URL d'une page de résultats de recherche Google, mais l'internaute peut voir le message "Rechercher sur Google ...". Ces navigations sont différentes des navigations typées, car l'utilisateur n'a pas saisi ni vu l'URL de destination. Voir aussi mot clé.
"auto_premierniveau"La page a été spécifiée dans la ligne de commande ou est la page d'accueil.
"form_submit"L'utilisateur a rempli un formulaire et envoyé les valeurs. Notez que dans certaines situations (par exemple, lorsqu'un formulaire utilise un script pour envoyer le contenu), l'envoi d'un formulaire n'entraîne pas ce type de transition.
"actualiser"L'utilisateur a actualisé la page en cliquant sur le bouton d'actualisation ou en appuyant sur Entrée dans la barre d'adresse. La restauration de session et la réouverture des onglets fermés utilisent également ce type de transition.
"mot clé"L'URL a été générée à partir d'un mot clé remplaçable autre que le moteur de recherche par défaut. Voir aussi keyword_generated.
"généré par le mot clé"Correspond à une visite générée pour un mot clé. Voir aussi mot clé.

Exemples

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

Types

HistoryItem

Objet encapsulant un résultat d'une requête d'historique.

Propriétés

  • id

    chaîne

    Identifiant unique de l'article.

  • lastVisitTime

    numéro facultatif

    Date du dernier chargement de cette page, exprimée en millisecondes depuis l'epoch.

  • titre

    chaîne facultatif

    Titre de la page lors de son dernier chargement.

  • typedCount

    numéro facultatif

    Nombre de fois où l'utilisateur a accédé à cette page en saisissant l'adresse.

  • url

    chaîne facultatif

    URL à laquelle un utilisateur accède.

  • visitCount

    numéro facultatif

    Nombre de fois où l'utilisateur a accédé à cette page.

TransitionType

Chrome (version 44 ou ultérieure)

Type de transition de cette visite provenant de son URL de provenance.

Énumération

"link"
L'utilisateur est arrivé sur cette page en cliquant sur un lien figurant sur une autre page.

"typed"
L'utilisateur a accédé à cette page en saisissant son URL dans la barre d'adresse. Il est également utilisé pour d'autres actions de navigation explicites.

"auto_bookmark"
L'utilisateur a accédé à cette page via une suggestion dans l'interface utilisateur, par exemple via un élément de menu.

"auto_subframe"
L'utilisateur est arrivé sur cette page via une navigation dans un sous-cadre qu'il n'a pas demandée, par exemple via le chargement d'une annonce dans un cadre de la page précédente. Ils ne génèrent pas toujours de nouvelles entrées de navigation dans les menus "Précédent" et "Suivant".

"manual_subframe"
L'utilisateur est arrivé sur cette page en sélectionnant quelque chose dans un sous-cadre.

"generated"
L'utilisateur a accédé à cette page en saisissant du texte dans la barre d'adresse et en sélectionnant une entrée qui ne ressemblait pas à une URL, telle qu'une suggestion de recherche Google. Par exemple, une correspondance peut être associée à l'URL d'une page de résultats de recherche Google, mais elle peut être présentée aux utilisateurs sous la forme "Rechercher sur Google ...". Elles sont différentes des navigations saisies, car l'utilisateur n'a pas saisi ni vu l'URL de destination. Elles sont également liées aux navigations par mots clés.

"auto_toplevel"
La page a été spécifiée dans la ligne de commande ou il s'agit de la page d'accueil.

"form_submit"
L'utilisateur est arrivé sur cette page après avoir rempli un formulaire, puis envoyé ce dernier. Tous les envois de formulaires n'utilisent pas ce type de transition.

"reload"
L'utilisateur a actualisé la page en cliquant sur le bouton d'actualisation ou en appuyant sur Entrée dans la barre d'adresse. La restauration de session et la réouverture des onglets fermés utilisent également ce type de transition.

"mot clé"
L'URL de cette page a été générée à partir d'un mot clé remplaçable autre que le moteur de recherche par défaut.

"keyword_generated"
correspond à une visite générée pour un mot clé.

UrlDetails

Chrome (version 88 ou ultérieure)

Propriétés

  • url

    chaîne

    URL de l'opération. Elle doit être au format renvoyé par un appel à history.search().

VisitItem

Objet encapsulant une visite sur une URL.

Propriétés

  • id

    chaîne

    Identifiant unique du history.HistoryItem correspondant.

  • isLocal

    booléen

    Chrome 115 ou version ultérieure

    "True" si la visite provient de cet appareil. "False" s'il a été synchronisé à partir d'un autre appareil.

  • referringVisitId

    chaîne

    ID de visite de l'URL de provenance.

  • transition

    TransitionType

    Type de transition de cette visite provenant de son URL de provenance.

  • visitId

    chaîne

    Identifiant unique de la visite.

  • visitTime

    numéro facultatif

    Date et heure de la visite, représentée en millisecondes depuis l'epoch.

Méthodes

addUrl()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.history.addUrl(
  details: UrlDetails,
  callback?: function,
)

Ajoute une URL à l'historique actuel avec un type de transition défini sur "link".

Paramètres

  • détails

    UrlDetails

  • rappel

    function facultatif

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

    () => void

Renvoie

  • Promesse<void>

    Chrome 96 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

deleteAll()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.history.deleteAll(
  callback?: function,
)

Supprime tous les éléments de l'historique.

Paramètres

  • rappel

    function facultatif

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

    () => void

Renvoie

  • Promesse<void>

    Chrome 96 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

deleteRange()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.history.deleteRange(
  range: object,
  callback?: function,
)

Supprime de l'historique tous les éléments compris dans la période spécifiée. Les pages ne seront pas supprimées de l'historique, sauf si toutes les visites sont comprises dans la plage.

Paramètres

  • niveaux

    objet

    • endTime

      Nombre

      Éléments ajoutés à l'historique avant cette date, représentés en millisecondes depuis l'epoch.

    • startTime

      Nombre

      Éléments ajoutés à l'historique après cette date, représentés en millisecondes depuis l'epoch.

  • rappel

    function facultatif

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

    () => void

Renvoie

  • Promesse<void>

    Chrome 96 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

deleteUrl()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.history.deleteUrl(
  details: UrlDetails,
  callback?: function,
)

Supprime toutes les occurrences de l'URL donnée de l'historique.

Paramètres

  • détails

    UrlDetails

  • rappel

    function facultatif

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

    () => void

Renvoie

  • Promesse<void>

    Chrome 96 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getVisits()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.history.getVisits(
  details: UrlDetails,
  callback?: function,
)

Récupère des informations sur les visites d'une URL.

Paramètres

  • détails

    UrlDetails

  • rappel

    function facultatif

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

    (results: VisitItem[]) => void

Renvoie

  • Promise&lt;VisitItem[]&gt;

    Chrome 96 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.history.search(
  query: object,
  callback?: function,
)

Recherche dans l'historique la date et l'heure de la dernière visite de chaque page correspondant à la requête.

Paramètres

  • requête

    objet

    • endTime

      numéro facultatif

      Limiter les résultats à ceux consultés avant cette date, représentés en millisecondes depuis l'époque.

    • maxResults

      numéro facultatif

      Nombre maximal de résultats à récupérer. La valeur par défaut est 100.

    • startTime

      numéro facultatif

      Limiter les résultats à ceux consultés après cette date, représentés en millisecondes depuis l'époque. Si aucune propriété n'est spécifiée, la valeur par défaut est de 24 heures.

    • texte

      chaîne

      Requête en texte libre envoyée au service d'historique. Laissez ce champ vide pour récupérer toutes les pages.

  • rappel

    function facultatif

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

    (results: HistoryItem[]) => void

Renvoie

  • Promise&lt;HistoryItem[]&gt;

    Chrome 96 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

Événements

onVisited

chrome.history.onVisited.addListener(
  callback: function,
)

Déclenché lors de la visite d'une URL, fournissant les données HistoryItem pour cette URL. Cet événement se déclenche avant le chargement de la page.

Paramètres

  • rappel

    fonction

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

    (result: HistoryItem) => void

onVisitRemoved

chrome.history.onVisitRemoved.addListener(
  callback: function,
)

Déclenché lorsqu'une ou plusieurs URL sont supprimées de l'historique. Une fois toutes les visites supprimées, l'URL est définitivement supprimée de l'historique.

Paramètres

  • rappel

    fonction

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

    (removed: object) => void

    • supprimé

      objet

      • allHistory

        booléen

        "True" si tout l'historique a été supprimé. Si la valeur est "true", les URL seront vides.

      • URL

        string[] facultatif