历史记录:replaceState() 方法

replaceState()History 接口的方法,它修改当前的历史记录条目,用方法参数中传递的状态对象和 URL 替换它。当您想要响应某些用户操作更新当前历史记录条目的状态对象或 URL 时,此方法特别有用。

语法

js
replaceState(state, unused)
replaceState(state, unused, url)

参数

state

与传递给 replaceState() 方法的历史记录条目关联的对象。状态对象可以为 null

未用

此参数出于历史原因存在,并且不能省略;传递空字符串是传统的,并且可以防止方法将来发生更改。

url 可选

历史记录条目的 URL。新 URL 必须与当前 URL 具有相同的来源;否则,replaceState() 方法将抛出异常。

返回值

无 (undefined)。

异常

SecurityError DOMException

如果关联的文档未完全激活,或者提供的 url 参数不是有效的 URL,则抛出此异常。浏览器还会限制导航,如果过于频繁地调用此方法,可能会抛出此错误、生成警告或忽略调用。

DataCloneError DOMException

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

示例

假设 https://www.mozilla.org/foo.html 执行以下 JavaScript 代码

js
const stateObj = { foo: "bar" };
history.pushState(stateObj, "", "bar.html");

在下一页,您可以使用 history.state 访问刚刚添加的 stateObj

上面这两行的解释可以在 使用历史记录 API 文章中找到。然后假设 https://www.mozilla.org/bar.html 执行以下 JavaScript 代码

js
history.replaceState(stateObj, "", "bar2.html");

这将导致 URL 地址栏显示 https://www.mozilla.org/bar2.html,但不会导致浏览器加载 bar2.html 甚至检查 bar2.html 是否存在。

现在假设用户导航到 https://www.microsoft.com,然后单击“后退”按钮。此时,URL 地址栏将显示 https://www.mozilla.org/bar2.html。如果用户现在再次单击“后退”,URL 地址栏将显示 https://www.mozilla.org/foo.html,并且完全绕过 bar.html。

规范

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

浏览器兼容性

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