chrome.history

Descrição

Use a API chrome.history para interagir com o registro de páginas visitadas do navegador. Você pode adicionar, remover e consultar URLs no histórico do navegador. Para substituir a página do histórico por uma versão própria, consulte Substituir páginas.

Permissões

history

Para interagir com o histórico de navegação do usuário, use a API de histórico.

Para usar a API History, declare a permissão "history" no manifesto de extensões. Exemplo:

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

Conceitos e uso

Tipos de transição

A API de histórico usa tipos de transição para descrever como o navegador navegou até um URL específico em uma visita específica. Por exemplo, se um usuário visitar uma página clicando em um link em outra página, o tipo de transição será "link". Consulte o conteúdo de referência para ver uma lista de tipos de transição.

Exemplos

Para testar essa API, instale o exemplo da API de histórico no repositório chrome-extension-samples.

Tipos

HistoryItem

Um objeto que encapsula um resultado de uma consulta de histórico.

Propriedades

  • id

    string

    Identificador exclusivo do item.

  • lastVisitTime

    número opcional

    Quando esta página foi carregada pela última vez, representada em milissegundos desde o período.

  • título

    string opcional

    O título da página quando ela foi carregada pela última vez.

  • typedCount

    número opcional

    O número de vezes que o usuário navegou para essa página digitando o endereço.

  • url

    string opcional

    O URL que um usuário acessou.

  • visitCount

    número opcional

    O número de vezes que o usuário navegou para a página.

TransitionType

Chrome 44 ou mais recente

O tipo de transição dessa visita do referenciador.

Tipo enumerado

"link"
O usuário chegou a esta página clicando em um link em outra página.

"typed"
O usuário chegou a esta página digitando o URL na barra de endereço. Ele também é usado para outras ações de navegação explícitas.

"auto_bookmark"
O usuário acessou esta página por uma sugestão na interface, por exemplo, por um item de menu.

"auto_subframe"
O usuário chegou a essa página por uma navegação de subframes que não foi solicitada, por exemplo, pelo carregamento de um anúncio em um frame na página anterior. Eles nem sempre geram novas entradas de navegação nos menus de avanço e retorno.

"manual_subframe"
O usuário chegou a esta página selecionando algo em um subframe.

"gerado"
O usuário chegou a esta página digitando na barra de endereço e selecionando uma entrada que não parece ser um URL, como uma sugestão da Pesquisa Google. Por exemplo, uma correspondência pode ter o URL de uma página de resultados da Pesquisa Google, mas pode aparecer para o usuário como "Pesquisar no Google ...". Elas são diferentes das navegações digitadas porque o usuário não digitou nem viu o URL de destino. Elas também estão relacionadas às navegações por palavras-chave.

"auto_toplevel"
A página foi especificada na linha de comando ou é a página inicial.

"form_submit"
O usuário chegou a esta página preenchendo os valores em um formulário e enviando o formulário. Nem todos os envios de formulário usam esse tipo de transição.

"recarregar"
O usuário recarregou a página, clicando no botão "Atualizar" ou pressionando Enter na barra de endereço. A restauração de sessão e a guia "Reabrir fechada" também usam esse tipo de transição.

"palavra-chave"
O URL dessa página foi gerado a partir de uma palavra-chave substituível que não é o provedor de pesquisa padrão.

"keyword_generated"
Corresponde a uma visita gerada para uma palavra-chave.

UrlDetails

Chrome 88 ou mais recente

Propriedades

  • url

    string

    O URL da operação. Ele precisa estar no formato retornado de uma chamada para history.search().

VisitItem

Um objeto que encapsula uma visita a um URL.

Propriedades

  • id

    string

    O identificador exclusivo do history.HistoryItem correspondente.

  • isLocal

    boolean

    Chrome 115 ou mais recente

    Verdadeiro se a visita tiver sido originada neste dispositivo. Falso se tiver sido sincronizada de um dispositivo diferente.

  • referringVisitId

    string

    O ID de visita do referenciador.

  • transition

    TransitionType

    O tipo de transição dessa visita do referenciador.

  • visitId

    string

    O identificador exclusivo desta visita.

  • visitTime

    número opcional

    Quando essa visita ocorreu, representada em milissegundos desde o período.

Métodos

addUrl()

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

Adiciona um URL ao histórico no momento atual com um tipo de transição de "link".

Parâmetros

  • detalhes

    UrlDetails

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 96 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

deleteAll()

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

Exclui todos os itens do histórico.

Parâmetros

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 96 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

deleteRange()

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

Remove todos os itens dentro do período especificado do histórico. As páginas não serão removidas do histórico, a menos que todas as visitas estejam dentro do intervalo.

Parâmetros

  • período

    objeto

    • endTime

      number

      Itens adicionados ao histórico antes dessa data, representados em milissegundos desde o período.

    • startTime

      number

      Itens adicionados ao histórico após essa data, representados em milissegundos desde o período.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 96 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

deleteUrl()

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

Remove todas as ocorrências do URL fornecido do histórico.

Parâmetros

  • detalhes

    UrlDetails

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 96 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

getVisits()

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

Recupera informações sobre visitas a um URL.

Parâmetros

  • detalhes

    UrlDetails

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (results: VisitItem[])=>void

Retorna

  • Promise<VisitItem[]>

    Chrome 96 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

Promessa 
chrome.history.search(
  query: object,
  callback?: function,
)

Pesquisa no histórico o horário da última visita de cada página que corresponde à consulta.

Parâmetros

  • consulta

    objeto

    • endTime

      número opcional

      Limitar os resultados àqueles visitados antes dessa data, representados em milissegundos desde o período.

    • maxResults

      número opcional

      O número máximo de resultados a serem recuperados. O padrão é 100.

    • startTime

      número opcional

      Limitar os resultados àqueles visitados depois dessa data, representados em milissegundos desde o período. Se a propriedade não for especificada, o padrão será de 24 horas.

    • texto

      string

      Uma consulta de texto livre para o serviço de histórico. Deixe em branco para recuperar todas as páginas.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (results: HistoryItem[])=>void

Retorna

  • Promise<HistoryItem[]>

    Chrome 96 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

Eventos

onVisited

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

Disparado quando um URL é visitado, fornecendo os dados de HistoryItem para esse URL. Este evento é disparado antes que a página seja carregada.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (result: HistoryItem)=>void

onVisitRemoved

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

Disparado quando um ou mais URLs são removidos do histórico. Quando todas as visitas forem removidas, o URL será excluído do histórico.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (removed: object)=>void

    • removido

      objeto

      • allHistory

        boolean

        Verdadeiro se todo o histórico foi removido. Se verdadeiro, os URLs ficarão vazios.

      • urls

        string[] opcional