Lenis 平滑滚动
Lenis 拦截滚轮输入并缓动原生滚动位置。粘性定位、IntersectionObserver 和 window.scrollY 都继续正常工作——这就是它成为正确选择的原因。问题源自那些与它对抗的东西,而不是 Lenis 本身。
设置
使用本地 vendor 文件而非热链接 CDN,以便网站保持自包含并能从 file:// 运行:
curl -sSL -o assets/vendor/lenis.min.js https://unpkg.com/[email protected]/dist/lenis.min.js
dist/lenis.min.js 构建产物是一个 IIFE,暴露 globalThis.Lenis——适用于普通的 <script> 标签。(dist/lenis.mjs 是 ESM,在普通 script 标签中不能工作。)
在你的脚本之前加载它。
var reduced = matchMedia('(prefers-reduced-motion: reduce)').matches;
var lenis = null;
if (!reduced && window.Lenis) {
var navH = parseInt(getComputedStyle(document.documentElement)
.getPropertyValue('--nav-h'), 10) || 0;
lenis = new Lenis({
duration: 1.05,
easing: t => Math.min(1, 1.001 - Math.pow(2, -10 * t)),
smoothWheel: true,
syncTouch: false, // 保持原生触摸——在手机上平滑触摸感觉有延迟
autoRaf: true, // Lenis 运行自己的 RAF 循环;无需手动 ticker
anchors: { offset: -(navH + 10) } // 页面内链接避开粘性标题
});
} else {
// 没有 Lenis——让浏览器恢复其自身行为
document.documentElement.style.scrollBehavior = reduced ? 'auto' : 'smooth';
}
必需的 CSS
html { /* 没有 scroll-behavior: smooth —— 它会与 Lenis 对抗 */ }
html.lenis, html.lenis body { height: auto; }
.lenis:not(.lenis-autoToggle).lenis-stopped { overflow: clip; }
.lenis.lenis-smooth [data-lenis-prevent] { overscroll-behavior: contain; }
.lenis.lenis-smooth iframe { pointer-events: none; }
html 上的 scroll-behavior: smooth 必须移除。如果保留,锚点跳转将双重动画并对抗缓动效果。
陷阱 1 —— overflow: clip 破坏了 position: sticky
这是会让你浪费一小时的问题。
lenis.stop() 添加了 .lenis-stopped 类,其 CSS 在 <html> 上设置了 overflow: clip。这会移除滚动视口,并且**position: sticky 就没有东西可以粘附了**——粘性元素会弹回它们在文档中的位置,即页面顶部。
在滚动到 1200px 时打开一个菜单,你的粘性标题渲染在 top: -1200 处。屏幕之外。连同它的关闭按钮一起。用户会报告“关闭按钮消失了。”
同样的现象也发生在经典的 body { position: fixed } 滚动锁定上,原因相同——没有滚动视口。
修复: 在滚动被锁定的期间,将标题固定到视口。
html.menu-open .nav-wrap { position: fixed; top: 0; left: 0; right: 0; }
document.documentElement.classList.toggle('menu-open', open);
在遮罩层仍不透明时切换类,以便粘性→固定布局的变化不可见。在 Lenis 路径和减少运动路径上都应用此修复。
在非零滚动偏移处测试遮罩层。 在滚动 0 处,有问题的粘性标题与正常工作的粘性标题像素级一致,所以 Bug 完全隐藏。在 0、~1200 和页面深处进行验证。
陷阱 2 —— 不要叠加两个滚动锁定
固定 body 并且 调用 lenis.stop() 会使它们互相冲突:body 上的 position: fixed 会折叠页面高度,Lenis 会重新同步到 0,关闭遮罩层时会将用户丢到页面顶部。
使用 Lenis 时,stop() 加上其自身的 overflow: clip 就能在不触碰 body 的情况下固定页面——因此滚动位置永远不会丢失,也无需恢复:
if (lenis) {
open ? lenis.stop() : lenis.start();
} else if (open) { // 仅减少运动路径
scrollY = window.scrollY;
document.body.style.position = 'fixed';
document.body.style.top = -scrollY + 'px';
document.body.style.width = '100%';
} else if (document.body.style.position === 'fixed') {
document.body.style.position = '';
document.body.style.top = '';
document.body.style.width = '';
window.scrollTo(0, scrollY);
}
验证:滚动到 1200 → 打开 → 滚轮 → 关闭。每一步位置都必须保持 1200,并且之后滚动必须再次正常工作。
陷阱 3 —— 锚点链接
Lenis 控制滚动,所以原始的 href="#id" 跳转看起来不正常。使用内置的 anchors 选项,并设置等于粘性标题高度的负偏移量,或者通过 lenis.scrollTo(target, { offset: -navH }) 手动路由点击。
检查目标位置:区域顶部必须位于标题底边处或其下方,而不是被其遮盖。
陷阱 4 —— Lenis 通常不是你的卡顿来源
添加 Lenis 后感觉滚动变差时,先测量再归咎于它。在某个版本中,原生滚动实际上测量结果更差(13% 丢帧 vs 9%)——Lenis 没问题,真正的开销在别处:
- 一个固定的全视口
mix-blend-mode叠加层(胶片颗粒):仅通过去除混合模式,丢帧率从 34% 降到了 3% - 粘性元素上的
backdrop-filter,该元素在每次滚动的每一帧都显示在屏幕上 - 通常,大面积元素上的
backdrop-filter—— 它每帧都会重新采样
帧计时工具
// 在页面中
window.__f = []; let l = performance.now();
const t = n => { window.__f.push(n - l); l = n; requestAnimationFrame(t); };
requestAnimationFrame(t);
在可疑区域上使用真实滚轮事件驱动它,然后报告均值、p95 和超过 33ms 的帧百分比。通过使用 add_style_tag 一次禁用一个效果来二分排查。健康状态是均值 ~16.7ms 和 0% 的长帧;超过 ~10% 的长帧即为可见卡顿。
检查清单
- 已从
html移除scroll-behavior: smooth - 已添加 Lenis CSS 块
- 已设置
autoRaf: true(或手动 RAF 循环——不能两者兼有) -
anchors偏移量与粘性标题高度匹配 - 已设置
syncTouch: false以保持手机的原生动量 - 在遮罩层锁定滚动期间,粘性标题已固定
- 只有一个滚动锁定机制在起作用
- 已在非零滚动偏移处测试遮罩层
-
prefers-reduced-motion跳过 Lenis 并恢复原生行为 - 在打开 → 关闭过程中保持了滚动位置
- 已测量帧计时,而非假设