O objeto DOM window fornece acesso ao histórico do navegador através do objeto history. Ele expõe métodos e propriedades úteis que permitem que você se mova para trás e para frente através do histórico de navegação do usuário, bem como -- iniciando com o HTML5 -- manipular o conteúdo da pilha de históricos.

Mover para trás e para a frente através do histórico do usuário é feito usando os métodos back(), forward() e go().

Movendo para frente e para trás

Para mover para trás no histórico, apenas faça:

window.history.back();

Isso funcionará exatamente como se o usuário clicasse no botão Voltar na barra de ferramentas do navegador.

Da mesma forma, você pode avançar (como se o usuário clicasse no botão Avançar), assim:

window.history.forward();

Movendo para um ponto específico no histórico

Você pode usar o método go() para carregar uma página específica do histórico. Cada página é identificada por sua posição relativa à página atual (sendo a página atual o indíce 0). 

Para retornar uma página (equivalente ao método back()):

window.history.go(-1);

Para adiantar uma página (equivalente ao método forward()):

window.history.go(1);

O número de páginas do histórico pode ser determinado pela propriedade length:

const numero_de_entradas = window.history.length;
Note: Internet Explorer  suporta URLs como argumento para o método go(); Isso não é um comportamento padrão e não é suportado pelo Gecko.

Adicionando e modificando entradas

HTML5 introduz os métodos history.pushState() e history.replaceState(), que permitem respectivamente adicionar e modificar entradas no histórico. Estes métodos funcionam em conjunto com o evento window.onpopstate.

Utilizar history.pushState() modifica a referência que é utilizada no cabeçalho HTTP para objetos XMLHttpRequest criados após a utilização do método. A referência será a URL do documento cuja janela é o this no momento de criação do objeto XMLHttpRequest.

Exemplo do método pushState()

Sunponha que http://mozilla.org/foo.html executa o seguinte JavaScript:

const stateObj = { foo: "bar" };
history.pushState(stateObj, "page 2", "bar.html");

Isto fará com que a barra URL mostre http://mozilla.org/bar.html, porém não fará com que o browser carregue bar.html ou cheque se bar.html existe. 

Agora supunha que o usuário navegue para http://google.com e logo em seguida clique no botão voltar. Nesse momento, a barra de URL mostrará http://mozilla.org/bar.html e a página receberá um evento popstate cujo objeto de estado contenha uma copia de stateObj. A página carregada em si será foo.html, porém a página pode modificar seu conteúdo durante o evento.

Se clicarmos no botão de voltar novamente, a URL modificará para http://mozilla.org/foo.html, e o documento receberá outro evento popstate, dessa vez com objeto de estado sendo nulo. Nesse momento, o documento também não altera seu conteúdo em relação ao passo anterior, porém o documento pode atualizar seu conteúdo manualmente após o recebimento do evento popstate.

O método pushState()

pushState() recebe três parâmetros: um objeto de estado, um título (que atualmente é ignorado) e (opcionalmente) uma URL. Vamos examinar cada um dos argumentos com mais detalhes:

  • objeto de estado — O objeto de estado é um objeto JavaScript que é associado com uma nova entrada no histórico criado por pushState(). Sempre que o usuário navegar para o novo estado um evento popstate é disparado e a propriedade state do evento contém uma copia do objeto de estado da entrada no histórico.

  • O objeto de estado pode ser qualquer coisa que possa ser serializada. Firefox salva o objeto de estado no disko do usuário para que possa ser restaurado após um restar do browser. É imposto um limite de 640k characteres na representação serializada do objeto de estado. Caso um objeto de estado serializado maior que este valor seja passado como argumento para pushState(), o método irá ativar uma exceção. Caso você precisa de mais espaço do que 640k, é recomendado a utilização do sessionStorage e/ou localSotrage.

  • título — Atualmente Firefox ignora este parâmetro.  Passar uma string vazia é suficiente contra futuras mudanças no método. Alternativamente, você poderia passar um título curto para o estado.

  • URL —  Este parâmetro fornece uma URL a nova entrada do histórico. Note que o browser não tentará carregar essa URL após uma chamada do método pushState(), porém pode tentar carregar a URL mais tarde, por exemplo depois que o usuário reinicie o browser. A nova URL não precisa ser absoluta; caso seja relativa, é resolvida em relação a atual URL. A nova URL precisar ser da mesma origem que a URL atual; caso contrário, pushState() ativará uma exceção. Este parâmetro é opicional; caso seja especificado, é utilizado como a atual URL do documento.

Nota: Em Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1) até Gecko 5.0 (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2), o objeto passado é serializado utilizando JSON. Começando do Gecko 6.0 (Firefox 6.0 / Thunderbird 6.0 / SeaMonkey 2.3), o objeto é serializado usando  o algorítmo de clonagem estruturada. Isso permite que uma variedade maior de objetos possam ser serializados.

