chrome.history

Description

Utilisez l'API chrome.history pour interagir avec l'enregistrement des pages consultées par le navigateur. Vous pouvez ajouter des URL, en supprimer et lancer des requêtes dans l'historique du navigateur. Pour remplacer la page d'historique par votre propre version, consultez la section Remplacer les pages.

Autorisations

history

Manifest

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

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

Types de transition

L'API d'historique utilise un type de transition pour décrire la manière dont le navigateur a accédé à une URL donnée au cours d'une visite donnée. Par exemple, si un utilisateur consulte une page en cliquant sur un lien d'une autre page, le type de transition est "link".

Le tableau suivant décrit chaque type de transition.

Type de transitionDescription
"saisie"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 Voir aussi généré, qui est utilisé lorsque l'utilisateur a sélectionné une réponse qui ne ressemble pas du tout à une URL.
"auto_bookmark"L'utilisateur a accédé à cette page via une suggestion de l'interface utilisateur (par exemple, un élément de menu).
"auto_subframe"Navigation dans le sous-cadre Il s'agit de tout contenu qui est automatiquement chargé dans un frame qui n'est pas de niveau supérieur. Par exemple, si une page se compose de plusieurs frames contenant des annonces, les URL d'annonce concernées comportent ce type de transition. L'utilisateur peut même ne pas réaliser que le contenu de ces pages est un cadre distinct et donc ne pas se soucier de l'URL (voir aussi manual_subframe).
"manuel_sous-cadre"Pour les navigations dans un 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édent/Suivant". Un frame explicitement demandé est probablement plus important qu'un frame chargé automatiquement, car l'utilisateur se soucie probablement du fait que le frame demandé ait été chargé.
"généré"L'utilisateur a accédé à cette page en saisissant du texte dans la barre d'adresse, puis en sélectionnant une entrée qui ne ressemblait pas à une URL. Par exemple, une correspondance peut contenir l'URL d'une page de résultats de recherche Google, mais elle peut apparaître sous la forme "Rechercher sur Google pour ...". Ces termes sont différents des navigations typées, 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 d'accueil.
"form_submit"L'utilisateur a rempli un formulaire et l'a envoyé. Notez que dans certains cas, 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.
"actualiser"L'utilisateur a actualisé la page soit en cliquant sur le bouton d'actualisation, soit en appuyant sur Entrée dans la barre d'adresse. La restauration de la session et la réouverture de l'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'article.

  • lastVisitTime

    numéro facultatif

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

  • title

    string 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

    string facultatif

    URL vers laquelle l'utilisateur a accédé.

  • visitCount

    numéro facultatif

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

TransitionType

Chrome 44 ou version ultérieure

Type de transition pour cette visite depuis son URL de provenance.

Enum

"link"
L'utilisateur a accédé à cette page en cliquant sur un lien figurant sur une autre page.

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

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

"auto_subframe"
L'utilisateur a accédé à cette page via une navigation dans un sous-frame qu'il n'a pas demandée (par exemple, via le chargement d'une annonce dans un frame sur 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 un élément dans un sous-frame.

"generated"
L'utilisateur est arrivé sur cette page en saisissant du texte dans la barre d'adresse, puis en sélectionnant une entrée qui ne ressemble pas à une URL, comme une suggestion de recherche Google. Par exemple, une correspondance peut contenir l'URL d'une page de résultats de recherche Google, mais elle peut apparaître 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 correspond à la page d'accueil.

"form_submit"
L'utilisateur est arrivé sur cette page en remplissant les valeurs d'un formulaire, puis en l'envoyant. Les envois de formulaire n'utilisent pas tous ce type de transition.

"reload"
L'utilisateur a rechargé 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 de l'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'une URL.

Propriétés

  • id

    chaîne

    Identifiant unique du history.HistoryItem correspondant.

  • isLocal

    boolean

    Chrome 115 et versions ultérieures

    "True" si la visite provient de cet appareil. et "false" si elle a été synchronisée à partir d'un autre appareil.

  • referringVisitId

    chaîne

    Identifiant de visite de l'URL de provenance.

  • transition

    TransitionType

    Type de transition pour cette visite depuis son URL de provenance.

  • visitId

    chaîne

    Identifiant unique de cette visite.

  • visitTime

    numéro facultatif

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

Méthodes

addUrl()

Promesse 
chrome.history.addUrl(
  details: UrlDetails,
  callback?: function,
)

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

Paramètres

  • détails

    UrlDetails

  • rappel

    fonction facultative

    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 versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

deleteAll()

Promesse 
chrome.history.deleteAll(
  callback?: function,
)

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

Paramètres

  • rappel

    fonction facultative

    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 versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

deleteRange()

Promesse 
chrome.history.deleteRange(
  range: object,
  callback?: function,
)

Supprime tous les éléments compris dans la plage de dates spécifiée de l'historique. Les pages ne sont pas supprimées de l'historique, sauf si toutes les visites sont comprises dans cette 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

    fonction facultative

    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 versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

deleteUrl()

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

    fonction facultative

    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 versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getVisits()

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

    fonction facultative

    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 versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

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

      Limitez les résultats aux visites antérieures à cette date, représentées en millisecondes depuis l'epoch.

    • maxResults

      numéro facultatif

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

    • startTime

      numéro facultatif

      Limitez les résultats aux visites après cette date, représentées en millisecondes depuis l'epoch. Si la propriété n'est pas spécifiée, la valeur par défaut est de 24 heures.

    • text

      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

    fonction facultative

    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 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 et fournissant les données HistoryItem pour cette URL Cet événement se déclenche avant le chargement de la page.

Paramètres

  • rappel

    function

    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 définitivement de l'historique.

Paramètres

  • rappel

    function

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

    (removed: object)=>void

    • supprimé

      objet

      • allHistory

        boolean

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

      • urls

        string[] facultatif