Locomotive Scroll

Locomotive Scroll を使用したスムーススクロール、パララックス効果、スクロール駆動アニメーションの実装に関する包括的ガイド。

概要

Locomotive Scroll は以下を提供する JavaScript ライブラリです:

• スムーススクロール: ハードウェアアクセラレーション対応のスムーススクロール（カスタマイズ可能なイージング）
• パララックス効果: 要素レベルの速度制御による奥行き表現
• ビューポート検出: 要素がビューポートに出入りするタイミングを追跡
• スクロールイベント: アニメーション同期のためのスクロール進度監視
• Sticky 要素: 定義された境界内での要素ピン留め
• 水平スクロール: 水平スクロールレイアウト対応

Locomotive Scroll を使用する場面:

• パララックスを備えた没入型ランディングページの構築
• Apple スタイルのスムーズなスクロール体験の作成
• スクロールトリガーアニメーションの実装
• ナラティブ/ストーリーテリング Web サイトの開発
• 長文コンテンツへの奥行きとモーション追加

トレードオフ:

• スクロール乗っ取りはアクセシビリティに影響（無効化オプション提供）
• ロースペックデバイスでのパフォーマンスオーバーヘッド（検出して無効化）
• モバイルタッチスクロールの感覚が異なる（徹底的にテスト）
• fixed ポジショニングは回避策が必要

インストール

npm install locomotive-scroll

// ES6
import LocomotiveScroll from 'locomotive-scroll';
import 'locomotive-scroll/dist/locomotive-scroll.css';

// または CDN 経由
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/locomotive-scroll/dist/locomotive-scroll.min.css">
<script src="https://cdn.jsdelivr.net/npm/locomotive-scroll/dist/locomotive-scroll.min.js"></script>

コアコンセプト

1. HTML 構造

すべての Locomotive Scroll 実装には特定のデータ属性が必要です:

<!-- スクロールコンテナ (必須) -->
<div data-scroll-container>

  <!-- スクロールセクション (オプション、パフォーマンス向上) -->
  <div data-scroll-section>

    <!-- 追跡対象要素 -->
    <h1 data-scroll>基本的な検出</h1>

    <!-- パララックス要素 -->
    <div data-scroll data-scroll-speed="2">
      スクロール速度より速く移動
    </div>

    <!-- Sticky 要素 -->
    <div data-scroll data-scroll-sticky>
      セクション内で固定
    </div>

    <!-- ID 付き追跡要素 -->
    <div data-scroll data-scroll-id="hero">
      JavaScript からアクセス可能
    </div>

    <!-- イベントトリガー -->
    <div data-scroll data-scroll-call="fadeIn">
      カスタムイベント発火
    </div>

  </div>
</div>

2. 初期化

const scroll = new LocomotiveScroll({
  el: document.querySelector('[data-scroll-container]'),
  smooth: true,
  lerp: 0.1,        // スムーズさ (0-1、低いほどスムーズ)
  multiplier: 1,    // 速度乗数
  class: 'is-inview', // 表示中の要素に追加するクラス
  repeat: false,    // 表示内検出を繰り返す
  offset: [0, 0]    // グローバルトリガーオフセット [下, 上]
});

3. データ属性

属性	目的	例
data-scroll	検出を有効化	data-scroll
data-scroll-speed	パララックス速度	data-scroll-speed="2"
data-scroll-direction	パララックス軸	data-scroll-direction="horizontal"
data-scroll-sticky	Sticky ポジショニング	data-scroll-sticky
data-scroll-target	Sticky 境界	data-scroll-target="#section"
data-scroll-offset	トリガーオフセット	data-scroll-offset="20%"
data-scroll-repeat	検出を繰り返す	data-scroll-repeat
data-scroll-call	イベントトリガー	data-scroll-call="myFunction"
data-scroll-id	ユニーク識別子	data-scroll-id="hero"
data-scroll-class	カスタムクラス	data-scroll-class="is-visible"

一般的なパターン

1. 基本的なスムーススクロール

import LocomotiveScroll from 'locomotive-scroll';

const scroll = new LocomotiveScroll({
  el: document.querySelector('[data-scroll-container]'),
  smooth: true
});

<div data-scroll-container>
  <div data-scroll-section>
    <h1>スムーススクロール有効化</h1>
  </div>
