Esta página foi traduzida do inglês pela comunidade.Saiba mais e junte-se à comunidade MDN Web Docs.
Manipulando o histórico do navegador
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since julho de 2015.
O objeto DOMwindow fornece acesso ao histórico do navegador através do objetohistory. 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.
Navegando através do histórico
Mover para trás e para a frente através do histórico do usuário é feito usando os métodosback(),forward() ego().
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étodogo() 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étodoback()):
window.history.go(-1);Para avançar uma página (equivalente ao métodoforward()):
window.history.go(1);O número de páginas do histórico pode ser determinado pela propriedadelength:
const numberOfEntries = window.history.length;Nota:O Internet Explorer suporta URLs como argumento para o métodogo(); isso não é um comportamento padrão e não é suportado pelo Gecko.
Adicionando e modificando entradas
O HTML5 introduziu os métodoshistory.pushState() ehistory.replaceState(), que permitem adicionar e modificar entradas no histórico, respectivamente. Estes métodos funcionam em conjunto com o eventowindow.onpopstate.
Usarhistory.pushState() modifica a referência que é utilizada no cabeçalho HTTP para objetosXMLHttpRequest criados após a utilização do método. A referência será a URL do documento cuja janela é othis no momento de criação do objetoXMLHttpRequest.
Exemplo do método pushState()
Suponha quehttp://mozilla.org/foo.html executa o seguinte #"bar" };history.pushState(stateObj, "page 2", "bar.html");
Isto fará com que a barra URL mostrehttp://mozilla.org/bar.html, porém não fará com que o navegador carreguebar.html ou verifique sebar.html existe.
Agora suponha que o usuário navegue parahttp://google.com e logo em seguida clique no botão Voltar. Nesse momento, a barra de URL mostraráhttp://mozilla.org/bar.html, e se você ler ohistory.state você receberá ostateObj. O eventopopstate não será disparado pois a página foi recarregada. A página carregada serábar.html.
Se clicarmos no botão Voltar novamente, a URL modificará parahttp://mozilla.org/foo.html, e o documento receberá um eventopopstate, 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 eventopopstate.
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 eventopopstateé disparado e a propriedadestatedo evento contém uma cópia do objeto de estado da entrada no histórico. - O objeto de estado pode ser qualquer coisa que possa ser serializada. O Firefox salva o objeto de estado no disco do usuário para que possa ser restaurado após um reinício do navegador. É imposto um limite de 640k caracteres 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ê precise de mais espaço do que 640k, é recomendada a utilização dosessionStoragee/oulocalStorage. - título — Atualmente o Firefox ignora este parâmetro. Passar uma string vazia é suficiente contra futuras mudanças no método. Alternativamente, você pode passar um título curto para o estado.
- URL — A URL da nova entrada no histórico é passada por este parâmetro. Note que o navegador 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 navegador. 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 é opcional; caso seja especificado, é utilizado como a atual URL do documento.
Nota:No Gecko 2.0 até Gecko 5.0, o objeto passado é serializado utilizando JSON. A partir do Gecko 6.0, o objeto é serializado usandoo algorítmo de clonagem estruturada. Isso permite que uma variedade maior de objetos possam ser serializados.
De certa forma, chamar o métodopushState() é similar a executarwindow.location = "#foo", no sentido de que ambos criarão e ativarão uma nova entrada no histórico associado com o documento atual. PorémpushState() tem algumas vantagens:
- A nova URL pode ser qualquer URL na mesma origem da atual. Em contrapartida, modificar o valor de
window.locationo mantém no mesmodocumentsomente se apenas a hash é modificada. - Você não precisa mudar a URL caso não queira. Em contrapartida, executar
window.location = "#foo"só cria uma nova entrada no histórico se a atual hash não for#foo. - Você pode associar dados arbitrários com a nova entrada do histórico. Com a solução baseada em hash, você precisa codificar todos os dados relevantes em uma string curta.
- Se
titlefor utilizado pelos navegadores, esse dado pode ser utilizado (independente do hash).
Note quepushState() nunca causa a ativação de um eventohashchange, mesmo se a nova URL diferir somente na hash,
Em um documentoXUL é criado o elemento XUL especificado.
Em outros documentos, é criado um elemento com um namespacenull de URI.
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 navegador.
replaceState() é particularmente útil quando você quer atualizar 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 até Gecko 5.0, o objeto passado é serializado utilizando JSON. Começando do Gecko 6.0, o objeto é serializado usandoo algorítmo de clonagem estruturada. Isso permite que uma variedade maior de objetos possam ser serializados.
Exemplo do método replaceState()
Suponha quehttp://mozilla.org/foo.html execute o seguinte #"bar" };history.pushState(stateObj, "page 2", "bar.html");