gsap-cursor

GSAP 光标 — 指针驱动效果

流程：gsap-setup → gsap-animate → gsap-cursor → gsap-optimise → gsap-test

配套技能：如需使用 GSAP 核心补间 API，请调用 gsap-core。如需使用性能方法，请调用 gsap-performance。本技能仅涵盖光标效果示例。需要：greensock/gsap-skills

所有模式均假设已配置 gsap.context() 清理（参见 gsap-animate 技能）。

---

1. 磁性按钮（quickTo）

gsap.quickTo 会预编译补间，在频繁更新时比 gsap.to 快 50-250%。

let xTo, yTo
ctx = gsap.context(() => {
  xTo = gsap.quickTo(btn, 'x', { duration: 0.4, ease: 'power3' })
  yTo = gsap.quickTo(btn, 'y', { duration: 0.4, ease: 'power3' })
}, scopeRef.value)

function onMagnetMove(e) {
  const rect = btn.getBoundingClientRect()
  xTo((e.clientX - rect.left - rect.width / 2) * 0.35)
  yTo((e.clientY - rect.top - rect.height / 2) * 0.35)
}
function onMagnetLeave() { xTo(0); yTo(0) }

有关 quickTo 与 quickSetter API 的对比，请参见 gsap-performance 技能。

---

2. Flair 粒子轨迹

使用 gsap.ticker 按距离生成粒子，并通过对象池循环复用。元素会在光标位置重新出现，播放离场动画，然后通过 gsap.utils.wrap 循环复用。

核心循环（通过 gsap.ticker.add 每个 tick 运行一次）：

gsap.ticker.add(() => {
  const dist = Math.hypot(lastPos.x - mousePos.x, lastPos.y - mousePos.y)
  if (dist > gap) { spawnParticle(); lastPos = mousePos }
})

生成：使用 gsap.set 将元素定位到光标处，使用 gsap.utils.wrap(0, pool.length) 循环索引，时间轴负责缩放、淡出并让粒子下落。

对象池设置和动画时间轴的完整实现见 references/cursor-patterns.md。

---

3. 弹簧物理弹性跟随器

多个圆团以不同的 duration 值追随光标，营造出错落有致、类似物理运动的感觉。每个圆团都使用 elastic.out 缓动和 overwrite: 'auto'。

self.add('moveBlobs', (mx, my) => {
  blobs.forEach((blob, i) => {
    gsap.to(blob.el, {
      x: mx, y: my,
      duration: blob.dur, ease: 'elastic.out(1.2, 0.3)',
      overwrite: 'auto', force3D: true,
    })
  })
})

静止位置基于百分比计算（containerWidth * pct / 100），并在重置时重新计算。

圆团配置、设置和重置的完整实现见 references/cursor-patterns.md。

---

4. 聚光灯光标（Clip-Path 圆形）

通过动画让 clipPath 圆形跟随光标，从而显露隐藏图层。

self.add('moveSpotlight', (x, y) => {
  gsap.to(spotlight, {
    clipPath: `circle(130px at ${x}px ${y}px)`,
    duration: 0.25, ease: 'power2.out', overwrite: 'auto',
  })
})

初始状态：使用 gsap.set(spotlight, { clipPath: 'circle(0px at 50% 50%)' })，以便干净地还原。

包含隐藏动画的完整实现见 references/cursor-patterns.md。

---

5. 光标跟踪图像预览

将光标悬停在列表项上时，图像会跟随光标。使用 gsap.quickTo，并在首次进入时使用双参数吸附，以避免插值延迟。

const setX = gsap.quickTo(image, "x", { duration: 0.4, ease: "power3" })
// On first enter, snap: setX(e.clientX, e.clientX)
// On subsequent moves: setX(e.clientX)

暂停的 autoAlpha 补间通过鼠标进入/离开时调用 play()/reverse() 来切换可见性。

完整实现见 references/cursor-patterns.md。

---

6. 光标驱动的透视倾斜

由指针位置驱动的 3D 透视倾斜。父元素设置 perspective: 650，子元素通过 gsap.quickTo + gsap.utils.interpolate 旋转/平移。

gsap.set("main", { perspective: 650 })
const outerRX = gsap.quickTo(".card", "rotationX", { ease: "power3" })
// pointermove: outerRX(gsap.utils.interpolate(15, -15, e.y / innerHeight))
// pointerleave: outerRX(0)

外层元素旋转（rotationX/Y），内层元素平移（x/y），以营造视差纵深感。

完整实现见 references/cursor-patterns.md。

---

7. 最佳实践

// 1. overwrite: 'auto' on EVERY rapid-fire tween — prevents pile-up
gsap.to(el, { x: 100, overwrite: 'auto' })

// 2. ctx.add for cleanup — all event-handler tweens registered via ctx.add
self.add('onMove', (x, y) => { gsap.to(el, { x, y, overwrite: 'auto' }) })

// 3. will-change lifecycle — set on start, release onComplete
el.style.willChange = 'transform'
gsap.to(el, { x: 0, onComplete: () => { el.style.willChange = 'auto' } })

// 4. force3D: true on repeatedly animated elements
gsap.set(el, { force3D: true })

// 5. quickTo in onMounted, not in handlers — create once, call many

清理检查清单

1. 每个光标补间都通过 ctx.add('name', fn) 注册
2. 在 onUnmounted 中调用 ctx.revert()
3. 在 onMounted 中创建 quickTo 实例，而不是在处理函数中创建
4. 在 onComplete 中释放 will-change，绝不永久保留
5. 基于 ticker 的效果需在清理时调用 gsap.ticker.remove(fn)

---

参考资料

• references/cursor-patterns.md — Flair 粒子轨迹、弹簧物理跟随器、聚光灯光标、电路发光效果、光标跟踪图像预览、光标驱动的透视倾斜