历史记录：pushState() 方法

pushState() 是 History 接口的一个方法，它向浏览器的会话历史堆栈添加一个条目。

语法

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

参数

state

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

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

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

未用

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

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 不同。

示例

这将创建一个新的浏览器历史记录条目，设置状态和URL。

JavaScript

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

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

更改查询参数

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

规范

规范
HTML 标准
# dom-history-pushstate-dev

浏览器兼容性

BCD 表格仅在启用 JavaScript 的浏览器中加载。

另请参阅