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

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

意义及使用

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

向前和向后跳转

在history中向后跳转:

window.history.back();

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

类似地,你可以向前跳转(如同用户点击了前进按钮):

window.history.forward();

跳转到 history 中指定的一个点

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

向后移动一个页面 (等同于调用 back()):

window.history.go(-1);

向前移动一个页面, 等同于调用了 forward():

window.history.go(1);

类似地,你可以传递参数值2并向前移动2个页面,等等。

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

 let numberOfEntries = window.history.length;
注意: IE 支持传递URLs作为参数给 go(); 这在Gecko是不标准且不支持的。

添加和修改历史记录中的条目

{{ gecko_minversion_header("2") }}

HTML5引入了 history.pushState() 和 history.replaceState() 方法,它们分别可以添加和修改历史记录条目。这些方法通常与{{ domxref("window.onpopstate") }} 配合使用。

使用 history.pushState() 可以改变referrer,它在用户发送 XMLHttpRequest 请求时在HTTP头部使用,改变state后创建的 XMLHttpRequest 对象的referrer都会被改变。因为referrer是标识创建  XMLHttpRequest 对象时 this 所代表的window对象中document的URL。

pushState() 方法的例子

假设在 http://mozilla.org/foo.html 页面的console中执行了以下 JavaScript 代码:

window.onpopstate = function(e) {
   alert(2);
}

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

history.pushState(stateObj, "page 2", "bar.html");

这将使浏览器地址栏显示为 http://mozilla.org/bar.html,但并不会导致浏览器加载 bar.html ,甚至不会检查bar.html 是否存在。

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

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

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

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

pushState() 方法

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

注意: 从 Gecko 2.0 {{ geckoRelease("2.0") }} 到 Gecko 5.0 {{ geckoRelease("5.0") }},传递的对象是使用JSON进行序列化的。 从  Gecko 6.0 {{ geckoRelease("6.0") }}开始,该对象的序列化将使用结构化克隆算法。这将会使更多对象可以被安全的传递。

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

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

在 XUL 文档中,它创建指定的 XUL 元素。

在其它文档中,它创建一个命名空间URI为null的元素。

replaceState() 方法

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

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

注意: 从Gecko 2.0 {{ geckoRelease("2.0") }} 到 Gecko 5.0 {{ geckoRelease("5.0") }},传递的对象是使用JSON进行序列化的。 从  Gecko 6.0 {{ geckoRelease("6.0") }}开始,该对象的序列化将使用结构化克隆算法。这将会使更多对象可以被安全的传递。

replaceState() 方法示例

假设 http://mozilla.org/foo.html 执行了如下JavaScript代码:

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

history.pushState(stateObj, "page 2", "bar.html");

上文2行代码可以在 "pushState()方法示例" 部分找到。然后,假设http://mozilla.org/bar.html执行了如下 JavaScript:

history.replaceState(stateObj, "page 3", "bar2.html");

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

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

popstate 事件

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

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

获取当前状态

        页面加载时,或许会有个非null的状态对象。这是有可能发生的,举个例子,假如页面(通过pushState() 或 replaceState() 方法)设置了状态对象而后用户重启了浏览器。那么当页面重新加载时,页面会接收一个onload事件,但没有 popstate 事件。然而,假如你读取了history.state属性,你将会得到如同popstate 被触发时能得到的状态对象。

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

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

例子

完整的AJAX网站示例,请参阅: Ajax navigation example.

规范

Specification Status Comment
{{SpecName('HTML WHATWG', "browsers.html#history", "History")}} {{Spec2('HTML WHATWG')}} No change from {{SpecName("HTML5 W3C")}}.
{{SpecName('HTML5 W3C', "browsers.html#history", "History")}} {{Spec2('HTML5 W3C')}} Initial definition.

浏览器兼容性

{{Compat("api.History")}}

另见

参考

Guides