Locomotive Scroll 快速上手：JavaScript 初始化、CSS 引入与水平滚动实战指南

【免费下载链接】locomotive-scroll Detection of elements in viewport smooth scrolling with parallax.项目地址https://gitcode.com/gh_mirrors/lo/locomotive-scroll点击查看免费下载本篇技术指南围绕 Locomotive Scroll 官方文档中的 Usage 使用指南 展开系统讲解如何通过打包器或 CDN 引入 JavaScript、如何通过import、link与 Sass 引入基础样式以及启用水平滚动所需的 CSS 规则。读完本文你将掌握new LocomotiveScroll()的最小可用配置、data-scroll与data-scroll-speed的实战用法并能结合仓库源码理解初始化背后的 Lenis Core 双层架构为后续深入 parallax 与视口检测调优打下基础。安装前置先获得库文件在使用本文的代码之前你需要先安装 Locomotive Scroll。官方推荐通过 NPM 安装详见 installation.mdnpm install locomotive-scroll仓库中 packages/lib/package.json 显示当前包名为locomotive-scroll版本5.0.1并声明了对lenis1.3.17的运行时依赖——这意味着安装时 Lenis 会被自动带入无需手动额外安装。如果不想使用打包器也可以直接通过 CDN 引入bundled/locomotive-scroll.min.js见下文“无打包器”一节。JavaScript两种引入方式使用打包器Bundler在支持 ESM 的工程Vite、Webpack、Astro、Next.js 等中直接以命名导入方式使用import LocomotiveScroll from locomotive-scroll; const locomotiveScroll new LocomotiveScroll();构造函数不传任何参数即可工作它会以window为滚动容器、document.documentElement为内容元素启动一个全页平滑滚动实例并自动开始渲染循环。不使用打包器CDN在 HTML 中通过script标签引入 UMD 构建产物库会暴露全局LocomotiveScroll构造函数script srchttps://cdn.jsdelivr.net/npm/locomotive-scroll/bundled/locomotive-scroll.min.js/script script const locomotiveScroll new LocomotiveScroll(); /script说明仓库中bundled/locomotive-scroll.min.js正是通过microbundle以 UMD 格式打包的产物参见 package.json 中的build:bundle-min脚本CDN 路径与该产物的包内路径一致。初始化时到底发生了什么从源码看new LocomotiveScroll()并非只创建一个对象而是会启动一个完整的两层生命周期见 packages/lib/index.ts创建 Lenis 实例lenisInstance负责平滑滚动与滚动数值scroll、limit、velocity、direction、progress在html上写入data-scroll-orientation属性标识当前滚动方向默认vertical在下一帧requestAnimationFrame中创建Core实例扫描容器内所有带[data-scroll]的元素Core内部再拆分出两套 Intersection ObserverIOTriggerInstance与IORafInstance分别用于“触发类”与“需逐帧计算类”元素参见 packages/lib/core/Core.ts若autoStart为默认的true立即启动 RAF 渲染循环。因此即使只写一行初始化代码data-scroll系列属性也已经自动生效——这正是“声明式使用”的基础。CSS三套引入方案与必备样式方案一CSS 中import在 CSS 入口文件顶部引入基础样式import locomotive-scroll/dist/locomotive-scroll.css;dist/locomotive-scroll.css是由 styles/main.css 经 PostCSS 构建生成的见 package.json 的build:css脚本它定义了[data-scroll-container]、.is-inview等基础规则。方案二HTML 中link直连 bundled CSSlink relstylesheet hrefhttps://cdn.jsdelivr.net/npm/locomotive-scroll/bundled/locomotive-scroll.css /该文件对应仓库中的packages/lib/bundled/locomotive-scroll.css适合无构建工具的纯静态页面。方案三Sass 中导入在 SCSS 工程中按 Vendor 方式导入// Vendors import node_modules/locomotive-scroll/dist/locomotive-scroll;样式注意事项推荐参考 Lenis 官方文档中关于样式考量的说明原文档给出的 Lenis 文档链接此处不展开外部内容。核心思路是尽量保持布局的简单与可控避免依赖原生滚动容器以外的复杂布局以确保 Lenis 的尺寸检测与定位计算准确。水平滚动Horizontal必备 CSS 规则当你通过lenisOptions.orientation: horizontal启用水平滚动时需要额外应用以下规则否则内容会被换行挤压/* Only necessary with horizontal scrolling */ html[data-scroll-orientationhorizontal] { body { width: fit-content; } [data-scroll-container] { display: flex; } }两点说明选择器html[data-scroll-orientationhorizontal]与源码行为严格对应初始化时 Lenis 的orientation会被写入html的data-scroll-orientation属性见 index.ts因此该 CSS 只有在水平模式实例下才会生效不会污染垂直滚动页面body { width: fit-content; }让页面宽度跟随内容收缩[data-scroll-container] { display: flex; }让子元素横向排列二者配合才能形成可水平滚动的“轨道”。在仓库 packages/lib/types.ts 中滚动方向类型定义为vertical | horizontal可见水平滚动是官方一等公民能力。动手试一试最小可运行示例将下面的 HTML 保存为页面配合上文的 JS 初始化代码即可看到视口检测与 parallax 效果main styleheight: 150vh; div h1Hello /h1 /div div h2>import LocomotiveScroll from locomotive-scroll; const locomotiveScroll new LocomotiveScroll();逐行拆解这个示例main styleheight: 150vh;撑出超过一屏的滚动空间让平滑滚动与 parallax 有施展余地data-scroll声明该元素参与视口检测。源码在初始化时通过querySelectorAll([data-scroll])收集这些元素见 Core.ts每个元素会被包装成ScrollElement实例见 ScrollElement.tsdata-scroll-speed0.5/data-scroll-speed0.8声明 parallax 速度系数。ScrollElement 会在每帧onRender中按公式计算位移位移 progress × containerSize × speed × -1其中containerSize是滚动容器的高度水平模式为宽度progress是元素在视口中的进度见 ScrollElement.ts。因此0.5表示元素以半速移动形成远近分层负值则会反向移动。建议从0.10.5的小值起步效果随视口尺寸自然缩放。触摸设备上的默认行为值得注意的是parallax 在触摸设备上默认自动关闭。构造函数通过ontouchstart in window || navigator.maxTouchPoints 0检测触摸能力见 index.ts并仅在非触摸设备上把smooth置为true当smooth为false时ScrollElement.onRender会把位移重置为 0见 ScrollElement.ts。若确实需要在移动端启用可为元素添加data-scroll-enable-touch-speed属性。进阶初始化参数与属性速查new LocomotiveScroll()支持一个可选配置对象完整参数说明见仓库文档 options.md与类型定义 types.ts 完全对应。常用项包括参数类型默认值作用lenisOptionsobject{}透传给 Lenis 的实例配置如wrapper、content、lerp、duration、orientation、smoothWheel等triggerRootMarginstring-1px -1px -1px -1px触发类元素的 IntersectionObserver rootMarginrafRootMarginstring100% 100% 100% 100%逐帧计算类元素含data-scroll-speed等的 IO rootMarginautoStartbooleantrue是否自动启动 RAF设为false后需手动调用start()scrollCallbackfunction无订阅滚动回调入参为{ scroll, limit, velocity, direction, progress }initCustomTicker/destroyCustomTickerfunction无用外部 ticker如 GSAP接管渲染循环实例方法方面常用有start()/stop()控制渲染循环、scrollTo(target, options)编程式滚动、resize()、addScrollElements($newContainer)/removeScrollElements($oldContainer)动态增删data-scroll元素实现均位于 index.ts。所有可用的data-scroll-*属性如data-scroll-position、data-scroll-offset、data-scroll-class、data-scroll-repeat、data-scroll-call、data-scroll-css-progress、data-scroll-to系列等的完整说明见仓库文档 attributes.md此处不逐一展开。真实工程参考Demo 中的用法仓库自带的 Demo 工程 展示了如何在框架化项目Astro 类型化模块中接入它通过自定义的Scroll类调用Scroll.init()完成初始化并监听progressEvent、progressPositionEvent、scrollEvent等自定义事件来更新页面上的进度标签——这正是data-scroll-event-progress、data-scroll-call属性的典型消费方式。如果你在 React/Vue/Astro 中接入可以参考这种“初始化一次、用事件驱动 UI”的模式避免在每次渲染时重复创建实例。小结本文完整覆盖了 Locomotive Scroll 使用文档的四个核心环节JS 引入打包器 / CDN、CSS 引入import/link/ Sass、水平滚动样式、以及一个可立即运行的 parallax 示例。在此基础上我们还沿着源码index.ts→Core.ts→ScrollElement.ts→IO.ts梳理了初始化流程与 parallax 计算原理并给出了触摸设备行为、常用配置参数与真实 Demo 参考。接下来建议结合 attributes.md 与 options.md 深入配置你的页面让视口检测与平滑滚动真正服务于你的动效设计。赞分享【免费下载链接】locomotive-scroll Detection of elements in viewport smooth scrolling with parallax.项目地址https://gitcode.com/gh_mirrors/lo/locomotive-scroll点击查看免费下载相关推荐Locomotive Astro Boilerplate 实战指南在 Astro 5 中集成 Locomotive Scroll 实现平滑滚动与视差Locomotive Astro Boilerplate 实战指南在 Astro 5 中集成 Locomotive Scroll 实现平滑滚动与视差 导读 p10分钟快速上手smooth-scroll从零开始实现平滑滚动效果终极指南10分钟快速上手smooth scroll从零开始实现平滑滚动效果终极指南 想要为你的网站添加优雅的平滑滚动动画吗smooth scroll是一个轻量级的J前端cube-ui 快速上手脚手架初始化、编译配置与按需引入实战cube ui 快速上手脚手架初始化、编译配置与按需引入实战 cube ui 是一套由滴滴开源、基于 Vue 实现的移动端 UI 组件库本指南以官方快速上手前端UI组件移动开发上一篇5分钟快速上手React Native WindowsWindows原生应用开发终极指南下一篇NymphCast终极音视频投送系统完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考