gsap-text

GSAP Text — 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、子元素使用遮罩时：使用 visibility，不要使用 autoAlpha
• 切勿在 scramble 前清空 textContent
• 并列的逐词补间动画设置 overwrite: false
• SplitText 会保留 <span>；渐变样式请使用 :deep(div)
• CSS .reveal + .text-reveal 预隐藏类可防止 FOUC

---

5. useReveal Composable 参考

方法	描述
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 个关键注意事项