如何修复 Locomotive Scroll 无法滚动的问题？-js教程-PHP中文网

如何修复 Locomotive Scroll 无法滚动的问题？

Locomotive Scroll 失效通常是因为缺少必需的 data-scroll-container 和 data-scroll-section 属性，且未正确初始化实例；本文详解配置要点、HTML 结构修正与 JS 初始化方法，并提供可直接运行的完整示例。

locomotive scroll 失效通常是因为缺少必需的 `data-scroll-container` 和 `data-scroll-section` 属性，且未正确初始化实例；本文详解配置要点、html 结构修正与 js 初始化方法，并提供可直接运行的完整示例。

要使 Locomotive Scroll 正常工作，HTML 结构、CSS 布局与 JavaScript 初始化三者必须协同配合。你当前代码中虽引入了库文件和 CSS，但存在三个关键缺失：

缺少容器标识：data-scroll-container 必须添加在最外层滚动容器上（如
）；
缺少分节标识：每个垂直“页面”（如 #page-1、#page-2）需包裹在 data-scroll-section 元素内；
未初始化实例：必须通过 new LocomotiveScroll({ el: ... }) 显式启动滚动引擎。

✅ 正确结构应如下（精简核心部分）：

<!-- ✅ 关键：添加 data-scroll-container -->
<div id="main" data-scroll-container>
  <!-- ✅ 关键：每个 section 包裹在 data-scroll-section 中 -->
  <div data-scroll-section>
    <div data-scroll data-scroll-speed="-5" id="page-1">
      <!-- 页面1内容 -->
      <video src="..." autoplay loop muted></video><h2>Experience Real Estate Agility</h2>
    </div>
  </div>

  <div data-scroll-section>
    <!-- ✅ #page-2 现在是独立 section，支持平滑滚动进入 -->
    <div id="page-2" data-scroll>
      <p>PAGE 2 — now scrollable and positioned correctly</p>
    </div>
  </div>
</div>

? CSS 注意事项：

#main 不应设置 height: 100vh 或 overflow: hidden，否则会截断后续内容；保持 overflow: visible（你已正确设置）；
所有 data-scroll-section 内的子元素（如 #page-1, #page-2）必须为块级、有明确高度（如 height: 100vh），否则 Locomotive Scroll 无法计算滚动锚点；
避免对 body 或 html 设置 overflow: hidden —— 这会直接禁用原生滚动，导致插件失去监听基础。

? JavaScript 初始化（务必放在所有 DOM 加载后）：

<script>
  // ✅ 确保 DOM 已就绪（推荐使用 DOMContentLoaded）
  document.addEventListener('DOMContentLoaded', () => {
    const scroll = new LocomotiveScroll({
      el: document.querySelector('[data-scroll-container]'),
      smooth: true,
      multiplier: 1,
      class: 'is-revealed',
      firefoxMultiplier: 50,
      smartphone: {
        smooth: true,
        breakpoint: 767
      }
    });

    // ✅ 可选：与 GSAP ScrollTrigger 同步（如需高级动画联动）
    // gsap.registerPlugin(ScrollTrigger);
    // ScrollTrigger.scrollerProxy('[data-scroll-container]', {
    //   scrollTop(value) {
    //     return arguments.length ? scroll.scrollTo(value, 0, 0) : scroll.scroll.instance.scroll.y;
    //   },
    //   getBoundingClientRect() {
    //     return { top: 0, left: 0, width: window.innerWidth, height: window.innerHeight };
    //   }
    // });
  });
</script>

⚠️ 常见陷阱提醒：

❌ 不要在上直接加 data-scroll-container（LoCo 不支持 body 作为容器）；
❌ 不要遗漏 data-scroll 属性在需要动效的子元素上（如 #page-1 的 data-scroll-speed="-5" 依赖该属性触发）；
❌ 初始化脚本必须在 locomotive-scroll.js 加载之后执行，且不能早于 DOM 渲染 —— 使用 DOMContentLoaded 是最稳妥方式；
✅ 若启用 smooth: true，请确保已引入 locomotive-scroll.css（你已正确引入）。

最后验证：打开浏览器开发者工具 → Elements 面板 → 检查 #main 是否有 data-scroll-container，其子 div[data-scroll-section] 是否存在，且控制台无 LocomotiveScroll is not defined 报错。满足以上条件后，滚动将立即生效，#page-2 将平滑上浮覆盖 #page-1 视口区域，实现预期视差与分页效果。