chrome.history

Descrizione

Utilizza l'API chrome.history per interagire con il record delle pagine visitate del browser. Puoi aggiungere, rimuovere ed eseguire query per gli URL nella cronologia del browser. Per sostituire la pagina della cronologia con la tua versione, vedi Override delle pagine.

Autorizzazioni

history

Manifest

Per utilizzare l'API History, devi dichiarare l'autorizzazione "history" nel manifest dell'estensione. Ad esempio:

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

Tipi di transizione

L'API History utilizza un tipo 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".

La tabella seguente descrive ogni tipo di transizione.

Tipo di transizioneDescrizione
"typed"L'utente ha visualizzato questa pagina digitando l'URL nella barra degli indirizzi. Utilizzato anche per altre azioni di navigazione esplicite. Vedi anche generato, utilizzato per i casi in cui l'utente ha selezionato una scelta che non assomigliava affatto a un URL.
"auto_bookmark"L'utente è arrivato a questa pagina tramite un suggerimento nell'interfaccia utente, ad esempio tramite una voce di menu.
"auto_subframe"Navigazione nel frame secondario. Si tratta di qualsiasi contenuto caricato automaticamente in un frame non di primo livello. Ad esempio, se una pagina è costituita da diversi frame contenenti annunci, questi URL annuncio hanno questo tipo di transizione. L'utente potrebbe non rendersi conto che i contenuti di queste pagine sono un frame separato e quindi non interessarsi all'URL (vedi anche manual_subframe).
"manual_subframe"Per le navigazioni nei frame secondari richieste esplicitamente dall'utente e che generano nuove voci di navigazione nell'elenco Indietro/Avanti. Un frame richiesto esplicitamente è probabilmente più importante di un frame caricato automaticamente perché l'utente si preoccupa del fatto che il frame richiesto sia stato caricato.
"generato"L'utente è arrivato a questa pagina digitando nella barra degli indirizzi e selezionando una voce che non sembrava un URL. Ad esempio, una corrispondenza potrebbe avere l'URL di una pagina dei risultati di ricerca di Google, ma potrebbe essere visualizzata dall'utente come "Cerca su Google…". Queste navigazioni non sono esattamente uguali a quelle digitate perché l'utente non ha digitato o visualizzato l'URL di destinazione. Vedi anche parola chiave.
"auto_toplevel"La pagina è stata specificata nella riga di comando o è la pagina iniziale.
"form_submit"L'utente ha compilato i valori in un modulo e lo ha inviato. Tieni presente che in alcune situazioni, ad esempio quando un modulo utilizza script per inviare contenuti, l'invio di un modulo non comporta questo tipo di transizione.
"reload"L'utente ha ricaricato la pagina facendo clic sul pulsante di ricarica o premendo Invio nella barra degli indirizzi. Anche il ripristino della sessione e la riapertura della scheda chiusa utilizzano questo tipo di transizione.
"parola chiave"L'URL è stato generato da una parola chiave sostituibile diversa dal provider di ricerca predefinito. Vedi anche keyword_generated.
"keyword_generated"Corrisponde a una visita generata per una parola chiave. Vedi anche parola chiave.

Esempi

Per provare questa API, installa l'esempio di API History dal repository chrome-extension-samples.

Tipi

HistoryItem

Un oggetto che incapsula un risultato di una query della cronologia.

Proprietà

  • id

    stringa

    L'identificatore univoco dell'elemento.

  • lastVisitTime

    number (facoltativo)

    L'ultima volta che è stata caricata questa pagina, rappresentata in millisecondi dall'epoca.

  • titolo

    stringa facoltativa

    Il titolo della pagina all'ultimo caricamento.

  • typedCount

    number (facoltativo)

    Il numero di volte in cui l'utente ha raggiunto questa pagina digitando l'indirizzo.

  • url

    stringa facoltativa

    L'URL a cui ha eseguito l'accesso un utente.

  • visitCount

    number (facoltativo)

    Il numero di volte in cui l'utente ha visitato questa pagina.

TransitionType

Chrome 44+

Il tipo di transizione per questa visita dal referrer.

Enum

"link"
L'utente è arrivato a questa pagina facendo clic su un link in un'altra pagina.

"digitato"
L'utente è arrivato a questa pagina digitando l'URL nella barra degli indirizzi. Viene utilizzato anche per altre azioni di navigazione esplicita.