De certa forma, chamar o método pushState() é similar com executar window.location = "#foo",  no sentido de que ambos criarão e ativarão uma nova entrada no histórico associado com o documento atual. Porém pushState() tem algumas vantagens:

  • A nova URL pode ser qualquer URL na mesma origem da atual. Em contraste, modificar o valor de window.location o mantém no mesmo document somente se apenas a hash é modificada.
  • Você não precisa mudar a URL caso não queira. Em contraste, executar window.location = "#foo" só cria uma nova entrada no histórico se a atual hash não for #foo.
  • Você pode associar arbitrariamente dados com a nova entrada do histórico.
  • Se title for utilizado pelos browser, esse dado pode ser utilizado (independente da hash).

Note que pushState() nunca causa a ativação de um evento hashchange, mesmo se a nova URL diferir somente na hash,

Em um documento XUL é criado o element XUL especificado.

Em outros documentos, é criado um elemento com URI namespase nulo.

O método replaceState()

history.replaceState() opera exatamente igual à history.pushState() com exceção de modificar a atual entrada no histórico ao invés de criar uma nova. Note que isso não impede a criação de uma nova entrada no histórico global do browser.

replaceState() é particularmente útil quando você quer atualiza o objeto de estado ou a URL da atual entrada do histórico como resposta a alguma ação do usuário.

Nota: Em Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1) até Gecko 5.0 (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2), o objeto passado é serializado utilizando JSON. Começando do Gecko 6.0 (Firefox 6.0 / Thunderbird 6.0 / SeaMonkey 2.3), o objeto é serializado usando  o algorítmo de clonagem estruturada. Isso permite que uma variedade maior de objetos possam ser serializados.

Exemplo do método replaceState()

Suponha que http://mozilla.org/foo.html execute o seguinte JavaScript:

const stateObj = { foo: "bar" };
history.pushState(stateObj, "page 2", "bar.html");

A explicação destas duas linhas acima pode ser encontrada na seção "Exemplo do método pushState()". Suponha, então, que http://mozilla.org/bar.html execute o seguinte JavaScript:

history.replaceState(stateObj, "page 3", "bar2.html");

Isso fará com que a barra de URL do navegador exiba http://mozilla.org/bar2.html, mas não fará com que o navegador carregue bar2.html ou cheque se bar2.html existe.

Suponha agora que o usuário navegue até http://www.microsoft.com e, em seguida, clique no botão voltar. Neste momento, a barra de URL mostrará http://mozilla.org/bar2.html. Caso o usuário clique novamente no botão voltar, a barra de URL mostrará http://mozilla.org/foo.html e ignorará completamente bar.html.

O evento popstate

O evento popstate é disparado sempre que a entrada do histórico ativo é alterada. Se a entrada do histórico ativa foi criada por uma chamada pushState ou afetada por uma chamada replaceState, a propriedade state do evento popstate contém uma cópia do objeto de estado da entrada do histórico.

Veja window.onpopstate para exemplo de utilização.

Lendo o estado atual

Quando sua página é carregada, ela pode ter um objeto de estado não nulo. Isso pode acontecer, por exemplo, se a página definir um objeto de estado (usando pushState() ou replaceState()) e, em seguida, o usuário reiniciar seu navegador. Quando sua página é recarregada, ela receberá um evento onload, mas nenhum evento popstate. No entanto, se você ler a propriedade history.state, receberá o objeto de estado que teria obtido se um popstate tivesse sido disparado.

Você pode ler o estado da entrada do histórico atual sem esperar por um evento popstate usando a propriedade history.state como o exemplo abaixo:

var currentState = history.state;

Exemplos

Para um exemplo completo de um web site AJAX, veja:  Exemplo de navegação Ajax.

Especificações

Especificação Status Comentário
HTML Living Standard
The definition of 'History' in that specification.
Padrão em tempo real Nenhuma alteração do HTML5.
HTML5
The definition of 'History' in that specification.
Recomendação Definição inicial

Compatibilidade de navegadores

Estamos convertendo nossos dados de compatibilidade para o formato JSON. Esta tabela de compatibilidade ainda usa o formato antigo, pois ainda não convertemos os dados que ela contém. Descubra como você pode ajudar!

Recurso Chrome Edge Firefox (Gecko) Internet Explorer Opera Safari
replaceState, pushState 5 (Yes) 4.0 (2.0) 10 11.50 5.0
history.state 18 (Yes) 4.0 (2.0) 10 11.50 6.0
Recurso Android Edge Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
replaceState, pushState ? (Yes) ? ? ? ?
history.state ? (Yes) ? ? ? ?

Veja também

Etiquetas do documento e colaboradores

Etiquetas: 
Colaboradores desta página: rodgerpaulo, william-costa, BernardoS, sistematico
Última atualização por: rodgerpaulo,