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.
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
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 recenteVerdadeiro 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
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()
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
-
callback
função optional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 96 ou mais recentePromessas 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()
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 recentePromessas 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()
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 recentePromessas 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()
chrome.history.deleteUrl(
details: UrlDetails,
callback?: function,
)
Remove todas as ocorrências do URL fornecido do histórico.
Parâmetros
-
detalhes
-
callback
função optional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 96 ou mais recentePromessas 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()
chrome.history.getVisits(
details: UrlDetails,
callback?: function,
)
Recupera informações sobre visitas a um URL.
Parâmetros
-
detalhes
-
callback
função optional
O parâmetro
callback
tem esta aparência:(results: VisitItem[]) => void
-
resultados
-
Retorna
-
Promise<VisitItem[]>
Chrome 96 ou mais recentePromessas 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.
search()
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
-
resultados
-
Retorna
-
Promise<HistoryItem[]>
Chrome 96 ou mais recentePromessas 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
-
resultado
-
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
-
-