Smart TOC & Scroll

一个面向长文与文档站点的 Chrome 扩展，为网页提供轻量阅读导航。当前提供两种导航类型：标准目录面板 与 Barcode；Barcode 可进一步选择滚轮、聚光灯或GPT标题预览。扩展支持主题自适应、hover 标题预览、已有控件避让与 SPA 页面更新，并提供平滑回顶能力。

当前版本：2.13（Manifest V3）。

功能特点

• 智能主题适配

  • 基于页面背景亮度自动选择浅色或深色浮层
  • Barcode 会额外采样 rail 附近的局部背景，克制调整短横线、回顶按钮与预览标题的对比度
  • 边缘 rail 本体保持透明背景，避免像独立面板一样遮挡正文
  • 使用磨砂玻璃风格主题变量
  • DOM 变化后自动重新应用主题
  • TOC 浮标与展开面板使用统一主题

• 回到顶部操作

  • 面板顶部提供 Top 按钮
  • 平滑滚动回到页面顶部
  • 与目录导航处于同一交互上下文
  • 在 Barcode 下，回顶按钮以低透明度独立显示，鼠标靠近时会轻柔显形并用水面回弹动效提示，hover 或键盘聚焦后进入稳定选中态

• 目录树功能

  • 自动生成页面目录
  • 智能识别标题层级
  • 平滑的展开/收起动画
  • 标题层级缩进与当前章节高亮
  • 长目录中自动将当前高亮章节滚动到可视区域
  • 点击章节后短暂保持目标高亮，避免平滑滚动期间反馈跳到相邻标题
  • 智能过滤导航栏和侧边栏内容
  • 支持自定义标题样式识别
  • 支持键盘导航、ARIA 属性与焦点态

• 阅读导航样式

  • 标准目录面板：适合文档站、博客和技术内容页面
  • Barcode：适合沉浸式长文阅读，用透明 rail 与短横线表达章节位置，悬停时向外产生 wave 延展
    • 滚轮：标题在固定观察窗内滚动，当前项进入固定焦点位置
    • 聚光灯：hover 时显示当前可见的完整标题列；命中项最清晰，高亮向上下各 1–2 项渐隐，不使用边框
    • GPT：idle 保留纯条形码；hover 时展开带背景和边框的完整标题面板，支持面板内滚动与标题跳转

• 性能监控

  • 实时监控目录生成性能
  • 跟踪目录更新性能
  • 监控滚动性能
  • 跟踪 rail pointer 与自适应主题热路径
  • 内存使用情况分析
  • 使用 Ctrl + Shift + P 快捷键查看性能统计
  • 当前章节高亮优先使用 IntersectionObserver，减少滚动时的布局读取

智能内容识别

• 自动识别主要内容区域

  • 支持多种内容容器选择器
  • 智能分析页面结构
  • 过滤无关内容
  • 适应不同网站布局

• 标题识别增强

  • 支持标准 HTML 标题标签
  • 识别自定义标题样式
  • 基于字体大小和权重判断层级
  • 智能过滤隐藏元素

安装方法

1. 从 Chrome 网上应用店安装

   • 访问 Chrome 网上应用店
   • 点击"添加到 Chrome"

