问题

传统的单页导航中，每次点击链接都会触发完整的浏览器重新加载，这会产生令人不适的“白屏闪烁”并打断读者的思路。浏览器必须丢弃当前状态，请求新的 HTML，并重新解析 CSS 和 JavaScript——即使只有中心内容区域发生了变化。

为什么重要

文档用户经常在不同章节之间跳转，例如教程、API 参考和概念指南。如果每次切换都需要一秒钟或更长时间，就会产生认知摩擦并阻碍深入探索。即时导航使文档感觉像是一个原生应用程序，显著提高了用户满意度和参与度。

方法

docmd 利用构建在预生成静态文件之上的高性能 单页应用 (SPA) 路由。这允许浏览器拦截链接点击，仅在后台获取必要的内容，并动态更新页面而无需完整重新加载。这种方法保留了侧边栏、目录和主题设置的状态，从而实现近乎瞬时的切换。

实施

docmd 的 SPA 路由默认启用，并使用几种先进技术来实现亚秒级导航速度：

1. 基于意图的预取

当用户将鼠标悬停在导航链接上时，docmd 会检测到导航意图并开始后台获取目标页面的内容。当用户真正点击链接时，数据通常已经存在于浏览器的缓存中，使得切换感觉是瞬间完成的。

2. 局部 DOM 更新

docmd 不是重新渲染整个页面，而是智能地仅更新必要的逻辑区域：

• 主体内容 (Main Content)：经过 Markdown 渲染的主要正文。
• 目录 (Table of Contents)：刷新以匹配新页面的标题。
• 导航状态 (Navigation State)：更新侧边栏中的活动和展开状态。

3. 用于自定义逻辑的生命周期事件

由于浏览器不执行完整加载，标准事件（如 DOMContentLoaded）仅触发一次。要在每次导航后执行自定义 JavaScript（例如重新初始化第三方小部件或跟踪页面视图），您应该监听 docmd:page-mounted 事件。

// 示例：导航后重新初始化自定义组件
document.addEventListener('docmd:page-mounted', (event) => {
  const currentPath = event.detail.path;
  console.log(`成功导航至：${currentPath}`);
  
  // 在此处编写自定义逻辑
  if (currentPath.includes('/api/')) {
    initApiConsole();
  }
});

有关更多详细信息，请参阅 客户端事件 文档。

权衡

脚本执行

SPA 路由会自动重新执行新页面 Markdown 正文中的 <script> 标签。但是，在您的主题或布局中定义的全局脚本仅在初始加载期间运行一次。对于必须在每个页面上执行的逻辑，请始终使用 docmd:page-mounted 事件。

SEO 和无障碍

尽管具有类似 SPA 的行为，docmd 仍然为每个页面生成完整的、独立的 .html 文件。这确保了搜索引擎爬虫可以抓取全部内容，并且对于禁用 JavaScript 的用户，网站仍然功能完备，从而保持了卓越的 SEO 和无障碍标准。