diff options
| author | Florian Merz <me@fiji-flo.de> | 2021-02-11 12:36:08 +0100 |
|---|---|---|
| committer | Florian Merz <me@fiji-flo.de> | 2021-02-11 12:36:08 +0100 |
| commit | 39f2114f9797eb51994966c6bb8ff1814c9a4da8 (patch) | |
| tree | 66dbd9c921f56e440f8816ed29ac23682a1ac4ef /files/fr/web/api/history_api | |
| parent | 8260a606c143e6b55a467edf017a56bdcd6cba7e (diff) | |
| download | translated-content-39f2114f9797eb51994966c6bb8ff1814c9a4da8.tar.gz translated-content-39f2114f9797eb51994966c6bb8ff1814c9a4da8.tar.bz2 translated-content-39f2114f9797eb51994966c6bb8ff1814c9a4da8.zip | |
unslug fr: move
Diffstat (limited to 'files/fr/web/api/history_api')
| -rw-r--r-- | files/fr/web/api/history_api/example/index.html | 392 | ||||
| -rw-r--r-- | files/fr/web/api/history_api/index.html | 245 |
2 files changed, 637 insertions, 0 deletions
diff --git a/files/fr/web/api/history_api/example/index.html b/files/fr/web/api/history_api/example/index.html new file mode 100644 index 0000000000..f19782d753 --- /dev/null +++ b/files/fr/web/api/history_api/example/index.html @@ -0,0 +1,392 @@ +--- +title: Exemple de navigation en Ajax +slug: Web/Guide/DOM/Manipuler_historique_du_navigateur/Example +translation_of: Web/API/History_API/Example +--- +<p>Voici un exemple de site web AJAX composé uniquement de trois pages (<em>page_un.php</em>, <em>page_deux.php</em> et <em>page_trois.php</em>). Pour tester cet exemple, merci de créer les fichiers suivants :</p> +<p><strong>page_un.php</strong>:</p> +<div style="height: 400px; margin-bottom: 12px; overflow: auto;"> + <pre class="brush: php"><?php + $page_title = "Page un"; + + $as_json = false; + if (isset($_GET["view_as"]) && $_GET["view_as"] == "json") { + $as_json = true; + ob_start(); + } else { +?> +<!doctype html> +<html> +<head> +<?php + include "include/header.php"; + echo "<title>" . $page_title . "</title>"; +?> +</head> + +<body> + +<?php include "include/before_content.php"; ?> + +<p>This paragraph is shown only when the navigation starts from <strong>first_page.php</strong>.</p> + +<div id="ajax-content"> +<?php } ?> + + <p>This is the content of <strong>first_page.php</strong>.</p> + +<?php + if ($as_json) { + echo json_encode(array("page" => $page_title, "content" => ob_get_clean())); + } else { +?> +</div> + +<p>This paragraph is shown only when the navigation starts from <strong>first_page.php</strong>.</p> + +<?php + include "include/after_content.php"; + echo "</body>\n</html>"; + } +?> +</pre> +</div> +<p><strong>page_deux.php</strong>:</p> +<div style="height: 400px; margin-bottom: 12px; overflow: auto;"> + <pre class="brush: php"><?php + $page_title = "Page deux"; + + $as_json = false; + if (isset($_GET["view_as"]) && $_GET["view_as"] == "json") { + $as_json = true; + ob_start(); + } else { +?> +<!doctype html> +<html> +<head> +<?php + include "include/header.php"; + echo "<title>" . $page_title . "</title>"; +?> +</head> + +<body> + +<?php include "include/before_content.php"; ?> + +<p>This paragraph is shown only when the navigation starts from <strong>second_page.php</strong>.</p> + +<div id="ajax-content"> +<?php } ?> + + <p>This is the content of <strong>second_page.php</strong>.</p> + +<?php + if ($as_json) { + echo json_encode(array("page" => $page_title, "content" => ob_get_clean())); + } else { +?> +</div> + +<p>This paragraph is shown only when the navigation starts from <strong>second_page.php</strong>.</p> + +<?php + include "include/after_content.php"; + echo "</body>\n</html>"; + } +?> +</pre> +</div> +<p><strong>page_trois.php</strong>:</p> +<div style="height: 400px; margin-bottom: 12px; overflow: auto;"> + <pre class="brush: php"><?php + $page_title = "Page trois"; + $page_content = "<p>Ceci est le contenu de la <strong>page_trois.php</strong>. Ce contenu est stocké dans une variable PHP.</p>"; + + if (isset($_GET["view_as"]) && $_GET["view_as"] == "json") { + echo json_encode(array("page" => $page_title, "content" => $page_content)); + } else { +?> +<!doctype html> +<html> +<head> +<?php + include "include/header.php"; + echo "<title>" . $page_title . "</title>"; +?> +</head> + +<body> + +<?php include "include/before_content.php"; ?> + +<p>This paragraph is shown only when the navigation starts from <strong>third_page.php</strong>.</p> + +<div id="ajax-content"> +<?php echo $page_content; ?> +</div> + +<p>This paragraph is shown only when the navigation starts from <strong>third_page.php</strong>.</p> + +<?php + include "include/after_content.php"; + echo "</body>\n</html>"; + } +?> +</pre> +</div> +<p><strong>css/style.css</strong>:</p> +<pre class="brush: css">#ajax-loader { + position: fixed; + display: table; + top: 0; + left: 0; + width: 100%; + height: 100%; +} + +#ajax-loader > div { + display: table-cell; + width: 100%; + height: 100%; + vertical-align: middle; + text-align: center; + background-color: #000000; + opacity: 0.65; +} +</pre> +<p><strong>include/after_content.php</strong>:</p> +<pre class="brush: php"><p>Ceci est le pied-de-page. Il est commun à toutes les pages ajax.</p> +</pre> +<p><strong>include/before_content.php</strong>:</p> +<pre class="brush: php"><p> +[ <a class="ajax-nav" href="page_un.php">Premier exemple</a> +| <a class="ajax-nav" href="page_deux.php">Second exemple</a> +| <a class="ajax-nav" href="page_trois.php">Troisième exemple</a> +| <a class="ajax-nav" href="inexistante.php">Page inexistante</a> ] +</p> + +</pre> +<p><strong>include/header.php</strong>:</p> +<pre class="brush: php"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> +<script type="text/javascript" src="js/ajax_nav.js"></script> +<link rel="stylesheet" href="css/style.css" /> +</pre> +<p><strong>js/ajax_nav.js</strong>:</p> +<div style="height: 400px; margin-bottom: 12px; overflow: auto;"> + <pre class="brush: js">"use strict"; + +var ajaxRequest = new (function () { + + function closeReq () { + oLoadingBox.parentNode && document.body.removeChild(oLoadingBox); + bIsLoading = false; + } + + function abortReq () { + if (!bIsLoading) { return; } + oReq.abort(); + closeReq(); + } + + function ajaxError () { + alert("Unknown error."); + } + + function ajaxLoad () { + var vMsg, nStatus = this.status; + switch (nStatus) { + case 200: + vMsg = JSON.parse(this.responseText); + document.title = oPageInfo.title = vMsg.page; + document.getElementById(sTargetId).innerHTML = vMsg.content; + if (bUpdateURL) { + history.pushState(oPageInfo, oPageInfo.title, oPageInfo.url); + bUpdateURL = false; + } + break; + default: + vMsg = nStatus + ": " + (oHTTPStatus[nStatus] || "Unknown"); + switch (Math.floor(nStatus / 100)) { + /* + case 1: + // Informational 1xx + console.log("Information code " + vMsg); + break; + case 2: + // Successful 2xx + console.log("Successful code " + vMsg); + break; + case 3: + // Redirection 3xx + console.log("Redirection code " + vMsg); + break; + */ + case 4: + /* Client Error 4xx */ + alert("Client Error #" + vMsg); + break; + case 5: + /* Server Error 5xx */ + alert("Server Error #" + vMsg); + break; + default: + /* Unknown status */ + ajaxError(); + } + } + closeReq(); + } + + function filterURL (sURL, sViewMode) { + return sURL.replace(rSearch, "") + ("?" + sURL.replace(rHost, "&").replace(rView, sViewMode ? "&" + sViewKey + "=" + sViewMode : "").slice(1)).replace(rEndQstMark, ""); + } + + function getPage (sPage) { + if (bIsLoading) { return; } + oReq = new XMLHttpRequest(); + bIsLoading = true; + oReq.onload = ajaxLoad; + oReq.onerror = ajaxError; + if (sPage) { oPageInfo.url = filterURL(sPage, null); } + oReq.open("get", filterURL(oPageInfo.url, "json"), true); + oReq.send(); + oLoadingBox.parentNode || document.body.appendChild(oLoadingBox); + } + + function requestPage (sURL) { + if (history.pushState) { + bUpdateURL = true; + getPage(sURL); + } else { + /* Ajax navigation is not supported */ + location.assign(sURL); + } + } + + function processLink () { + if (this.className === sAjaxClass) { + requestPage(this.href); + return false; + } + return true; + } + + function init () { + oPageInfo.title = document.title; + for (var oLink, nIdx = 0, nLen = document.links.length; nIdx < nLen; document.links[nIdx++].onclick = processLink); + } + + const + + /* customizable constants */ + sTargetId = "ajax-content", sViewKey = "view_as", sAjaxClass = "ajax-nav", + + /* not customizable constants */ + rSearch = /\?.*$/, rHost = /^[^\?]*\?*&*/, rView = new RegExp("&" + sViewKey + "\\=[^&]*|&*$", "i"), rEndQstMark = /\?$/, + oLoadingBox = document.createElement("div"), oCover = document.createElement("div"), oLoadingImg = new Image(), + oPageInfo = { + title: null, + url: location.href + }, oHTTPStatus = /* http://www.iana.org/assignments/http-status-codes/http-status-codes.xml */ { + 100: "Continue", + 101: "Switching Protocols", + 102: "Processing", + 200: "OK", + 201: "Created", + 202: "Accepted", + 203: "Non-Authoritative Information", + 204: "No Content", + 205: "Reset Content", + 206: "Partial Content", + 207: "Multi-Status", + 208: "Already Reported", + 226: "IM Used", + 300: "Multiple Choices", + 301: "Moved Permanently", + 302: "Found", + 303: "See Other", + 304: "Not Modified", + 305: "Use Proxy", + 306: "Reserved", + 307: "Temporary Redirect", + 308: "Permanent Redirect", + 400: "Bad Request", + 401: "Unauthorized", + 402: "Payment Required", + 403: "Forbidden", + 404: "Not Found", + 405: "Method Not Allowed", + 406: "Not Acceptable", + 407: "Proxy Authentication Required", + 408: "Request Timeout", + 409: "Conflict", + 410: "Gone", + 411: "Length Required", + 412: "Precondition Failed", + 413: "Request Entity Too Large", + 414: "Request-URI Too Long", + 415: "Unsupported Media Type", + 416: "Requested Range Not Satisfiable", + 417: "Expectation Failed", + 422: "Unprocessable Entity", + 423: "Locked", + 424: "Failed Dependency", + 425: "Unassigned", + 426: "Upgrade Required", + 427: "Unassigned", + 428: "Precondition Required", + 429: "Too Many Requests", + 430: "Unassigned", + 431: "Request Header Fields Too Large", + 500: "Internal Server Error", + 501: "Not Implemented", + 502: "Bad Gateway", + 503: "Service Unavailable", + 504: "Gateway Timeout", + 505: "HTTP Version Not Supported", + 506: "Variant Also Negotiates (Experimental)", + 507: "Insufficient Storage", + 508: "Loop Detected", + 509: "Unassigned", + 510: "Not Extended", + 511: "Network Authentication Required" + }; + + var + + oReq, bIsLoading = false, bUpdateURL = false; + + oLoadingBox.id = "ajax-loader"; + oCover.onclick = abortReq; + oLoadingImg.src = "data:image/gif;base64,R0lGODlhEAAQAPIAAP///wAAAMLCwkJCQgAAAGJiYoKCgpKSkiH/C05FVFNDQVBFMi4wAwEAAAAh/hpDcmVhdGVkIHdpdGggYWpheGxvYWQuaW5mbwAh+QQJCgAAACwAAAAAEAAQAAADMwi63P4wyklrE2MIOggZnAdOmGYJRbExwroUmcG2LmDEwnHQLVsYOd2mBzkYDAdKa+dIAAAh+QQJCgAAACwAAAAAEAAQAAADNAi63P5OjCEgG4QMu7DmikRxQlFUYDEZIGBMRVsaqHwctXXf7WEYB4Ag1xjihkMZsiUkKhIAIfkECQoAAAAsAAAAABAAEAAAAzYIujIjK8pByJDMlFYvBoVjHA70GU7xSUJhmKtwHPAKzLO9HMaoKwJZ7Rf8AYPDDzKpZBqfvwQAIfkECQoAAAAsAAAAABAAEAAAAzMIumIlK8oyhpHsnFZfhYumCYUhDAQxRIdhHBGqRoKw0R8DYlJd8z0fMDgsGo/IpHI5TAAAIfkECQoAAAAsAAAAABAAEAAAAzIIunInK0rnZBTwGPNMgQwmdsNgXGJUlIWEuR5oWUIpz8pAEAMe6TwfwyYsGo/IpFKSAAAh+QQJCgAAACwAAAAAEAAQAAADMwi6IMKQORfjdOe82p4wGccc4CEuQradylesojEMBgsUc2G7sDX3lQGBMLAJibufbSlKAAAh+QQJCgAAACwAAAAAEAAQAAADMgi63P7wCRHZnFVdmgHu2nFwlWCI3WGc3TSWhUFGxTAUkGCbtgENBMJAEJsxgMLWzpEAACH5BAkKAAAALAAAAAAQABAAAAMyCLrc/jDKSatlQtScKdceCAjDII7HcQ4EMTCpyrCuUBjCYRgHVtqlAiB1YhiCnlsRkAAAOwAAAAAAAAAAAA=="; + oCover.appendChild(oLoadingImg); + oLoadingBox.appendChild(oCover); + + onpopstate = function (oEvent) { + bUpdateURL = false; + oPageInfo.title = oEvent.state.title; + oPageInfo.url = oEvent.state.url; + getPage(); + }; + + window.addEventListener ? addEventListener("load", init, false) : window.attachEvent ? attachEvent("onload", init) : (onload = init); + + // Public methods + + this.open = requestPage; + this.stop = abortReq; + this.rebuildLinks = init; + +})(); +</pre> +</div> +<div class="note" id="const_compatibility"> + <strong>Note:</strong> <a href="/en/JavaScript/Reference/Statements/const" title="en/JavaScript/Reference/Statements/const"><code>const</code></a> (instruction de constante) <strong>ne fait pas partie de ECMAScript 5</strong>. Il est supporté dans Firefox et Chrome (V8) et partiellement supporté dans Opera 9+ et Safari. <strong>Il n'est pas supporté dans Internet Explorer 6-9, ou dans la version de prévisualisation de Internet Explorer 10</strong>. <a href="/en/JavaScript/Reference/Statements/const" title="en/JavaScript/Reference/Statements/const"><code>const</code></a> sera défini par ECMAScript 6, mais avec une sémantique différente. Proches des variables déclarées avec l'instruction <a href="/en/JavaScript/Reference/Statements/let" title="en/JavaScript/Reference/Statements/let"><code>let</code></a>, les constantes déclarées avec <a href="/en/JavaScript/Reference/Statements/const" title="en/JavaScript/Reference/Statements/const"><code>const</code></a> seront limitées en portée. <strong>Nous ne l'avons utilisé que pour des raisons pédagogiques, si vous souhaitez une compatibilité maximale de ce code, merci de remplacer les références à </strong><strong><a href="/en/JavaScript/Reference/Statements/const" title="en/JavaScript/Reference/Statements/const"><code>const</code></a> par des instructions <a href="/en/JavaScript/Reference/Statements/var" title="en/JavaScript/Reference/Statements/var"><code>var</code></a>.</strong></div> +<p>Pour plus d'informations, voyez : <a href="/fr/docs/DOM/manipuler_lhistorique_du_navigateur" title="/fr/docs/DOM/manipuler_lhistorique_du_navigateur">Manipuler l'historique du navigateur</a>.</p> +<h2 id="Lire_également">Lire également</h2> +<ul> + <li>{{ domxref("window.history") }}</li> + <li>{{ domxref("window.onpopstate") }}</li> +</ul> diff --git a/files/fr/web/api/history_api/index.html b/files/fr/web/api/history_api/index.html new file mode 100644 index 0000000000..5e199dd521 --- /dev/null +++ b/files/fr/web/api/history_api/index.html @@ -0,0 +1,245 @@ +--- +title: Manipuler l'historique du navigateur +slug: Web/Guide/DOM/Manipuler_historique_du_navigateur +tags: + - API + - DOM + - Historique +translation_of: Web/API/History_API +--- +<p>L'objet DOM {{ domxref("window") }} fournit un accès à l'historique du navigateur via l'objet {{ domxref("window.history", "history") }}. Il expose un ensemble de méthodes et de propriétés qui permettent d'avancer et de reculer dans l'historique de l'utilisateur ainsi que -- à partir d'HTML5 -- manipuler le contenu de l'ensemble de l'historique.</p> + +<h2 id="Se_déplacer_dans_l'historique">Se déplacer dans l'historique</h2> + +<p>Avancer ou reculer dans l'historique de l'utilisateur est possible en utilisant les méthodes <code>back()</code>, <code>forward()</code> et <code>go()</code>.</p> + +<h3 id="Avancer_et_reculer">Avancer et reculer</h3> + +<p>Pour reculer dans l'historique, il vous suffit de faire :</p> + +<pre class="brush: js">window.history.back(); +</pre> + +<p>Cela agira exactement comme si l'utilisateur cliquait sur le bouton Retour de la barre d'outils de son navigateur.</p> + +<p>De la même manière, il est possible d'avancer (comme si l'utilisateur cliquait sur le bouton Avancer) :</p> + +<pre class="brush: js">window.history.forward(); +</pre> + +<h3 id="Se_déplacer_à_un_élément_précis_de_l'historique">Se déplacer à un élément précis de l'historique</h3> + +<p>Vous pouvez utiliser la méthode <code>go()</code> pour charger une page spécifique de l'historique de la session, identifiée par sa position relative par rapport à la page en cours (la page courante étant, évidemment, d'index 0).</p> + +<p>Pour reculer d'une page (l'équivalent d'un appel à <code>back()</code>):</p> + +<pre class="brush: js"><code>window.history.go(-1);</code> +</pre> + +<p>Pour avancer d'une page, comme en appelant <code>forward()</code>:</p> + +<pre class="brush: js"><code>window.history.go(1);</code> +</pre> + +<p>De la même manière, vous pouvez avancer de 2 pages en passant la valeur 2, et ainsi de suite.</p> + +<p>Vous pouvez déterminer le nombre de pages de l'historique en accédant à la valeur de la propriété length (<em>longeur</em>) :</p> + +<pre class="brush: js">var numberOfEntries = window.history.length; +</pre> + +<div class="note"><strong>Note:</strong> Internet Explorer supporte le passage d'une URL sous forme de chaîne de caractères comme paramètre de la méthode <code>go()</code>; ce comportement est non standard et non supporté par Gecko.</div> + +<h2 id="Ajouter_et_modifier_des_entrées_de_l'historique">Ajouter et modifier des entrées de l'historique</h2> + +<p>{{ gecko_minversion_header("2") }}</p> + +<p>HTML5 a introduit les méthodes <a href="/fr/docs/Web/Guide/DOM/Manipuler_historique_du_navigateur#La_méthode_pushState()">history.pushState()</a> et <a href="/fr/docs/Web/Guide/DOM/Manipuler_historique_du_navigateur#La_méthode_replaceState()">history.replaceState()</a>, qui permettent, respectivement, d'ajouter et de modifier des entrées de l'historique. Ces méthodes fonctionnent conjointement avec l'événement <a href="/fr/docs/Web/API/WindowEventHandlers/onpopstate">onpopstate</a>.</p> + +<p>L'utilisation de <code>history.pushState()</code> change le référent créé habituellement dans l'en-tête HTTP pour les objets <a href="/en/DOM/XMLHttpRequest" title="en/XMLHttpRequest"><code>XMLHttpRequest</code></a>, chaque fois que son état a été changé. Le référent sera l'URL de la page dont l'objet window est <code>this</code> au moment de la création de l'objet <a href="/en/DOM/XMLHttpRequest" title="en/XMLHttpRequest"><code>XMLHttpRequest</code></a>.</p> + +<h3 id="Exemple_de_la_méthode_pushState()"><a id="Exemple de la méthode pushState()" name="Exemple de la méthode pushState()"></a>Exemple de la méthode pushState()</h3> + +<p>Supposons que <span class="nowiki">http://mozilla.org/foo.html</span> exécute la séquence JavaScript suivante :</p> + +<pre class="brush: js">var stateObj = { foo: "bar" }; +history.pushState(stateObj, "page 2", "bar.html"); +</pre> + +<p>Cela va provoquer l'apparition dans la barre de navigation de <span class="nowiki">http://mozilla.org/bar.html</span>, mais ne provoquera pas le chargement effectif de <code>bar.html</code> ni même le test d'existence de <code>bar.html</code>.</p> + +<p>Supposons à présent que l'utilisateur accède à la page <span class="nowiki">http://google.com</span>, puis clique sur l'icône "Recul". La barre de navigation va alors afficher <span class="nowiki">http://mozilla.org/bar.html</span>, et si vous lisez l'<code>history.state</code>, vous obtiendrez le <code>stateObj</code>. L'événement <code>popstate</code> ne sera pas lancé car la page a été rechargée. La page elle-même ressemblera à <code>bar.html</code>.</p> + +<p>Si on clique à nouveau sur Recul, l'URL de la barre de navigation va se changer en <span class="nowiki">http://mozilla.org/foo.html</span> et le document va recevoir un autre événement <code>popstate</code>, qui comportera, cette fois, un état null. Dans ce cas aussi, revenir en arrière ne modifie pas le contenu du document par rapport à ce qu'il était à l'étape précédente, cela bien qu'il ait pu être mis à jour manuellement sur réception de l'événement <code>popstate</code>.</p> + +<h3 id="La_méthode_pushState()">La méthode pushState()</h3> + +<p><code>La méthode pushState()</code> utilise trois paramètres : un objet état, un titre (qui est pour l'instant ignoré) et, éventuellement, une URL. Examinons chacun de ces paramètres en détail :</p> + +<ul> + <li> + <p><strong>state object</strong> (<em><strong>objet état</strong></em>) — L'objet état est un objet JavaScript qui est associé à une nouvelle entrée de l'historique par <code>pushState()</code>. Chaque fois qu'un utilisateur ouvre une nouvelle page, un événement <code>popstate</code> est émis et la propriété <code>state</code> de l'événement contient une copie de l'objet état de ce nouvel élément de l'historique.<br> + L'objet état peut être tout ce qui peut être sous forme de liste. Puisque Firefox sauvegarde les objets état sur le disque de l'utilisateur de façon à ce qu'ils puissent être rétablis après redémarrage du navigateur, le codage de l'objet état est limité à une taille de 640k octets. Si vous donnez à <code>pushState()</code> un objet état dont la représentation a une taille plus importante, la méthode génèrera une exception. Si vous avez un besoin d'espace plus important, il est conseillé d'utiliser <code>sessionStorage</code> et/ou <code>localStorage</code>.</p> + </li> + <li> + <p><strong>title</strong> (<strong><em>titre</em>)</strong> — Firefox, pour l'instant, ignore ce paramètre, bien qu'il puisse être utilisé plus tard. Afin de prévenir les changements futurs de cette méthode, il serait prudent de fournir ici, en paramètre, une chaîne vide. Vous pourriez aussi donner un titre court à l'état vers lequel vous vous dirigez.</p> + </li> + <li> + <p><strong>URL</strong> — L'URL de la nouvelle entrée de l'historique est donnée par ce paramètre. Il convient de préciser que le navigateur n'essaiera pas de charger la page pointée par cette URL après un appel à <code>pushState()</code>, mais il se peut qu'il tente de le faire plus tard, par exemple, lorsque l'utilisateur relancera son navigateur. Il n'est pas nécessaire que la nouvelle URL soit absolue ; si elle est relative, ce sera par rapport à l'URL courante. La nouvelle URL doit avoir la même origine (domaine) que l'URL courante ; dans le cas contraire, <code>pushState()</code> génèrera une exception. Ce paramètre est optionnel ; s'il n'est pas spécifié, sa valeur par défaut est l'URL de la page courante.</p> + </li> +</ul> + +<div class="note"><strong>Note :</strong> Dans Gecko 2.0 {{ geckoRelease("2.0") }} jusqu'à Gecko 5.0 {{ geckoRelease("5.0") }}, l'objet fourni est sérialisé en utilisant JSON. À partir de Gecko 6.0 {{ geckoRelease("6.0") }}, l'objet est sérialisé à l'aide de<a href="/en/DOM/The_structured_clone_algorithm" title="en/DOM/The structured clone algorithm"> "structured clone algorithm"</a> qui autorise, en particulier, la sérialisation d'arbres récursifs cycliques. Cela permet de passer de façon sûre une plus grande diversité d'objets.</div> + +<p>On peut assimiler l'appel à <code>pushState()</code> à l'affectation <code>window.location = "#foo"</code>, en cela que l'un comme l'autre auront pour effet de créer et déclencher une autre entrée de l'historique associée au document courant. Mais <code>pushState()</code> a quelques avantages :</p> + +<ul> + <li>La nouvelle URL peut être quelconque pourvu qu'elle ait la même origine que l'URL courante. En revanche, affecter <code>window.location</code> vous maintient au même {{ domxref("document") }} seulement si vous modifiez uniquement le hash.</li> + <li>Vous n'êtes pas contraint de modifier l'URL si vous ne le voulez pas. Par contre, affecter <code>window.location = "#foo";</code> crée une nouvelle entrée de l'historique seulement si le hash courant n'est pas <code>#foo</code>.</li> + <li>Vous pouvez associer des données quelconques avec votre nouvelle entrée de l'historique. Avec l'approche basée sur le hash, il est nécessaire de coder toute donnée pertinente en une chaîne courte.</li> +</ul> + +<p>Notez que <code>pushState()</code> n'entraîne jamais le déclenchement d'un événement <code>hashchange</code>, même si la nouvelle URL diffère de l'ancienne seulement par son hash.</p> + +<p>Dans un document <a href="https://developer.mozilla.org/fr/docs/Mozilla/Tech/XUL">XUL</a> elle crée l'élément XUL spécifié.</p> + +<p>Dans d'autres documents, elle crée un élément avec l'URI d'espace de nom <code>null</code>. </p> + +<h3 id="La_méthode_replaceState()">La méthode replaceState()</h3> + +<p><code>history.replaceState()</code> fonctionne exactement comme <code>history.pushState()</code> hormis le fait que <code>replaceState()</code> modifie l'entrée courante de l'historique au lieu d'en créer une nouvelle. À noter que ceci n'empêche pas la création d'une nouvelle entrée dans l'historique global du navigateur.</p> + +<p><code>replaceState()</code> est particulièrement utile si vous désirez mettre à jour l'objet état ou l'URL de l'entrée courante de l'historique en réponse à une action de l'utilisateur.</p> + +<div class="note"><strong>Note :</strong> Dans Gecko 2.0 {{ geckoRelease("2.0") }} jusqu'à Gecko 5.0 {{ geckoRelease("5.0") }}, l'objet transmis est sérialisé avec JSON. À partir de Gecko 6.0 {{ geckoRelease("6.0") }}, l'objet est sérialisé à l'aide de<a href="/en/DOM/The_structured_clone_algorithm" title="en/DOM/The structured clone algorithm"> "structured clone algorithm"</a> qui autorise, en particulier, la sérialisation d'arbres récursifs cycliques. Cela permet de passer de façon sûre une plus grande diversité d'objets.</div> + +<h3 id="Exemple_de_la_méthode_replaceState()">Exemple de la méthode replaceState()</h3> + +<p><span id="result_box" lang="fr"><span>Supposons que http://mozilla.org/foo.html exécute le code JavaScript suivant :</span></span></p> + +<pre class="brush: js line-numbers language-js"><code class="language-js"><span class="keyword token">var</span> stateObj <span class="operator token">=</span> <span class="punctuation token">{</span> foo<span class="punctuation token">:</span> <span class="string token">"bar"</span> <span class="punctuation token">}</span><span class="punctuation token">;</span> +history<span class="punctuation token">.</span><span class="function token">pushState</span><span class="punctuation token">(</span>stateObj<span class="punctuation token">,</span> <span class="string token">"page 2"</span><span class="punctuation token">,</span> <span class="string token">"bar.html"</span><span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre> + +<p>L'explication des deux lignes ci-dessus peut être trouvée dans la section "<a href="#">Exemple de la méthode pushState()</a>". Supposons ensuite que http://mozilla.org/bar.html exécute le code JavaScript suivant :</p> + +<pre class="brush: js line-numbers language-js"><code class="language-js">history<span class="punctuation token">.</span><span class="function token">replaceState</span><span class="punctuation token">(</span>stateObj<span class="punctuation token">,</span> <span class="string token">"page 3"</span><span class="punctuation token">,</span> <span class="string token">"bar2.html"</span><span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre> + +<p>Cela entraînera l'affichage de la barre d'URL http://mozilla.org/bar2.html, mais le navigateur ne chargera pas <code>bar2.html</code> ou même vérifiera que <code>bar2.html</code> existe.</p> + +<p>Supposons maintenant que l'utilisateur accède à http://www.microsoft.com, puis clique sur le bouton Précédent. À ce stade, la barre d'URL affichera http://mozilla.org/bar2.html. Si l'utilisateur clique à nouveau sur Retour, la barre d'URL affichera http://mozilla.org/foo.html et contournera totalement bar.html.</p> + +<h3 id="L'événement_popstate">L'événement popstate</h3> + +<p>Un événement <code>popstate</code> est envoyé à la fenêtre chaque fois que l'entrée active de l'historique change. Si l'entrée de l'historique activée a été créée par un appel à <code>replaceState</code>, la propriété <code>state </code>de l'événement <code>popstate</code> contient une copie de l'objet état de l'entrée de l'historique.</p> + +<p>Voir {{ domxref("window.onpopstate") }} pour un exemple d'utilisation.</p> + +<h3 id="Lire_l'état_courant">Lire l'état courant</h3> + +<p>Quand votre page est chargée, il se pourrait qu'elle ait un objet état non nul. Cela peut se produire, par exemple, si la page fixe un objet état (avec <code>pushState()</code> ou <code>replaceState()</code>) et qu'ensuite l'utilisateur redémarre le navigateur. Quand votre page sera rechargée, elle recevra l'événement <span style="font-family: courier new;">onload</span><span style="font-family: helvetica;"> , mais pas l'événement <span style="font-family: courier new;">popstate</span>.</span> Néanmoins, si vous lisez la propriété <span style="font-family: courier new;">history.state</span>, vous récupèrerez l'objet état que vous auriez obtenu si un événement <span style="font-family: courier new;">popstate</span> avait été déclenché.</p> + +<p>Vous pouvez lire l'état de l'entrée courante de l'historique sans devoir attendre un événement <code>popstate</code> en utilisant la propriété <code>history.state</code> comme ceci :</p> + +<pre class="brush: js">var currentState = history.state; +</pre> + +<h2 id="Exemples">Exemples</h2> + +<p>Pour un exemple comple de site web AJAX, vous pouvez voir : <a href="https://developer.mozilla.org/fr/docs/Web/Guide/DOM/Manipuler_historique_du_navigateur/Example" title="/en-US/docs/Web/Guide/API/DOM/Manipulating_the_browser_history/Example">Exemple de navigation en Ajax</a>.</p> + +<h2 id="Spécifications">Spécifications</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">Spécification</th> + <th scope="col">Statut</th> + <th scope="col">Commentaire</th> + </tr> + <tr> + <td>{{SpecName('HTML WHATWG', "browsers.html#history", "History")}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>Pas de changement de {{SpecName("HTML5 W3C")}}.</td> + </tr> + <tr> + <td>{{SpecName('HTML5 W3C', "browsers.html#history", "History")}}</td> + <td>{{Spec2('HTML5 W3C')}}</td> + <td>Définition initiale.</td> + </tr> + </tbody> +</table> + +<h2 id="Compatibilité_des_navigateurs">Compatibilité des navigateurs</h2> + +<p>{{ CompatibilityTable() }}</p> + +<div id="compat-desktop"> +<table class="compat-table"> + <tbody> + <tr> + <th>Fonctionnalité</th> + <th>Chrome</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>{{ 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>{{ CompatGeckoDesktop("2.0") }}</td> + <td>10</td> + <td>11.50</td> + <td>{{ CompatNo() }}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Fonctionnalité</th> + <th>Android</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>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + </tr> + <tr> + <td>history.state</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + </tr> + </tbody> +</table> +</div> + +<p>Vous pouvez utiliser <a class="link-https" href="https://github.com/browserstate/history.js" title="https://github.com/balupton/history.js">History.js</a> pour contourner les <a class="link-https" href="https://github.com/balupton/history.js/wiki/The-State-of-the-HTML5-History-API" title="https://github.com/balupton/history.js/wiki/The-State-of-the-HTML5-History-API">problèmes</a> de compatibilité entre navigateurs.</p> + +<h2 id="Voir_aussi">Voir aussi</h2> + +<ul> + <li>{{ domxref("window.history") }}</li> + <li>{{ domxref("window.onpopstate") }}</li> +</ul> |