事件 - htmx:beforeHistorySave

htmx:beforeHistorySave 是 HTMX 在即将把当前页面状态保存到浏览器历史记录中时触发的事件。

你可以在这个事件中：

• 修改即将保存的历史状态（如 DOM 快照或 URL）

• 添加自定义状态字段（如当前页签、滚动位置）

• 控制保存行为（如阻止某些页面被保存）

它通常配合 hx-push-url="true" 或 hx-history="true" 使用。

触发时机

• HTMX 准备调用 history.pushState() 或 history.replaceState() 之前

• 页面内容更新后，但在历史记录实际更新前

事件参数

• detail.path - 正在恢复的页面的路径和查询
• detail.historyElt - 历史被恢复到的元素
• detail.configEventSource - 将传递给构造函数的配置

示例：记录滚动位置到历史记录

<a hx-get="/page1" hx-target="#main" hx-push-url="true">加载 Page 1</a>
<a hx-get="/page2" hx-target="#main" hx-push-url="true">加载 Page 2</a>

<div id="main" style="height: 200px; overflow: auto;">
  <!-- 可滚动内容区域 -->
</div>

<script>
  document.body.addEventListener("htmx:beforeHistorySave", function (event) {
    const scrollTop = document.querySelector("#main").scrollTop;

    // 将滚动位置写入 history state
    event.detail.history.scrollTop = scrollTop;
    console.log("将滚动位置保存进历史记录：", scrollTop);
  });

  // 当恢复历史状态时还原滚动位置
  document.body.addEventListener("htmx:historyRestore", function (event) {
    const scrollTop = event.detail.cache?.scrollTop || 0;
    document.querySelector("#main").scrollTop = scrollTop;
    console.log("从历史中恢复 scrollTop：", scrollTop);
  });
</script>

使用场景

用途	示例
保存滚动位置	上述示例所示
保存分页状态	如表格当前第几页、第几行
保存筛选条件	搜索框、过滤选项的状态
自定义标签页标识	例如某个 tab 被选中时记录 tab ID
修改 path	修改 URL 中的查询参数或 hash 部分