animation Number

作用

基于 requestAnimationFrame 的数值动画，支持预设缓动与控制对象；可选启用“末段整数台阶减速”。

签名

animation({ duration=2000, from=0, to=1, callback?, onComplete?, easing='linear', endSlowUnits=0 })

引入

import { animation } from 'flit-kit'

参数

参数	类型	默认值	说明
`duration`	`number`	`2000`	动画时长（毫秒）
`from`	`number`	`0`	起始值
`to`	`number`	`100`	目标值
`callback`	`(value:number)=>void`	`undefined`	每帧数值回调（进行中传中间值，结束传 `to`）
`onComplete`	`(final:number)=>void`	`undefined`	动画结束回调（传入 `to`）
`easing`	`string`	`'linear'`	缓动类型：`linear` / `easeIn` / `easeOut` / `easeInOut` / `bounceOut`
`endSlowUnits`	`number`	`0`	靠近目标值的“最后 N 个单位”显著变慢并按整数台阶推进；`0` 关闭

示例

// 计数动画：0→100（1s，easeInOut），末段 12 个单位一个一个慢慢加，文本显示为整数
const ctrl1 = animation({
  from: 0,
  to: 100,
  duration: 1000,
  easing: 'easeInOut',
  endSlowUnits: 12,
  callback: (v) => { document.getElementById('count').textContent = String(Math.round(v)) },
  onComplete: (v) => console.log('done', v),
})

// 进度条：宽度从 0%→100%，中途停止
const bar = document.getElementById('bar')
const ctrl2 = animation({
  from: 0,
  to: 100,
  duration: 3000,
  easing: 'easeOut',
  endSlowUnits: 0,
  callback: (v) => { bar.style.width = `${v}%` },
})
setTimeout(() => ctrl2.stop(), 1000)

返回值

{ stop: ()=>void, isRunning: ()=>boolean }

输出

done 100

事件与功能

callback(value)：每帧调用；当进度达到 100% 时传入最终值 to，保证最后一帧为终值。
onComplete(final)：动画结束时调用一次（传入 to）。
控制对象：stop() 立即停止后续帧；isRunning() 查询当前是否仍在进行。

行为说明

当 from===to 或 duration===0 时，立即触发 callback(to) 与 onComplete(to)（如果提供）。
在无 requestAnimationFrame 环境下（如 Node），内部自动降级为定时器驱动。
数值推进始终单调逼近目标，不出现跳变到终值的情况。
endSlowUnits>0 时，靠近目标值的“最后 N 个单位”显著变慢并按整数台阶推进，适合计数类视觉效果。