</div>

2. パララックス効果

<!-- スローパララックス -->
<div data-scroll data-scroll-speed="0.5">
  スクロール速度より遅く移動（背景効果）
</div>

<!-- ファストパララックス -->
<div data-scroll data-scroll-speed="3">
  スクロール速度より速く移動（前景効果）
</div>

<!-- リバースパララックス -->
<div data-scroll data-scroll-speed="-2">
  逆方向に移動
</div>

<!-- 水平パララックス -->
<div data-scroll data-scroll-speed="2" data-scroll-direction="horizontal">
  水平方向に移動
</div>

3. ビューポート検出とコールバック

// スクロール進度を追跡
scroll.on('scroll', (args) => {
  console.log(args.scroll.y); // 現在のスクロール位置
  console.log(args.speed);    // スクロール速度
  console.log(args.direction); // スクロール方向

  // 特定の要素の進度にアクセス
  if (args.currentElements['hero']) {
    const progress = args.currentElements['hero'].progress;
    console.log(`Hero の進度: ${progress}`); // 0 から 1
  }
});

// イベント呼び出し
scroll.on('call', (value, way, obj) => {
  console.log(`イベント発火: ${value}`);
  // value = data-scroll-call 属性値
  // way = 'enter' または 'exit'
  // obj = {id, el}
});

<div data-scroll data-scroll-id="hero">Hero セクション</div>
<div data-scroll data-scroll-call="playVideo">動画セクション</div>

4. Sticky 要素

<!-- 親セクション内で固定 -->
<div data-scroll-section>
  <div data-scroll data-scroll-sticky>
    セクションが表示中に固定
  </div>
</div>

<!-- 特定ターゲットで固定 -->
<div id="sticky-container">
  <div data-scroll data-scroll-sticky data-scroll-target="#sticky-container">
    #sticky-container 内で固定
  </div>
</div>

5. プログラマティックスクロール

// 要素へスクロール
scroll.scrollTo('#target-section');

// トップへスクロール
scroll.scrollTo('top');

// ボトムへスクロール
scroll.scrollTo('bottom');

// オプション付きでスクロール
scroll.scrollTo('#target', {
  offset: -100,      // ピクセル単位のオフセット
  duration: 1000,    // ミリ秒単位の期間
  easing: [0.25, 0.0, 0.35, 1.0], // Cubic Bezier
  disableLerp: true, // スムーズな lerp を無効化
  callback: () => console.log('スクロール完了!')
});

// ピクセル値へスクロール
scroll.scrollTo(500);

6. 水平スクロール

const scroll = new LocomotiveScroll({
  el: document.querySelector('[data-scroll-container]'),
  smooth: true,
  direction: 'horizontal'
});

<div data-scroll-container>
  <div data-scroll-section style="display: flex; width: 300vw;">
    <div>セクション 1</div>
    <div>セクション 2</div>
    <div>セクション 3</div>
  </div>
</div>

7. モバイルレスポンシブ対応

const scroll = new LocomotiveScroll({
  el: document.querySelector('[data-scroll-container]'),
  smooth: true,

  // タブレット設定
  tablet: {
    smooth: true,
    breakpoint: 1024
  },

  // スマートフォン設定
  smartphone: {
    smooth: false, // パフォーマンス用に無効化
    breakpoint: 768
  }
});

GSAP ScrollTrigger との統合

Locomotive Scroll と GSAP ScrollTrigger は高度なアニメーションで連携します:

import LocomotiveScroll from 'locomotive-scroll';
import { gsap } from 'gsap';
import { ScrollTrigger } from 'gsap/ScrollTrigger';

gsap.registerPlugin(ScrollTrigger);

const locoScroll = new LocomotiveScroll({
  el: document.querySelector('[data-scroll-container]'),
  smooth: true
});

// Locomotive Scroll と ScrollTrigger を同期
locoScroll.on('scroll', ScrollTrigger.update);

ScrollTrigger.scrollerProxy('[data-scroll-container]', {
  scrollTop(value) {
    return arguments.length
      ? locoScroll.scrollTo(value, 0, 0)
      : locoScroll.scroll.instance.scroll.y;
  },
  getBoundingClientRect() {
    return {
      top: 0,
      left: 0,
      width: window.innerWidth,
      height: window.innerHeight
    };
  },
  pinType: document.querySelector('[data-scroll-container]').style.transform
    ? 'transform'
    : 'fixed'
});

