HTML Academy · 课时

pushState 与 replaceState

无需完整重新加载页面即可更新浏览器 URL

pushState 与 replaceState 是 CoddyKit 上的免费 HTML Academy 课时。这是第 1 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 HTML Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 HTML Academy 课程共包含 4 节课。

历史记录接口

历史记录接口允许页面更改地址栏中显示的地址，而不会触发完整的导航。结合客户端渲染，它可以支持具有原生体验的单页应用，同时保留可收藏的地址。

pushState

history.pushState(state, "", url) 会向浏览器历史记录添加一条新记录。地址栏中的地址会立即更新，不会发起网络请求。用户可以使用浏览器的后退按钮返回上一条记录。

history.pushState({ view: "settings" }, "", "/settings");

状态参数

第一个参数是附加到该记录的任意可序列化数据。之后可以通过 history.state 或历史记录变化事件中的状态读取它。可以使用它传递界面状态（例如打开的是哪个标签页、滚动位置），这样用户返回时就能恢复完全相同的视图。

title 参数

第二个参数是历史记录项的标题。在实践中，所有现代浏览器都会忽略它——请直接设置 document.title = "..." 来更改标题。按照惯例传入空字符串；它不会产生任何效果。

url 参数

第三个参数是新的 URL。相对 URL 会根据当前页面解析；新的 URL 必须与当前页面同源（跨源时会抛出 SecurityError）。浏览器不会获取这个 URL——pushState 只会更新地址栏和历史记录。

replaceState

history.replaceState(state, "", url) 会替换当前历史记录项，而不是新增一项。当您想在不创建新的返回导航步骤的情况下更新 URL 时使用它（例如更新筛选条件的查询字符串）。

// Update query string in place
const url = new URL(location);
url.searchParams.set("filter", "open");
history.replaceState(null, "", url);

pushState 的使用场景

SPA route 变更（点击导航链接而不进行完整重新加载）、打开模态框（这样返回按钮可以关闭模态框）、向导中的步骤切换。每个有意义的状态都应成为新的历史记录项，这样返回按钮的行为才符合用户预期。

replaceState 的使用场景

不应污染历史记录的筛选、排序和分页更新；部分完成表单后的重定向；更新跟踪参数而不创建可导航的历史记录项。用户按下返回按钮时会跳过这些“中间”状态。

pushState 后更新视图

pushState 只会更改 URL，您的代码必须另外更新 DOM。处理模式是：先渲染新内容，再调用 pushState。两者结合起来才能实现 SPA 体验。

function navigate(path) {
  renderPage(path);
  history.pushState(null, "", path);
  window.scrollTo(0, 0);
}

更新标题和元数据

导航后请更新 document.title 和 og:title 元标签，使社交分享内容和浏览器标签页标题反映当前视图。忘记更新会导致后续分享仍显示原始标题，这是 SPA 中一个隐蔽但常见的错误。

页面加载时的初始 pushState

在用户进行导航之前调用 pushState 会覆盖初始历史记录项。若要为页面的第一条历史记录项附加状态，请改用 replaceState——它会添加状态而不改变历史记录深度。

安全限制

pushState 的 URL 必须与当前页面同源。尝试将 pushState 指向 https://evil.com 会抛出 SecurityError。这可以防止页面伪造地址栏，让用户误以为自己位于另一个网站。

知识检查

history.replaceState 做了什么，而 history.pushState 不会做什么？

总结

pushState 会在不重新加载页面的情况下新增历史记录项，这是 SPA 路由的基础。replaceState 会原地更新当前记录项，适用于装饰性的 URL 变更。两者都要求 URL 同源，并且都会忽略 title 参数。请始终另外更新 DOM，并记得在导航后更新 document.title 和元标签。

常见问题解答

「pushState 与 replaceState」课时是免费的吗？

是的 — 「pushState 与 replaceState」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 HTML Academy 课程的其余内容，请升级到 CoddyKit PRO。 HTML Academy 课程共包含 4 节课。

「pushState 与 replaceState」这节课中我会学到什么？

无需完整重新加载页面即可更新浏览器 URL 你通过在浏览器中直接运行的动手代码来练习 HTML Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 HTML Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 HTML Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 1 节课，共 4 节。

「pushState 与 replaceState」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 HTML Academy 课中编写并运行代码吗？

能。每节 HTML Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 HTML Academy