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 eseguire l'override della pagina della cronologia con la tua versione, consulta Override delle pagine.

Autorizzazioni

history

Manifest

Devi dichiarare la "cronologia" nel manifest dell'estensione per usare l'API History. Ad esempio:

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

Tipi di transizione

L'API History utilizza un tipo di transizione per descrivere in che modo il browser ha raggiunto un determinato URL. durante 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 trovato questa pagina digitando l'URL nella barra degli indirizzi. Utilizzato anche per altre azioni di navigazione esplicite. Vedi anche generato, che viene utilizzato nei casi in cui l'utente ha selezionato una scelta che non sembrava affatto come 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 contenuti che vengono caricati automaticamente in un frame non di primo livello. Ad esempio, se una pagina è composta da più frame che contengono annunci, gli URL degli annunci presentano questo tipo di transizione. L'utente potrebbe persino non rendersi conto che i contenuti in queste pagine sono un frame separato e quindi potrebbe non essere interessato all'URL (vedi anche manual_subframe).
"manual_subframe" (frame secondario manuale)Per le navigazioni del frame secondario richieste esplicitamente dall'utente e che generano nuove voci di navigazione nell'elenco back-forward. Un frame richiesto esplicitamente è probabilmente più importante di un frame caricato automaticamente perché l'utente probabilmente è interessato al 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 assomigliava a un URL. Ad esempio, una corrispondenza potrebbe avere l'URL di una pagina dei risultati di ricerca di Google, ma l'utente potrebbe essere visualizzata come "Cerca su Google ...". Non sono come le navigazioni 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 uno script per inviare i contenuti, l'invio di un modulo non comporta questo tipo di transizione.
"ricarica"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 scheda Riapri 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.
"generato_parola chiave"Corrisponde a una visita generata per una parola chiave. Vedi anche parola chiave.

Esempi

Per provare questa API, installa l'esempio dell'API della cronologia da chrome-extension-samples repository Git.

Tipi

HistoryItem

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

Proprietà

  • id

    stringa

    L'identificatore univoco dell'articolo.

  • lastVisitTime

    numero facoltativo

    Data dell'ultimo caricamento della pagina, espressa in millisecondi dall'epoca.

  • titolo

    stringa facoltativo

    Il titolo della pagina quando è stata caricata l'ultima volta.

  • 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 ha raggiunto questa pagina.

TransitionType

Chrome 44 e versioni successive .

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 tramite la navigazione nel frame secondario che non ha richiesto, ad esempio tramite il caricamento di un annuncio in un frame nella pagina precedente. In questi casi non sempre generano nuove voci di navigazione nei menu Avanti e Indietro.

"manual_subframe"
L'utente è arrivato a 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 assomigliava a 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 all'utente potrebbe essere visualizzata come "Cerca su Google ...". Sono diverse dalle navigazioni digitate perché l'utente non ha digitato o visualizzato l'URL di destinazione. Sono correlati anche alla navigazione tra 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 scheda Riapri scheda chiusa usano questo tipo di transizione.

"keyword"
L'URL di questa pagina è stato generato da una parola chiave sostituibile diversa dal provider di ricerca predefinito.

"keyword_generate"
Corrisponde a una visita generata per una parola chiave.

UrlDetails

Chrome 88 e versioni successive .

Proprietà

  • url

    stringa

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

VisitItem

Un oggetto che include una visita a un URL.

Proprietà

  • id

    stringa

    L'identificatore univoco della history.HistoryItem corrispondente.

  • isLocal

    booleano

    Chrome 115 e versioni successive .

    True se la visita ha avuto origine su questo dispositivo. Falso se la sincronizzazione è stata eseguita da un altro dispositivo.

  • referringVisitId

    stringa

    L'ID visita del referrer.

  • transizione

    TransitionType

    Il tipo di transizione per questa visita dal relativo referrer.

  • visitId

    stringa

    L'identificatore univoco della visita in questione.

  • visitTime

    numero facoltativo

    Data e ora di questa visita, espresse in millisecondi a partire dall'epoca.

Metodi

addUrl()

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

Aggiunge un URL alla cronologia al momento attuale con il tipo di transizione "link".

Parametri

  • dettagli

    UrlDetails

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Chrome 96 e versioni successive .

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

deleteAll()

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

Elimina tutte le voci dalla cronologia.

Parametri

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Chrome 96 e versioni successive .

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

deleteRange()

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

Rimuove dalla cronologia tutte le voci comprese 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, rappresentati in millisecondi a partire dall'epoca.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Chrome 96 e versioni successive .

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

deleteUrl()

Promesso .
chrome.history.deleteUrl(
  details: UrlDetails,
  callback?: function,
)

Rimuove dalla cronologia tutte le occorrenze dell'URL specificato.

Parametri

  • dettagli

    UrlDetails

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Chrome 96 e versioni successive .

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

getVisits()

Promesso .
chrome.history.getVisits(
  details: UrlDetails,
  callback?: function,
)

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&lt;VisitItem[]&gt;

    Chrome 96 e versioni successive .

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

Promesso .
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 alle visite prima di questa data, rappresentate in millisecondi dall'epoca.

    • maxResults

      numero facoltativo

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

    • startTime

      numero facoltativo

      Limita i risultati alle visite dopo questa data, rappresentate in millisecondi dall'epoca. Se la proprietà non è specificata, il valore predefinito sarà 24 ore.

    • testo

      stringa

      Una query in 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

Resi

  • Promise&lt;HistoryItem[]&gt;

    Chrome 96 e versioni successive .

    Le promesse sono supportate solo per Manifest V3 e versioni successive, mentre 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 l'URL. Questo evento viene attivato prima del caricamento della pagina.

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. 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

        booleano

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

      • Url

        string[] facoltativo