browser.history

Description

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

Autorisations

history

Pour interagir avec l'historique de navigation de l'utilisateur, utilisez l'API History.

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

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

Concepts et utilisation

Types de transition

L'API History utilise des types de transition pour décrire la manière dont le navigateur a accédé à une URL particulière lors d'une visite spécifique. Par exemple, si un utilisateur accède à une page en cliquant sur un lien sur une autre page, le type de transition est "link". Consultez le contenu de référence pour obtenir la liste des types de transition.

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

    Dernier chargement de cette page, représenté en millisecondes depuis l'epoch.

  • titre

    chaîne facultatif

    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 facultatif

    URL à laquelle un utilisateur a accédé.

  • visitCount

    number facultatif

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

TransitionType

Chrome 44+ browser.* depuis Chrome 148

Type de transition pour cette visite depuis son site référent.

Énumération

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

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

"auto_bookmark"
L'utilisateur est arrivé sur 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-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-cadre.

"generated"
L'utilisateur est arrivé sur cette page en saisissant du texte 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 s'afficher pour l'utilisateur sous la forme "Rechercher sur Google ...". Ces navigations 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 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 est arrivé sur cette page en remplissant et en envoyant un formulaire. Tous les envois de formulaires n'utilisent pas ce type de transition.

"reload"
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 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+ browser.* depuis Chrome 148

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 de l'objet history.HistoryItem correspondant.

  • isLocal

    booléen

    Chrome 115 et versions ultérieures browser.* depuis Chrome 148

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

  • referringVisitId

    chaîne

    ID de visite de l'URL de provenance.

  • transition

    TransitionType

    Type de transition pour cette visite depuis son site référent.

  • visitId

    chaîne

    Identifiant unique de cette visite.

  • visitTime

    number facultatif

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

Méthodes

addUrl()

browser.history.addUrl(
  details: UrlDetails,
): Promise<void>

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

Paramètres

Renvoie

  • Promise<void>

    Chrome 96+ browser.* depuis Chrome 148

deleteAll()

browser.history.deleteAll(): Promise<void>

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

Renvoie

  • Promise<void>

    Chrome 96+ browser.* depuis Chrome 148

deleteRange()

browser.history.deleteRange(
  range: object,
): Promise<void>

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

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.

Renvoie

  • Promise<void>

    Chrome 96+ browser.* depuis Chrome 148

deleteUrl()

browser.history.deleteUrl(
  details: UrlDetails,
): Promise<void>

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

Paramètres

Renvoie

  • Promise<void>

    Chrome 96+ browser.* depuis Chrome 148

getVisits()

browser.history.getVisits(
  details: UrlDetails,
): Promise<VisitItem[]>

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

Paramètres

Renvoie

  • Promise<VisitItem[]>

    Chrome 96+ browser.* depuis Chrome 148 
browser.history.search(
  query: object,
): Promise<HistoryItem[]>

Recherche dans l'historique l'heure de la dernière 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'epoch.

    • 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'epoch. Si cette 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 adressée au service d'historique. Laissez ce champ vide pour récupérer toutes les pages.

Renvoie

  • Promise<HistoryItem[]>

    Chrome 96+ browser.* depuis Chrome 148

Événements

onVisited

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

Déclenché lorsqu'une URL est consultée, 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

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

Se déclenche lorsqu'une ou plusieurs URL sont supprimées de l'historique. Lorsque toutes les visites ont été supprimées, l'URL est purgé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