refactor(components): 优化动画组件代码结构并移除冗余样式

style(pages): 使用实用类替换内联样式
refactor(composables): 简化页面标题模板逻辑
docs(components): 添加详细注释说明动画逻辑

app/app.vue

@@ -10,10 +10,10 @@ const siteImage = '/og-image.png'
 
 // 配置全局 Title 模板
 useHead({
-  titleTemplate: computed(() => (titleChunk?: string) => {
+  titleTemplate: (titleChunk?: string) => {
     const siteName = t('app.name')
     return titleChunk ? `${titleChunk} - ${siteName}` : siteName
-  })
+  }
 })
 
 // 配置全局基础 SEO 和 Meta (响应式支持国际化)

app/components/common/AppLoader.vue

@@ -8,7 +8,7 @@ const loaderRef = ref<HTMLElement | null>(null)
 const loaderBarRef = ref<HTMLElement | null>(null)
 const appStore = useAppStore()
 
-// Lock scroll while app is loading
+// 加载期间锁定页面滚动
 usePageScrollLock(appStore.isAppLoading)
 
 let loaderTween: gsap.core.Tween | null = null
@@ -16,17 +16,14 @@ let removeLoadListener: (() => void) | null = null
 let introStartTimer: ReturnType<typeof window.setTimeout> | null = null
 
 onMounted(() => {
-  const loaderElement = loaderRef.value
+  if (!loaderRef.value || !loaderBarRef.value) return
-  const loaderBarElement = loaderBarRef.value
 
-  if (!loaderElement || !loaderBarElement) return
+  // 1. 初始化 GSAP 样式状态
+  gsap.set(loaderRef.value, { display: 'grid', yPercent: 0, autoAlpha: 1 })
+  gsap.set(loaderBarRef.value, { scaleX: 0.18, transformOrigin: 'left center' })
 
-  // Initial GSAP setup
+  // 2. 进度条往复加载动画
-  gsap.set(loaderElement, { display: 'grid', yPercent: 0, autoAlpha: 1 })
+  loaderTween = gsap.to(loaderBarRef.value, {
-  gsap.set(loaderBarElement, { scaleX: 0.18, transformOrigin: 'left center' })
-
-  // Loader bar bouncing animation
-  loaderTween = gsap.to(loaderBarElement, {
     scaleX: 0.82,
     duration: 1.2,
     ease: 'power1.inOut',
@@ -35,43 +32,32 @@ onMounted(() => {
   })
 
   const loaderStartedAt = window.performance.now()
-  const minLoaderDuration = 1200
+  const minLoaderDuration = 1200 // 保证加载动画至少播放 1.2 秒，避免一闪而过
 
   const finishLoading = () => {
     removeLoadListener?.()
-    removeLoadListener = null
+    if (introStartTimer) clearTimeout(introStartTimer)
-
-    if (introStartTimer) {
-      window.clearTimeout(introStartTimer)
-      introStartTimer = null
-    }
 
+    // 计算还需要等待多久才能达到最小加载时间
     const remainingTime = Math.max(0, minLoaderDuration - (window.performance.now() - loaderStartedAt))
 
-    introStartTimer = window.setTimeout(() => {
+    introStartTimer = setTimeout(() => {
-      // End the loader loop and slide out
+      // 停止往复动画
       loaderTween?.kill()
-      loaderTween = null
+      
-
+      // 3. 执行加载器退场动画
-      const tl = gsap.timeline({
+      gsap.timeline({
         onComplete: () => {
-          gsap.set(loaderElement, { display: 'none' })
+          gsap.set(loaderRef.value, { display: 'none' })
-          appStore.setAppLoading(false)
+          appStore.setAppLoading(false) // 触发全局状态，通知其他组件入场
         }
       })
-
+      .to(loaderBarRef.value, { scaleX: 1, duration: 0.25, ease: 'power2.out' })
-      tl.to(loaderBarElement, {
+      .to(loaderRef.value, { yPercent: -100, duration: 0.75, ease: 'power4.inOut' })
-        scaleX: 1,
-        duration: 0.25,
-        ease: 'power2.out',
-      }).to(loaderElement, {
-        yPercent: -100,
-        duration: 0.75,
-        ease: 'power4.inOut',
-      })
     }, remainingTime)
   }
 
+  // 监听浏览器 window.onload 事件以判断页面资源是否加载完毕
   if (document.readyState === 'complete') {
     finishLoading()
   } else {
@@ -82,59 +68,18 @@ onMounted(() => {
 
 onBeforeUnmount(() => {
   loaderTween?.kill()
-  if (introStartTimer) window.clearTimeout(introStartTimer)
+  if (introStartTimer) clearTimeout(introStartTimer)
   removeLoadListener?.()
 })
 </script>
 
 <template>
-  <div ref="loaderRef" class="page-loader" aria-hidden="true">
+  <div ref="loaderRef" class="fixed inset-0 z-[90] grid place-items-center bg-black text-white will-change-transform" aria-hidden="true">
-    <div class="page-loader-content">
+    <div class="w-[min(220px,calc(100vw-48px))] text-xs uppercase tracking-[0.18em]">
-      <p>Loading</p>
+      <p class="m-0 mb-[14px]">Loading</p>
-      <span class="page-loader-line">
+      <span class="block h-px w-full overflow-hidden bg-white/20">
-        <span ref="loaderBarRef" class="page-loader-line-inner" />
+        <span ref="loaderBarRef" class="block h-full w-full origin-left scale-x-0 bg-white"></span>
       </span>
     </div>
   </div>
 </template>
-
-<style scoped>
-.page-loader {
-  position: fixed;
-  inset: 0;
-  z-index: 90;
-  display: grid;
-  place-items: center;
-  color: #fff;
-  background: #000;
-  will-change: transform;
-}
-
-.page-loader-content {
-  width: min(220px, calc(100vw - 48px));
-  font-size: 12px;
-  letter-spacing: 0.18em;
-  text-transform: uppercase;
-}
-
-.page-loader-content p {
-  margin: 0 0 14px;
-}
-
-.page-loader-line {
-  display: block;
-  width: 100%;
-  height: 1px;
-  overflow: hidden;
-  background: rgb(255 255 255 / 20%);
-}
-
-.page-loader-line-inner {
-  display: block;
-  width: 100%;
-  height: 100%;
-  background: #fff;
-  transform: scaleX(0);
-  transform-origin: left center;
-}
-</style>

app/components/home/HomeHero.vue

@@ -3,27 +3,11 @@ import { onMounted, onBeforeUnmount, ref } from 'vue'
 import { useNuxtApp } from '#app'
 import gsap from 'gsap'
 
+// 定义背景画廊与主视图绑定的总滚动距离（像素），数值越大，用户向下滚动时 Hero 面板缩放的过程就越长
 const heroPinDistance = 1200
-
 const heroGalleryColumns = [
-  {
+  { side: 'left', images: ['1018', '1015', '1024', '1039'].map(id => `https://picsum.photos/id/${id}/900/1200`) },
-    side: 'left',
+  { side: 'right', images: ['1043', '1050', '1067', '1074'].map(id => `https://picsum.photos/id/${id}/900/1200`) },
-    images: [
-      'https://picsum.photos/id/1018/900/1200',
-      'https://picsum.photos/id/1015/900/1200',
-      'https://picsum.photos/id/1024/900/1200',
-      'https://picsum.photos/id/1039/900/1200',
-    ],
-  },
-  {
-    side: 'right',
-    images: [
-      'https://picsum.photos/id/1043/900/1200',
-      'https://picsum.photos/id/1050/900/1200',
-      'https://picsum.photos/id/1067/900/1200',
-      'https://picsum.photos/id/1074/900/1200',
-    ],
-  },
 ] as const
 
 const heroStageRef = ref<HTMLElement | null>(null)
@@ -32,16 +16,19 @@ const heroPanelRef = ref<HTMLElement | null>(null)
 
 let cleanupHeroScroll: (() => void) | null = null
 
+// 暴露供外部（如 index.vue）使用的异步播放方法
 const play = () => new Promise<void>((resolve) => {
   if (!heroRef.value) return resolve()
-
+  
   let eventDispatched = false
-
+  
+  // 执行入场动画：将 Hero 整体容器从屏幕下方（yPercent: 100）滑入屏幕（yPercent: 0）
   gsap.to(heroRef.value, {
     yPercent: 0,
     duration: 1.2,
     ease: 'power3.out',
     onUpdate() {
+      // 当上滑动画进度超过 60% 时，触发全局事件，通知导航栏等其他组件可以开始它们自己的进场动画了
       if (!eventDispatched && this.progress() > 0.6) {
         eventDispatched = true
         window.dispatchEvent(new CustomEvent('hero-intro-done'))
@@ -51,83 +38,89 @@ const play = () => new Promise<void>((resolve) => {
   })
 })
 
-onMounted(() => {
+// 设置页面向下滚动时的视差缩放逻辑（绑定到 Lenis 的平滑滚动数值上）
-  if (heroRef.value) {
+const setupHeroScroll = () => {
-    gsap.set(heroRef.value, { yPercent: 100 })
-  }
-
   if (!heroStageRef.value || !heroPanelRef.value) return
 
   const { $lenis } = useNuxtApp() as { $lenis?: { scroll: number } }
-  const pinEndScale = 0.65
-  const finalScale = 0.18
   const stageTop = heroStageRef.value.offsetTop
-
-  gsap.set(heroPanelRef.value, {
-    scale: 1,
-    force3D: true,
-    transformOrigin: 'center center',
-  })
-
   let renderedScale = -1
 
+  // 初始化 Hero 面板的缩放状态和 3D 硬件加速
+  gsap.set(heroPanelRef.value, { scale: 1, force3D: true, transformOrigin: 'center center' })
+
+  // 核心的每帧更新逻辑
   const updateHeroPanelScale = () => {
     const exitDistance = window.innerHeight
     const totalDistance = heroPinDistance + exitDistance
+    // 如果启用了 Lenis，则读取其平滑的插值滚动值，否则回退到浏览器原生的 window.scrollY
     const currentScroll = $lenis ? $lenis.scroll : window.scrollY
+    
+    // 计算当前元素在滚动容器内走过的有效距离
     const currentDistance = gsap.utils.clamp(0, totalDistance, currentScroll - stageTop)
 
+    // 根据滚动距离，分两个阶段计算 Hero 面板的缩放比例 (scale):
+    // 阶段一：在设置的 1200px 距离内，面板从 1.0 缩小到 0.65
+    // 阶段二：超过 1200px 后，跟随页面继续向下滚出的过程，面板从 0.65 继续缩小到 0.18
     const newScale = currentDistance <= heroPinDistance
-      ? gsap.utils.interpolate(1, pinEndScale, currentDistance / heroPinDistance)
+      ? gsap.utils.interpolate(1, 0.65, currentDistance / heroPinDistance)
-      : gsap.utils.interpolate(pinEndScale, finalScale, (currentDistance - heroPinDistance) / exitDistance)
+      : gsap.utils.interpolate(0.65, 0.18, (currentDistance - heroPinDistance) / exitDistance)
 
+    // 只有当缩放值的变化超过肉眼/渲染的有效阈值（0.001）时，才真正触发 DOM 更新，节省性能
     if (Math.abs(renderedScale - newScale) > 0.001) {
       renderedScale = newScale
       gsap.set(heroPanelRef.value, { scale: newScale })
     }
   }
 
+  // 立即执行一次计算初始状态
   updateHeroPanelScale()
+  
+  // 将更新函数绑定到 gsap 的全局 ticker（类似于 requestAnimationFrame），保证在每一帧平滑读取数据并更新
   gsap.ticker.add(updateHeroPanelScale)
+  
+  // 返回清理函数
   cleanupHeroScroll = () => gsap.ticker.remove(updateHeroPanelScale)
+}
+
+onMounted(() => {
+  // 组件挂载时，先将整个 Hero 强行置于屏幕下方，等待外部调用 `play()` 才滑入
+  if (heroRef.value) gsap.set(heroRef.value, { yPercent: 100 })
+  // 初始化滚动监听逻辑
+  setupHeroScroll()
 })
 
 onBeforeUnmount(() => {
   cleanupHeroScroll?.()
-  cleanupHeroScroll = null
 })
 
-defineExpose({
+defineExpose({ heroStageRef, heroRef, play })
-  heroStageRef,
-  heroRef,
-  play,
-})
 </script>
 
 <template>
   <section
     ref="heroStageRef"
-    class="hero-stage"
+    class="relative bg-black"
-    :style="{ '--hero-pin-distance': `${heroPinDistance}px` }"
+    :style="{ height: `calc(100svh + ${heroPinDistance}px)` }"
   >
-    <section ref="heroRef" class="hero-section" v-once>
+    <section ref="heroRef" class="sticky top-0 h-[100svh] overflow-hidden bg-[#111]" v-once>
-      <div class="hero-backdrop" aria-hidden="true">
+      <div class="absolute inset-0 overflow-hidden bg-black" aria-hidden="true">
         <div
           v-for="column in heroGalleryColumns"
           :key="column.side"
-          class="hero-gallery"
+          class="absolute -bottom-10 -top-10 w-[49vw] overflow-hidden"
-          :class="`hero-gallery-${column.side}`"
+          :class="column.side === 'left' ? 'left-0' : 'right-0'"
         >
           <!-- 复制两份图片组，配合 translateY(-50%) 做无缝循环。 -->
           <div
-            class="hero-gallery-track"
+            class="hero-gallery-track will-change-transform"
             :class="{ 'hero-gallery-track-slow': column.side === 'right' }"
           >
-            <div v-for="copy in 2" :key="`${column.side}-copy-${copy}`" class="hero-gallery-group">
+            <div v-for="copy in 2" :key="`${column.side}-copy-${copy}`" class="grid gap-9 pb-9">
               <img
                 v-for="image in column.images"
                 :key="`${column.side}-${copy}-${image}`"
-                class="hero-gallery-image"
+                class="block w-full rounded-none object-cover h-[clamp(260px,42vh,430px)]"
                 :src="image"
                 alt=""
                 decoding="async"
@@ -137,7 +130,7 @@ defineExpose({
           </div>
         </div>
       </div>
-      <div ref="heroPanelRef" class="hero-panel">
+      <div ref="heroPanelRef" class="absolute inset-0 grid place-items-center bg-white text-5xl will-change-transform">
         <p>Hero Section</p>
       </div>
     </section>
@@ -145,45 +138,7 @@ defineExpose({
 </template>
 
 <style scoped>
-.hero-stage {
-  position: relative;
-  height: calc(100svh + var(--hero-pin-distance));
-  background: #000;
-}
-
-.hero-section {
-  position: sticky;
-  top: 0;
-  height: 100svh;
-  overflow: hidden;
-  background: #111;
-}
-
-.hero-backdrop {
-  position: absolute;
-  inset: 0;
-  overflow: hidden;
-  background: #000;
-}
-
-.hero-gallery {
-  position: absolute;
-  top: -40px;
-  bottom: -40px;
-  width: 49vw;
-  overflow: hidden;
-}
-
-.hero-gallery-left {
-  left: 0;
-}
-
-.hero-gallery-right {
-  right: 0;
-}
-
 .hero-gallery-track {
-  will-change: transform;
   animation: hero-gallery-scroll 28s linear infinite;
 }
 
@@ -191,33 +146,9 @@ defineExpose({
   animation-duration: 42s;
 }
 
-.hero-gallery-group {
-  display: grid;
-  gap: 36px;
-  padding-bottom: 36px;
-}
-
-.hero-gallery-image {
-  display: block;
-  width: 100%;
-  height: clamp(260px, 42vh, 430px);
-  border-radius: 0;
-  object-fit: cover;
-}
-
 @keyframes hero-gallery-scroll {
   to {
     transform: translateY(-50%);
   }
 }
-
-.hero-panel {
-  position: absolute;
-  inset: 0;
-  display: grid;
-  place-items: center;
-  background: #fff;
-  font-size: 48px;
-  will-change: transform;
-}
 </style>

app/components/home/HomeIntro.vue

@@ -3,119 +3,74 @@ import { ref, onBeforeUnmount } from 'vue'
 import gsap from 'gsap'
 
 const introTitle = 'ArcticNewOne'
+// 将标题拆分为单个字符，用于后续 GSAP 的逐字动画
 const introLetters = introTitle.split('')
 const introRef = ref<HTMLElement | null>(null)
 const introTitleRef = ref<HTMLElement | null>(null)
 let ctx: gsap.Context | null = null
 
+// 暴露供外部（如 index.vue）使用的异步播放方法
 const play = () => new Promise<void>((resolve) => {
   if (!introRef.value || !introTitleRef.value) return resolve()
 
+  // 获取所有需要执行动画的字符和 TM 标志 DOM 节点
   const chars = gsap.utils.toArray('.hero-intro-char', introRef.value)
   const tm = introRef.value.querySelector('.hero-intro-tm')
 
   if (!chars.length || !tm) return resolve()
 
+  // 使用 gsap.context 包装时间轴，方便在组件卸载时统一清理所有动画状态（revert）
   ctx = gsap.context(() => {
-    // 初始化样式
+    // 1. 初始化 DOM 的初始样式状态，防止闪烁
     gsap.set(introRef.value, { display: 'grid', yPercent: 0, autoAlpha: 1 })
     gsap.set(introTitleRef.value, { y: 0, autoAlpha: 1 })
+    // 将每个字符初始放置在视口下方（yPercent: 110），等待升起
     gsap.set(chars, { y: 0, yPercent: 110 })
+    // TM 标志初始透明度为 0
     gsap.set(tm, { autoAlpha: 0 })
 
+    // 2. 创建并执行时间轴
     gsap.timeline({
       defaults: { ease: 'power3.out' },
       onComplete: () => {
+        // 动画完全结束时，隐藏整个组件容器并 resolve Promise，通知外部可进行下一步
         gsap.set(introRef.value, { display: 'none' })
         resolve()
       }
     })
-      // 逐字升起
+      // 步骤 A：字符从下方逐字平滑升起入场 (stagger 产生阶梯感)
       .to(chars, { yPercent: 0, duration: 0.75, stagger: 0.055 })
-      // TM 渐显
+      // 步骤 B：TM 标志渐显入场
       .to(tm, { autoAlpha: 1, duration: 0.4, ease: 'power2.out' })
-      // 停顿 0.35s 后，整体上移并淡出标题
+      // 停顿 0.35s 后，为接下来的离场动画打上时间标签
       .addLabel('introOut', '+=0.35')
+      // 步骤 C：标题整体淡出
       .to(introTitleRef.value, { autoAlpha: 0, duration: 1.05, ease: 'power4.inOut' }, 'introOut')
+      // 步骤 D：同时，整个 Intro 黑色背景容器向上滑出屏幕
       .to(introRef.value, { yPercent: -100, duration: 1.05, ease: 'power4.inOut' }, 'introOut')
   }, introRef.value)
 })
 
+// 组件销毁前清理 GSAP 动画上下文，避免内存泄漏或在 SPA 路由切换时导致状态异常
 onBeforeUnmount(() => ctx?.revert())
 
 defineExpose({ play })
 </script>
 
 <template>
-  <div ref="introRef" class="hero-intro" aria-hidden="true">
+  <div ref="introRef" class="fixed inset-0 z-[80] hidden place-items-center overflow-hidden bg-black text-white opacity-0 invisible will-change-transform" aria-hidden="true">
-    <h1 ref="introTitleRef" class="hero-intro-title" :aria-label="introTitle" v-once>
+    <h1 ref="introTitleRef" class="m-0 flex whitespace-nowrap font-bold leading-[0.9] tracking-[-0.07em] text-[clamp(36px,6.2vw,104px)]" :aria-label="introTitle" v-once>
-      <span class="hero-intro-word">
+      <span class="relative inline-flex">
         <span
           v-for="(letter, index) in introLetters"
           :key="`${letter}-${index}`"
-          class="hero-intro-char-wrap"
+          class="relative inline-block overflow-hidden"
         >
-          <span class="hero-intro-char">{{ letter }}</span>
+          <!-- GSAP 将通过操作此元素的 translateY 来实现逐字浮现 -->
+          <span class="hero-intro-char inline-block will-change-transform">{{ letter }}</span>
         </span>
-        <span class="hero-intro-tm">TM</span>
+        <span class="hero-intro-tm absolute left-[calc(100%+0.12em)] top-[0.08em] text-[0.13em] font-bold leading-none tracking-[-0.02em] opacity-0 invisible">TM</span>
       </span>
     </h1>
   </div>
 </template>
-
-<style scoped>
-.hero-intro {
-  position: fixed;
-  inset: 0;
-  z-index: 80;
-  display: none;
-  place-items: center;
-  overflow: hidden;
-  color: #fff;
-  background: #000;
-  opacity: 0;
-  visibility: hidden;
-  will-change: transform;
-}
-
-.hero-intro-title {
-  display: flex;
-  margin: 0;
-  font-size: clamp(36px, 6.2vw, 104px);
-  font-weight: 700;
-  line-height: 0.9;
-  letter-spacing: -0.07em;
-  white-space: nowrap;
-}
-
-.hero-intro-word {
-  position: relative;
-  display: inline-flex;
-}
-
-.hero-intro-char-wrap,
-.hero-intro-char {
-  display: inline-block;
-}
-
-.hero-intro-char-wrap {
-  position: relative;
-  overflow: hidden;
-}
-
-.hero-intro-char {
-  will-change: transform;
-}
-
-.hero-intro-tm {
-  position: absolute;
-  left: calc(100% + 0.12em);
-  top: 0.08em;
-  font-size: 0.13em;
-  font-weight: 700;
-  letter-spacing: -0.02em;
-  line-height: 1;
-  opacity: 0;
-  visibility: hidden;
-}
-</style>

app/pages/index.vue

@@ -64,20 +64,11 @@ watch(() => appStore.isAppLoading, async (isLoading) => {
     <HomeIntro ref="homeIntroRef" />
     <HomeHero ref="homeHeroRef" />
 
-    <section class="next-section">
+    <section class="grid min-h-[100svh] place-items-center">
       <h2>Next Section</h2>
     </section>
-    <section id="work" class="work-section" data-cursor-label="Read more">
+    <section id="work" class="grid min-h-[100svh] place-items-center" data-cursor-label="Read more">
       <p>{{ t('home.welcome') }}</p>
     </section>
   </main>
 </template>
-
-<style scoped>
-.next-section,
-.work-section {
-  min-height: 100svh;
-  display: grid;
-  place-items: center;
-}
-</style>