Lenis 平滑滾動
Lenis 會攔截滾輪輸入,並對原生的滾動位置進行緩動處理。因此,position: sticky、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 標籤中使用。)請在你自己的 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 { /* NO 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 class,其 CSS 設定 <html> 的 overflow: clip。此舉會移除滾動容器,而**position: sticky 就沒有東西可以附著了**——sticky 元素會跳回它在文件流中的位置,也就是頁面頂部。
在滾動到 1200px 時開啟選單,你的 sticky 標頭會渲染在 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);
在覆蓋層仍然不透明的時候切換 class,讓 sticky → fixed 的版面變化不易察覺。在 Lenis 路徑和減少動畫效果的路徑上都套用這個 class。
在非零滾動偏移下測試覆蓋層。 在滾動為 0 時,損壞的 sticky 標頭與正常的標頭看起來一模一樣,所以這個 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 選項,並設定一個等於你 sticky 標頭高度的負偏移量,或者手動透過 lenis.scrollTo(target, { offset: -navH }) 來路由點擊事件。
檢查著陸位置:章節頂部必須位於標頭底部邊緣的下方,而不是被它遮住。
陷阱 4 — Lenis 通常不是卡頓的原因
當加入 Lenis 後感覺滾動不順暢時,先測量再責怪它。在某個專案中,原生滾動實際上測量結果更差(掉幀 13% 對比 9%)——Lenis 沒問題,真正的效能成本來自其他地方:
- 一個固定全視口的
mix-blend-mode覆蓋層(底片顆粒效果):僅僅移除混合模式,掉幀率就從 34% 降到 3% - sticky 元素上的
backdrop-filter,它在每次滾動的每一幀都顯示在螢幕上 - 大型元素上的
backdrop-filter通常都是問題——它每幀都要重新取樣
幀計時測試工具
// 在頁面中
window.__f = []; let l = performance.now();
const t = n => { window.__f.push(n - l); l = n; requestAnimationFrame(t); };
requestAnimationFrame(t);
使用真實的滾輪事件在可疑的區段上驅動它,然後回報平均值 (mean)、第 95 百分位數 (p95) 和超過 33ms 的幀數百分比。使用 add_style_tag 一次停用一個效果來進行二分法測試。健康的數值大約是平均值 ~16.7ms 且 0% 的長幀;超過 ~10% 的長幀就是肉眼可見的卡頓。
檢查清單
-
scroll-behavior: smooth已從html移除 - Lenis CSS 區塊已加入
- 已設定
autoRaf: true(或手動的 RAF 循環——但不能兩者並存) -
anchors偏移量與 sticky 標頭高度相符 -
syncTouch: false以讓手機保留原生動量 - sticky 標頭在覆蓋層鎖定滾動時已固定
- 只有一個滾動鎖定機制在運作
- 覆蓋層已在非零的滾動偏移下測試過
-
prefers-reduced-motion會跳過 Lenis 並恢復原生行為 - 滾動位置在開啟 → 關閉之間得以保留
- 幀計時已測量,而非假設