From 074785cea106179cb3305637055ab0a009ca74f2 Mon Sep 17 00:00:00 2001 From: Peter Bengtsson Date: Tue, 8 Dec 2020 14:42:52 -0500 Subject: initial commit --- files/pt-br/web/api/history_api/index.html | 257 +++++++++++++++++++++++++++++ 1 file changed, 257 insertions(+) create mode 100644 files/pt-br/web/api/history_api/index.html (limited to 'files/pt-br/web/api/history_api/index.html') diff --git a/files/pt-br/web/api/history_api/index.html b/files/pt-br/web/api/history_api/index.html new file mode 100644 index 0000000000..5b763f9a97 --- /dev/null +++ b/files/pt-br/web/api/history_api/index.html @@ -0,0 +1,257 @@ +--- +title: Manipulando o histórico do navegador +slug: Web/API/History_API +tags: + - Avançado + - DOM + - HTML5 + - Histórico +translation_of: Web/API/History_API +--- +

O objeto DOM {{ domxref("window") }} fornece acesso ao histórico do navegador através do objeto {{ domxref("window.history", "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 avançar 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 numberOfEntries = window.history.length;
+
+ +
Note: 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

+ +

{{ gecko_minversion_header("2") }}

+ +

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

+ +

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:

+ +
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 a página receberá um evento popstate cujo objeto de estado contém uma copia de stateObj 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:

+ + + +
Nota: No Gecko 2.0 {{ geckoRelease("2.0") }} até Gecko 5.0 {{ geckoRelease("5.0") }}, o objeto passado é serializado utilizando JSON. A partir do Gecko 6.0 {{ geckoRelease("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:

+ + + +

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 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 {{ geckoRelease("2.0") }} até Gecko 5.0 {{ geckoRelease("5.0") }}, o objeto passado é serializado utilizando JSON. Começando do Gecko 6.0 {{ geckoRelease("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:

+ +
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 {{ domxref("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çãoStatusComentário
{{SpecName('HTML WHATWG', "browsers.html#history", "History")}}{{Spec2('HTML WHATWG')}}Nenhuma alteração do {{SpecName("HTML5 W3C")}}.
{{SpecName('HTML5 W3C', "browsers.html#history", "History")}}{{Spec2('HTML5 W3C')}}Definição inicial
+ +

Compatibilidade de navegadores

+ +

{{ CompatibilityTable() }}

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
RecursoChromeEdgeFirefox (Gecko)Internet ExplorerOperaSafari
replaceState, pushState5{{CompatVersionUnknown}}{{ CompatGeckoDesktop("2.0") }}1011.505.0
history.state18{{CompatVersionUnknown}}{{ CompatGeckoDesktop("2.0") }}1011.506.0
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
RecursoAndroidEdgeFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
replaceState, pushState{{ CompatUnknown() }}{{CompatVersionUnknown}}{{ CompatUnknown() }}{{ CompatUnknown() }}{{ CompatUnknown() }}{{ CompatUnknown() }}
history.state{{ CompatUnknown() }}{{CompatVersionUnknown}}{{ CompatUnknown() }}{{ CompatUnknown() }}{{ CompatUnknown() }}{{ CompatUnknown() }}
+
+ +

Veja também

+ + + +

{{ languages( { "ja": "ja/DOM/Manipulating_the_browser_history"} ) }}

-- cgit v1.2.3-54-g00ecf