【极客前端】“每一篇都要自己做目录吗？！”——原生 CSS Grid + RAF 动力引擎打造全自适应悬浮文章大纲

来自自媒体主理人的真实发端

“挤到下面来了，并没有在右侧啊！随着鼠标往下滚动，这个目录并没有一直悬浮，看不见了，你理解我的意思吗？…… 刚刚发布的这篇怎么又没有了，每一篇都要自己做呀？！”
—— 当我们在给长篇博文排版大纲目录时，老汪的一连串直击灵魂的实测反馈，逼出了全站自愈级 TOC 悬浮引擎的诞生。

长文必须有目录，这是严肃技术自媒体的立足之本。读者看一篇动辄四五千字的硬核实操教程，如果没有右侧伴随视野的目录导航，极易产生信息过载与眼球疲劳。然而，在以“导航卡片”为核心的 WordPress 主题里，原生压根就没有为长文详情页设计过右侧悬浮大纲组件。

一、跌落正文底下与被滚动条吞没：两大前端噩梦

在第一版实现中，由于生硬套用常规网传教程，我们遭遇了极其滑稽的两次严重翻车：

▲ 图 1：老汪当场抓包的尴尬现场：目录没有在右侧，而是被硬生生挤落到正文最下方的大片空白中！

噩梦一：Grid 弹性容器在移动端与父级边距冲突，导致右侧栏无法并列，被强行挤落；
噩梦二：传统 position: sticky 彻底失效。只要父级容器（如主题默认的 .card 或 .panel）带有哪怕一行 overflow: hidden 或 overflow: clip，CSS 原生的 sticky 就会被瞬间破坏，鼠标往下滚，目录停在原地直接被视口吞没！

▲ 图 2：文章页面右侧缺少大纲视野导航，读者阅读长篇教程时极易迷失位置

二、动力革命：放弃 Sticky，改用 RAF + GPU 3D 位移引擎

为了彻底打破父级 overflow 的物理诅咒，我们重构了底层动力体系：

双栏 Grid 结构：桌面端强制将正文容器分为左侧主正文（73%）与右侧悬浮栏（25%）；
RAF 动力引擎：通过浏览器的 requestAnimationFrame 实时监听滚动事件，计算距离顶部导航栏的安全高度（96px），通过 GPU 硬件加速的 translate3d(0, offsetY, 0) 推动目录跟随；
100% 免疫溢出：无论父级、祖先级容器有什么样的 overflow 限制，GPU 3D 位移始终维持 120fps 的丝滑手感，且在滑到正文底部时自动优雅刹车！

三、终结手动配置：多层级向下自愈探测

解决了悬浮，老汪紧接着提出了最核心的自媒体诉求：
“难道我以后每发布一篇新博文，都要手动在 HTML 源码里加上特定的类名才能激活目录吗？！”

绝对不能给创作者增加负担！我们把 Snippet 11 的 JavaScript 逻辑升级为全站通用自适应探测：

// 全自动通用探测：无论使用自定义包装还是后台常规编辑器，100% 自动识别正文
var article = document.querySelector('.video-post-article') 
           || document.querySelector('.blog-article-content') 
           || document.querySelector('.panel-body.single');

// 优先扫描主章节 h2；若 h2 少于 2 个自动向下兼容提取 h3 小标题并追加缩进
var headings = article.querySelectorAll('h2');
if (!headings || headings.length < 2) {
    headings = article.querySelectorAll('h2, h3');
}

这一改动让全站彻底迈入**“写完即走、全自动大纲”**时代。不论是通过后台 Gutenberg 编辑器、Markdown 插件还是外部脚本导入，只要发布，右侧目录立刻自愈生效！