History: pushState() 方法

语法

pushState(state, unused)
pushState(state, unused, url)

参数

state

state 对象是一个 JavaScript 对象，它与 pushState() 创建的新历史条目相关联。每当用户导航到新的 state 时，就会触发一个 popstate 事件，并且事件的 state 属性包含历史条目 state 对象的一个副本。

state 对象可以是任何可序列化的内容。

注意： 某些浏览器会将 state 对象保存到用户的磁盘上，以便在用户重启浏览器后进行恢复，并且会对 state 对象的序列化表示施加大小限制，如果您传递的 state 对象的序列化表示大于该大小限制，则会抛出异常。因此，如果您希望确保有比某些浏览器可能施加的更多的空间，建议使用 sessionStorage 和/或 localStorage。

unused

此参数是出于历史原因而存在的，不能省略；传递空字符串可以防止将来对该方法进行更改。

url 可选

新历史条目的 URL。请注意，浏览器在调用 pushState() 后不会尝试加载此 URL，但之后可能会尝试加载该 URL，例如，在用户重启浏览器后。新 URL 不需要是绝对路径；如果是相对路径，则会相对于当前 URL 进行解析。新 URL 必须与当前 URL 具有相同的 源；否则，pushState() 将抛出异常。如果未指定此参数，则将其设置为文档的当前 URL。

返回值

无（undefined）。

异常

SecurityError DOMException

如果关联的文档不是完全活动的，或者提供的 url 参数不是有效的 URL，或者该方法被调用的频率过高，则会抛出此异常。

DataCloneError DOMException

如果提供的 state 参数不可序列化，则会抛出此异常。

描述

某种程度上，调用 pushState() 类似于设置 window.location = "#foo"，因为两者都会创建并激活与当前文档关联的另一个历史条目。但是 pushState() 有一些优点：

• 新的 URL 可以是与当前 URL 同源的任何 URL。相比之下，设置 window.location 只有在仅修改哈希时才将您保留在同一文档中。
• 更改页面的 URL 是可选的。相比之下，设置 window.location = "#foo"; 仅当当前哈希不是 #foo 时才会创建新的历史条目。
• 您可以将任意数据与新的历史条目关联。使用基于哈希的方法，您需要将所有相关数据编码成一个短字符串。

请注意，pushState() 永远不会触发 hashchange 事件，即使新 URL 与旧 URL 仅在哈希部分不同。

示例

这会创建一个新的浏览器历史条目，设置 state 和 url。

JavaScript

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

history.pushState(state, "", url);

更改查询参数

const url = new URL(location);
url.searchParams.set("foo", "bar");
history.pushState({}, "", url);

规范

浏览器兼容性

另见

• 使用 History API
• Window: popstate 事件