Lenis 平滑滚动库完整指南从安装到上生产的快速上手【免费下载链接】lenisSmooth scroll as it should be项目地址: https://gitcode.com/GitHub_Trending/le/lenisLenis 是一个几 KB、零依赖的轻量平滑滚动库它包裹浏览器原生滚动来消除原生滚动的生硬顿挫同时保住 sticky、锚点跳转和键盘可访问性。适合想给网站加平滑滚动、视差或 WebGL 滚动同步的前端开发者10 分钟可以跑通。为什么不用自己造虚拟滚动Lenis 解决什么问题传统平滑滚动两条路都有坑CSSscroll-behavior: smooth只管程序化跳转管不住滚轮手感自己拦截滚轮做虚拟滚动则会把position: sticky、锚点、浏览器滚动回弹、辅助功能全部打断。Lenis 的做法是劫持输入、保留轨道——滚动手感被接管但滚动本身始终发生在原生滚动轨道上页面结构不需要任何改造也不强制改变 DOM 层级不像部分同类库要求把内容包进 transform 容器。典型场景WebGL 场景滚动驱动、视差、横向滚动区、分屏锁定式翻页。最快上手十行代码接入 Lenis 平滑滚动npm 安装yarn/pnpm 同理没有构建系统则直接在 HTML 里引 CDN 上的dist/lenis.min.js和dist/lenis.cssnpm i lenisimport Lenis from lenis import lenis/dist/lenis.css // 必须否则停止态/iframe 行为不对 const lenis new Lenis({ autoRaf: true, // 内置 rAF 循环省去手写 requestAnimationFrame }) lenis.on(scroll, (e) { // e.velocity / e.progress / e.direction可驱动任意动画 })不开autoRaf时需要自己驱动每帧更新这是官方文档里最常见的排错项先记住const lenis new Lenis() function raf(time) { lenis.raf(time) requestAnimationFrame(raf) } requestAnimationFrame(raf)工作原理接管滚轮输入逐帧插值滚动位置核心逻辑在 核心实现 里文件头部有作者自己写的五步注释直接照它理解即可监听容器的wheel/touch事件并preventDefault阻止原生滚动事件归一化在 VirtualScroll把归一化后的 delta 累加到目标值targetScroll每帧由 Animate 类 把当前值animatedScroll向targetScroll逼近——默认用指数衰减的damp插值lerp指定durationeasing时切换为时间基缓动算出的新位置通过scrollTo({ behavior: instant })写回浏览器也就是滚动始终跑在原生滚动轨道上没有平滑动画在跑时Lenis 退化为监听原生scroll事件被动同步。这套设计的直接收益position: sticky、锚点定位、屏幕阅读器对滚动条的感知都不受影响副作用是 iframe 内拿不到滚轮事件它不转发官方 CSS 里顺手把平滑滚动期间的 iframe 设成了pointer-events: none。最常被调的 6 个参数及默认值完整选项见 官方文档 的 Settings 表先认这 6 个参数作用默认值lerp滚轮输入的插值强度越小越飘0.1duration程序化滚动动画时长秒设了easing后生效1.2easing缓动函数任意(t) t形态的函数内置自定义曲线smoothWheel是否平滑滚轮事件false时触摸仍可平滑trueorientation滚动轴vertical/horizontalverticalautoRaf是否内置 rAF 循环false必须手动raf(time)false另外两个高频开关anchors: true接管锚点链接走平滑跳转allowNestedScroll: true让页面内嵌套滚动容器侧栏、弹窗里的列表保留原生滚动——但它在每次滚动事件时都要检查 DOM 树有性能开销注意下面上生产前那节。主流框架组合React、Vue 与 GSAP 的最小接线Lenis 对每个框架都有一等适配包实例通过 context 下发不用手动传 prop。Reactlenis/reactimport { ReactLenis, useLenis } from lenis/react function App() { const lenis useLenis((lenis) { // 每次滚动触发 }) return ReactLenis root{/* 页面内容 */}/ReactLenis }root属性让实例挂到html滚动容器上并且全局可通过useLenis访问。Vue / Nuxtlenis/vue// Nuxt: nuxt.config 里加一行 modules: [lenis/nuxt] // Vue: app.use(LenisVue)template VueLenis root :options{ autoRaf: true } / /templateGSAP ScrollTrigger 是它最主要的搭档关键是把 Lenis 的raf交给 GSAP 的 ticker、让 ScrollTrigger 听 Lenis 的 scroll 事件两边共享同一个时钟才不会不同步lenis.on(scroll, ScrollTrigger.update) gsap.ticker.add((time) { lenis.raf(time * 1000) // GSAP 给秒Lenis 要毫秒 }) gsap.ticker.lagSmoothing(0)配合框架时记得把autoRaf关掉把raf挂进对应驱动React 版本示例见 packages/react/README.md 的 GSAP 一节。做分屏锁定翻页则用 lenis/snap 插件CSS scroll-snap 在 Lenis 下不生效别指望它import Snap from lenis/snap const snap new Snap(lenis) snap.addElement(document.querySelector(.section), { align: start })上生产前的注意事项嵌套滚动、iframe 与帧率CSS 必须带lenis.css不止是修饰它负责停止态的overflow: clip、data-lenis-prevent的overscroll-behavior等关键行为漏掉会有诡异 bugautoRaf是排错第一怀疑对象不设autoRaf: true又不手动调lenis.raf(time)页面会完全不滚嵌套滚动优先用属性而不是自动检测给需要原生滚动的容器直接挂data-lenis-prevent还有-wheel/-touch/-vertical/-horizontal细分版本比allowNestedScroll的全树检查便宜得多iframe 内容不会平滑滚iframe 不向前滚动容器转发 wheel 事件且平滑滚动期间 iframe 默认不可交互内嵌视频/地图要有心理预期帧率天花板Safari 封顶 60fps、低功耗模式 30fpsWebKit 已知限制requestAnimationFrame驱动的库都绕不开移动端惯性需显式开启syncTouch让触摸手势也走平滑插值但 iOS 16 上行为可能不稳定上线前在真机验证SPA 路由切换跨页跳转前可开stopInertiaOnNavigate: true或手动lenis.reset()避免旧惯性带着新页面走。从new Lenis({ autoRaf: true })起步先用scroll事件驱动一个视差动画验证手感再按项目栈接上 ScrollTrigger 或框架适配包——这条路径走完平滑滚动就算能进生产了。【免费下载链接】lenisSmooth scroll as it should be项目地址: https://gitcode.com/GitHub_Trending/le/lenis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考