Skip to content

彻底解决侧边栏闪烁

AKA. 共享侧边栏与局部导航机制

1. 目标与结论

之前对侧边栏的更新已经有过一些优化记录,但是发现侧边栏还是会闪烁。

总而言之,最终修改的逻辑是:同一顶部栏目内切换文章时,左侧栏和目录树应继续使用原来的 DOM 节点,只更新当前文章高亮,并展开所需的祖先目录。

最终效果:

最终效果

2. 以前有 sessionStorage,侧边栏仍会闪烁

原因:即使命中缓存,只要重新创建了 DOM,仍然可能看到闪烁。

2.1 缓存 HTML 与保留 DOM 是两件事

旧流程:

点击另一篇文章
  → 浏览器加载新文档,卸载旧文档
  → 新文档出现侧栏占位内容
  → 从 sessionStorage 读取目录 HTML 字符串
  → innerHTML 创建一套新的目录节点
  → 设置高亮、展开目录、恢复滚动位置

缓存能够减少目录文件的网络请求,但旧节点已经随着文档卸载而消失。浏览器仍需要解析 HTML、创建节点、绑定事件、计算布局和绘制;恢复宽度、展开状态或滚动位置的时机也可能晚于第一帧。

即使不刷新整个文档,在一个已有容器里再次执行下面的语句,也会替换其原有子节点:

container.innerHTML = cached.html;

2.2 当前正常切换流程

点击另一篇文章
  → 主题拦截符合条件的站内链接
  → 获取并解析目标页面
  → 只替换文章所属的页面容器
  → document$ 通知页面已更新
  → 读取新页面要求的共享目录地址
  → 地址相同:保留目录节点,只调整高亮和必要的展开状态

左侧栏不需要先消失,再从缓存中恢复。

3. 页面结构:左侧栏在外,文章容器在内

源码 base.html 的页面结构简化后如下,省略了头部、部分嵌套容器和其他主题元素:

<!-- 独立存在的左侧栏 -->
<div class="custom-sidebar-shell custom-page-shell md-grid">
  <div class="md-sidebar md-sidebar--primary" data-md-type="navigation">
    <div class="md-sidebar__scrollwrap">
      <div class="md-sidebar__inner">
        <div data-shared-navigation="..." data-site-root=".../">
          <!-- 目录树 -->
        </div>
      </div>
    </div>
  </div>
</div>

<!-- 主题局部导航会替换的区域 -->
<div class="md-container"
     data-md-component="container"
     data-shared-navigation-target="..."
     data-site-root=".../"
     data-navigation-hidden="false">
  <!-- 顶部栏目、正文、右侧目录、页脚等 -->
</div>

左侧栏不再是 [data-md-component="container"] 的后代。因此,主题替换目标页面容器时,不会连同左侧栏一起替换。

左侧栏也去掉了原先的 data-md-component="sidebar",不再参加主题对这类组件的每页重新初始化。主题原有侧栏初始化会设置尺寸、位置,并尝试滚动到当前文章;本项目已经用自己的固定布局和共享导航脚本管理左栏。

右侧文章目录仍然属于可替换区域,并由主题管理,因为它需要随文章变化。

4. 浏览器运行阶段:如何判断目录是否相同

主要由 shared-navigation.js 实现,核心判断依据有三个属性:

属性 用途
data-shared-navigation-target 新文章需要的共享目录资源地址
data-site-root 解析共享目录内部相对链接、图片地址时使用的站点根路径
data-navigation-hidden 表达目标页面是否通过元数据隐藏左侧导航

假设 A 是 /Main/one/,B 是 /Main/Nested/two/,下面说明打开 A 和 B 的过程。

4.1 打开文章 A

此时浏览器地址栏是:

window.location.href
// "http://127.0.0.1:8000/Main/one/"

A 页面 HTML 中的属性是:

<div
  data-md-component="container"
  data-shared-navigation-target="../../navigation/shared/group-1-a1b2c3d4e5f6.html"
>
  <!-- 文章 A -->
</div>

脚本读取属性并计算完整地址:

var target = document.querySelector('[data-shared-navigation-target]');

target.dataset.sharedNavigationTarget
// "../../navigation/shared/group-1-a1b2c3d4e5f6.html"

var url = new URL(
  target.dataset.sharedNavigationTarget,
  window.location.href
).href;

// 等价于:
new URL(
  "../../navigation/shared/group-1-a1b2c3d4e5f6.html",
  "http://127.0.0.1:8000/Main/one/"
).href;

// 结果:
// "http://127.0.0.1:8000/navigation/shared/group-1-a1b2c3d4e5f6.html"

首次加载时,目录容器还没有记录加载地址:

container.dataset.navigationLoaded
// undefined

container.dataset.navigationLoaded === url
// false

因此需要加载目录。加载成功后执行 render(),装入左侧目录:

container.innerHTML = html;

container.dataset.navigationLoaded = url;
// "http://127.0.0.1:8000/navigation/shared/group-1-a1b2c3d4e5f6.html"

4.2 切换文章 B 时文章区域先被替换

设置中开启了 navigation.instant 后,此时主题会先获取新页面 HTML,找到其中的页面容器并替换,最后会通过 document$ 发出页面更新通知。简化后的代码如下:

// 获取 B 的完整页面 HTML
const html = await fetch(B的地址).then(response => response.text());

// 解析成一个暂时没有显示在页面上的文档
const nextDocument = new DOMParser().parseFromString(html, "text/html");

