Tween 动画

介绍

Tween 用来做数值补间，适合滚动过渡、数值动画和轻量 UI 过场这类“只有一条时间轴”的场景。

它支持：

• 基于 requestAnimationFrame 的逐帧推进
• play / pause / resume / cancel / reset / seek
• 自定义 easing
• 注入 scheduler，便于测试或宿主接管时间推进

快速使用

import { Tween, tweenEasings } from '@cat-kit/fe'

const tween = new Tween({
  from: 0,
  to: 100,
  duration: 400,
  easing: tweenEasings.easeOutQuad,
  onUpdate: ({ value }) => {
    console.log(value)
  }
})

tween.play()

交互示例

下面的 demo 会把 state、progress、value 和 easing 切换放在同一个面板里，适合先感受 Tween 的时间推进方式，再回头看 API。

vue

单条时间轴补间

切换 easing，观察位置、进度和值的同步变化。

EasinglineareaseOutQuadeaseInOutQuad

stateidle

progress0.0%

value0.0

elapsed0ms

点击 play 观察 Tween 逐帧推进

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300

<template>
  <div class="tween-demo">
    <div class="panel">
      <div class="panel-head">
        <div>
          <h3>单条时间轴补间</h3>
          <p>切换 easing，观察位置、进度和值的同步变化。</p>
        </div>

        <label class="easing-select">
          <span>Easing</span>
          <select v-model="easingName">
            <option v-for="option in easingOptions" :key="option" :value="option">
              {{ option }}
            </option>
          </select>
        </label>
      </div>

      <div class="track">
        <div class="track-fill" :style="{ width: `${value}%` }" />
        <div class="track-orb" :style="{ left: `calc(${value}% - 14px)` }" />
      </div>

      <div class="metrics">
        <div class="metric">
          <span class="metric-label">state</span>
          <strong>{{ state }}</strong>
        </div>
        <div class="metric">
          <span class="metric-label">progress</span>
          <strong>{{ progress.toFixed(1) }}%</strong>
        </div>
        <div class="metric">
          <span class="metric-label">value</span>
          <strong>{{ value.toFixed(1) }}</strong>
        </div>
        <div class="metric">
          <span class="metric-label">elapsed</span>
          <strong>{{ elapsed }}ms</strong>
        </div>
      </div>

      <p class="status">{{ statusText }}</p>

      <div class="controls">
        <button type="button" @click="playTween">play</button>
        <button type="button" @click="pauseTween">pause</button>
        <button type="button" @click="resumeTween">resume</button>
        <button type="button" @click="seekHalf">seek(0.5)</button>
        <button type="button" @click="resetTween">reset</button>
      </div>
    </div>
  </div>
</template>

<script lang="ts" setup>
import { Tween, tweenEasings } from '@cat-kit/fe/src'
import type { TweenFrame, TweenState } from '@cat-kit/fe/src'
import { onUnmounted, ref, watch } from 'vue'

type EasingName = 'linear' | 'easeOutQuad' | 'easeInOutQuad'

const easingOptions: EasingName[] = ['linear', 'easeOutQuad', 'easeInOutQuad']
const easingName = ref<EasingName>('easeOutQuad')
const state = ref<TweenState>('idle')
const progress = ref(0)
const value = ref(0)
const elapsed = ref(0)
const statusText = ref('点击 play 观察 Tween 逐帧推进')

let tween: Tween | null = null

function syncFrame(frame?: TweenFrame) {
  state.value = frame?.state ?? tween?.getState() ?? 'idle'
  progress.value = (frame?.progress ?? tween?.getProgress() ?? 0) * 100
  value.value = frame?.value ?? tween?.getValue() ?? 0
  elapsed.value = Math.round(frame?.elapsed ?? 0)
}

function createTween() {
  tween?.cancel()
  tween = new Tween({
    from: 0,
    to: 100,
    duration: 1400,
    easing: tweenEasings[easingName.value],
    onUpdate(frame) {
      syncFrame(frame)
    },
    onFinish(frame) {
      statusText.value = '已完成，当前值停在终点'
      syncFrame(frame)
    },
    onCancel(frame) {
      syncFrame(frame)
    }
  })

  syncFrame()
}

function ensureTween() {
  if (!tween) {
    createTween()
  }

  return tween!
}

function playTween() {
  createTween()
  ensureTween().play()
  statusText.value = `正在播放，easing = ${easingName.value}`
  syncFrame()
}

function pauseTween() {
  ensureTween().pause()
  statusText.value = '已暂停，可以继续 resume'
  syncFrame()
}

