减少侧边栏闪烁
博客在切换文章时,左侧边栏会闪烁,这个其实是预期的问题,因为现在每次加载文章会异步请求一份侧边栏 HTML,然后插入到页面中。所以会闪烁。
1. 问题与目标
优化前,每次切换文章都会经历:
加载新页面
→ 显示“加载栏目目录…”
→ 等待 DOMContentLoaded,开始异步获取目录
→ 插入目录 HTML
→ 高亮当前文章、展开祖先目录、初始化目录按钮
→ 恢复侧边栏滚动位置
2. 实现涉及的文件
以下路径均位于 D:/Blog/scripts/web/:
| 文件 | 职责 |
|---|---|
generate_shared_navigation.py |
按顶部栏目生成目录 HTML、内容指纹和目录清单 |
overrides/partials/shared-nav.html |
声明当前页引用的目录,并在侧边栏后加载相关脚本 |
overrides/javascripts/shared-navigation.js |
读取缓存或请求目录,插入 HTML,计算当前文章状态 |
overrides/javascripts/sidebar-directory-actions.js |
初始化本地版的目录展开按钮和概览入口 |
overrides/javascripts/sidebar-scroll-position.js |
保存与恢复侧边栏滚动位置 |
3. 浏览器端:如何缓存侧边栏
如果想详细了解,可以先看当时改成共享侧边栏的记录:共享侧边栏原理。
每次切换文章时,浏览器会请求一份侧边栏 HTML,然后插入到页面中,所以会闪烁。
// 示意代码
const response = await fetch("/navigation/shared/group-3-012345abcdef.html");
const html = await response.text();
document.querySelector("#sidebar").innerHTML = html;
做法就是需要让浏览器缓存这份侧边栏 HTML,这样下次切换文章时,就不需要再请求了。当前实现中,缓存保存在当前标签页会话的 sessionStorage 中,键名为:
CUSTOM_SHARED_NAVIGATION
值是序列化后的 JSON,包含目录文件的绝对 URL 和原始 HTML:
{
"url": "http://127.0.0.1:8000/navigation/shared/group-3-012345abcdef.html",
"html": "<nav>……原始目录 HTML……</nav>"
}
所以假如同栏目连续切换,他们的侧边栏是一个,这样就可以快速加载。
关于 sessionStorage
我之前不是很理解这部分,当时我的问题:缓存这不是浏览器的行为吗,应该在浏览器软件中做一些缓存设置啥的,难道我们可以直接用其他方式能让他保存吗?
其实,这里有两种不同的机制:
| 机制 | 谁决定保存、读取 |
|---|---|
| 普通 HTTP 缓存 | 浏览器根据响应头等规则管理,例如缓存 JS、图片、HTML 文件 |
sessionStorage |
网页代码主动写入、读取数据 |
可以把 sessionStorage 理解为浏览器给网页提供的一个键值字典。第一次取得目录后,代码主动保存:
sessionStorage.setItem(
"CUSTOM_SHARED_NAVIGATION", // 自己起的名字,相当于字典的键
JSON.stringify({
url: url, // 目录地址
html: html // 目录内容
})
);
切换文章后,新页面的代码再主动读取:
const saved = sessionStorage.getItem("CUSTOM_SHARED_NAVIGATION");
const cached = JSON.parse(saved);
网页重新加载时,普通 JavaScript 变量会消失,而同一标签页、同一站点的 sessionStorage 可以继续保留。 因此上一篇文章存进去的数据,下一篇文章还能读出来。
4. 一些细节代码
这一步都是细节,没必要细看。
4.1 缓存命中与未命中
关键逻辑如下,省略了异常处理和请求细节:
var cached = JSON.parse(sessionStorage.getItem(CACHE_KEY));
if (cached && cached.url === url) {
render(cached.html);
return;
}
fetch(url)
.then(response => response.text())
.then(html => {
sessionStorage.setItem(CACHE_KEY, JSON.stringify({url, html}));
render(html);
});
缓存命中后,同步读取字符串、解析 JSON 并插入目录,不再发起目录 HTML 的 fetch()。未命中时仍按原有方式异步获取,成功后覆盖缓存。
实际代码对存储读取、JSON 解析和写入都使用了 try/catch。浏览器禁止存储、缓存无法解析或写入失败时,目录仍可通过正常请求显示。
4.2 每次重新计算当前文章状态
侧边栏需要高亮当前文章的那一条目,所以需要有一个 render() 函数,这个函数的顺序是:
设置 container.innerHTML
→ activate() 计算当前文章状态
→ 设置 aria-busy="false"
→ 发出 shared-navigation-ready 事件
→ 发出 resize 事件,通知已有布局监听器
activate() 执行以下操作:
- 将目录中的
a[href]和img[src]按站点根目录转换为绝对地址。 - 检查链接与当前页面是否同源,并比较规范化后的路径。
- 为当前文章链接添加
md-nav__link--active和aria-current="page"。 - 从当前文章所在的
li向上遍历祖先目录,添加活动标记,并将展开开关设为checked = true。 - 根据开关状态同步目录的
aria-expanded,并监听后续开关变化。
路径规范化会解码 URL 编码、移除末尾的 /index.html 并统一末尾斜杠。例如 /Main/one/ 与 /Main/one/index.html 可以匹配同一页面。
4.3 保存与恢复滚动位置
侧边栏还需要保存滚动位置,使用独立的 sessionStorage 键:CUSTOM_SIDEBAR_SCROLL_TOP,这个就是一个数值。
切换文章时会发生两步,第一步是离开旧页面,第二步是进入新页面。离开旧的页面时,代码监听 pagehide 事件,在离开页面时保存数值 scrollwrap.scrollTop。
如何监听 pagehide 事件?本质就是提前告诉浏览器,当当前页面被离开时,执行指定函数。
window.addEventListener('pagehide', savePosition);
进入新页面,需要恢复滚动位置,代码读取之前的数值即可。但是其实这里需要恢复好几次,因为目录可能还没有准备好。
即恢复位置时,目录必须已经存在、具有足够的可滚动高度。 如果侧边栏还准备好,设置 160 可能被浏览器限制成 0。
所以代码在三个时机尝试恢复:
- 脚本立即执行时:目录缓存命中,目录已经插入,可以直接恢复。
- 目录加载完成时:缓存未命中,等异步取得目录后再恢复。
- 页面解析完成后的动画帧中:后续布局可能发生调整,再恢复一次。
可以理解成:离开时记住位置,回来后等目录准备好,再滚回原处。
5. 另一个重点:提前执行脚本
浏览器通常从上往下解析 HTML,比如页面是:
<body>
<header>顶部导航</header>
<div id="sidebar">侧边栏</div>
<main>
很长的文章正文……
</main>
<footer>页脚</footer>
</body>
以前目录脚本放在页面底部,需要等待 DOMContentLoaded。这个事件表示 HTML 已经解析完成。顺序相当于:
解析顶部导航
→ 解析侧边栏占位内容
→ 解析整篇正文和页脚
→ DOMContentLoaded
→ 开始加载侧边栏目录
在等待期间,浏览器可能已经把“加载栏目目录…”画到了屏幕上。
现在,把脚本直接放在侧边栏容器面,此时达到效果:侧边栏的容器刚被浏览器读出来,就立即运行恢复目录的代码,不必等整份 HTML 解析完。
<div id="sidebar">加载栏目目录…</div>
<script src="shared-navigation.js"></script>
<main>
很长的文章正文……
</main>
这样目录更有机会在首次绘制时就准备好。首次没有缓存时,fetch() 仍然异步加载,所以仍可能看到加载提示。