简介

TOC Menu 是一个轻量级的目录导航组件，能够自动扫描页面中的标题标签（H1-H6），并生成可交互的目录菜单。当用户滚动页面时，目录会自动高亮当前正在阅读的章节。

该组件基于现代浏览器的 IntersectionObserver API 实现，性能优异，资源占用小。

核心特性

TOC Menu 提供了以下核心特性：

自动扫描

组件会自动扫描指定容器内的所有标题标签（H1-H6），无需手动配置目录结构。只需要确保你的标题标签包含唯一的 id 属性即可。

智能高亮

使用 IntersectionObserver API 监听标题元素的可见性，当标题进入视口时自动高亮对应的目录项，提供流畅的用户体验。

平滑滚动

点击目录项时，页面会平滑滚动到对应的标题位置，使用原生的 scrollIntoView 方法实现，无需额外的依赖库。

安装方式

TOC Menu 支持多种安装方式，适应不同的使用场景。

通过 npm 安装

推荐使用包管理器安装：

npm install toc-nav
# 或者
yarn add toc-nav
# 或者
pnpm add toc-nav

npm 使用示例

在你的项目中引入并使用：

import { TocMenu } from 'toc-nav';
import 'toc-nav/style.css';

const toc = new TocMenu({
  contentElement: document.getElementById('content'),
  tocElement: document.getElementById('toc-container'),
  useHash: true
});

通过 CDN 引入

如果不想使用构建工具，可以直接通过 CDN 引入：

<!-- 引入样式 -->
<link rel="stylesheet" href="./toc-nav/dist/style.css">

<!-- 引入脚本 -->
<script src="./toc-nav/dist/index.global.js"></script>

<script>
  new TocMenu.TocMenu({
    contentElement: document.getElementById('content'),
    tocElement: document.getElementById('toc-container'),
    useHash: true
  });
</script>

使用指南

本页面就是一个完整的使用示例，展示了 TOC Menu 的所有功能。

基础配置

创建 TOC Menu 实例时需要提供以下配置：

内容容器 (contentElement)

指定需要扫描标题的容器元素。组件会在该容器内查找所有标题标签。如果内容在特定的滚动容器内（而非整个页面），请确保传入正确的容器元素。

目录容器 (tocElement)

指定用于渲染目录的容器元素。目录会以列表的形式渲染在该元素内。

使用 Hash (useHash)

是否在 URL 中使用 Hash 来标识当前章节。当设置为 true 时，点击目录项会更新 URL 的 Hash 部分，方便分享和书签收藏。

高级功能

除了基础功能外，TOC Menu 还提供了一些高级特性。

动态刷新

如果页面内容是动态加载的（例如富文本编辑器、Markdown 渲染器等），可以调用 refresh() 方法来重新扫描标题并更新目录。

// 内容更新后刷新目录
toc.refresh();

SPA 框架集成

TOC Menu 可以无缝集成到 React、Vue、Angular 等单页应用框架中。只需要在组件挂载后创建实例，在内容更新时调用 refresh() 即可。

自定义样式

组件提供了默认样式，但你可以通过覆盖 CSS 类来自定义外观。主要的 CSS 类包括：.toc-list、.toc-item、 .toc-item.active 等。

浏览器兼容性

TOC Menu 支持所有现代浏览器：

桌面浏览器

Chrome / Edge ≥ 51
Firefox ≥ 55
Safari ≥ 12.1

移动浏览器

iOS Safari ≥ 12.2
Chrome for Android ≥ 51

所需 Web API

组件依赖以下现代 Web API：

IntersectionObserver - 用于监听元素可见性
ResizeObserver - 用于响应容器大小变化
scrollend 事件 - 用于检测滚动结束

性能优化

TOC Menu 在设计时充分考虑了性能问题。

延迟观察

使用 IntersectionObserver API 实现懒观察，只在元素进入或离开视口时触发回调，避免频繁的滚动事件监听。

智能更新

refresh() 方法在更新前会进行深度对比，只有当标题结构真正发生变化时才会重新渲染，避免不必要的 DOM 操作。

内存管理

组件会自动管理观察器的生命周期，在刷新时先断开旧的观察，避免内存泄漏和冗余回调。

最佳实践

以下是使用 TOC Menu 的一些最佳实践建议。

确保 ID 唯一性

每个标题的 id 属性必须是唯一的，否则可能导致锚点定位错误。建议使用语义化的 ID 名称，例如 id="introduction" 而不是 id="h1"。

正确指定滚动容器

如果你的内容在特定的滚动容器内（而非整个页面滚动），务必将该容器传入 contentElement 参数，否则 IntersectionObserver 无法正确工作。

处理动态内容

对于动态加载的内容，记得在内容加载完成后调用 refresh()。如果使用富文本编辑器，可以监听内容变化事件并适时刷新目录。

常见问题

为什么目录没有显示？

请检查以下几点：
1. 标题标签是否包含 id 属性
2. CSS 样式文件是否正确引入
3. JavaScript 是否正确初始化
4. 浏览器控制台是否有错误信息

为什么高亮的目录项不正确？

这可能是因为滚动容器配置错误。请确保 contentElement 参数指向的是实际发生滚动的容器元素。

在 React 中目录没有更新？

当组件内容更新后，需要手动调用 refresh() 方法。建议使用 useEffect 监听内容变化并触发刷新。

总结

TOC Menu 是一个简单而强大的目录导航组件，适用于文档网站、博客、在线书籍等各种场景。它提供了优雅的用户体验，同时保持了代码的简洁性。

感谢使用 TOC Menu！如果你有任何问题或建议，欢迎在 GitHub 上提 Issue。