// 找到当前页面中的容器
const oldContainer = document.querySelector(
  '[data-md-component="container"]'
);

// 找到 B 页面中的对应容器
const newContainer = nextDocument.querySelector(
  '[data-md-component="container"]'
);

// 用 B 的整个容器替换 A 的容器
oldContainer.replaceWith(newContainer);

替换后,主题接着通过 document$ 发出页面更新通知。我们的脚本已经订阅了它:

document$.subscribe(init);

PS: document$ 是主题提供的“页面更新通知流”,技术上叫 RxJS Observable。它不是 JavaScript 或浏览器自带的对象。我们通过 subscribe() 告诉主题:“页面更新后,运行这个函数。” 名字末尾的 $ 只是常见命名习惯,表示“这是一个通知流”,没有特殊语法含义。

于是此时运行目录的 init():

function init() {
  // 此时读到的已经是 B 的容器
  var target = document.querySelector(
    '[data-shared-navigation-target]'
  );

  // 后面是目录的加载逻辑
}

外面的 custom-sidebar-shell 没被碰到,原目录仍留在页面上。

4.3 切换文章 B 后目录的加载逻辑

地址变成:

window.location.href
// "http://127.0.0.1:8000/Main/Nested/two/"

文章区域被替换为 B 的 HTML,其属性也随之更新:

<div
  data-md-component="container"
  data-shared-navigation-target="../../../navigation/shared/group-1-a1b2c3d4e5f6.html"
>
  <!-- 文章 B -->
</div>

和 4.1 一样,脚本会计算目标目录的完整地址:

var target = document.querySelector('[data-shared-navigation-target]');

var url = new URL(
  target.dataset.sharedNavigationTarget,
  window.location.href
).href;

// 等价于:
new URL(
  "../../../navigation/shared/group-1-a1b2c3d4e5f6.html",
  "http://127.0.0.1:8000/Main/Nested/two/"
).href;

// 结果仍然是:
// "http://127.0.0.1:8000/navigation/shared/group-1-a1b2c3d4e5f6.html"

左侧目录容器没有被替换,所以还记着打开 A 时写入的值:

if (container.dataset.navigationLoaded === url) {
  delete container.dataset.navigationLoading;
  activate(container, root); // 高亮从 A 移到 B,展开 B 的祖先目录
  return;                   // 跳过目录加载与 innerHTML 替换
}

4.4 讨论

一共三种状态:

条件 处理
已加载地址等于目标地址 复用目录树,运行 activate() 后返回
目标地址已经在加载中 不重复发起同一请求
目标地址与已加载地址不同 尝试缓存,未命中再请求目录 HTML

activate() 的主要工作是:

  1. 将目录中的链接和图片地址相对于站点根路径解析为绝对地址。
  2. 清除旧的 .md-nav__link--active、.md-nav__item--active 和对应的 aria-current。
  3. 找到与当前页面同源、路径匹配的文章链接。
  4. 给它添加 .md-nav__link--active 与 aria-current="page"。
  5. 沿祖先导航项向上设置活动状态,并勾选尚未展开的祖先开关。
  6. 对程序修改的展开开关触发 change,同步展开按钮和导航的辅助属性。

页面路径匹配会进行 URL 解码、把末尾 /index.html 视为目录首页,并忽略末尾多余斜杠。当前实现按路径匹配,不把查询参数和文章锚点作为独立目录项。

5. 其他繁琐细节

5.1 同栏目滚动位置主要靠节点保留

同栏目切换时,.md-sidebar__scrollwrap 没有被替换,scrollTop 随同一个元素继续存在,无需先归零再从缓存恢复。

这不意味着数值在所有操作下绝对不变。例如浏览器为了把被点击的链接滚动到可见区域,或者某个目录展开后内容高度改变,都可能调整滚动位置。验收重点是避免切页额外引入一次重建和重置。

5.2 整页加载时仍有滚动恢复脚本

sidebar-scroll-position.js 使用 CUSTOM_SIDEBAR_SCROLL_TOP:

  • 在 pagehide 保存滚动位置。
  • 首次执行及 shared-navigation-ready 后尝试恢复。
  • 在 DOMContentLoaded 后通过两次动画帧再次恢复,以等待初始布局。

这是整页加载或目录重建时的补充。当前保存的是一个位置值,没有按栏目分别保存滚动历史;普通同栏目局部切换也不会触发 pagehide。

5.3 未转义的 & 导致策略失效

有一个目录是 code&report/,结果这个目录导致上面整个策略失效了。

因为 XML 把 & 当作特殊引用的开头,比如 &lt; 表示 <,比如 &amp; 表示 &。

主题会先把所有站内地址解析到 sitemap.xml 中,如果不做特殊处理,那这个目录对应的地址是:

<loc>https://masterallen.github.io/.../code&report/</loc>

XML 解析器读到 & 时,会尝试把后面的内容识别为 &名称; 这样的引用。但 &report/ 不是合法引用,因此报语法错误。

一旦有错误,那整个站点地图解析失败,得到一张空表。最终影响整个网站导航,因为主题需要先解析完整的站点地图:

sitemap.xml
  → XML 解析
  → 获得所有站内页面的 URL 清单 → 解析失败,得到空表
  → 点击链接时,判断它是否在清单中
  → 在清单中才使用局部导航

所以最终用一个新的 overrides/sitemap.xml 来解决这个问题,新的 XML 文件里写的是 &amp;,对应 & 的转义。

Comments

本文阅读 Loading 次 本站访问 Loading 次 访客 Loading 人