Manipulando o histórico do navegador
====================================

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.

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étodos `back()`, `forward()` e `go()`.

### Movendo para frente e para trás

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


```js
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:


```js
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()`):


```js
window.history.go(-1);
```


Para avançar uma página (equivalente ao método `forward()`):


```js
window.history.go(1);
```


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


```js
const numberOfEntries = window.history.length;
```


> 
> \*\*Nota:\*\*O 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
----------------------------------

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

Usar `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()

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


```js
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 navegador carregue `bar.html` ou verifique se `bar.html` existe.

Agora suponha 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 se você ler o `history.state` você receberá o `stateObj`. O evento `popstate` 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á para `http://mozilla.org/foo.html`, e o documento receberá um 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 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 do `sessionStorage` e/ou `localStorage`.
* **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 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 a 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 contrapartida, 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 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 `title` for utilizado pelos navegadores, esse dado pode ser utilizado (independente do 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 elemento XUL especificado.

Em outros documentos, é criado um elemento com um namespace `null` 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 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:


```js
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:


```js
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` (en-US) 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:


```js
var currentState = history.state;
```

Exemplos
--------

Para um exemplo completo de um web site AJAX, veja: Exemplo de navegação Ajax (en-US).

Especificações
--------------

| Specification |
| --- |
| HTML Standard # the-history-interface |

Compatibilidade com navegadores
-------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.