编辑“︁HTML历史API”︁（章节）

= HTML历史API =

'''HTML历史API'''（History API）是现代Web开发中用于操作浏览器会话历史的核心接口，它允许开发者以编程方式添加、修改或读取浏览历史记录，而无需重新加载页面。此技术是实现'''单页应用（SPA）'''和无刷新页面导航的关键。

== 概述 ==
历史API通过{{code|window.history}}对象提供，主要功能包括：
* 动态修改URL（不触发页面刷新）
* 存储和读取与历史条目关联的状态数据
* 监听用户导航行为（前进/后退）

传统Web应用中，每次URL变更都会导致页面完全刷新。历史API打破了这一限制，使得现代Web应用能提供更接近原生应用的流畅体验。

== 核心方法 ==
=== pushState() ===
向历史堆栈添加新记录并更新URL：
<syntaxhighlight lang="javascript">
// 语法：history.pushState(state, title[, url])
history.pushState(
  { page: "settings" },  // 状态对象
  "Settings Page",       // 标题（现代浏览器通常忽略）
  "/settings"            // 可选的新URL
);
</syntaxhighlight>

'''参数说明：'''
* {{code|state}}：可序列化的关联数据（最大640k）
* {{code|title}}：历史条目标题（多数浏览器未实现）
* {{code|url}}：新相对/绝对路径（需同源）

=== replaceState() ===
替换当前历史记录而不新增条目：
<syntaxhighlight lang="javascript">
history.replaceState(
  { page: "updated" },
  "Updated Page",
  "/updated"
);
</syntaxhighlight>

=== popstate 事件 ===
当用户导航历史记录时触发：
<syntaxhighlight lang="javascript">
window.addEventListener('popstate', (event) => {
  console.log("导航至状态:", event.state);
  // 通常在此处更新UI以匹配新状态
});
</syntaxhighlight>

== 状态管理 ==
历史API的状态对象支持复杂数据结构：
<syntaxhighlight lang="javascript">
const projectState = {
  id: 123,
  view: "3d-preview",
  layers: [1, 3, 5],
  lastUpdated: Date.now()
};
history.pushState(projectState, "", "/project/123");
</syntaxhighlight>

'''最佳实践：'''
* 只存储必要标识符而非完整数据
* 状态大小控制在2MB以内（各浏览器限制不同）
* 使用JSON.parse(JSON.stringify())深拷贝避免引用问题

== 实际应用案例 ==
=== 单页应用路由 ===
典型SPA路由实现：
<syntaxhighlight lang="javascript">
// 路由配置
const routes = {
  '/': showHomePage,
  '/about': showAboutPage,
  '/contact': showContactPage
};

// 初始化路由
function navigate(path) {
  const handler = routes[path];
  if (handler) {
    handler();
    history.pushState({ path }, null, path);
  }
}

// 处理浏览器后退/前进
window.addEventListener('popstate', (e) => {
  const path = e.state?.path || window.location.pathname;
  routes[path]?.();
});
</syntaxhighlight>

=== 表单多步骤向导 ===
保存各步骤状态而不提交：
<mermaid>
graph LR
  A[步骤1] -->|pushState| B[步骤2]
  B -->|pushState| C[步骤3]
  C -->|用户点击返回| B
  B -->|用户点击返回| A
</mermaid>

对应代码实现：
<syntaxhighlight lang="javascript">
let formData = {};

function goToStep(step, data) {
  Object.assign(formData, data);
  history.pushState({ step }, `Step ${step}`, `?step=${step}`);
  renderStep(step);
}

window.addEventListener('popstate', (e) => {
  const step = e.state?.step || 1;
  renderStep(step);
});
</syntaxhighlight>

== 数学建模 ==
历史堆栈可视为'''有限状态自动机'''：
<math>
H = (Q, \Sigma, \delta, q_0, F)
</math>
其中：
* <math>Q</math> = 所有可能的历史状态集合
* <math>\Sigma</math> = {push, replace, back, forward}
* <math>\delta</math> = 状态转移函数
* <math>q_0</math> = 初始页面状态
* <math>F</math> = 可接受状态

== 浏览器兼容性 ==
{| class="wikitable"
|+ 主要浏览器支持情况
! 特性
! Chrome
! Firefox
! Safari
! Edge
|-
| pushState/replaceState
| 5+
| 4+
| 5+
| 12+
|-
| popstate事件
| 5+
| 4+
| 5+
| 12+
|-
| state大小限制
| 2MB
| 2MB
| 640KB
| 1MB
|}

== 安全限制 ==
* '''同源策略'''：只能修改当前域下的URL路径
* '''用户交互要求'''：部分浏览器要求pushState必须在用户触发的事件（如click）中调用
* '''URL编码'''：非ASCII字符需手动编码

== 调试技巧 ==
使用Chrome DevTools检查历史状态：
# 打开开发者工具（F12）
# 进入"Application"面板
# 查看"History"下的状态快照

== 常见问题 ==
=== 为什么URL变了但页面没更新？ ===
pushState()'''仅修改URL'''而不触发加载。需要手动监听变化：
<syntaxhighlight lang="javascript">
// 错误做法：期望自动刷新
history.pushState({}, "", "/new-url");

// 正确做法：主动更新UI
function updateRoute() {
  const path = window.location.pathname;
  // 根据path更新DOM
}
history.pushState({}, "", "/new-url");
updateRoute();
</syntaxhighlight>

=== 如何检测浏览器支持？ ===
<syntaxhighlight lang="javascript">
if (window.history && history.pushState) {
  // API可用
} else {
  // 回退方案（如整页刷新）
}
</syntaxhighlight>

== 进阶主题 ==
* 与{{code|window.location}}API的协同使用
* 服务端渲染（SSR）中的历史API处理
* 滚动位置恢复技术
* 历史状态加密方案

通过掌握历史API，开发者可以创建更动态、响应更快的Web应用，同时保持可访问的URL结构和完整的浏览器历史记录。

[[Category:编程语言]]
[[Category:HTML]]
[[Category:HTML高级特性]]