will-changeの使いどころと注意点！CSSアニメーション最適化術

/* 1. デフォルト：特別な最適化を行わない */
.box {
  will-change: auto;
}

/* 2. プロパティ名の指定：transform の変化に備えてコンポジットレイヤーを事前生成 */
.box--will-transform {
  will-change: transform;
}

/* 3. プロパティ名の指定：opacity の変化に備える場合 */
.box--will-opacity {
  will-change: opacity;
}

/* 4. キーワード値：要素のスクロール位置の変化を事前通知 */
.scroll-container {
  will-change: scroll-position;
}

/* 5. キーワード値：子要素やコンテンツ自体の変化を事前通知 */
.dynamic-content {
  will-change: contents;
}

/* 良い例：カンマ区切りで複数指定 */
.modal {
  will-change: transform, opacity;
}

/* 悪い例：スペース区切りは無効(構文エラーとして無視される) */
.modal--invalid {
  will-change: transform opacity;
}

/* 良い例：hoverアニメーションにtransformを使用 */
.card {
  transition: transform 0.3s ease;
}

.card:hover {
  transform: scale(1.05);
}

/* will-changeを指定するclass */
.card.is-animating {
  will-change: transform;
}

// 良い例：アニメーション開始前にwill-changeを付与
const card = document.querySelector('.card');

card.addEventListener('mouseenter', () => {
  card.classList.add('is-animating');
});

card.addEventListener('mouseleave', () => {
  card.classList.remove('is-animating');
});

/* 要検証：filterをアニメーションさせる場合 */
.overlay {
  filter: blur(0px);
  transition: filter 0.5s ease;
}

.overlay.is-active {
  filter: blur(10px);
}

.overlay.needs-optimization {
  will-change: filter;
}

/* 悪い例：height/widthの変化にwill-changeを指定(効果なし) */
.accordion-item {
  height: 0;
  overflow: hidden;
  will-change: height; /* 無効。むしろメモリ浪費 */
}

.accordion-item.is-open {
  height: auto;
}

/* CSSによる簡易実装例（注意：max-heightもレイアウト再計算が発生するため will-change は無効） */
.accordion-item {
  max-height: 0;
  overflow: hidden;
  transition: max-height 0.3s ease;
  /* will-change: max-height; 指定してもリフローは回避できないため不要 */
}

.accordion-item.is-open {
  max-height: 500px; /* 実際の開いた状態の高さに設定 */
}

/* 推奨案（パフォーマンス優先）：transformでスケーリング(コンポジット段階で完結) */
.accordion-item {
  transform-origin: top;
  transform: scaleY(0);
  transition: transform 0.3s ease;
}

.accordion-item.will-animate {
  will-change: transform; /* コンポジット処理で完結するため極めて有効 */
}

.accordion-item.is-open {
  transform: scaleY(1);
}

<!-- HTMLマークアップ：基本的な構造 -->
<div class="card">
  <h3>コンテンツ</h3>
</div>

/* CSS：基本スタイル */
.card {
  transition: transform 0.3s ease, opacity 0.3s ease;
  transform: scale(1);
  opacity: 1;
}

/* アニメーション用の準備状態 */
.card.will-animate {
  will-change: transform, opacity;
}

/* ホバー時の状態変化 */
.card:hover {
  transform: scale(1.05);
  opacity: 0.9;
}

// 良い例：アニメーション開始時にクラスを付与
const button = document.querySelector('.button');
const box = document.querySelector('.box');

button.addEventListener('click', () => {
  // アニメーション開始前にwill-changeクラスを付与
  box.classList.add('will-animate');

  // アニメーションをトリガー
  box.classList.add('is-active');
});

// 悪い例：アニメーション終了後の削除忘れ
const box = document.querySelector('.box');

box.addEventListener('click', () => {
  box.classList.add('will-animate');
  box.classList.add('is-active');
  // ここでwill-animateを外さない → メモリ漏洩
});

// 良い例：animationend/transitionendイベントで確実に削除
const box = document.querySelector('.box');

box.addEventListener('click', () => {
  box.classList.add('will-animate');
  box.classList.add('is-active');
});

// トランジション終了時にwill-changeクラスを削除
box.addEventListener('transitionend', () => {
  box.classList.remove('will-animate');
});

// 別案：setTimeout で明示的に解除タイミングを設定
const box = document.querySelector('.box');
const ANIMATION_DURATION = 300; // ミリ秒

