第3章 三大核心 API 详解

gsap.to(target, { vars });

// 方块从当前位置（x=0）移动到 x=200
gsap.to('.box', {
  x: 200,
  duration: 1.5,
  ease: 'power2.out'
});

const tween = gsap.to('.box', {
  x: 200,
  duration: 1.5,
  paused: true  // 创建但不播放
});

// 需要时再启动
tween.play();

// 随时修改
tween.timeScale(2);  // 2 倍速
tween.reverse();     // 反向
tween.seek(0.5);     // 跳到 0.5 秒处

// 样式类属性
gsap.to('.box', {
  width: 300,          // CSS width
  backgroundColor: '#ff6b6b',  // 背景色（需 CSSPlugin）
  borderRadius: '50%', // 圆角
  filter: 'blur(5px)', // 滤镜
});

// transform 简写（推荐，性能最优）
gsap.to('.box', {
  x: 100,        // translateX
  y: 50,         // translateY
  rotation: 45,  // rotate
  scale: 1.5,    // scale
  skewX: 10,     // skewX
});

// 纯数据对象
gsap.to(counter, { value: 100, duration: 2 });

gsap.from(target, { vars });

// 卡片从透明+下方 50px 的位置，过渡到原始位置
gsap.from('.card', {
  opacity: 0,
  y: 50,
  duration: 0.8,
  ease: 'power2.out'
});

// CSS 布局保持原始状态
.card { opacity: 1; transform: translateY(0); }
// 用户的静态页面是完整、清晰、可读的

// JS 只负责"入场表演"
gsap.from('.card', {
  opacity: 0,
  y: 50,
  duration: 0.6,
  stagger: 0.1  // 每张卡片间隔 0.1 秒
});

/* CSS 方案：需要定义两套状态 */
.card {
  animation: cardEnter 0.6s ease-out both;
}
.card:nth-child(1) { animation-delay: 0s; }
.card:nth-child(2) { animation-delay: 0.1s; }
.card:nth-child(3) { animation-delay: 0.2s; }
/* ... 每张卡片都要写一遍 */

@keyframes cardEnter {
  from { opacity: 0; transform: translateY(50px); }
  to   { opacity: 1; transform: translateY(0); }
}

// from() 默认 immediateRender: true
// 意味着 GSAP 会立即将元素设置为 vars 中的状态
// 然后再开始动画

gsap.from('.box', { x: 200, duration: 1 });
// 执行流程：
// 1. 立即设置 x=200（元素跳到右边）         ← immediateRender
// 2. 第一帧从 x=200 开始
// 3. 1 秒后回到当前 x=0

gsap.from('.box', {
  x: 200,
  duration: 1,
  immediateRender: false  // 创建时不写入起点；播放开始后仍从 x=200 回到原值
});

// 页面加载：标题从上方滑入
gsap.from('.hero-title', {
  y: -80,
  opacity: 0,
  duration: 1,
  delay: 0.3,
  ease: 'power3.out'
});

// 特性列表：逐项淡入（stagger 的威力）
gsap.from('.feature-item', {
  opacity: 0,
  x: -30,
  duration: 0.5,
  stagger: 0.15,  // 间隔 0.15 秒
  ease: 'power2.out'
});

// 数字滚动
gsap.from('.stat-number', {
  textContent: 0,  // 从 0 开始
  duration: 2,
  snap: { textContent: 1 },  // 取整
  ease: 'power2.out'
});

gsap.fromTo(target, { fromVars }, { toVars });

gsap.fromTo('.box',
  { x: -100, opacity: 0 },           // 起始状态
  { x: 200, opacity: 1, duration: 1 } // 目标状态
);

// 元素之前被移动过（x 已经是 200），现在需要从 0 重新开始
// to() 会从 200 开始，from() 会跳变后回到 200
// fromTo() 才能精确控制起点

gsap.fromTo('.box',
  { x: 0, opacity: 0 },              // 明确起点
  { x: 200, opacity: 1, duration: 1 } // 明确终点
);

gsap.fromTo('.pulse',
  { scale: 1 },
  {
    scale: 1.3,
    duration: 1,
    repeat: -1,      // 无限循环
    yoyo: true,      // 往返
    ease: 'power2.inOut',
    repeatDelay: 0.5
  }
);

// 第一段：从透明滑入
gsap.fromTo('.modal-overlay',
  { opacity: 0 },
  { opacity: 1, duration: 0.3 }
);