2. 手动安装

   • 下载最新版本的 ZIP 文件
   • 解压文件
   • 打开 Chrome 浏览器，进入扩展程序页面 (chrome://extensions/)
   • 开启"开发者模式"
   • 点击"加载已解压的扩展程序"
   • 选择解压后的文件夹

使用方法

1. 滚动到顶部

   • 展开 TOC 面板后点击顶部 Top 按钮
   • 页面会平滑滚动到顶部

2. 使用目录树

   • 标准目录面板 默认悬停预览，点击浮标可固定展开
   • 也可在设置中改为“点击开关”或“高级：短按回顶 / 长按展开”
   • 点击目录项可以跳转到对应的标题位置
   • 点击面板顶部 Top 按钮可直接回顶
   • 点击面板外部区域或按 Esc 可收起固定展开的面板
   • 可用 Esc 折叠面板，方向键在目录项间移动
   • 当前阅读位置会在目录中高亮
   • Barcode / 滚轮 使用固定观察窗和全量标题 track，鼠标沿 bar 移动时标题像机械表日期窗一样滑动
   • Barcode / 聚光灯 不移动标题列；hover / focus 时显示所有当前可见标题，只让亮度与缩放焦点平滑移动，离开后全部收起
   • Barcode / GPT 平时只显示短横线；hover / focus 后展开可滚动的完整标题面板，并自动让命中项进入可视区域
   • GPT 面板使用单一 Tab 停靠点，可用方向键、Home / End 在标题间移动

3. 性能监控

   • 使用 Ctrl + Shift + P 快捷键显示/隐藏性能统计面板
   • 查看目录生成、更新和滚动的性能指标
   • 监控内存使用情况（仅在 Chromium 支持 performance.memory 时显示）

设置

在扩展管理页中打开“扩展程序选项”，可配置：

• 导航类型：标准目录面板、Barcode
• Barcode 标题预览：滚轮、聚光灯、GPT
• 展开方式：推荐：悬停预览、点击开关、高级：短按回顶 / 长按展开
• TOC 显示条件：滚动到指定屏幕数后显示、最少标题数量
• 浮层位置：左下角 / 右下角
• 禁用域名列表
• 检测页面已有 TOC/回到顶部按钮时自动避开
• 强制显示（忽略页面已有控件）
• 视口内固定保存区、明确的“已保存 / 保存更改”状态与亮暗色系统配色

主题系统

• theme-dark：用于浅色背景页面
• theme-light：用于深色或中色背景页面
• theme-auto：保留为跟随系统偏好的兼容类
• 旧版 theme-blue / theme-green / theme-purple 仍保留兼容映射
• Barcode 会在标准主题之外做局部 surface 采样；该自适应只影响 rail、独立回顶按钮、.toc-rail-preview、.toc-spotlight-layer 和 .toc-gpt-preview 的 CSS 变量

限制与说明

• 目录识别依赖页面结构与样式，极少数站点可能需要额外适配。
• 在内容频繁变动的页面中，目录可能会重新生成。
• 标题结构不变时，目录不会整棵重建，标题观察器也不会重复创建。
• 对 Astro / View Transitions 一类客户端路由站点，已补充页面交换与恢复阶段的 TOC 重建兜底。
• 如果宿主页面在客户端切页时替换 body 内节点，TOC 会自动重新挂载而不需要手动刷新。
• 性能面板为开发调试用途，默认隐藏，可通过快捷键开启/关闭。
• 当前已提供兼容性诊断入口：
  • document.documentElement.dataset.smartTocSkipReason
  • window.__SMART_TOC_LAST_SKIP__
  • window.__SMART_TOC_WIDGET_DIAGNOSTICS__
  • window.__SMART_TOC_INSPECT_WIDGETS__()
• Barcode 视觉调试可使用 test-pages/rail-hover-performance.html?preview=gpt&position=right&surface=dark；preview=wheel/spotlight/gpt 切换三种预览，position=left/right、surface=light/dark/color/lightstrip、motion=reduce 用于复核镜像方向、局部配色与减少动态效果。
• 该测试页顶部提供 Rail QA 控制条，可直接切换模式、位置、surface 与减少动态效果状态，便于截图审阅和回归。
• 兼容性检测会优先区分“侧栏导航”和“正文内小目录”，减少误跳过

更新日志

查看 CHANGELOG.md 了解详细的更新历史。

产品与路线图

• 产品与体验分析：查看 PRODUCT_UX_ROADMAP.md
• 性能与代码质量治理：查看 PERFORMANCE_CODE_QUALITY_PLAN.md
• Chrome 商店文案草稿：查看 CHROME_STORE_LISTING.md

发布

• 本地打包与校验：./scripts/validate_package.sh
• GitHub 发布：手动运行 Package & GitHub Release 可下载临时 Artifact；推送与 Manifest 一致的 v* Tag 会创建带 ZIP 和 SHA-256 附件的 GitHub Release
• Chrome Web Store：从 GitHub 产物下载 ZIP 后手动上传，详见 CHROME_STORE_RELEASE.md

技术栈

• 原生 JavaScript
• CSS3 动画和过渡效果
• Material Design 风格
• Chrome Extension Manifest V3
• 智能颜色分析算法
• 自适应布局系统
• 性能监控和分析工具

贡献

欢迎提交 Issue 和 Pull Request！

许可证

MIT License - 查看 LICENSE 文件了解详情。