事件 - htmx:replacedInHistory

htmx:replacedInHistory 是 HTMX 在使用 history.replaceState() 修改浏览器地址栏后触发的事件。

你可以监听这个事件来响应 URL 的替换操作，比如更新 UI 状态、面包屑导航、记录埋点等。

HTMX 中用于改变浏览器地址栏的属性是 hx-push-url：

• hx-push-url="true" → 使用 pushState()，添加历史记录 → 触发 htmx:pushedIntoHistory

• hx-push-url="false" → 不改变 URL（默认行为）→ 不触发任何历史事件

• hx-push-url="replace" → 使用 replaceState() 替换当前记录 → 触发 htmx:replacedInHistory

事件参数

• detail.path - 历史记录中被替换的 URL 的路径和查询

示例代码

<nav>
  <a href="/dashboard" 
     hx-get="/dashboard" 
     hx-target="#content" 
     hx-push-url="replace">仪表盘（Replace URL）</a>
</nav>

<div id="content">
  <p>点击上方链接加载仪表盘，并替换当前地址栏 URL。</p>
</div>

<script>
  document.body.addEventListener("htmx:replacedInHistory", function(evt) {
    console.log("当前历史记录已被替换为：", window.location.pathname);
    // 可执行：更新 UI、记录分析、刷新导航等
  });
</script>

以上示例代码中，用户点击链接，HTMX 发送 AJAX 请求加载内容。设置了 hx-push-url="replace"，HTMX 会执行：history.replaceState(...)，浏览器地址栏更新，但不会新增历史记录项。此时触发 htmx:replacedInHistory 事件。

你可以在事件监听器中做 UI 或状态更新。

常见用途

用途	示例
更新地址栏但不增加历史记录	表单验证状态改变时
改变 URL 参数	用于搜索过滤、分页切换
同步 UI 状态	更新导航高亮、状态提示等
与前端路由联动	Vue/React 混合场景中更新地址栏但不跳转

与其他 HTMX 历史事件对比

事件名	说明
htmx:pushedIntoHistory	使用 pushState() 后触发（新增历史项）
htmx:replacedInHistory	使用 replaceState() 后触发（替换当前项）
htmx:historyRestore	浏览器后退/前进时触发