gsap-text

GSAP テキスト — SplitText + ScrambleText

フロー: gsap-setup → gsap-animate → gsap-text → gsap-optimise → gsap-test 主要ファイル: composables/useReveal.js、plugins/gsap.js、assets/css/tailwind.css

関連スキル: SplitText／ScrambleText API のリファレンスについては、gsap-plugins を呼び出してください。このスキルでは、テキストアニメーションのレシピのみを扱います。必要なもの: greensock/gsap-skills

---

1. SplitText のセットアップ

// Preferred — useReveal handles everything:
const { init, hero, scroll, split } = useReveal(sectionRef)
onMounted(() => init(() => scroll()))

// Manual setup:
const { $gsap: gsap, $lazyLoadSplitText, $lazyLoadScramble } = useNuxtApp()
let SplitText, ctx
const splits = []

onMounted(async () => {
  await document.fonts.ready               // CRITICAL: fonts before split
  SplitText = await $lazyLoadSplitText()
  ctx = gsap.context(() => { /* ... */ }, scopeRef.value)
})

onUnmounted(() => {
  splits.forEach(s => s.revert())
  splits.length = 0
  ctx?.revert()
})

分割の作成

const s = SplitText.create(el, { type: 'words', mask: 'words' })
splits.push(s)
gsap.set(s.words, { y: '100%' })
gsap.set(el, { visibility: 'visible' })

---

2. マスク付き単語スライドアップ（本番環境向けパターン）

25 以上のコンポーネントで使用されている標準的な見出しのリビールです。

ctx = gsap.context(() => {
  const s = SplitText.create(el, { type: 'words', mask: 'words' })
  splits.push(s)
  gsap.set(s.words, { y: '100%' })
  gsap.set(el, { visibility: 'visible' })

  gsap.to(s.words, {
    y: '0%', duration: 0.8, ease: 'power4.out', stagger: 0.06, force3D: true,
    scrollTrigger: {
      trigger: el, start: 'top 85%',
      toggleActions: 'play none none reverse', invalidateOnRefresh: true,
    },
  })
}, scopeRef.value)

useReveal を使用する場合（推奨）

<div ref="sectionRef">
  <div class="reveal">
    <h2 class="text-reveal">HEADING TEXT</h2>
  </div>
</div>

const { init, scroll } = useReveal(sectionRef)
onMounted(() => init(() => scroll()))

---

3. ScrambleText のデコード

ScrambleText API のリファレンスについては、gsap-plugins スキルを参照してください。レシピ:

gsap.to(el, {
  duration: 0.8 + el.textContent.length * 0.005,
  scrambleText: { text: 'FINAL TEXT', chars: '▓░▒█▀▄╬╠╣▐▌■□', revealDelay: 0.3, speed: 0.4 },
})

---

4. 注意点のまとめ

詳細とコード例については、references/learnings.md を参照してください。

• SplitText.create() の前に document.fonts.ready を待機します
• autoSplit: true は行専用です（レスポンシブな再配置）。単語や文字には不要です。必ず onSplit() と組み合わせます
• 親に autoAlpha、子にマスクを適用する場合は、autoAlpha ではなく visibility を使用します
• スクランブルの前に textContent を空にしてはいけません
• 同じ場所に配置する単語ごとのトゥイーンには overwrite: false を設定します
• SplitText は <span> を保持します。グラデーションスタイルには :deep(div) を使用します
• CSS の .reveal + .text-reveal プリハイドクラスで FOUC を防ぎます

---

5. useReveal コンポーザブルのリファレンス

メソッド	説明
init(fn)	非同期: フォントの読み込みを待ち、SplitText + Scramble を遅延読み込みして、gsap.context を作成します
hero(selector?, overrides?)	ファーストビューの即時リビールです。.text-reveal の子要素を自動検出します
scroll(selector?, overrides?)	.reveal + .text-reveal を使用した、要素ごとの ScrollTrigger リビールです
split(target)	SplitText ラッパー: マスク付きの単語分割を作成し、クリーンアップ対象として追跡します

// Hero (above-fold, immediate)
const { init, hero } = useReveal(sectionRef)
onMounted(() => init(() => hero('.reveal', { textDelay: 0.2 })))

// Scroll (below-fold, per-element ScrollTrigger)
const { init, scroll } = useReveal(sectionRef)
onMounted(() => init(() => scroll('.reveal', { start: 'top 75%', once: true })))

クリーンアップは自動的に行われます。onUnmounted により、gsap.context とすべての SplitText インスタンスが元に戻されます。

---

参考資料

• references/text-patterns.md — クリップ＋スクランブルの組み合わせ、文字のキネティック分割、弾性タイプの組み立て、ローリングテキスト（3D スロットマシン）、水平テキスト（containerAnimation）、マスク付き行のリビール、ScrollTrigger を使用した autoSplit
• references/learnings.md — 本番環境のデバッグで得られた 7 つの重要な注意点