History.pushState()

History API

HTML 文档中,history.pushState() 方法向当前浏览器会话的历史堆栈中添加一个状态(state)。

语法

history.pushState(state, title[, url])

参数

state
状态对象是一个JavaScript对象,它与pushState()创建的新历史记录条目相关联。 每当用户导航到新状态时,都会触发popstate (en-US)事件,并且该事件的状态属性包含历史记录条目的状态对象的副本。
状态对象可以是任何可以序列化的对象。 因为Firefox将状态对象保存到用户的磁盘上,以便用户重新启动浏览器后可以将其还原,所以我们对状态对象的序列化表示施加了640k个字符的大小限制。 如果将序列化表示形式大于此状态的状态对象传递给pushState(),则该方法将引发异常。 如果您需要更多空间,建议您使用 sessionStorage或者localStorage
title
当前大多数浏览器都忽略此参数,尽管将来可能会使用它。 在此处传递空字符串应该可以防止将来对方法的更改。 或者,您可以为要移动的状态传递简短的标题。
url 可选
新历史记录条目的URL由此参数指定。 请注意,浏览器不会在调用pushState() 之后尝试加载此URL,但可能会稍后尝试加载URL,例如在用户重新启动浏览器之后。 新的URL不必是绝对的。 如果是相对的,则相对于当前URL进行解析。 新网址必须与当前网址相同 origin; 否则,pushState()将引发异常。 如果未指定此参数,则将其设置为文档的当前URL。

描述

从某种程度来说, 调用 pushState() 和 window.location = "#foo"基本上一样, 他们都会在当前的document中创建和激活一个新的历史记录。但是 pushState() 有以下优势:

  • 新的URL可以是任何和当前URL同源的URL。但是设置 window.location 只会在你只设置锚的时候才会使当前的URL。
  • 非强制修改URL。相反,设置 window.location = "#foo"; 仅仅会在锚的值不是#foo情况下创建一条新的历史记录。
  • 可以在新的历史记录中关联任何数据。window.location = "#foo"形式的操作,你只可以将所需数据写入锚的字符串中。

注意: pushState() 不会造成 hashchange (en-US) 事件调用, 即使新的URL和之前的URL只是锚的数据不同。

示例

以下代码通过设置statetitleurl创建一条新的历史记录。

JavaScript

const state = { 'page_id': 1, 'user_id': 5 }
const title = ''
const url = 'hello-world.html'

history.pushState(state, title, url)

规范

规范 状态 备注
HTML Living Standard
History.pushState()
Living Standard 没有改变HTML5.
HTML5
History.pushState()
Recommendation 初始化

浏览器兼容性

BCD tables only load in the browser

参见