box.addEventListener('click', () => {
  box.classList.add('will-animate');
  box.classList.add('is-active');

  // アニメーション期間後にwill-changeを削除
  setTimeout(() => {
    box.classList.remove('will-animate');
  }, ANIMATION_DURATION);
});

// ベストプラクティス：will-changeの付与・削除を管理するヘルパー関数
class AnimationManager {
  static async animateWithWillChange(element, className, options = {}) {
    const { duration = 300, willChangeClass = 'will-animate' } = options;

    try {
      // アニメーション開始前にwill-changeを付与
      element.classList.add(willChangeClass);

      // 次フレームで状態変化をトリガー(ブラウザの最適化を促進)
      await new Promise(resolve => requestAnimationFrame(() => resolve()));

      // アニメーションクラスを付与
      element.classList.add(className);

      // アニメーション終了を待つ
      await this.waitForTransitionEnd(element, duration);

      // アニメーション終了後にwill-changeを削除
      element.classList.remove(willChangeClass);
    } catch (error) {
      console.error('Animation failed:', error);
      // エラー発生時もクリーンアップ
      element.classList.remove(willChangeClass);
    }
  }

  static waitForTransitionEnd(element, fallbackDuration) {
    return new Promise((resolve) => {
      const onTransitionEnd = () => {
        element.removeEventListener('transitionend', onTransitionEnd);
        resolve();
      };

      // イベントリスナを設定
      element.addEventListener('transitionend', onTransitionEnd, { once: true });

      // イベントが発火しない場合のフォールバック
      setTimeout(() => {
        element.removeEventListener('transitionend', onTransitionEnd);
        resolve();
      }, fallbackDuration + 50);
    });
  }
}

// 使用例
const card = document.querySelector('.card');
AnimationManager.animateWithWillChange(card, 'is-active', {
  duration: 300,
  willChangeClass: 'will-animate'
});

// 悪い例：複数要素に同時にwill-changeを付与
document.querySelectorAll('.item').forEach(item => {
  item.classList.add('will-animate');
  item.classList.add('is-active');
});

// 良い例：スタッガー効果でwill-changeのタイミングをずらす
document.querySelectorAll('.item').forEach((item, index) => {
  setTimeout(() => {
    item.classList.add('will-animate');
    item.classList.add('is-active');

    item.addEventListener('transitionend', () => {
      item.classList.remove('will-animate');
    }, { once: true });
  }, index * 50); // 50msずつズラす
});

<!-- Tailwind標準ユーティリティの使用例 -->
<div class="card hover:scale-105 transition-transform duration-300 will-change-transform">
  <h3>カード内容</h3>
</div>

// tailwind.config.js での拡張例
module.exports = {
  theme: {
    extend: {
      willChange: {
        // 標準は auto, transform, opacity, scroll のみ
        // 必要に応じて追加
        filter: 'filter',
        'backdrop-filter': 'backdrop-filter',
      },
    },
  },
  plugins: [],
};

// tailwind.config.js：セーフリストで動的クラスを許可
module.exports = {
  safelist: [
    'will-change-transform',
    'will-change-opacity',
    'will-change-filter',
  ],
  theme: { /* ... */ },
};

/* globals.css：カスタムユーティリティの定義 */
@layer utilities {
  .will-animate-transform {
    @apply will-change-transform;
  }

  .will-animate-opacity {
    @apply will-change-opacity;
  }

  /* 複数プロパティ指定が必要な場合 */
  .will-animate-multi {
    will-change: transform, opacity;
  }
}

<!-- HTML/JSXテンプレート -->
<div id="card" class="transition-transform duration-300 hover:scale-105">
  <h3>アニメーション対象</h3>
</div>

// JavaScript：カスタムクラスを動的に付与
const card = document.getElementById('card');

card.addEventListener('mouseenter', () => {
  card.classList.add('will-animate-transform');
});

card.addEventListener('mouseleave', () => {
  // アニメーション終了後に削除
  card.addEventListener('transitionend', () => {
    card.classList.remove('will-animate-transform');
  }, { once: true });
});

// 基本的な例：useStateとuseEffectを使用
import { useState, useEffect, useRef } from 'react';