// ScrollTrigger を使用した GSAP アニメーション
gsap.to('.fade-in', {
  scrollTrigger: {
    trigger: '.fade-in',
    scroller: '[data-scroll-container]',
    start: 'top bottom',
    end: 'top center',
    scrub: true
  },
  opacity: 1,
  y: 0
});

// Locomotive 更新時に ScrollTrigger を更新
ScrollTrigger.addEventListener('refresh', () => locoScroll.update());
ScrollTrigger.refresh();

インスタンスメソッド

const scroll = new LocomotiveScroll();

// ライフサイクル
scroll.init();     // 再初期化
scroll.update();   // 要素位置を更新
scroll.destroy();  // クリーンアップ
scroll.start();    // スクロール再開
scroll.stop();     // スクロール一時停止

// ナビゲーション
scroll.scrollTo(target, options);
scroll.setScroll(x, y);

// イベント
scroll.on('scroll', callback);
scroll.on('call', callback);
scroll.off('scroll', callback);

パフォーマンス最適化

1. data-scroll-section を使用して長いページをセグメント化:

<div data-scroll-container>
  <div data-scroll-section>セクション 1</div>
  <div data-scroll-section>セクション 2</div>
  <div data-scroll-section>セクション 3</div>
</div>

2. パララックス要素を制限 - 多すぎるとパフォーマンスに影響

3. モバイルでは無効化 - パフォーマンスが悪い場合:

smartphone: { smooth: false }

4. リサイズ時に更新:

window.addEventListener('resize', () => {
  scroll.update();
});

5. 不要な場合は破棄:

scroll.destroy();

一般的な落とし穴

1. Fixed ポジショニングの問題

問題: position: fixed 要素はスムーススクロールで破損

解決策: data-scroll-sticky を使用するか、fixed 要素をコンテナ外に配置:

<!-- コンテナ外の fixed ナビゲーション -->
<nav style="position: fixed;">ナビゲーション</nav>

<div data-scroll-container>
  <!-- ページコンテンツ -->
</div>

2. 画像の遅延読み込みが機能しない

問題: すべての画像が一度に読み込まれる

解決策: 遅延読み込みと統合:

<img data-scroll data-src="image.jpg" class="lazy">

scroll.on('call', (func) => {
  if (func === 'lazyLoad') {
    // 遅延読み込みをトリガー
  }
});

3. スクロール位置が更新されない

問題: 動的コンテンツがスクロール位置を更新しない

解決策: DOM 変更後に update() を呼び出し:

// コンテンツ追加後
addDynamicContent();
scroll.update();

4. アクセシビリティの懸念

問題: スクリーンリーダーとキーボードナビゲーションが破損

解決策: 無効化オプションを提供:

const prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;

const scroll = new LocomotiveScroll({
  smooth: !prefersReducedMotion
});

5. メモリリーク

問題: ルート変更時（SPA）にスクロールインスタンスがクリーンアップされない

解決策: アンマウント時に常に破棄:

// React の例
useEffect(() => {
  const scroll = new LocomotiveScroll();

  return () => scroll.destroy();
}, []);

6. Z-Index の衝突

問題: パララックス要素が不正に重なる

解決策: パララックスレイヤーで明示的な z-index を設定:

[data-scroll-speed] {
  position: relative;
  z-index: var(--layer-depth);
}

関連スキル

• gsap-scrolltrigger: 高度なスクロール駆動アニメーション（一緒に使用）
• barba-js: Locomotive Scroll 統合のページトランジション
• scroll-reveal-libraries: 基本的なフェードイン効果の簡潔な代替案
• react-three-fiber: スクロール駆動 3D シーン（Locomotive イベントで同期）
• motion-framer: React でのスクロールアニメーション代替案

リソース

• スクリプト: generate_config.py - 設定生成器、integration_helper.py - GSAP 統合コード
• 参照: api_reference.md - 完全な API、gsap_integration.md - GSAP ScrollTrigger パターン
• アセット: starter_locomotive/ - 例を備えた完全なスターターテンプレート