chrome.history

Description

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

Autorisations

history

Fichier manifeste

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

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

Types de transitions

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

Le tableau suivant décrit chaque type de transition.

Type de transitionDescription
"typed"L'utilisateur a accédé à cette page en saisissant l'URL dans la barre d'adresse. Également utilisé pour d'autres actions de navigation explicites. Consultez également generated, qui est utilisé lorsque l'utilisateur a sélectionné un choix qui ne ressemblait pas du tout à une URL.
"auto_bookmark"L'utilisateur a accédé à cette page via une suggestion dans l'UI, par exemple via un élément de menu.
"auto_subframe"Navigation dans les sous-frames. Il s'agit de tout contenu chargé automatiquement dans un frame autre que celui de premier niveau. Par exemple, si une page se compose de plusieurs frames contenant des annonces, les URL de ces annonces ont ce type de transition. Il est possible que l'utilisateur ne se rende même pas compte que le contenu de ces pages se trouve dans un frame distinct et qu'il ne se soucie donc pas de l'URL (voir aussi manual_subframe).
"manual_subframe"Pour les navigations de sous-frame explicitement demandées par l'utilisateur et qui génèrent de nouvelles entrées de navigation dans la liste "Précédent/Suivant". Un frame demandé explicitement est probablement plus important qu'un frame chargé automatiquement, car l'utilisateur se soucie probablement du fait que le frame demandé a été chargé.
"generated"L'utilisateur a accédé à cette page en saisissant une entrée qui ne ressemblait pas à une URL dans la barre d'adresse, puis en la sélectionnant. Par exemple, une correspondance peut avoir l'URL d'une page de résultats de recherche Google, mais elle peut apparaître à l'utilisateur sous la forme "Rechercher sur Google : …". Ces correspondances ne sont pas tout à fait identiques aux navigations saisies, car l'utilisateur n'a pas saisi ni vu l'URL de destination. Voir aussi mot clé.
"auto_toplevel"La page a été spécifiée dans la ligne de commande ou est la page de démarrage.
"form_submit"L'utilisateur a rempli les valeurs d'un formulaire et l'a envoyé. Notez que dans certaines situations (par exemple, lorsqu'un formulaire utilise un script pour envoyer du contenu), l'envoi d'un formulaire n'entraîne 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 d'un onglet fermé 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.
"keyword_generated"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 à partir du dépôt chrome-extension-samples.

Types

HistoryItem

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

Propriétés

  • id

    chaîne

    Identifiant unique de l'élément.

  • lastVisitTime

    number facultatif

    Heure à laquelle cette page a été chargée pour la dernière fois, exprimée en millisecondes depuis l'epoch.

  • titre

    chaîne facultative

    Titre de la page lors de son dernier chargement.

  • typedCount

    number facultatif

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

  • url

    chaîne facultative

    URL vers laquelle un utilisateur a accédé.

  • visitCount

    number facultatif

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

TransitionType

Chrome 44 et versions ultérieures

Le type de transition pour cette visite à partir de son site référent.

Énumération

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

"typed"
L'utilisateur est arrivé sur cette page en saisissant l'URL dans la barre d'adresse. Elle est également utilisée pour d'autres actions de navigation explicites.

"auto_bookmark"
L'utilisateur est arrivé sur cette page via une suggestion dans l'UI, par exemple via un élément de menu.

"auto_subframe"
L'utilisateur est arrivé sur cette page via une navigation dans un sous-frame qu'il n'a pas demandée, par exemple via une annonce se chargeant dans un frame sur la page précédente. Elles 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 un élément dans un sous-frame.

"generated"
L'utilisateur est arrivé sur 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, comme une suggestion de recherche Google. Par exemple, une correspondance peut avoir l'URL d'une page de résultats de recherche Google, mais elle peut apparaître à l'utilisateur sous la forme "Rechercher sur Google : …". Ces correspondances 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 au clavier.

"auto_toplevel"
La page a été spécifiée dans la ligne de commande ou est la page de démarrage.

"form_submit"
L'utilisateur est arrivé sur cette page en remplissant les valeurs d'un formulaire et en l'envoyant. 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 d'un onglet fermé utilisent également ce type de transition.

"keyword"
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 88 et versions ultérieures

Propriétés

  • url

    chaîne

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

VisitItem

Objet encapsulant une visite d'URL.

Propriétés

  • id

    chaîne

    Identifiant unique du history.HistoryItem correspondant.

  • isLocal

    booléen

    Chrome 115 et versions ultérieures

    "True" si la visite a commencé sur cet appareil. "False" si elle a été synchronisée depuis un autre appareil.

  • referringVisitId

    chaîne

    ID de visite du site de provenance.

  • transition

    TransitionType

    Le type de transition pour cette visite à partir de son site référent.

  • visitId

    chaîne

    Identifiant unique de cette visite.

  • visitTime

    number facultatif

    Heure à laquelle cette visite a eu lieu, représentée en millisecondes depuis l'epoch.

Méthodes

addUrl()

Promise 
chrome.history.addUrl(
  details: UrlDetails,
  callback?: function,
): Promise<void>

Ajoute une URL à l'historique à l'heure actuelle avec un type de transition "link".

Paramètres

  • détails

    UrlDetails

  • callback

    function facultatif

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

    () => void

Renvoie

  • Promise<void>

    Chrome 96 et versions ultérieures

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

deleteAll()

Promise 
chrome.history.deleteAll(
  callback?: function,
): Promise<void>

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

Paramètres

  • callback

    function facultatif

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

    () => void

Renvoie

  • Promise<void>

    Chrome 96 et versions ultérieures

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

deleteRange()

Promise 
chrome.history.deleteRange(
  range: object,
  callback?: function,
): Promise<void>

Supprime de l'historique tous les éléments compris dans la plage de dates spécifiée. Les pages ne seront supprimées de l'historique que si toutes les visites se trouvent dans la plage.

Paramètres

  • niveaux

    objet

    • endTime

      Total

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

    • startTime

      Total

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

  • callback

    function facultatif

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

    () => void

Renvoie

  • Promise<void>

    Chrome 96 et versions ultérieures

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

deleteUrl()

Promise 
chrome.history.deleteUrl(
  details: UrlDetails,
  callback?: function,
): Promise<void>

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

Paramètres

  • détails

    UrlDetails

  • callback

    function facultatif

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

    () => void

Renvoie

  • Promise<void>

    Chrome 96 et versions ultérieures

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

getVisits()

Promise 
chrome.history.getVisits(
  details: UrlDetails,
  callback?: function,
): Promise<VisitItem[]>

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

Paramètres

  • détails

    UrlDetails

  • callback

    function facultatif

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

    (results: VisitItem[]) => void

Renvoie

  • Promise<VisitItem[]>

    Chrome 96 et versions ultérieures

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

Promise 
chrome.history.search(
  query: object,
  callback?: function,
): Promise<HistoryItem[]>

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

Paramètres

  • requête

    objet

    • endTime

      number facultatif

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

    • maxResults

      number facultatif

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

    • startTime

      number facultatif

      Limitez les résultats à ceux visités après cette date, représentée en millisecondes depuis l'époque. Si la propriété n'est pas 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.

  • callback

    function facultatif

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

    (results: HistoryItem[]) => void

Renvoie

  • Promise<HistoryItem[]>

    Chrome 96 et versions ultérieures

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

Événements

onVisited

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

Déclenché lorsqu'une URL est visitée, en fournissant les données HistoryItem pour cette URL. Cet événement se déclenche avant le chargement de la page.

Paramètres

  • callback

    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 supprimée de l'historique.

Paramètres

  • callback

    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