// 第二段：弹窗放大
gsap.fromTo('.modal-content',
  { scale: 0.7, opacity: 0 },
  { scale: 1, opacity: 1, duration: 0.4, ease: 'back.out(1.7)' }
);

// 单位：秒（不是毫秒）
gsap.to('.box', { x: 100, duration: 2 });   // 2 秒
gsap.to('.box', { x: 100, duration: 0.3 }); // 0.3 秒 = 300ms
gsap.to('.box', { x: 100 });                 // 默认 0.5 秒

// 延迟 1 秒后才开始
gsap.to('.box', { x: 100, duration: 1, delay: 1 });

// GSAP 3.x 支持函数式 delay（做 stagger 的精细控制）
gsap.to('.items', {
  x: 100,
  duration: 1,
  delay: (i) => i * 0.1 * Math.random()  // 随机化延迟
});

// ease 可以用字符串或自定义函数
gsap.to('.a', { x: 100, duration: 1, ease: 'power3.out' });
gsap.to('.b', { x: 100, duration: 1, ease: 'steps(8)' });
gsap.to('.c', { x: 100, duration: 1, ease: 'rough({ strength: 5 })' });

// repeat: -1 表示无限循环
gsap.to('.spinner', { rotation: 360, duration: 1, repeat: -1, ease: 'none' });

// repeat: 3 表示额外执行 3 次（总共 4 次）
gsap.to('.bounce', {
  y: -100,
  duration: 0.5,
  repeat: 3,
  yoyo: true,        // 往返：下去→上来→下去→上来
  ease: 'power2.in'
});

// repeatDelay: 每次重复之间的停顿
gsap.to('.blink', {
  opacity: 0,
  duration: 0.3,
  repeat: -1,
  yoyo: true,
  repeatDelay: 1     // 闪烁间隔 1 秒
});

// 基本用法：每个目标间隔 0.2 秒
gsap.to('.card', { y: 20, duration: 0.5, stagger: 0.2 });

// stagger 对象形式——精细控制
gsap.from('.card', {
  opacity: 0,
  y: 60,
  duration: 0.8,
  stagger: {
    each: 0.1,           // 每个间隔 0.1 秒
    from: 'center',      // 从中间开始（'start' | 'center' | 'end' | 'edges'）
    grid: [3, 4],        // 3 行 4 列的网格（按网格扩散）
    axis: 'y',            // 按 y 轴方向
    ease: 'power2.inOut', // stagger 自身的缓动
    amount: 1,            // 全部在 1 秒内完成
  }
});

gsap.to('.box', {
  x: 200,
  duration: 1.5,
  onStart: () => console.log('动画即将开始'),
  onUpdate: () => console.log('每帧都会调用——性能敏感，别放重逻辑'),
  onComplete: () => console.log('动画正常结束'),
  onRepeat: () => console.log('每次重复时调用'),
  onInterrupt: () => console.log('动画被中断（被覆盖或 kill）'),

  // 回调参数
  onCompleteParams: ['完成', 100],
  onComplete: (msg, value) => console.log(msg, value), // '完成' 100
});

创建 Tween ──→ onStart ──→ onUpdate(每帧) ──→ onRepeat(如果 repeat) ──→
...循环... ──→ onUpdate(最后一帧) ──→ onComplete

// 场景：两个动画同时操作同一个元素的 x 属性
gsap.to('.box', { x: 100, duration: 1 });
// 0.3 秒后启动另一个动画
setTimeout(() => gsap.to('.box', { x: 300, duration: 1 }), 300);

// overwrite: 'auto' —— 只覆盖冲突属性
gsap.to('.box', { x: 100, opacity: 0, duration: 1 });
setTimeout(() => {
  // 新动画的 x 会覆盖旧动画的 x，但 opacity 不会被影响
  gsap.to('.box', { x: 300, duration: 0.5, overwrite: 'auto' });
}, 300);

// from() 和 fromTo() 默认 immediateRender: true

// 对于 from()：立即将元素设为起始状态
gsap.from('.box', { x: 200, duration: 1 });
// 元素瞬间跳到 x=200，然后动画回 x=0

// 如果设置 false：创建时保持当前位置，开始播放时再应用 from 起点
gsap.from('.box', { x: 200, duration: 1, immediateRender: false });
// 创建后暂留原位；播放开始后仍从 x=200 回到原位。

// 用 GSAP 做比 CSS transition 更细腻的 hover 效果
const buttons = document.querySelectorAll('.btn');

