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 do histórico pela sua própria versão, consulte Substituir páginas.

Permissões

history

Essa permissão aciona um aviso.

Manifesto

É necessário declarar o "histórico" permissão no manifesto de 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 chegou a um URL específico. em um determinado acesso. Por exemplo, se um usuário visita uma página clicando em um link em outra página, o o tipo de transição é "link".

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

Tipo de transição	Descrição
"link"	O usuário chegou a esta página clicando em um link em outra página.
"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 gerado, que é usado para casos em que o usuário selecionou uma opção que não se parece com um URL.
"auto_bookmark"	O usuário chegou a essa página por uma sugestão na interface, por exemplo, por um item de menu.
"auto_subframe"	Navegação de subframes. Qualquer conteúdo carregado automaticamente em um frame que não seja de nível superior. Por exemplo, se uma página consiste em vários frames que contêm anúncios, os URLs desses anúncios têm esse tipo de transição. O usuário pode nem perceber que o conteúdo dessas páginas é um frame separado e, portanto, pode não se importar com o URL (veja também manual_subframe).
"manual_subframe"	Para navegações de subframes que são explicitamente solicitadas pelo usuário e geram novas entradas de navegação na lista de avanço e retorno. Provavelmente, um frame solicitado explicitamente é mais importante do que um carregado automaticamente porque o usuário provavelmente se preocupa com o fato de que o frame solicitado foi carregado.
"gerado"	O usuário chegou a essa 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 de pesquisa do Google, mas pode aparecer para o usuário como "Pesquisar no Google ...". Elas não são exatamente iguais às navegações 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.
"formulário_enviar"	O usuário preencheu os valores de um formulário e o enviou. Observe que em algumas situações, como quando um formulário usa um script para enviar conteúdo, o envio de um formulário não resulta nesse 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 opção Reabrir guia fechada também usam esse tipo de transição.
"palavra-chave"	O URL foi gerado a partir de uma palavra-chave substituível, diferente do provedor de pesquisa padrão. Veja também keyword_generated.
"palavra-chave_gerada"	Corresponde a uma visita gerada para uma palavra-chave. Consulte também palavra-chave.

Exemplos

Para testar essa API, instale o exemplo de API de histórico disponível em chrome-extension-samples repositório de dados.

Tipos

HistoryItem

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

Propriedades

• id

  string

  O identificador exclusivo do item.

• lastVisitTime

  número opcional

  Quando a 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 foi carregada pela última vez.

• typedCount

  número opcional

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

• url

  string opcional

  O URL acessado pelo usuário.

• visitCount

  número opcional

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

TransitionType

Chrome 44 ou superior

O tipo de transição para essa visita do referenciador.

Enumeração

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

"typed"
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 essa página por meio de uma sugestão na interface do usuário, por exemplo, por um item de menu.

"auto_subframe"
O usuário chegou a esta página pela navegação de subframes que ele não solicitou, como pelo carregamento de um anúncio em um frame na página anterior. Elas nem sempre geram novas entradas de navegação nos menus de voltar e avançar.

"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 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. Eles também estão relacionados à navegação 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 de 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 opção Reabrir guia 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, diferente do provedor de pesquisa padrão.

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

UrlDetails

Chrome 88 ou superior

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 ou versões mais recentes

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

• referringVisitId

  string

  O ID da visita do referenciador.

• transição

  TransitionType

  O tipo de transição para essa visita do referenciador.

• visitId

  string

  O identificador exclusivo da visita.

• visitTime

  número opcional

  Quando essa visita ocorreu, representado 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 opcional

  O parâmetro callback tem esta aparência:

  () => void

Retorna

• Promessa<void>

  Chrome 96 ou versão mais recente

  As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

deleteAll()

Promessa

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

Exclui todos os itens do histórico.

Parâmetros

• callback

  função opcional

  O parâmetro callback tem esta aparência:

  () => void

Retorna

• Promessa<void>

  Chrome 96 ou versão mais recente

  As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

deleteRange()

Promessa

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

Remove todos os itens no 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 epoch.

• callback

  função opcional

  O parâmetro callback tem esta aparência:

  () => void

Retorna

• Promessa<void>

  Chrome 96 ou versão mais recente

  As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

deleteUrl()

Promessa

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

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

• Promessa<void>

  Chrome 96 ou versão mais recente

  As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getVisits()

Promessa

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

Recupera informações sobre as visitas a um URL.

Parâmetros

• detalhes

  UrlDetails

• callback

  função opcional

  O parâmetro callback tem esta aparência:

  (results: VisitItem[]) => void

  • resultados

    VisitItem[]

Retorna

• Promise&lt;VisitItem[]&gt;

  Chrome 96 ou versão mais recente

  As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

search()

Promessa

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

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

Parâmetros

• consulta

  objeto

  • endTime

    número opcional

    Limite 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

    Limite os resultados àqueles visitados após essa data, representados 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

  • resultados

    HistoryItem[]

Retorna

• Promise&lt;HistoryItem[]&gt;

  Chrome 96 ou versão mais recente

  As promessas só têm suporte no Manifesto 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 de HistoryItem para esse URL. Este evento é disparado antes do carregamento da página.

Parâmetros

• callback

  função

  O parâmetro callback tem esta aparência:

  (result: HistoryItem) => void

  • resultado

    HistoryItem

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

  • removida

    objeto

    • allHistory

      booleano

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

    • urls

      string[] opcional