Tradução em progresso.

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 de voltar. Nesse momento, a barra 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 ignores 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");

The explanation of these two lines above can be found at "Example of pushState() method" section. Then suppose http://mozilla.org/bar.html executes the following JavaScript:

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

This will cause the URL bar to display http://mozilla.org/bar2.html, but won't cause the browser to load bar2.html or even check that bar2.html exists.

Suppose now that the user now navigates to http://www.microsoft.com, then clicks back. At this point, the URL bar will display http://mozilla.org/bar2.html. If the user now clicks back again, the URL bar will display http://mozilla.org/foo.html, and totally bypass bar.html.

O evento popstate

A popstate event is dispatched to the window every time the active history entry changes. If the history entry being activated was created by a call to pushState or affected by a call to replaceState, the popstate event's state property contains a copy of the history entry's state object.

See window.onpopstate for sample usage.

Lendo o estado atual

When your page loads, it might have a non-null state object.  This can happen, for example, if the page sets a state object (using pushState() or replaceState()) and then the user restarts their browser.  When your page reloads, the page will receive an onload event, but no popstate event.  However, if you read the history.state property, you'll get back the state object you would have gotten if a popstate had fired.

You can read the state of the current history entry without waiting for a popstate event using the history.state property like this:

var currentState = history.state;

Exemplos

For a complete example of AJAX web site, please see: Ajax navigation example.

Especificações

Specification Status Comment
HTML Living Standard
The definition of 'History' in that specification.
Padrão em tempo real No change from HTML5.
HTML5
The definition of 'History' in that specification.
Recomendação Initial definition.

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!

Feature 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
Feature 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

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