buttons.forEach(btn => {
  // hoverShadow 是一个保存引用的变量
  btn.addEventListener('mouseenter', () => {
    gsap.to(btn, {
      scale: 1.05,
      boxShadow: '0 8px 25px rgba(108,92,231,0.4)',
      duration: 0.3,
      ease: 'power2.out',
      overwrite: 'auto'
    });
  });

  btn.addEventListener('mouseleave', () => {
    gsap.to(btn, {
      scale: 1,
      boxShadow: '0 2px 10px rgba(0,0,0,0.1)',
      duration: 0.4,
      ease: 'power2.out',
      overwrite: 'auto'
    });
  });
});

// 配合 Intersection Observer 实现滚动触发
const observer = new IntersectionObserver((entries) => {
  entries.forEach(entry => {
    if (entry.isIntersecting) {
      // 卡片从下方淡入
      gsap.from(entry.target, {
        opacity: 0,
        y: 60,
        duration: 0.7,
        ease: 'power3.out'
      });
      observer.unobserve(entry.target);
    }
  });
}, { threshold: 0.2 });

document.querySelectorAll('.card').forEach(card => observer.observe(card));

function animateCounter(el, targetValue, duration = 2) {
  const counter = { value: 0 };

  gsap.to(counter, {
    value: targetValue,
    duration,
    ease: 'power2.out',
    onUpdate: () => {
      el.textContent = Math.round(counter.value).toLocaleString();
    },
    onComplete: () => {
      el.textContent = targetValue.toLocaleString(); // 确保最终值精确
    }
  });
}

// 使用
animateCounter(document.getElementById('revenue'), 15800000, 2.5);
// 显示：0 → 15,800,000

// ❌ 创建 from() 但不立即播放，元素先闪现到起始状态然后不动
const tween = gsap.from('.box', { x: 200, duration: 1, paused: true });
// 元素已经跳到 x=200！（immediateRender=true 的默认行为）

// ✅ 设置 immediateRender: false
const tween = gsap.from('.box', {
  x: 200,
  duration: 1,
  paused: true,
  immediateRender: false  // 现在不会跳变了
});
// 调用 tween.play() 时才从 x=200 开始动画

// 淡入与缩放是不同属性，可以同时执行
gsap.to('.modal', { opacity: 1, duration: 0.5 });
// 0.2 秒后，另一段代码操作了同一个元素的 scale
gsap.to('.modal', { scale: 1, duration: 0.3, overwrite: 'auto' });
// overwrite: 'auto' 只覆盖 scale，opacity 还在——这符合预期

// 但如果想要新动画完全接管：
gsap.to('.modal', { scale: 1, duration: 0.3, overwrite: true });
// 新动画会杀灭旧动画的所有属性——opacity 也被停了

// ❌ 闭包陷阱
for (let i = 0; i < 5; i++) {
  gsap.to('.box' + i, {
    x: 100,
    duration: 1,
    onComplete: () => console.log('Box ' + i + ' 完成')
  });
}
// 如果用 var 声明 i：打印 5 次 "Box 5 完成"
// 用 let 声明：正确，每个闭包捕获自己的 i

// ✅ 更安全的方式：使用回调参数
gsap.to('.box', {
  x: 100,
  duration: 1,
  onCompleteParams: [i],
  onComplete: (index) => console.log('Box ' + index + ' 完成')
});

// ❌ 用 fromTo 做 stagger 时，注意 overwrite
gsap.fromTo('.item',
  { x: -50, opacity: 0 },
  { x: 0, opacity: 1, duration: 0.5, stagger: 0.2 }
);
// 第 1 个元素动画 0.5s，第 2 个 0.2s 后开始...
// 没问题，因为每个元素是独立的目标

// 但如果误选了同一个元素...（初学者常见错误）
gsap.fromTo('.box',
  { x: 0 },
  { x: 100, duration: 1 }
);
gsap.fromTo('.box',
  { x: 200 },
  { x: 300, duration: 0.5, delay: 0.5 }
);
// 第二个 fromTo 会被第一个覆盖掉部分属性

// ❌ 每次事件都创建新 tween，不清理旧动画
button.addEventListener('click', () => {
  gsap.to('.box', { x: 200, duration: 1 });
});
// 点 10 次 = 10 个 tween 在争夺同一个 .box

// ✅ 方案一：先杀掉旧动画
button.addEventListener('click', () => {
  gsap.killTweensOf('.box');
  gsap.to('.box', { x: 200, duration: 1 });
});

// ✅ 方案二：overwrite: true
button.addEventListener('click', () => {
  gsap.to('.box', { x: 200, duration: 1, overwrite: true });
});