path: root/files/zh-cn/web/api/history_api/index.html

---
title: History API
slug: Web/API/History_API
tags:
  - API
  - History
  - History API
translation_of: Web/API/History_API
---
<div>{{DefaultAPISidebar("History API")}}</div>

<p>DOM {{ domxref("window") }} 对象通过 {{ domxref("window.history", "history") }} 对象提供了对浏览器的会话历史的访问(不要与 <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/history">WebExtensions history</a>搞混了)。它暴露了很多有用的方法和属性，允许你在用户浏览历史中向前和向后跳转，同时——从HTML5开始——提供了对history栈中内容的操作。</p>

<h2 id="意义及使用">意义及使用</h2>

<p>使用 {{DOMxRef("History.back","back()")}},  {{DOMxRef("History.forward","forward()")}}和  {{DOMxRef("History.go","go()")}} 方法来完成在用户历史记录中向后和向前的跳转。</p>

<h3 id="向前和向后跳转">向前和向后跳转</h3>

<p>在history中向后跳转：</p>

<pre class="brush: js notranslate">window.history.back();
</pre>

<p>这和用户点击浏览器回退按钮的效果相同。</p>

<p>类似地，你可以向前跳转（如同用户点击了前进按钮）：</p>

<pre class="brush: js notranslate">window.history.forward();
</pre>

<h3 id="跳转到_history_中指定的一个点">跳转到 history 中指定的一个点</h3>

<p>你可以用 <code>go()</code> 方法载入到会话历史中的某一特定页面， 通过与当前页面相对位置来标志 (当前页面的相对位置标志为0).</p>

<p>向后移动一个页面 (等同于调用 <code>back()</code>):</p>

<pre class="brush: js notranslate">window.history.go(-1);
</pre>

<p>向前移动一个页面, 等同于调用了 <code>forward()</code>:</p>

<pre class="brush: js notranslate">window.history.go(1);
</pre>

<p>类似地，你可以传递参数值2并向前移动2个页面，等等。</p>

<p>您可以通过查看长度属性的值来确定的历史堆栈中页面的数量:</p>

<pre class="brush: js notranslate"> let numberOfEntries = window.history.length;
</pre>

<div class="note"><strong>注意:</strong> IE 支持传递URLs作为参数给 go(); 这在Gecko是不标准且不支持的。</div>

<h2 id="添加和修改历史记录中的条目">添加和修改历史记录中的条目</h2>

<p>{{ gecko_minversion_header("2") }}</p>

<p>HTML5引入了 <a href="/en-US/docs/Web/API/History/pushState">history.pushState()</a> 和 <a href="/en-US/docs/Web/API/History_API#The_replaceState()_method">history.replaceState()</a> 方法，它们分别可以添加和修改历史记录条目。这些方法通常与{{ domxref("window.onpopstate") }} 配合使用。</p>

<p>使用 <code>history.pushState()</code> 可以改变referrer，它在用户发送 <a href="/en/DOM/XMLHttpRequest" title="en/XMLHttpRequest"><code>XMLHttpRequest</code></a> 请求时在HTTP头部使用，改变state后创建的 <a href="/en/DOM/XMLHttpRequest" title="en/XMLHttpRequest"><code>XMLHttpRequest</code></a> 对象的referrer都会被改变。因为referrer是标识创建  <code><a href="/en/DOM/XMLHttpRequest" title="en/XMLHttpRequest">XMLHttpRequest</a></code> 对象时 <code>this</code> 所代表的window对象中document的URL。</p>

<h3 id="pushState_方法的例子">pushState() 方法的例子</h3>

<p><span class="nowiki">假设在 http://mozilla.org/foo.html</span> 页面的console中执行了以下 JavaScript 代码:</p>

<pre class="brush: js notranslate">window.onpopstate = function(e) {
   alert(2);
}

let stateObj = {
    foo: "bar",
};

history.pushState(stateObj, "page 2", "bar.html");
</pre>

<p>这将使浏览器地址栏显示为 <span class="nowiki">http://mozilla.org/bar.html，但并不会导致浏览器加载 </span><code>bar.html</code> ，甚至不会检查<code>bar.html</code> 是否存在。</p>

<p>假如现在用户在bar.html点击了返回按钮，将会执行alert(2)。</p>

<p><span class="nowiki">假设现在用户在bar.html又访问了 http://google.com</span>，然后点击了返回按钮。此时，地址栏将显示 <span class="nowiki">http://mozilla.org/bar.html，<code>history.</code></span><code>state</code> 中包含了 <code>stateObj</code> 的一份拷贝。页面此时展现为<font face='consolas,"Liberation Mono",courier,monospace'><font><code>bar.html</code></font></font>。且因为页面被重新加载了，所以<code>popstate</code>事件将不会被触发，也不会执行alert(2)。</p>

<p>如果我们再次点击返回按钮，页面URL会变为<span class="nowiki">http://mozilla.org/foo.html，文档对象</span>document会触发另外一个 <code>popstate</code> 事件(如果有bar.html，且bar.html注册了onpopstate事件，将会触发此事件，因此也不会执行foo页面注册的onpopstate事件，也就是不会执行alert(2))，这一次的事件对象state object为null。 这里也一样，返回并不改变文档的内容，尽管文档在接收 <code>popstate</code> 事件时可能会改变自己的内容，其内容仍与之前的展现一致。</p>

<p>如果我们再次点击返回按钮，页面URL变为其他页面的url，依然不会执行alert(2)。因为在返回到foo页面的时候并没有pushState。</p>

<h3 id="pushState_方法">pushState() 方法</h3>

<p><code>pushState()</code> 需要三个参数: 一个状态对象, 一个标题 (目前被忽略), 和 (可选的) 一个URL. 让我们来解释下这三个参数详细内容：</p>

<ul>
 <li>
  <p><strong>状态对象</strong> — 状态对象state是一个JavaScript对象，通过pushState () 创建新的历史记录条目。无论什么时候用户导航到新的状态，popstate事件就会被触发，且该事件的state属性包含该历史记录条目状态对象的副本。</p>

  <p>        状态对象可以是能被序列化的任何东西。原因在于Firefox将状态对象保存在用户的磁盘上，以便在用户重启浏览器时使用，我们规定了状态对象在序列化表示后有640k的大小限制。如果你给 <code>pushState()</code> 方法传了一个序列化后大于640k的状态对象，该方法会抛出异常。如果你需要更大的空间，建议使用 <code>sessionStorage</code> 以及 <code>localStorage</code>.</p>
 </li>
 <li>
  <p><strong>标题</strong> — Firefox 目前忽略这个参数，但未来可能会用到。在此处传一个空字符串应该可以安全的防范未来这个方法的更改。或者，你可以为跳转的state传递一个短标题。</p>
 </li>
 <li>
  <p><strong>URL</strong> — 该参数定义了新的历史URL记录。注意，调用 <code>pushState()</code> 后浏览器并不会立即加载这个URL，但可能会在稍后某些情况下加载这个URL，比如在用户重新打开浏览器时。新URL不必须为绝对路径。如果新URL是相对路径，那么它将被作为相对于当前URL处理。新URL必须与当前URL同源，否则 <code>pushState()</code> 会抛出一个异常。该参数是可选的，缺省为当前URL。</p>
 </li>
</ul>

<div class="note"><strong>注意:</strong> 从 Gecko 2.0 {{ geckoRelease("2.0") }} 到 Gecko 5.0 {{ geckoRelease("5.0") }}，传递的对象是使用JSON进行序列化的。 从  Gecko 6.0 {{ geckoRelease("6.0") }}开始，该对象的序列化将使用<a href="/en/DOM/The_structured_clone_algorithm" title="en/DOM/The structured clone algorithm">结构化克隆算法</a>。这将会使更多对象可以被安全的传递。</div>

<p>        在某种意义上，调用 <code>pushState()</code> 与 设置 <code>window.location = "#foo"</code> 类似，二者都会在当前页面创建并激活新的历史记录。但 <code>pushState()</code> 具有如下几条优点：</p>

<ul>
 <li>新的 URL 可以是与当前URL同源的任意URL 。相反，只有在修改哈希时，设置 <code>window.location</code> 才能是同一个 {{ domxref("document") }}。</li>
 <li>如果你不想改URL，就不用改。相反，设置 <code>window.location = "#foo";</code>在当前哈希不是 <code>#foo</code> 时， 才能创建新的历史记录项。</li>
 <li>你可以将任意数据和新的历史记录项相关联。而基于哈希的方式，要把所有相关数据编码为短字符串。 </li>
 <li>如果 <code>标题</code> 随后还会被浏览器所用到，那么这个数据是可以被使用的（哈希则不是）。</li>
</ul>

<p>注意 <code>pushState()</code> 绝对不会触发 <code>hashchange</code> 事件，即使新的URL与旧的URL仅哈希不同也是如此。</p>

<p>在 <a href="/en-US/docs/Mozilla/Tech/XUL">XUL</a> 文档中，它创建指定的 XUL 元素。</p>

<p>在其它文档中，它创建一个命名空间URI为<code>null</code>的元素。</p>

<h3 id="replaceState_方法">replaceState() 方法</h3>

<p><code>history.replaceState()</code> 的使用与 <code>history.pushState()</code> 非常相似，区别在于  <code>replaceState()</code>  是修改了当前的历史记录项而不是新建一个。 注意这并不会阻止其在全局浏览器历史记录中创建一个新的历史记录项。</p>

<p><code>replaceState()</code> 的使用场景在于为了响应用户操作，你想要更新状态对象state或者当前历史记录的URL。</p>

<div class="note"><strong>注意：</strong> 从Gecko 2.0 {{ geckoRelease("2.0") }} 到 Gecko 5.0 {{ geckoRelease("5.0") }}，传递的对象是使用JSON进行序列化的。 从  Gecko 6.0 {{ geckoRelease("6.0") }}开始，该对象的序列化将使用<a href="/en/DOM/The_structured_clone_algorithm" title="en/DOM/The structured clone algorithm">结构化克隆算法</a>。这将会使更多对象可以被安全的传递。</div>

<h3 id="replaceState_方法示例">replaceState() 方法示例</h3>

<p>假设 <span class="nowiki">http://mozilla.org/foo.html</span> 执行了如下JavaScript代码：</p>

<pre class="brush: js notranslate">let stateObj = {
    foo: "bar",
};

history.pushState(stateObj, "page 2", "bar.html");
</pre>

<p>上文2行代码可以在 "pushState()方法示例" 部分找到。然后，假设<span class="nowiki">http://mozilla.org/bar.html执行了如下</span> JavaScript：</p>

<pre class="brush: js notranslate">history.replaceState(stateObj, "page 3", "bar2.html");
</pre>

<p>这将会导致地址栏显示<span class="nowiki">http://mozilla.org/bar2.html</span>,，但是浏览器并不会去加载<code>bar2.html</code> 甚至都不需要检查 <code>bar2.html</code> 是否存在。</p>

<p>假设现在用户重新导向到了<span class="nowiki">http://www.microsoft.com，然后点击了回退按钮。这里，地址栏会显示</span><span class="nowiki">http://mozilla.org/bar2.html。假如用户再次点击回退按钮，地址栏会显示http://mozilla.org/foo.html，完全跳过了bar.html。</span></p>

<h3 id="popstate_事件">popstate 事件</h3>

<p>        每当活动的历史记录项发生变化时， <code>popstate</code> 事件都会被传递给window对象。如果当前活动的历史记录项是被 <code>pushState</code> 创建的，或者是由 <code>replaceState</code> 改变的，那么 <code>popstate</code> 事件的状态属性 <code>state</code> 会包含一个当前历史记录状态对象的拷贝。</p>

<p>使用示例请参见 {{ domxref("window.onpopstate") }} 。</p>

<h3 id="获取当前状态">获取当前状态</h3>

<p>        页面加载时，或许会有个非null的状态对象。这是有可能发生的，举个例子，假如页面（通过<code>pushState()</code> 或 <code>replaceState()</code> 方法）设置了状态对象而后用户重启了浏览器。那么当页面重新加载时，页面会接收一个<span style="font-family: courier new;">onload事件，但没有</span><span style="font-family: helvetica;"> <span style="font-family: courier new;">popstate</span> 事件。然而，假如你读取了</span><span style="font-family: courier new;">history.state属性，你将会得到如同</span><span style="font-family: courier new;">popstate</span> 被触发时能得到的状态对象。</p>

<p>你可以读取当前历史记录项的状态对象state，而不必等待<code>popstate</code> 事件， 只需要这样使用<code>history.state</code> 属性： </p>

<pre class="brush: js notranslate">  // 尝试通过 pushState 创建历史条目,然后再刷新页面查看state状态对象变化;
  window.addEventListener('load',() =&gt; {
    let currentState = history.state;
    console.log('currentState',currentState);
  })
</pre>

<h2 id="例子">例子</h2>

<p>完整的AJAX网站示例，请参阅： <a href="/en-US/docs/Web/Guide/API/DOM/Manipulating_the_browser_history/Example" title="/en-US/docs/Web/Guide/API/DOM/Manipulating_the_browser_history/Example">Ajax navigation example</a>.</p>

<h2 id="规范">规范</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
  <tr>
   <td>{{SpecName('HTML WHATWG', "browsers.html#history", "History")}}</td>
   <td>{{Spec2('HTML WHATWG')}}</td>
   <td>No change from {{SpecName("HTML5 W3C")}}.</td>
  </tr>
  <tr>
   <td>{{SpecName('HTML5 W3C', "browsers.html#history", "History")}}</td>
   <td>{{Spec2('HTML5 W3C')}}</td>
   <td>Initial definition.</td>
  </tr>
 </tbody>
</table>

<h2 id="浏览器兼容性">浏览器兼容性</h2>

<p>{{Compat("api.History")}}</p>

<h2 id="另见"><strong>另见</strong></h2>

<h3 id="参考"><strong>参考</strong></h3>

<ul>
 <li>{{ domxref("window.history") }}</li>
 <li>{{ domxref("window.onpopstate") }}</li>
</ul>

<h3 id="Guides">Guides</h3>

<ul>
 <li><a href="/zh-CN/docs/Web/API/History_API/Working_with_the_History_API">Working with the History API</a></li>
</ul>