滚动依赖补丁
OverlayScrollbars 2.16.0
overlayscrollbars@2.16.0.patch 通过 pnpm-workspace.yaml 的 patchedDependencies 安装,覆盖 ESM / CommonJS 四个包入口;依赖固定为 2.16.0,避免范围升级绕过补丁。
- 相同属性值不重复写入 DOM,减少滚动期间无效 MutationObserver 通知;缺失属性与空值属性保持区别。
- viewport 与 target 相同时,子节点已在原容器内,跳过重复 append,避免输入失焦和动画重启。
- 初始化和销毁只在焦点确实改变后恢复焦点,不重复聚焦仍处于激活状态的输入框。
- 默认创建包装层以及 viewport 与 target 不同的模式保留原有结构初始化和必要的焦点恢复。
- viewport 与 target 相同时,内容观察及溢出尺寸更新都会在测量期间隐藏直属滚动条,避免滚动条旧 transform 撑住缩短前的滚动范围;有效位置保留,越界位置按真实内容自动收回。body 的原生页面滚动分支保持不变。
官网集成位于 .vitepress/theme/components/SiteScrollbars.vue:body、菜单等复用自身 viewport;左侧栏使用固定 .VPSidebar 外框和独立 .nav viewport,保留 padding: false;右侧目录使用固定 .aside-container 外框和现有 .aside-content viewport,原顶部留白换成外框偏移,文字位置不变,轨道限制在目录区域内。两个侧栏通过 overscroll-behavior: contain 阻止滚动传递到正文,并保留原生回弹。表格和代码块继续使用现有 table / pre,保留左侧栏 Logo 下沿布局和移动菜单的 body 滚动锁同步。
目录高亮只改变颜色,标记只改变 transform / opacity。集成层仅忽略这两类视觉变化:对比旧、新 class 去除 active 后的集合,以及旧、新 style 去除 transform / opacity 后的声明值和优先级;其他属性、内容及尺寸变化仍由滚动库处理。
VitePress 2.0.0-alpha.21
vitepress@2.0.0-alpha.21.patch 将默认目录标记从 top 动画改为 transform 动画,保留原始定位公式、初始 2rem 位置、0.25s 时长、缓动和透明度,并保留 alpha.21 的 inset-inline-start 逻辑定位。补丁覆盖实际使用的 dist/client/theme-default/composables/outline.js 与 components/VPDocAsideOutline.vue。导航补丁同时覆盖 Layout.vue、components/VPNavBar.vue 和 components/VPLocalNav.vue:首页不挂载无可见用途的局部导航;顶栏与文档局部导航改用被动滚动监听,只读取 window.scrollY 并维护阈值布尔状态,避免 useWindowScroll 每次滚动重复读取根元素样式和双轴尺寸。挂载及 pageshow 同步当前位置,路由切换时随组件卸载清理监听。VitePress 固定当前版本,升级时须重核这些文件及上述 MutationObserver 过滤条件。
项目根目录的 .ncurc.json 将 overlayscrollbars 和 typescript 排除在 ncu 检测与升级之外,分别保留 2.16.0 和 6.0.3。VitePress 预发布版通过 ncu --filter vitepress --target @next 检查;升级时同步迁移上述补丁及锁文件。
安装与回归
本地安装和构建使用 pnpm 11.25.0(Node.js >= 22.13),执行 pnpm install --frozen-lockfile 和 pnpm build。源码必须同时包含补丁、workspace 配置和锁文件。官网发布 dist/ 静态产物,补丁已进入构建后的 JavaScript,静态部署端无需再安装依赖。
EdgeOne 使用 edgeone.json 和 Node.js 22.21.1。阿里云 ESA Pages 使用 esa.jsonc,控制台的 Node.js 版本须满足 pnpm 的要求(>= 22.13)。两个平台的配置都显式调用 pnpm@11.25.0,并发布 dist/。后续调整 pnpm 版本时,同步更新 edgeone.json 和 esa.jsonc,并重新验证冻结安装和构建。
升级 OverlayScrollbars 时须重新核对四个入口的结构初始化、焦点恢复与两处动态尺寸测量实现,更新精确依赖版本、补丁及锁文件;不要仅修改版本号。回归自身 viewport、独立现有 viewport 和默认包装层三种模式,检查同值属性写入去重、输入焦点、子节点顺序、内容缩短后的有效及越界滚动位置、侧栏回弹/轨道位置、代码复制、表格横向滚动和移动菜单滚动锁。
目录回归需确认滚动高亮与标记位置、首尾章节和锚点跳转、窄屏目录隐藏、滚动隔离;同时验证 class 或 style 混入真实尺寸变化后仍触发测量,不能将全部属性变化都忽略。
导航回归需覆盖首页与文档页往返、顶部与非顶部状态、浏览器前进后退及恢复事件、窄屏菜单与文档目录;滚动采样应核对根元素样式/尺寸读取,不能把文档目录优化数据当作首页帧率保证。