Nuxt 3页面过渡干扰GSAP ScrollTrigger动画问题求助

是否为已知问题 #

是的，这是Nuxt 3页面过渡机制与GSAP ScrollTrigger之间的已知兼容问题。核心原因是Nuxt的CSS页面过渡会在页面切换时修改DOM的可见性、布局状态（比如元素的位置、尺寸变化），而ScrollTrigger在onMounted钩子中初始化时，可能捕获到的是过渡过程中的临时DOM状态，而非最终稳定的布局，导致动画触发条件计算错误，表现为触发不稳定或完全不触发。这类问题在GSAP社区和Nuxt的GitHub讨论中均有提及。

稳定触发ScrollTrigger的最佳实践与解决方案 #

1. 延迟初始化至页面过渡完成 #

利用Nuxt提供的page:finish钩子，在页面过渡完全结束、DOM状态稳定后再初始化GSAP动画：

<script setup>
import gsap from 'gsap'
import { ScrollTrigger } from 'gsap/ScrollTrigger'

gsap.registerPlugin(ScrollTrigger)

const nuxtApp = useNuxtApp()

// 替换原onMounted中的初始化逻辑
nuxtApp.hook('page:finish', async () => {
  await nextTick() // 确保v-for列表完全渲染
  // 初始化ScrollTrigger动画
  gsap.from('.list-item', {
    y: 50,
    opacity: 0,
    stagger: 0.1,
    scrollTrigger: {
      trigger: '.list-container',
      start: 'top 80%',
      toggleActions: 'play none none reverse'
    }
  })
})
</script>

2. 强制刷新ScrollTrigger状态 #

如果必须在onMounted中初始化动画，可在页面过渡结束后强制刷新ScrollTrigger的位置计算：

<script setup>
import gsap from 'gsap'
import { ScrollTrigger } from 'gsap/ScrollTrigger'

gsap.registerPlugin(ScrollTrigger)

onMounted(() => {
  // 先初始化动画
  gsap.from('.list-item', {
    y: 50,
    opacity: 0,
    stagger: 0.1,
    scrollTrigger: {
      trigger: '.list-container',
      start: 'top 80%',
      toggleActions: 'play none none reverse'
    }
  })
})

const nuxtApp = useNuxtApp()
nuxtApp.hook('page:finish', () => {
  // 过渡结束后刷新ScrollTrigger
  ScrollTrigger.refresh()
})
</script>

3. 确保v-for列表DOM完全就绪 #

对于v-for渲染的列表，需确保所有元素都已挂载到DOM后再初始化动画，可结合nextTick和页面过渡钩子：

<script setup>
import gsap from 'gsap'
import { ScrollTrigger } from 'gsap/ScrollTrigger'

gsap.registerPlugin(ScrollTrigger)

const nuxtApp = useNuxtApp()

nuxtApp.hook('page:finish', async () => {
  // 等待v-for列表完成渲染
  await nextTick()
  // 可选：再等待一小段时间确保样式生效
  await new Promise(resolve => setTimeout(resolve, 100))
  // 初始化动画
  // ... 你的GSAP代码
})
</script>

4. 调整页面过渡配置（可选） #

如果不需要复杂的页面过渡效果，可修改nuxt.config.ts中的过渡配置，减少对DOM布局的影响：

// nuxt.config.ts
export default defineNuxtConfig({
  app: {
    pageTransition: {
      name: 'page',
      mode: 'out-in', // 先完成离开动画再进入，减少DOM重叠
      duration: 300 // 缩短过渡时长，降低状态不稳定窗口
    }
  }
})

内容的提问来源于stack exchange，提问作者anywhereseason