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

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

Para usar a API History, declare a permissão "history" no manifesto da extensão. Por exemplo:

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

Conceitos e uso

Tipos de transição

A API History usa tipos de transição para descrever como o navegador acessou um URL específico em uma visita específica. Por exemplo, se um usuário acessa uma página clicando em um link em outra página, o tipo de transição é "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 History do repositório chrome-extension-samples.

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 optional

    Quando esta página foi carregada pela última vez, representada em milissegundos desde a época.

  • título

    string opcional

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

  • typedCount

    número optional

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

  • url

    string opcional

    O URL acessado por um usuário.

  • visitCount

    número optional

    O número de vezes que o usuário acessou essa página.

TransitionType

Chrome 44+ browser.* desde o Chrome 148

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

Enumeração

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

"typed"
O usuário acessou a 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 uma sugestão na interface, por exemplo, um item de menu.

"auto_subframe"
O usuário chegou a essa página por uma navegação de subframe que não solicitou, como um carregamento de anúncios em um frame na página anterior. Nem sempre eles geram novas entradas de navegação nos menus de voltar e avançar.

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

"generated"
O usuário chegou a essa página digitando na barra de endereço 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 do Google, mas aparecer para o usuário como "Pesquisar no Google por…". 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 à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 essa página preenchendo e enviando um formulário. Nem todos os envios de formulário usam esse tipo de transição.

"reload"
O usuário atualizou a página, seja 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.

"keyword"
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+ browser.* desde o Chrome 148

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+ browser.* desde o Chrome 148

    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 optional

    Quando essa visita ocorreu, representada em milissegundos desde a época.

Métodos

addUrl()

browser.history.addUrl(
  details: UrlDetails,
): Promise<void>

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

Parâmetros

Retorna

  • Promessa<void>

    Chrome 96+ browser.* desde o Chrome 148

deleteAll()

browser.history.deleteAll(): Promise<void>

Exclui todos os itens do histórico.

Retorna

  • Promessa<void>

    Chrome 96+ browser.* desde o Chrome 148

deleteRange()

browser.history.deleteRange(
  range: object,
): Promise<void>

Remove do histórico todos os itens dentro do 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 a época.

    • startTime

      número

      Itens adicionados ao histórico após essa data, representados em milissegundos desde a época.

Retorna

  • Promessa<void>

    Chrome 96+ browser.* desde o Chrome 148

deleteUrl()

browser.history.deleteUrl(
  details: UrlDetails,
): Promise<void>

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

Parâmetros

Retorna

  • Promessa<void>

    Chrome 96+ browser.* desde o Chrome 148

getVisits()

browser.history.getVisits(
  details: UrlDetails,
): Promise<VisitItem[]>

Recupera informações sobre visitas a um URL.

Parâmetros

Retorna

  • Promise<VisitItem[]>

    Chrome 96+ browser.* desde o Chrome 148 
browser.history.search(
  query: object,
): Promise<HistoryItem[]>

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

Parâmetros

  • consulta

    objeto

    • endTime

      número optional

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

    • maxResults

      número optional

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

    • startTime

      número optional

      Limita os resultados aos visitados após essa data, representada em milissegundos desde o início. 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.

Retorna

  • Promise<HistoryItem[]>

    Chrome 96+ browser.* desde o Chrome 148

Eventos

onVisited

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

Acionado quando um URL é visitado, fornecendo os dados HistoryItem para esse URL. Este evento é acionado antes de a página ser carregada.

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a: 

    (result: HistoryItem) => void

onVisitRemoved

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

Disparado 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 é semelhante a: 

    (removed: object) => void

    • removido

      objeto

      • allHistory

        booleano

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

      • urls

        string[] opcional