chrome.history

Descrição

Use a API chrome.history para interagir com o registro de páginas visitadas do navegador. É possível adicionar, remover e consultar URLs no histórico do navegador. Para substituir a página de histórico pela sua própria versão, consulte Substituir páginas.

Permissões

history

Manifesto

Você precisa declarar a permissão "history" no manifesto da extensão para usar a API History. Por exemplo:

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

Tipos de transição

A API History usa um tipo 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 clicar em um link em outra página para acessar uma página, o tipo de transição será "link".

A tabela a seguir descreve cada tipo de transição.

Tipo de transiçãoDescrição
"typed"O usuário acessou esta página digitando o URL na barra de endereço. Também usado para outras ações de navegação explícitas. Consulte também generated, que é usado em casos em que o usuário selecionou uma opção que não parecia um URL.
"auto_bookmark"O usuário chegou a esta página por uma sugestão na interface, por exemplo, um item de menu.
"auto_subframe"Navegação por subframe. É qualquer conteúdo carregado automaticamente em um frame que não seja de nível superior. Por exemplo, se uma página consistir em vários frames com anúncios, os URLs desses anúncios terão esse tipo de transição. O usuário pode nem perceber que o conteúdo dessas páginas é um frame separado e, portanto, não se importar com o URL (consulte também manual_subframe).
"manual_subframe"Para navegações de subframes explicitamente solicitadas pelo usuário e que geram novas entradas de navegação na lista de voltar/avançar. Um frame solicitado explicitamente provavelmente é mais importante do que um carregado automaticamente, porque o usuário provavelmente se importa com o fato de o frame solicitado ter sido carregado.
"gerado"O usuário chegou a esta página digitando na barra de endereço e selecionando uma entrada que não parecia um URL. Por exemplo, uma correspondência pode ter o URL de uma página de resultados da pesquisa do Google, mas aparecer para o usuário como "Pesquisar no Google por ...". Essas navegações não são exatamente iguais às digitadas porque o usuário não digitou nem viu o URL de destino. Consulte também palavra-chave.
"auto_toplevel"A página foi especificada na linha de comando ou é a página inicial.
"form_submit"O usuário preencheu e enviou um formulário. Em algumas situações, como quando um formulário usa script para enviar conteúdo, o envio não resulta nesse tipo de transição.
"recarregar"O usuário atualizou a página clicando no botão de atualização ou pressionando "Enter" na barra de endereço. A restauração de sessão e a reabertura de guias fechadas também usam esse tipo de transição.
"palavra-chave"O URL foi gerado com uma palavra-chave substituível diferente do provedor de pesquisa padrão. Consulte também keyword_generated.
"keyword_generated"Corresponde a uma visita gerada para uma palavra-chave. Consulte também palavra-chave.

Exemplos

Para testar essa API, instale o exemplo da API History no repositório chrome-extension-samples (link em inglês).

Tipos

HistoryItem

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

Propriedades

  • ID

    string

    O identificador exclusivo do item.

  • lastVisitTime

    number optional

    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

    number optional

    O número de vezes que o usuário acessou esta página digitando o endereço.

  • url

    string opcional

    O URL acessado por um usuário.

  • visitCount

    number optional

    O número de vezes que o usuário navegou até essa página.

TransitionType

Chrome 44 ou mais recente

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

Enumeração

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

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

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

"auto_subframe"
O usuário chegou a esta página por uma navegação de subframe que não foi solicitada, como um anúncio carregado em um frame na página anterior. Elas nem sempre geram novas entradas de navegação nos menus "Voltar" e "Avançar".

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

"gerado"
O usuário chegou a esta página digitando na barra de endereços e selecionando uma entrada que não parecia 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 aparecer para o usuário como "Pesquisar no Google por ...". Isso é diferente das navegações digitadas porque o usuário não digitou nem viu o URL de destino. Elas também estão relacionadas a 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. Nem todos os envios de formulário usam esse tipo de transição.

"reload"
O usuário atualizou a página clicando no botão de atualização ou pressionando "Enter" na barra de endereço. A restauração de sessão e a reabertura de guias fechadas também usam esse tipo de transição.

palavra-chave
O URL desta página foi gerado com base em 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

    booleano

    Chrome 115+

    Verdadeiro se a visita tiver sido originada neste dispositivo. Falso se ele foi sincronizado de um dispositivo diferente.

  • referringVisitId

    string

    O ID da visita do referenciador.

  • transição

    TransitionType

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

  • visitId

    string

    O identificador exclusivo desta visita.

  • visitTime

    number optional

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

Métodos

addUrl()

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

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

Parâmetros

  • detalhes

    UrlDetails

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promise<void>

    Chrome 96+

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

deleteAll()

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

Exclui todos os itens do histórico.

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promise<void>

    Chrome 96+

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

deleteRange()

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

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

Parâmetros

  • período

    objeto

    • endTime

      número

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

    • startTime

      número

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

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promise<void>

    Chrome 96+

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

deleteUrl()

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

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

Parâmetros

  • detalhes

    UrlDetails

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promise<void>

    Chrome 96+

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getVisits()

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

Recupera informações sobre visitas a um URL.

Parâmetros

  • detalhes

    UrlDetails

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (results: VisitItem[]) => void

Retorna

  • Promise<VisitItem[]>

    Chrome 96+

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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

Pesquisa no histórico a última visita de cada página que corresponde à consulta.

Parâmetros

  • consulta

    objeto

    • endTime

      number optional

      Limita os resultados aos visitados antes dessa data, representada em milissegundos desde o período.

    • maxResults

      number optional

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

    • startTime

      number optional

      Limita os resultados aos visitados após essa data, representada em milissegundos desde o período. Se a propriedade não for especificada, o padrão será 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 opcional

    O parâmetro callback tem esta aparência: 

    (results: HistoryItem[]) => void

Retorna

  • Promise<HistoryItem[]>

    Chrome 96+

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

Eventos

onVisited

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

Disparado quando um URL é visitado, fornecendo os dados HistoryItem desse URL. Esse evento é disparado antes do carregamento da página.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (result: HistoryItem) => void

onVisitRemoved

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

Acionado quando um ou mais URLs são removidos do histórico. Quando todas as visitas são removidas, o URL é excluído do histórico.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (removed: object) => void

    • removido

      objeto

      • allHistory

        booleano

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

      • urls

        string[] opcional