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
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 comment le navigateur a accédé à une URL particulière lors 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". Consultez le contenu de référence pour obtenir la liste des types de transitions.
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
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
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
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()
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
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :() => void
Renvoie
-
Promise<void>
Chrome 96 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
deleteAll()
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érieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
deleteRange()
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érieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
deleteUrl()
chrome.history.deleteUrl(
details: UrlDetails,
callback?: function,
)
Supprime toutes les occurrences de l'URL donnée de l'historique.
Paramètres
-
détails
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :() => void
Renvoie
-
Promise<void>
Chrome 96 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
getVisits()
chrome.history.getVisits(
details: UrlDetails,
callback?: function,
)
Récupère des informations sur les visites d'une URL.
Paramètres
-
détails
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(results: VisitItem[]) => void
-
résultats
-
Renvoie
-
Promise<VisitItem[]>
Chrome 96 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
search()
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
-
résultats
-
Renvoie
-
Promise<HistoryItem[]>
Chrome 96 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
É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
-
résultat
-
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
-
-