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

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

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: [
-      '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',
-    ],
-  },
+  { side: 'left', images: ['1018', '1015', '1024', '1039'].map(id => `https://picsum.photos/id/${id}/900/1200`) },
+  { side: 'right', images: ['1043', '1050', '1067', '1074'].map(id => `https://picsum.photos/id/${id}/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(() => {
-  if (heroRef.value) {
-    gsap.set(heroRef.value, { yPercent: 100 })
-  }
-
+// 设置页面向下滚动时的视差缩放逻辑（绑定到 Lenis 的平滑滚动数值上）
+const setupHeroScroll = () => {
   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(pinEndScale, finalScale, (currentDistance - heroPinDistance) / exitDistance)
+      ? gsap.utils.interpolate(1, 0.65, currentDistance / heroPinDistance)
+      : 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({
-  heroStageRef,
-  heroRef,
-  play,
-})
+defineExpose({ heroStageRef, heroRef, play })
 </script>
 
 <template>
   <section
     ref="heroStageRef"
-    class="hero-stage"
-    :style="{ '--hero-pin-distance': `${heroPinDistance}px` }"
+    class="relative bg-black"
+    :style="{ height: `calc(100svh + ${heroPinDistance}px)` }"
   >
-    <section ref="heroRef" class="hero-section" v-once>
-      <div class="hero-backdrop" aria-hidden="true">
+    <section ref="heroRef" class="sticky top-0 h-[100svh] overflow-hidden bg-[#111]" v-once>
+      <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="`hero-gallery-${column.side}`"
+          class="absolute -bottom-10 -top-10 w-[49vw] overflow-hidden"
+          :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">
-    <h1 ref="introTitleRef" class="hero-intro-title" :aria-label="introTitle" v-once>
-      <span class="hero-intro-word">
+  <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="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="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>