Locomotive Scroll v5 完整配置指南：从 lenisOptions 到自定义 Ticker 的实战解析

【免费下载链接】locomotive-scroll Detection of elements in viewport smooth scrolling with parallax.项目地址https://gitcode.com/gh_mirrors/lo/locomotive-scroll点击查看免费下载Locomotive Scroll 是一款轻量级、现代化的滚动库专注于元素视口检测、动画与平滑滚动并构建在 Lenis 之上。本指南围绕官方文档中的 Options 章节逐项讲解lenisOptions、triggerRootMargin、rafRootMargin、autoStart、scrollCallback、initCustomTicker与destroyCustomTicker的语义、默认值与典型用法并结合仓库源码packages/lib/core/Core.ts 等说明这些配置在底层是如何被消费的帮助你写出可复制、可调优的初始化代码。Locomotive Scroll v5 完整配置指南从 lenisOptions 到自定义 Ticker 的实战解析Locomotive Scroll 是一款构建于 Lenis 之上的现代化滚动库用于元素视口检测、平滑滚动与视差动画。本指南以官方 Options 文档为骨架逐一解析lenisOptions、triggerRootMargin、rafRootMargin、autoStart、scrollCallback、initCustomTicker与destroyCustomTicker的语义、默认值与实战用法并结合仓库源码packages/lib/core/Core.ts、packages/lib/index.ts、packages/lib/types.ts说明每个配置项在底层如何被消费与联动助你写出可复制、可调优的初始化代码。lenisOptions透传给 Lenis 的核心滚动行为lenisOptions是构造LocomotiveScroll时可选的object类型参数用于按 Lenis 实例设置覆盖默认值。它在源码中的消费方式是直接展开传入 Lenis 构造函数// packages/lib/index.ts this.lenisInstance new Lenis({ ...this.lenisOptions });因此你所能配置的全部键与 Lenis 的 instance settings 保持一致。下表汇总了官方文档列出的键、类型与说明键类型说明wrapperHTMLElement \| Window作为滚动容器的元素默认window整页滚动可设为自定义元素实现局部滚动contentHTMLElement被滚动内容的容器通常为wrapper的直接子元素默认document.documentElementlerpnumber帧间线性插值强度取值 0 到 1越大越“跟手”durationnumber动画时长秒orientationstringvertical或horizontal会在html上写入data-scroll-orientation属性gestureOrientationboolean手势方向可设为vertical、horizontal或bothsmoothWheelboolean是否对鼠标滚轮启用平滑滚动smoothTouchboolean是否对触摸事件启用平滑滚动默认关闭因为无法模拟触屏的原生顺滑度wheelMultipliernumber鼠标滚轮事件的滚动倍率touchMultipliernumber触摸事件的滚动倍率normalizeWheelboolean是否跨浏览器归一化滚轮输入easingfunction值的缓动函数默认使用自定义缓动可替换为 Easings.net 上的曲线带默认值的完整示例const locomotiveScroll new LocomotiveScroll({ lenisOptions: { wrapper: window, content: document.documentElement, lerp: 0.1, duration: 1.2, orientation: vertical, gestureOrientation: vertical, smoothWheel: true, smoothTouch: false, wheelMultiplier: 1, touchMultiplier: 2, normalizeWheel: true, easing: (t) Math.min(1, 1.001 - Math.pow(2, -10 * t)), }, });值得注意的是orientation配置并非仅作用于 Lenis 的滚动方向初始化时 Locomotive Scroll 会把它同步到html标签并将该值作为scrollOrientation传给 Core驱动所有ScrollElement的计算。在 ScrollElement.ts 中可以看到方向不同会缓存不同的窗口尺寸与度量函数纵向取height/top横向取width/left视差位移也会按方向写成translate3d(0, y, 0)或translate3d(x, 0, 0)。自定义滚动容器当页面存在局部滚动区域而非整页滚动时可以显式指定wrapper与contentconst locomotiveScroll new LocomotiveScroll({ lenisOptions: { wrapper: document.querySelector(.scroll-container), content: document.querySelector(.scroll-content), }, });div classscroll-container styleheight: 100vh; overflow: hidden; div classscroll-content div>// 默认值 const locomotiveScroll new LocomotiveScroll({ triggerRootMargin: -1px -1px -1px -1px, });触发型元素指带有data-scroll但不依赖 RAF 更新的元素。Core 在_checkRafNeededCore.ts中根据属性判定是否需要 RAF仅当元素带有非默认的data-scroll-offset、非默认的data-scroll-position、合法的data-scroll-speed或存在data-scroll-css-progress/data-scroll-event-progress时才走 RAF 通道否则归入触发型通道由IOTriggerInstance以triggerRootMargin观察。默认的-1px让元素边界略微内收保证在元素真正进入视口时才触发进入/离开回调。rafRootMargin扩大 RAF 元素的检测窗口类型string默认值100% 100% 100% 100%该配置指定需要基于 RequestAnimationFrame 持续更新的元素的 IntersectionObserverrootMargin适用于带以下任意属性的元素data-scroll-offset、data-scroll-position、data-scroll-css-progress、data-scroll-event-progress、data-scroll-speed。// 默认值 const locomotiveScroll new LocomotiveScroll({ rafRootMargin: 100% 100% 100% 100%, });默认的100%在上下各扩展一个视口高度、左右各扩展一个视口宽度让视差元素提前进入观察范围、提前开始平滑插值。源码注释Core.ts明确写道加100vhtop/bottom 与100vwleft/right 是为了让data-scroll-speed使用更大的值。这些元素由IORafInstance观察进入视野后通过setInteractivityOn订阅到主渲染循环IO.ts并在离开后取消订阅、把进度强制收敛到最近的端点ScrollElement.ts。两个 rootMargin 之所以分离是因为触发型元素与 RAF 型元素的生命周期不同前者只需在边界处各触发一次后者需要持续每帧计算。autoStart手动控制 RAF 的启停类型boolean默认值true初始化时是否自动启动 RequestAnimationFrame。默认true即实例化后 RAF 立即运行。若想手动控制启动时机可关闭它再调用start()// 默认值 const locomotiveScroll new LocomotiveScroll({ autoStart: false, }); // 手动启动 RAF setTimeout(() { locomotiveScroll.start(); }, 2000)源码中autoStart作为构造参数默认trueindex.ts并在requestAnimationFrame内执行this.autoStart this.start()index.ts。start()会先调用lenisInstance.start()再进入内部_raf循环stop()则相反地停止 Lenis 并取消 RAFindex.ts。rafPlaying标志保证了重复调用start()/stop()是幂等的。这一配置在页面预加载、路由切换、需要暂停滚动动画的场景中非常实用。scrollCallback获取 Lenis 的滚动数据流类型function指定一个回调函数返回对象{ scroll, limit, velocity, direction, progress }。该能力由 Lenis 的 scroll 回调提供import LocomotiveScroll from locomotive-scroll; function onScroll({ scroll, limit, velocity, direction, progress }) { console.log(scroll, limit, velocity, direction, progress); } const locomotiveScroll new LocomotiveScroll({ scrollCallback: onScroll, });各字段在 types.ts 中定义为ILenisScrollValuesscroll为当前滚动位置、limit为最大可滚动距离、velocity为当前速度、direction为滚动方向、progress为 0 到 1 的整体进度。源码在初始化时执行this.lenisInstance.on(scroll, this.scrollCallback)index.ts因此回调会随每次滚动事件触发。相比手动监听原生scroll事件从这里拿到的数值已经过 Lenis 平滑处理适合驱动导航高亮、进度条、页面过渡等 UI 状态。initCustomTicker / destroyCustomTicker接入外部时间轴两者都是function类型成对使用用于以外部 ticker 替代 Locomotive Scroll 默认的 requestAnimationFrame。官方示例以 GSAP 的 ticker 接管渲染循环import LocomotiveScroll from locomotive-scroll; import { gsap } from gsap/all; const locomotiveScroll new LocomotiveScroll({ initCustomTicker: (render) { gsap.ticker.add(render); }, destroyCustomTicker: (render) { gsap.ticker.remove(render); }, });initCustomTicker指定初始化外部 ticker 的回调把内部渲染函数render注册进外部循环destroyCustomTicker指定销毁外部 ticker 的回调把render从外部循环移除。源码中start()在存在initCustomTicker时改走外部 ticker 路径stop()则对称地调用destroyCustomTickerindex.ts。如果两者只声明其一控制台会输出警告index.ts。将滚动渲染并入 GSAP ticker 的好处是让页面内所有动画共享同一时间基准避免多套 RAF 循环造成的帧时序不一致。配置的底层联动双 Intersection Observer 架构理解以上选项还需了解它们共同作用的运行时架构。Core 在初始化时建立两套观察器Core.tsTrigger IOIOTriggerInstance以triggerRootMargin观察触发型元素进入时调用setInview添加is-inviewclass、派发data-scroll-call事件离开且无data-scroll-repeat时停止观察RAF IOIORafInstance以rafRootMargin观察需要持续计算的元素进入时setInteractivityOn订阅主循环、离开时setInteractivityOff取消订阅。这两个观察器的 root 都取决于lenisOptions.wrapperwindow时为null否则为 wrapper 元素。滚动值统一来自 Lenis 实例因此lenisOptions中的lerp、orientation等不仅影响平滑手感也会间接决定每个ScrollElement的进度与视差幅度triggerRootMargin与rafRootMargin则精确控制两套观察器何时“唤醒”元素。理解这条链路你就能在调试视差“提前/滞后触发”“元素卡在边界”等问题时迅速定位到对应的配置项。Locomotive Scroll v5 完整配置指南从 lenisOptions 到自定义 Ticker 的实战解析Locomotive Scroll 是一款构建于 Lenis 之上的现代化滚动库专为元素视口检测、平滑滚动与视差动画而设计。本指南以官方 Options 文档为骨架逐一解析lenisOptions、triggerRootMargin、rafRootMargin、autoStart、scrollCallback、initCustomTicker与destroyCustomTicker的语义、默认值与实战用法并结合仓库源码packages/lib/core/Core.ts、packages/lib/index.ts、packages/lib/types.ts说明每个配置项在底层如何被消费与联动助你写出可复制、可调优的初始化代码。lenisOptions透传给 Lenis 的核心滚动行为lenisOptions是构造LocomotiveScroll时可选的object类型参数用于按 Lenis 实例设置覆盖默认值。它在源码中的消费方式是直接展开传入 Lenis 构造函数// packages/lib/index.ts this.lenisInstance new Lenis({ ...this.lenisOptions });因此你所能配置的全部键与 Lenis 的 instance settings 保持一致。下表汇总了官方文档列出的键、类型与说明键类型说明wrapperHTMLElement \| Window作为滚动容器的元素默认window整页滚动可设为自定义元素实现局部滚动contentHTMLElement被滚动内容的容器通常为wrapper的直接子元素默认document.documentElementlerpnumber帧间线性插值强度取值 0 到 1越大越“跟手”durationnumber动画时长秒orientationstringvertical或horizontal会在html上写入data-scroll-orientation属性gestureOrientationboolean手势方向可设为vertical、horizontal或bothsmoothWheelboolean是否对鼠标滚轮启用平滑滚动smoothTouchboolean是否对触摸事件启用平滑滚动默认关闭因为无法模拟触屏的原生顺滑度wheelMultipliernumber鼠标滚轮事件的滚动倍率touchMultipliernumber触摸事件的滚动倍率normalizeWheelboolean是否跨浏览器归一化滚轮输入easingfunction值的缓动函数默认使用自定义缓动可替换为 Easings.net 上的曲线带默认值的完整示例const locomotiveScroll new LocomotiveScroll({ lenisOptions: { wrapper: window, content: document.documentElement, lerp: 0.1, duration: 1.2, orientation: vertical, gestureOrientation: vertical, smoothWheel: true, smoothTouch: false, wheelMultiplier: 1, touchMultiplier: 2, normalizeWheel: true, easing: (t) Math.min(1, 1.001 - Math.pow(2, -10 * t)), }, });值得注意的是orientation配置并非仅作用于 Lenis 的滚动方向初始化时 Locomotive Scroll 会把它同步到html标签并将该值作为scrollOrientation传给 Core驱动所有ScrollElement的计算。在 ScrollElement.ts 中可以看到方向不同会缓存不同的窗口尺寸与度量函数纵向取height/top横向取width/left视差位移也会按方向写成translate3d(0, y, 0)或translate3d(x, 0, 0)。自定义滚动容器当页面存在局部滚动区域而非整页滚动时可以显式指定wrapper与contentconst locomotiveScroll new LocomotiveScroll({ lenisOptions: { wrapper: document.querySelector(.scroll-container), content: document.querySelector(.scroll-content), }, });div classscroll-container styleheight: 100vh; overflow: hidden; div classscroll-content div>// 默认值 const locomotiveScroll new LocomotiveScroll({ triggerRootMargin: -1px -1px -1px -1px, });触发型元素指带有data-scroll但不依赖 RAF 更新的元素。Core 在_checkRafNeededCore.ts中根据属性判定是否需要 RAF仅当元素带有非默认的data-scroll-offset、非默认的data-scroll-position、合法的data-scroll-speed或存在data-scroll-css-progress/data-scroll-event-progress时才走 RAF 通道否则归入触发型通道由IOTriggerInstance以triggerRootMargin观察。默认的-1px让元素边界略微内收保证在元素真正进入视口时才触发进入/离开回调。rafRootMargin扩大 RAF 元素的检测窗口类型string默认值100% 100% 100% 100%该配置指定需要基于 RequestAnimationFrame 持续更新的元素的 IntersectionObserverrootMargin适用于带以下任意属性的元素data-scroll-offset、data-scroll-position、data-scroll-css-progress、data-scroll-event-progress、data-scroll-speed。// 默认值 const locomotiveScroll new LocomotiveScroll({ rafRootMargin: 100% 100% 100% 100%, });默认的100%在上下各扩展一个视口高度、左右各扩展一个视口宽度让视差元素提前进入观察范围、提前开始平滑插值。源码注释Core.ts明确写道加100vhtop/bottom 与100vwleft/right 是为了让data-scroll-speed使用更大的值。这些元素由IORafInstance观察进入视野后通过setInteractivityOn订阅到主渲染循环IO.ts并在离开后取消订阅、把进度强制收敛到最近的端点ScrollElement.ts。两个 rootMargin 之所以分离是因为触发型元素与 RAF 型元素的生命周期不同前者只需在边界处各触发一次后者需要持续每帧计算。autoStart手动控制 RAF 的启停类型boolean默认值true初始化时是否自动启动 RequestAnimationFrame。默认true即实例化后 RAF 立即运行。若想手动控制启动时机可关闭它再调用start()// 默认值 const locomotiveScroll new LocomotiveScroll({ autoStart: false, }); // 手动启动 RAF setTimeout(() { locomotiveScroll.start(); }, 2000)源码中autoStart作为构造参数默认trueindex.ts并在requestAnimationFrame内执行this.autoStart this.start()index.ts。start()会先调用lenisInstance.start()再进入内部_raf循环stop()则相反地停止 Lenis 并取消 RAFindex.ts。rafPlaying标志保证了重复调用start()/stop()是幂等的。这一配置在页面预加载、路由切换、需要暂停滚动动画的场景中非常实用。scrollCallback获取 Lenis 的滚动数据流类型function指定一个回调函数返回对象{ scroll, limit, velocity, direction, progress }。该能力由 Lenis 的 scroll 回调提供import LocomotiveScroll from locomotive-scroll; function onScroll({ scroll, limit, velocity, direction, progress }) { console.log(scroll, limit, velocity, direction, progress); } const locomotiveScroll new LocomotiveScroll({ scrollCallback: onScroll, });各字段在 types.ts 中定义为ILenisScrollValuesscroll为当前滚动位置、limit为最大可滚动距离、velocity为当前速度、direction为滚动方向、progress为 0 到 1 的整体进度。源码在初始化时执行this.lenisInstance.on(scroll, this.scrollCallback)index.ts因此回调会随每次滚动事件触发。相比手动监听原生scroll事件从这里拿到的数值已经过 Lenis 平滑处理适合驱动导航高亮、进度条、页面过渡等 UI 状态。initCustomTicker / destroyCustomTicker接入外部时间轴两者都是function类型成对使用用于以外部 ticker 替代 Locomotive Scroll 默认的 requestAnimationFrame。官方示例以 GSAP 的 ticker 接管渲染循环import LocomotiveScroll from locomotive-scroll; import { gsap } from gsap/all; const locomotiveScroll new LocomotiveScroll({ initCustomTicker: (render) { gsap.ticker.add(render); }, destroyCustomTicker: (render) { gsap.ticker.remove(render); }, });initCustomTicker指定初始化外部 ticker 的回调把内部渲染函数render注册进外部循环destroyCustomTicker指定销毁外部 ticker 的回调把render从外部循环移除。源码中start()在存在initCustomTicker时改走外部 ticker 路径stop()则对称地调用destroyCustomTickerindex.ts。如果两者只声明其一控制台会输出警告index.ts。将滚动渲染并入 GSAP ticker 的好处是让页面内所有动画共享同一时间基准避免多套 RAF 循环造成的帧时序不一致。配置的底层联动双 Intersection Observer 架构理解以上选项还需了解它们共同作用的运行时架构。Core 在初始化时建立两套观察器Core.tsTrigger IOIOTriggerInstance以triggerRootMargin观察触发型元素进入时调用setInview添加is-inviewclass、派发data-scroll-call事件离开且无data-scroll-repeat时停止观察RAF IOIORafInstance以rafRootMargin观察需要持续计算的元素进入时setInteractivityOn订阅主循环、离开时setInteractivityOff取消订阅。这两个观察器的 root 都取决于lenisOptions.wrapperwindow时为null否则为 wrapper 元素。滚动值统一来自 Lenis 实例因此lenisOptions中的lerp、orientation等不仅影响平滑手感也会间接决定每个ScrollElement的进度与视差幅度triggerRootMargin与rafRootMargin则精确控制两套观察器何时“唤醒”元素。理解这条链路你就能在调试视差“提前/滞后触发”“元素卡在边界”等问题时迅速定位到对应的配置项。赞分享【免费下载链接】locomotive-scroll Detection of elements in viewport smooth scrolling with parallax.项目地址https://gitcode.com/gh_mirrors/lo/locomotive-scroll点击查看免费下载相关推荐locomotive-scroll中的CSS Paint API自定义滚动指示器locomotive scroll中的CSS Paint API自定义滚动指示器 概述 locomotive scroll是一个专注于视口元素检测和平滑滚动的tp6-vue-admin用 ThinkPHP6Vue 快速搭建前后端分离后台管理系统的完整指南tp6 vue admin用 ThinkPHP6Vue 快速搭建前后端分离后台管理系统的完整指南 tp6 vue admin 是一个基于 ThinkPHP6locomotive-scroll中的Web Components自定义滚动元素locomotive scroll中的Web Components自定义滚动元素 在现代Web开发中滚动体验是用户交互的核心部分。locomotive sc上一篇Midday AI v1 开源项目使用教程下一篇《Midday AI v1 开源项目安装与配置指南》创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考