Descrizione
Utilizza l'API chrome.history
per interagire con il record del browser delle pagine visitate. Puoi aggiungere, rimuovere ed eseguire query sugli URL nella cronologia del browser. Per eseguire l'override della pagina della cronologia con la tua versione, consulta la sezione Override pagine.
Autorizzazioni
history
Per interagire con la cronologia del browser dell'utente, utilizza l'API History.
Per utilizzare l'API History, dichiara l'autorizzazione "history"
nel manifest dell'estensione. Ad
esempio:
{
"name": "My extension",
...
"permissions": [
"history"
],
...
}
Concetti e utilizzo
Tipi di transizione
L'API History utilizza i tipi di transizione per descrivere il modo in cui il browser ha raggiunto un determinato URL in una determinata visita. Ad esempio, se un utente visita una pagina facendo clic su un link in un'altra pagina, il tipo di transizione è "link". Consulta i contenuti di riferimento per un elenco dei tipi di transizione.
Esempi
Per provare questa API, installa l'esempio dell'API History dal repository chrome-extension-samples.
Tipi
HistoryItem
Un oggetto che incapsula un risultato di una query sulla cronologia.
Proprietà
-
id
stringa
L'identificatore univoco dell'articolo.
-
lastVisitTime
numero facoltativo
L'ultimo caricamento della pagina, espresso in millisecondi dall'epoca.
-
title
stringa facoltativo
Il titolo della pagina quando è stato caricato l'ultimo caricamento.
-
typedCount
numero facoltativo
Il numero di volte in cui l'utente è arrivato a questa pagina digitando l'indirizzo.
-
url
stringa facoltativo
L'URL raggiunto da un utente.
-
visitCount
numero facoltativo
Il numero di volte in cui l'utente è arrivato a questa pagina.
TransitionType
Il tipo di transizione per questa visita dal relativo referrer.
Enum
"link"
L'utente è arrivato a questa pagina facendo clic su un link in un'altra pagina.
"typed"
L'utente è arrivato a questa pagina digitando l'URL nella barra degli indirizzi. Viene utilizzato anche per altre azioni di navigazione esplicite.
"auto_bookmark"
L'utente è arrivato a questa pagina tramite un suggerimento nell'interfaccia utente, ad esempio tramite una voce di menu.
"auto_subframe"
L'utente è arrivato a questa pagina mediante una navigazione tra frame secondari che non ha richiesto, ad esempio tramite il caricamento di un annuncio in un frame nella pagina precedente. Non sempre generano nuove voci di navigazione nei menu Avanti e Indietro.
"manual_subframe"
L'utente è arrivato in questa pagina selezionando un elemento in un frame secondario.
"generate"
L'utente è arrivato a questa pagina digitando nella barra degli indirizzi e selezionando una voce che non sembrava un URL, ad esempio un suggerimento di Ricerca Google. Ad esempio, una corrispondenza potrebbe avere l'URL di una pagina dei risultati della Ricerca Google, ma l'utente potrebbe sembrare "Cerca su Google ...". Queste corrispondenze sono diverse dalle navigazioni digitate, perché l'utente non ha digitato o visualizzato l'URL di destinazione. e riguardano anche le navigazioni per parole chiave.
"auto_toplevel"
La pagina è stata specificata nella riga di comando o è la pagina iniziale.
"form_submit"
L'utente è arrivato a questa pagina compilando i valori in un modulo e inviandolo. Non tutti gli invii di moduli utilizzano questo tipo di transizione.
"reload"
L'utente ha ricaricato la pagina facendo clic sul pulsante Ricarica o premendo Invio nella barra degli indirizzi. Anche il ripristino delle sessioni e la riapertura della scheda chiusa utilizzano questo tipo di transizione.
"keyword"
L'URL di questa pagina è stato generato da una parola chiave sostituibile diversa dal provider di ricerca predefinito.
"keyword_generated"
Corrisponde a una visita generata per una parola chiave.
UrlDetails
Proprietà
-
url
stringa
L'URL dell'operazione. Deve essere nel formato restituito da una chiamata a
history.search()
.
VisitItem
Un oggetto che contiene una visita a un URL.
Proprietà
-
id
stringa
L'identificatore univoco del file
history.HistoryItem
corrispondente. -
isLocal
boolean
Chrome 115 e versioni successiveTrue se la visita ha avuto origine da questo dispositivo. Falso se è stata sincronizzata da un altro dispositivo.
-
referringVisitId
stringa
L'ID visita del referrer.
-
transizione
Il tipo di transizione per questa visita dal relativo referrer.
-
visitId
stringa
L'identificatore univoco di questa visita.
-
visitTime
numero facoltativo
Data e ora della visita, espressa in millisecondi dall'epoca.
Metodi
addUrl()
chrome.history.addUrl(
details: UrlDetails,
callback?: function,
)
Aggiunge un URL alla cronologia nel momento attuale con un tipo di transizione di "link".
Parametri
-
dettagli
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
Promise<void>
Chrome 96 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
deleteAll()
chrome.history.deleteAll(
callback?: function,
)
Elimina tutti gli elementi dalla cronologia.
Parametri
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
Promise<void>
Chrome 96 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
deleteRange()
chrome.history.deleteRange(
range: object,
callback?: function,
)
Rimuove dalla cronologia tutti gli elementi all'interno dell'intervallo di date specificato. Le pagine non verranno rimosse dalla cronologia a meno che tutte le visite non rientrino nell'intervallo.
Parametri
-
gamma
oggetto
-
endTime
numero
Elementi aggiunti alla cronologia prima di questa data, rappresentati in millisecondi dall'epoca.
-
startTime
numero
Elementi aggiunti alla cronologia dopo questa data, rappresentati in millisecondi dall'epoca.
-
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
Promise<void>
Chrome 96 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
deleteUrl()
chrome.history.deleteUrl(
details: UrlDetails,
callback?: function,
)
Rimuove dalla cronologia tutte le occorrenze dell'URL specificato.
Parametri
-
dettagli
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
Promise<void>
Chrome 96 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
getVisits()
chrome.history.getVisits(
details: UrlDetails,
callback?: function,
)
Recupera le informazioni sulle visite a un URL.
Parametri
-
dettagli
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(results: VisitItem[]) => void
-
risultati
-
Ritorni
-
Promise<VisitItem[]>
Chrome 96 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
search()
chrome.history.search(
query: object,
callback?: function,
)
Cerca nella cronologia l'ora dell'ultima visita di ogni pagina corrispondente alla query.
Parametri
-
query
oggetto
-
endTime
numero facoltativo
Limita i risultati a quelli visitati prima di questa data, espressa in millisecondi dall'epoca.
-
maxResults
numero facoltativo
Il numero massimo di risultati da recuperare. Il valore predefinito è 100.
-
startTime
numero facoltativo
Limita i risultati a quelli visitati dopo questa data, espressa in millisecondi dall'epoca. Se la proprietà non è specificata, il valore predefinito sarà di 24 ore.
-
testo
stringa
Una query di testo libero al servizio di cronologia. Lascia vuoto questo campo per recuperare tutte le pagine.
-
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(results: HistoryItem[]) => void
-
risultati
-
Ritorni
-
Promise<HistoryItem[]>
Chrome 96 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
Eventi
onVisited
chrome.history.onVisited.addListener(
callback: function,
)
Si attiva quando un URL viene visitato, fornendo i dati HistoryItem
per quell'URL. Questo evento si attiva prima del caricamento della pagina.
Parametri
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:(result: HistoryItem) => void
-
risultato
-
onVisitRemoved
chrome.history.onVisitRemoved.addListener(
callback: function,
)
Attivato quando uno o più URL vengono rimossi dalla cronologia. Quando tutte le visite sono state rimosse, l'URL viene eliminato definitivamente dalla cronologia.
Parametri
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:(removed: object) => void
-
rimosso
oggetto
-
allHistory
boolean
True se è stata rimossa tutta la cronologia. Se il valore è true, gli URL saranno vuoti.
-
urls
string[] facoltativo
-
-