"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 tramite la navigazione nel subframe che non ha richiesto, ad esempio tramite un annuncio caricato in un frame nella pagina precedente. Questi non generano sempre nuove voci di navigazione nei menu Indietro e Avanti.

"manual_subframe"
L'utente è arrivato a questa pagina selezionando un elemento in un iframe.

"generato"
L'utente è arrivato a questa pagina digitando nella barra degli indirizzi e selezionando una voce che non sembrava un URL, ad esempio un suggerimento della Ricerca Google. Ad esempio, una corrispondenza potrebbe avere l'URL di una pagina dei risultati della Ricerca Google, ma potrebbe essere visualizzata dall'utente come "Cerca su Google…". Queste corrispondenze sono diverse dalle navigazioni digitate perché l'utente non ha digitato o visualizzato l'URL di destinazione. Sono anche correlate alle 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 di ricarica o premendo Invio nella barra degli indirizzi. Anche il ripristino della sessione e la riapertura della scheda chiusa utilizzano questo tipo di transizione.

"parola chiave"
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

Chrome 88+

Proprietà

  • url

    stringa

    L'URL dell'operazione. Deve essere nel formato restituito da una chiamata a history.search().

VisitItem

Un oggetto che incapsula una visita a un URL.

Proprietà

  • id

    stringa

    L'identificatore univoco del history.HistoryItem corrispondente.

  • isLocal

    booleano

    Chrome 115+

    True se la visita ha avuto origine su questo dispositivo. False se è stata sincronizzata da un altro dispositivo.

  • referringVisitId

    stringa

    L'ID visita del referrer.

  • transizione

    TransitionType

    Il tipo di transizione per questa visita dal referrer.

  • visitId

    stringa

    L'identificatore univoco di questa visita.

  • visitTime

    number (facoltativo)

    Data e ora in cui si è verificata la visita, espresse in millisecondi dall'epoca.

Metodi

addUrl()

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

Aggiunge un URL alla cronologia all'ora corrente con un tipo di transizione "link".

Parametri

  • dettagli

    UrlDetails

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 96+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, le altre piattaforme devono utilizzare i callback.

deleteAll()

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

Elimina tutti gli elementi dalla cronologia.

Parametri

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 96+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, le altre piattaforme devono utilizzare i callback.

deleteRange()

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

Rimuove tutti gli elementi della cronologia nell'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, rappresentata in millisecondi dall'epoca.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 96+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, le altre piattaforme devono utilizzare i callback.

deleteUrl()

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

Rimuove tutte le occorrenze dell'URL specificato dalla cronologia.

Parametri

  • dettagli

    UrlDetails

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 96+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, le altre piattaforme devono utilizzare i callback.

getVisits()

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

Recupera le informazioni sulle visite a un URL.

Parametri

  • dettagli

    UrlDetails

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (results: VisitItem[]) => void

Resi

  • Promise<VisitItem[]>

    Chrome 96+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, le altre piattaforme devono utilizzare i callback.

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

Cerca nella cronologia l'ora dell'ultima visita di ogni pagina corrispondente alla query.

Parametri

  • query

    oggetto

    • endTime

      number (facoltativo)

      Limita i risultati a quelli visitati prima di questa data, rappresentata in millisecondi dall'epoca.

    • maxResults

      number (facoltativo)

      Il numero massimo di risultati da recuperare. Il valore predefinito è 100.

    • startTime

      number (facoltativo)

      Limita i risultati a quelli visitati dopo questa data, rappresentata in millisecondi trascorsi da epoca. Se la proprietà non è specificata, il valore predefinito è 24 ore.

    • testo

      stringa

      Una query di testo libero al servizio di cronologia. Lascia questo campo vuoto per recuperare tutte le pagine.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (results: HistoryItem[]) => void

Resi

  • Promise<HistoryItem[]>

    Chrome 96+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, le altre piattaforme devono utilizzare i callback.

Eventi

onVisited

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

Attivato quando viene visitato un URL, fornendo i dati HistoryItem per quell'URL. Questo evento viene attivato prima che la pagina venga caricata.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (result: HistoryItem) => void

onVisitRemoved

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

Attivato quando uno o più URL vengono rimossi dalla cronologia. Una volta rimosse tutte le visite, l'URL viene eliminato dalla cronologia.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (removed: object) => void

    • rimosso

      oggetto

      • allHistory

        booleano

        Vero se tutta la cronologia è stata rimossa. Se true, gli URL saranno vuoti.

      • Url

        string[] facoltativo