Lenis 平滑滚动实战：3 行代码接入，4 组参数定手感

Lenis 平滑滚动实战3 行代码接入4 组参数定手感【免费下载链接】lenisSmooth scroll as it should be项目地址: https://gitcode.com/GitHub_Trending/le/lenisLenis拉丁语smooth是基于原生滚动实现的轻量级平滑滚动库smooth scroll核心功能是为滚动驱动动画、视差、WebGL 同步提供一条可控的滚动链路。本文覆盖最小接入、手感调参、生态联动与高频问题排查。为什么是 Lenis对比两条技术路线平滑滚动库大致分两类一类用transform劫持容器位置实现自由度高但脱离原生滚动Lenis 属于另一类——它接管输入、保留浏览器真实滚动位置。这个区别直接决定了后续成本维度LenisLocomotiveScrollify实现方式原生滚动 输入接管独立滚动容器jQuery 分节跳转打包体积约 3KBgzip约 10KB约 6KB依赖 jQuery运行时依赖00jQueryposition: sticky/ 锚点原生可用需自行兼容锚点可用Lenis 的核心循环只有五步源码注释写得很直白核心引擎实现监听wheel→ 阻止默认滚动 → 归一化 delta → 累加到targetScroll→ 在 RAF 中把当前值逼近目标值。事件归一化逻辑在 virtual-scroll其中按deltaMode换算滚轮增量屏蔽了 Windows 行式滚动与 Mac 像素式滚动的差异。接入落地从 npm 到可运行的最小闭环1. 最小代码npm i lenis然后import Lenis from lenis import lenis/dist/lenis.css const lenis new Lenis() lenis.on(scroll, (e) { console.log(e.scroll, e.progress) // 每帧回调 }) function raf(time) { lenis.raf(time) // 每帧推进一次插值 requestAnimationFrame(raf) } requestAnimationFrame(raf)不想手写循环就传autoRaf: true由 Lenis 自己维护 RAFplayground/core/browser.js 是手动版示例。2. 配套 CSS推荐样式很短直接看 lenis.csshtml.lenis, html.lenis body { height: auto; } .lenis [data-lenis-prevent] { overscroll-behavior: contain; }缺了height: autooverflow高度计算会出错data-lenis-prevent系列属性则用于给嵌套滚动区豁免平滑。3. 拿到运行时状态每个scroll事件携带实例本身常用字段scroll当前值、progress0~1 进度、velocity速度、direction1/-1、isScrollingfalse/native/smooth。调试时可以把animatedScroll与window.scrollY并排打出来核对参考 playground/core/test.ts 里的 debug 面板写法。 调校手感按影响面分三组核心手感lerp / duration / easinglerp默认0.1是每帧向目标值逼近的比例值越小追得越慢、阻尼感越强是手感的头号变量。duration秒与easing组成另一套时间基动画二者会互相接管只要定义了duration就用时间基lerp不生效见 配置类型定义。默认缓动是Math.min(1, 1.001 - 2 ** (-10 * t))近似 easeOutExpo起快收慢。输入灵敏度wheelMultiplier / touchMultiplier / gestureOrientationwheelMultiplier与touchMultiplier默认均为1放大或缩小输入增量gestureOrientation决定采纳哪个轴的 delta默认verticalboth时取绝对值更大的轴。想按条件拦截用prevent: (node) boolean或virtualScroll回调可改写deltaY再放行。边界与特殊行为syncTouch默认false触摸端也走平滑链路惯性强度由touchInertiaExponent默认1.7控制iOS 16 以下可能不稳overscroll默认true嵌套容器越界时是否继续回传事件语义类似 CSSoverscroll-behavioranchors: true点锚点链接时走平滑scrollToinfinite循环滚动触摸端需配合syncTouch: trueallowNestedScroll自动放行嵌套可滚区但每帧要检查 DOM 树页面很重时改用data-lenis-prevent生态联动GSAP、snap 与框架适配与 GSAP ScrollTrigger 同步官方推荐让 GSAP ticker 驱动 Lenis避免双循环打架const lenis new Lenis() lenis.on(scroll, ScrollTrigger.update) gsap.ticker.add((time) { lenis.raf(time * 1000) // ticker 以秒计转为毫秒 }) gsap.ticker.lagSmoothing(0) // 关掉补偿避免双重平滑snap分节吸附Lenis 不支持 CSSscroll-snap官方用 lenis/snap 补齐import Snap from lenis/snap const snap new Snap(lenis) snap.add(500) // 在 500px 处吸附 snap.addElement(document.querySelector(.section), { align: center, // start | center | end })框架包React 包提供ReactLenisProvider 与useLenisHookprovider 实现root实例会写入全局 storeuseLenis(cb, deps, priority)按优先级接收每次scroll回调组件卸载自动清理。Vue 与 Nuxt 模块packages/vue/提供等价的组合式 API。排障四个高频症状按症状 → 根因 → 修复走滚轮转了但页面不动根因RAF 循环没跑。raf不推进插值永远不执行。修复autoRaf: true或确认手动循环没被卸载逻辑提前中断同时确认引入了配套 CSS。页面里有区域该滚动却滚不动根因平滑层把事件吃掉了。修复给嵌套滚动区加data-lenis-prevent或初始化时allowNestedScroll: true需要精确控制时用prevent回调返回true放行该节点。点锚点直接跳变根因默认不走平滑锚点浏览器按原生行为瞬时定位。修复anchors: true可传ScrollToOptions如offset微调落点页面内跳转打断惯性可加stopInertiaOnNavigate: true。两个已知硬限制iframe 内滚轮事件不回传Lenis 无法接管平滑期间 CSS 里 iframe 被设为pointer-events: none缓解误触Safari 的 RAF 上限 60fps高刷屏上 Safari 的表现不会超过桌面 Chrome。这两条来自 README 的 Limitations 一节属于引擎限制而非配置问题。适用边界需要 CSSscroll-snap语义、依赖 120Hz 平滑渲染或主交互发生在 iframe 内的场景Lenis 不是合适选择。完整参数表、事件与方法说明见仓库根目录 README各子包文档见 packages/。【免费下载链接】lenisSmooth scroll as it should be项目地址: https://gitcode.com/GitHub_Trending/le/lenis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考