function AnimatedCard() {
  const [isAnimating, setIsAnimating] = useState(false);
  const cardRef = useRef(null);

  const handleAnimationStart = () => {
    setIsAnimating(true);
  };

  useEffect(() => {
    const card = cardRef.current;
    if (!card) return;

    if (isAnimating) {
      // アニメーション開始前にwill-changeを付与
      card.classList.add('will-change-transform');

      // アニメーションをトリガー
      card.classList.add('is-active');

      // アニメーション終了時にwill-changeを削除
      const handleTransitionEnd = () => {
        card.classList.remove('will-change-transform');
        setIsAnimating(false);
      };

      card.addEventListener('transitionend', handleTransitionEnd, { once: true });

      // クリーンアップ
      return () => {
        card.removeEventListener('transitionend', handleTransitionEnd);
      };
    }
  }, [isAnimating]);

  return (
    <div
      ref={cardRef}
      className="card transition-transform duration-300"
      onClick={handleAnimationStart}
    >
      クリックでアニメーション
    </div>
  );
}

// 修正版カスタムフック：useWillChange
import { useState, useEffect } from 'react';

function useWillChange(ref, properties = ['transform'], duration = 300) {
  const [isActive, setIsActive] = useState(false);

  useEffect(() => {
    const element = ref.current;
    if (!element || !isActive) return;

    // DOMのstyleプロパティに直接 will-change を設定
    // （TailwindのJITビルド制限を回避し、複数プロパティの指定にも安全に対応）
    const propertyValue = properties.join(', ');
    element.style.willChange = propertyValue;

    // トランジション終了時にクリーンアップ（autoへ戻す）
    const handleEnd = () => {
      element.style.willChange = 'auto';
      setIsActive(false);
    };

    // フォールバック付きのタイムアウト設定
    const timerId = setTimeout(handleEnd, duration + 50);
    element.addEventListener('transitionend', handleEnd, { once: true });

    return () => {
      clearTimeout(timerId);
      element.removeEventListener('transitionend', handleEnd);
      element.style.willChange = 'auto'; // アンマウント時も確実に解除
    };
  }, [isActive, duration, properties]);

  return { isActive, setIsActive };
}

// 使用例
function AnimatedButton() {
  const ref = useRef(null);
  // 複数プロパティを指定しても 'transform, opacity' として正しく適用される
  const { isActive, setIsActive } = useWillChange(ref, ['transform', 'opacity'], 300);

  return (
    <button
      ref={ref}
      className={`px-4 py-2 transition-all ${isActive ? 'scale-95 opacity-75' : ''}`}
      onClick={() => setIsActive(true)}
    >
      クリック
    </button>
  );
}

// Next.js での安全な実装
'use client'; // クライアントコンポーネントとして明示

import { useEffect, useRef } from 'react';

function SafeAnimatedComponent() {
  const ref = useRef(null);

  useEffect(() => {
    // このコード内はクライアントサイドのみで実行される
    const element = ref.current;
    if (!element) return;

    element.classList.add('will-change-transform');

    return () => {
      element.classList.remove('will-change-transform');
    };
  }, []); // マウント時のみ実行

  return <div ref={ref}>コンテンツ</div>;
}

/* スクロール駆動アニメーション */
.fade-in {
  animation: fadeIn linear;
  animation-timeline: view();
}

@keyframes fadeIn {
  from { opacity: 0; }
  to { opacity: 1; }
}

/* will-changeの併用について：検証が必要 */
.fade-in.will-optimize {
  will-change: opacity;
}

// Next.js での View Transitions API の使用例
import { useTransitionRouter } from 'next/transitions';

export default function Link({ href, children }) {
  const router = useTransitionRouter();

  const handleClick = async (e) => {
    e.preventDefault();
    // View Transitions APIが自動的に最適化を行う
    // ここでwill-changeを付与する必要はない
    await router.push(href);
  };

  return <a onClick={handleClick}>{children}</a>;
}

// View Transitions 内で独自のアニメーションを追加する場合
function CardWithCustomAnimation() {
  const [isHovered, setIsHovered] = useState(false);
  const cardRef = useRef(null);

  useEffect(() => {
    if (!cardRef.current) return;

    if (isHovered) {
      cardRef.current.classList.add('will-change-transform');
      cardRef.current.classList.add('is-hovered');

      const cleanup = () => {
        cardRef.current?.classList.remove('will-change-transform');
      };

      cardRef.current.addEventListener('transitionend', cleanup, { once: true });
      return cleanup;
    }
  }, [isHovered]);

  return (
    <div
      ref={cardRef}
      className="transition-transform duration-300"
      onMouseEnter={() => setIsHovered(true)}
      onMouseLeave={() => setIsHovered(false)}
    >
      コンテンツ
    </div>
  );
}