diff options
author | Peter Bengtsson <mail@peterbe.com> | 2020-12-08 14:42:52 -0500 |
---|---|---|
committer | Peter Bengtsson <mail@peterbe.com> | 2020-12-08 14:42:52 -0500 |
commit | 074785cea106179cb3305637055ab0a009ca74f2 (patch) | |
tree | e6ae371cccd642aa2b67f39752a2cdf1fd4eb040 /files/pt-br/web/api/history_api/index.html | |
parent | da78a9e329e272dedb2400b79a3bdeebff387d47 (diff) | |
download | translated-content-074785cea106179cb3305637055ab0a009ca74f2.tar.gz translated-content-074785cea106179cb3305637055ab0a009ca74f2.tar.bz2 translated-content-074785cea106179cb3305637055ab0a009ca74f2.zip |
initial commit
Diffstat (limited to 'files/pt-br/web/api/history_api/index.html')
-rw-r--r-- | files/pt-br/web/api/history_api/index.html | 257 |
1 files changed, 257 insertions, 0 deletions
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 +--- +<p>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.</p> + +<h2 id="Navegando_através_do_histórico">Navegando através do histórico</h2> + +<p><span id="result_box" lang="pt"><span>Mover para trás e para a frente através do histórico do usuário é feito usando os métodos <code>back()</code>, <code>forward()</code> e <code>go()</code>. </span></span></p> + +<h3 id="Movendo_para_frente_e_para_trás">Movendo para frente e para trás</h3> + +<p>Para mover para trás no histórico, apenas faça:</p> + +<pre class="brush: js">window.history.back(); +</pre> + +<p><span id="result_box" lang="pt"><span>Isso funcionará exatamente como se o usuário clicasse no botão Voltar na barra de ferramentas do navegador.</span><br> + <br> + <span>Da mesma forma, você pode avançar (como se o usuário clicasse no botão Avançar), assim:</span></span></p> + +<pre class="brush: js">window.history.forward(); +</pre> + +<h3 id="Movendo_para_um_ponto_específico_no_histórico">Movendo para um ponto específico no histórico</h3> + +<p>Você pode usar o método <code>go()</code> 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). </p> + +<p>Para retornar uma página (equivalente ao método <code>back()</code>):</p> + +<pre class="brush: js">window.history.go(-1); +</pre> + +<p>Para avançar uma página (equivalente ao método <code>forward()</code>):</p> + +<pre class="brush: js">window.history.go(1); + +</pre> + +<p>O número de páginas do histórico pode ser determinado pela propriedade <em>length</em>:</p> + +<pre class="brush: js">const numberOfEntries = window.history.length; +</pre> + +<div class="note"><strong>Note: </strong>O Internet Explorer suporta URLs como argumento para o método <code>go()</code>; isso não é um comportamento padrão e não é suportado pelo Gecko.</div> + +<h2 id="Adicionando_e_modificando_entradas">Adicionando e modificando entradas</h2> + +<p>{{ gecko_minversion_header("2") }}</p> + +<p>O HTML5 introduziu os métodos <a href="/en-US/docs/Web/API/History/pushState">history.pushState()</a> e <a href="/en-US/docs/Web/API/History_API#The_replaceState()_method">history.replaceState()</a>, que permitem adicionar e modificar entradas no histórico, respectivamente. Estes métodos funcionam em conjunto com o evento {{ domxref("window.onpopstate") }}.</p> + +<p>Usar <code>history.pushState()</code> modifica a referência que é utilizada no cabeçalho HTTP para objetos <code><a href="/en/DOM/XMLHttpRequest" title="en/XMLHttpRequest">XMLHttpRequest</a></code> criados após a utilização do método. A referência será a URL do documento cuja janela é o <code>this</code> no momento de criação do objeto <code><a href="/en/DOM/XMLHttpRequest" title="en/XMLHttpRequest">XMLHttpRequest</a></code>.</p> + +<h3 id="Exemplo_do_método_pushState()">Exemplo do método pushState()</h3> + +<p>Suponha que <span class="nowiki">http://mozilla.org/foo.html executa o seguinte JavaScript:</span></p> + +<pre class="brush: js">const stateObj = { foo: "bar" }; +history.pushState(stateObj, "page 2", "bar.html"); +</pre> + +<p>Isto fará com que a barra URL mostre <span class="nowiki">http://mozilla.org/bar.html, porém não fará com que o navegador carregue </span><code>bar.html</code> ou verifique se <code>bar.html</code> existe. </p> + +<p>Agora suponha que o usuário navegue para <span class="nowiki">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 <s>a página receberá um evento </s></span><s><code>popstate</code> cujo <em>objeto de estado</em> contém uma copia de <code>stateObj</code></s> se você ler o <code>history.state</code> você receberá o <code>stateObj</code>. O evento <code>popstate</code> não será disparado pois a página foi recarregada. A página carregada será <code>bar.html</code>.</p> + +<p>Se clicarmos no botão Voltar novamente, a URL modificará para <span class="nowiki">http://mozilla.org/foo.html, e o documento receberá um evento </span><code>popstate</code>, 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 <code>popstate</code>.</p> + +<h3 id="O_método_pushState()">O método pushState()</h3> + +<p><code>pushState()</code> 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:</p> + +<ul> + <li> + <p><strong>objeto de estado</strong> — O objeto de estado é um objeto JavaScript que é associado com uma nova entrada no histórico criado por <code>pushState()</code>. Sempre que o usuário navegar para o novo estado um evento <code>popstate</code> é disparado e a propriedade <code>state</code> do evento contém uma cópia do objeto de estado da entrada no histórico.</p> + </li> + <li> + <p>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 <code>pushState()</code>, o método irá ativar uma exceção. Caso você precise de mais espaço do que 640k, é recomendada a utilização do <code>sessionStorage</code> e/ou <code>localSotrage</code>.</p> + </li> + <li> + <p><strong>título </strong>— 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.</p> + </li> + <li> + <p><strong>URL</strong> — 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 <code>pushState()</code>, 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, <code>pushState()</code> ativará uma exceção. Este parâmetro é opcional; caso seja especificado, é utilizado como a atual URL do documento.</p> + </li> +</ul> + +<div class="note"><strong>Nota: </strong>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 <a href="/en/DOM/The_structured_clone_algorithm" title="en/DOM/The structured clone algorithm"> o algorítmo de clonagem estruturada</a>. Isso permite que uma variedade maior de objetos possam ser serializados.</div> + +<p>De certa forma, chamar o método <code>pushState()</code> é similar a executar <code>window.location = "#foo"</code>, no sentido de que ambos criarão e ativarão uma nova entrada no histórico associado com o documento atual. Porém <code>pushState()</code> tem algumas vantagens:</p> + +<ul> + <li>A nova URL pode ser qualquer URL na mesma origem da atual. Em contrapartida, modificar o valor de <code>window.location</code> o mantém no mesmo {{ domxref("document") }} somente se apenas a hash é modificada.</li> + <li>Você não precisa mudar a URL caso não queira. Em contrapartida, executar <code>window.location = "#foo"</code> só cria uma nova entrada no histórico se a atual hash não for <code>#foo</code>.</li> + <li>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.</li> + <li>Se <code>title</code> for utilizado pelos navegadores, esse dado pode ser utilizado (independente do hash).</li> +</ul> + +<p>Note que <code>pushState()</code> nunca causa a ativação de um evento <code>hashchange</code>, mesmo se a nova URL diferir somente na hash,</p> + +<p>Em um documento <a href="/en-US/docs/Mozilla/Tech/XUL">XUL</a> é criado o elemento XUL especificado.</p> + +<p>Em outros documentos, é criado um elemento com um namespace <code>null</code> de URI.</p> + +<h3 id="O_método_replaceState()">O método replaceState()</h3> + +<p><code>history.replaceState()</code> opera exatamente igual à <code>history.pushState()</code> 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.</p> + +<p><code>replaceState()</code> é 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.</p> + +<div class="note"><strong>Nota: </strong>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 <a href="/en/DOM/The_structured_clone_algorithm" title="en/DOM/The structured clone algorithm"> o algorítmo de clonagem estruturada</a>. Isso permite que uma variedade maior de objetos possam ser serializados.</div> + +<h3 id="Exemplo_do_método_replaceState()">Exemplo do método replaceState()</h3> + +<p>Suponha que <span class="nowiki">http://mozilla.org/foo.html</span> execute o seguinte JavaScript:</p> + +<pre class="brush: js">const stateObj = { foo: "bar" }; +history.pushState(stateObj, "page 2", "bar.html"); + +</pre> + +<p>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:</p> + +<pre class="brush: js">history.replaceState(stateObj, "page 3", "bar2.html"); +</pre> + +<p>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 <code>bar2.html</code> ou cheque se <code>bar2.html</code> existe.</p> + +<p>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 <code>bar.html</code>.</p> + +<h3 id="O_evento_popstate">O evento popstate</h3> + +<p>O evento <code>popstate</code> é disparado sempre que a entrada do histórico ativo é alterada. Se a entrada do histórico ativa foi criada por uma chamada <code>pushState</code> ou afetada por uma chamada <code>replaceState</code>, a propriedade <code>state</code> do evento <code>popstate</code> contém uma cópia do objeto de estado da entrada do histórico.</p> + +<p>Veja {{ domxref("window.onpopstate") }} para exemplo de utilização.</p> + +<h3 id="Lendo_o_estado_atual">Lendo o estado atual</h3> + +<p>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 <code>pushState()</code> ou <code>replaceState()</code>) e, em seguida, o usuário reiniciar seu navegador. Quando sua página é recarregada, ela receberá um evento <code>onload</code>, mas nenhum evento <code>popstate</code>. No entanto, se você ler a propriedade <code>history.state</code>, receberá o objeto de estado que teria obtido se um <code>popstate</code> tivesse sido disparado.</p> + +<p>Você pode ler o estado da entrada do histórico atual sem esperar por um evento <code>popstate</code> usando a propriedade <code>history.state</code> como o exemplo abaixo:</p> + +<pre class="brush: js">var currentState = history.state; +</pre> + +<h2 id="Exemplos">Exemplos</h2> + +<p>Para um exemplo completo de um web site AJAX, veja: <a href="/pt-BR/docs/Web/Guide/API/DOM/Manipulating_the_browser_history/Example" title="/en-US/docs/Web/Guide/API/DOM/Manipulating_the_browser_history/Example">Exemplo de navegação Ajax</a>.</p> + +<h2 id="Especificações">Especificações</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">Especificação</th> + <th scope="col">Status</th> + <th scope="col">Comentário</th> + </tr> + <tr> + <td>{{SpecName('HTML WHATWG', "browsers.html#history", "History")}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>Nenhuma alteração do {{SpecName("HTML5 W3C")}}.</td> + </tr> + <tr> + <td>{{SpecName('HTML5 W3C', "browsers.html#history", "History")}}</td> + <td>{{Spec2('HTML5 W3C')}}</td> + <td>Definição inicial</td> + </tr> + </tbody> +</table> + +<h2 id="Compatibilidade_de_navegadores">Compatibilidade de navegadores</h2> + +<p>{{ CompatibilityTable() }}</p> + +<div id="compat-desktop"> +<table class="compat-table"> + <tbody> + <tr> + <th>Recurso</th> + <th>Chrome</th> + <th>Edge</th> + <th>Firefox (Gecko)</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari</th> + </tr> + <tr> + <td>replaceState, pushState</td> + <td>5</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{ CompatGeckoDesktop("2.0") }}</td> + <td>10</td> + <td>11.50</td> + <td>5.0</td> + </tr> + <tr> + <td>history.state</td> + <td>18</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{ CompatGeckoDesktop("2.0") }}</td> + <td>10</td> + <td>11.50</td> + <td>6.0</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Recurso</th> + <th>Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>replaceState, pushState</td> + <td>{{ CompatUnknown() }}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + </tr> + <tr> + <td>history.state</td> + <td>{{ CompatUnknown() }}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + </tr> + </tbody> +</table> +</div> + +<p><strong style="font-size: 2.143rem; font-weight: 700; letter-spacing: -1px; line-height: 1;">Veja também</strong></p> + +<ul> + <li>{{ domxref("window.history") }}</li> + <li>{{ domxref("window.onpopstate") }}</li> +</ul> + +<p>{{ languages( { "ja": "ja/DOM/Manipulating_the_browser_history"} ) }}</p> |