function resumeTween() {
  ensureTween().resume()
  statusText.value = '继续播放中'
  syncFrame()
}

function seekHalf() {
  ensureTween().seek(0.5)
  statusText.value = '已跳到 50% 位置'
  syncFrame()
}

function resetTween() {
  ensureTween().reset()
  statusText.value = '已重置到起点'
  syncFrame()
}

watch(easingName, () => {
  const currentProgress = tween?.getProgress() ?? 0
  createTween()
  tween?.seek(currentProgress)
  statusText.value = `已切换为 ${easingName.value}`
  syncFrame()
})

createTween()

onUnmounted(() => {
  tween?.cancel()
  tween = null
})
</script>

<style scoped>
.tween-demo {
  padding: 4px 0;
}

.panel {
  display: flex;
  flex-direction: column;
  gap: 16px;
  padding: 16px;
  border: 1px solid var(--vp-c-divider);
  border-radius: 16px;
  background:
    radial-gradient(circle at top left, rgba(255, 210, 167, 0.28), transparent 38%),
    linear-gradient(135deg, rgba(255, 247, 237, 0.95), rgba(255, 255, 255, 0.98));
}

.panel-head {
  display: flex;
  justify-content: space-between;
  gap: 12px;
  align-items: flex-start;
}

.panel-head h3 {
  margin: 0;
  font-size: 16px;
}

.panel-head p {
  margin: 6px 0 0;
  color: var(--vp-c-text-2);
  font-size: 13px;
}

.easing-select {
  display: flex;
  flex-direction: column;
  gap: 6px;
  min-width: 150px;
  font-size: 12px;
  color: var(--vp-c-text-2);
}

.easing-select select {
  padding: 8px 10px;
  border: 1px solid var(--vp-c-divider);
  border-radius: 10px;
  background: rgba(255, 255, 255, 0.9);
  color: var(--vp-c-text-1);
}

.track {
  position: relative;
  height: 14px;
  border-radius: 999px;
  background: rgba(148, 163, 184, 0.18);
  overflow: hidden;
}

.track-fill {
  height: 100%;
  border-radius: inherit;
  background: linear-gradient(90deg, #ff9f68, #ff6b4a);
}

.track-orb {
  position: absolute;
  top: 50%;
  width: 28px;
  height: 28px;
  border: 3px solid rgba(255, 255, 255, 0.95);
  border-radius: 50%;
  background: linear-gradient(135deg, #ff824d, #ff5b3f);
  box-shadow: 0 8px 20px rgba(255, 107, 74, 0.25);
  transform: translateY(-50%);
}

.metrics {
  display: grid;
  grid-template-columns: repeat(4, minmax(0, 1fr));
  gap: 10px;
}

.metric {
  display: flex;
  flex-direction: column;
  gap: 4px;
  padding: 10px 12px;
  border-radius: 12px;
  background: rgba(255, 255, 255, 0.72);
  border: 1px solid rgba(255, 255, 255, 0.8);
}

.metric-label {
  font-size: 11px;
  color: var(--vp-c-text-2);
  text-transform: uppercase;
  letter-spacing: 0.04em;
}

.status {
  margin: 0;
  color: #c2410c;
  font-size: 13px;
  font-weight: 600;
}

.controls {
  display: flex;
  flex-wrap: wrap;
  gap: 10px;
}

.controls button {
  padding: 9px 14px;
  border: 0;
  border-radius: 999px;
  background: #111827;
  color: white;
  font-size: 13px;
  cursor: pointer;
}

.controls button:hover {
  background: #1f2937;
}

@media (max-width: 640px) {
  .panel-head {
    flex-direction: column;
  }

  .easing-select {
    min-width: 100%;
  }

  .metrics {
    grid-template-columns: repeat(2, minmax(0, 1fr));
  }
}
</style>

API参考

构造参数

interface TweenOptions {
  from?: number
  to?: number
  duration?: number
  delay?: number
  easing?: (progress: number) => number
  autoplay?: boolean
  scheduler?: TweenScheduler
  onUpdate?: (frame: TweenFrame) => void
  onFinish?: (frame: TweenFrame) => void
  onCancel?: (frame: TweenFrame) => void
}

常用实例方法

tween.play()
tween.pause()
tween.resume()
tween.cancel()
tween.reset()
tween.seek(0.5)

状态与数值读取

tween.getState()
tween.getValue()
tween.getProgress()

内置 easing

tweenEasings.linear
tweenEasings.easeInQuad
tweenEasings.easeOutQuad
tweenEasings.easeInOutQuad