NumberAnimation 数字滚动

数字从当前值缓动到目标值的动画组件，到目标值停止并派发 oas-finish；prefers-reduced-motion 时直接跳目标，断开连接自动取消 rAF 无泄漏。

基础用法

默认 1500ms 从 0 滚到目标

示例代码

速度与小数位

duration=3000 + to-fixed=2

示例代码

起始值 from

from 指定新一轮起播的起始值（默认 0）；动画中途改 value 仍从当前显示值续动，不受 from 影响。

from=500 起播

示例代码

受控播放（active + play()）

active 控制播放：默认即播；"false" 停帧在当前值，改回 "true" 从当前值续动到目标。play() 手动重播一轮（从 from 起播，播放中防重入）——同值刷新数据时无需改 value 即可重播。滚动进入视口才播的场景可用 IntersectionObserver 喂 active 实现。块内第二个示例静态展示 active="false" 停帧态（停在起始值 6666）。

active 暂停/恢复 + play() 重播

暂停重播

示例代码

缓动档 easing

easing 五档枚举：ease-out（默认，先快后慢）/ linear（匀速，下载字节等场景）/ ease-in / ease-in-out / spring（轻度过冲回弹）；非法值回落 ease-out。

easing 五档对比

示例代码

千分位

group-separator="true" 按 locale 千分位格式化动画值（Intl.NumberFormat，config-provider / setLocale 感知；格式化器按 locale|小数位缓存，每帧零构造开销）。

group-separator 千分位

示例代码

结束事件

oas-finish 回调

示例代码

字号定制

字号默认固定为 --oas-font-size-lg（16px，不随外层变化），可用 CSS 变量 --oas-number-animation-font 显式定制（如 32px）。

API

oas-number-animation

属性

属性	说明	类型	默认值
active	受控播放：缺省即播；"false" 停帧，改回 "true" 从当前值续动到目标	string	—
duration	动画时长（毫秒）；0 直接跳目标	number | string	—
easing	缓动档：ease-out（默认）/ linear / ease-in / ease-in-out / spring（轻度过冲）；非法值回落 ease-out	string	ease-out
from	起始值（默认 0）；仅新一轮起播生效，续动不受影响	string	0
group-separator	千分位分组（"true" 开启，Intl locale 感知；默认关闭）	string	—
to-fixed	小数位（Number.prototype.toFixed）；缺省整数显示	string	—
value	目标数值；非法按 0	string	0

事件

事件	说明
oas-finish	动画抵达目标时派发一次，detail { value: 目标值 }

CSS 变量

CSS 变量	默认值
--oas-number-animation-font	var(--oas-font-size-lg)

• 动画中途修改 value 会从当前显示值续动到新目标。
• 系统开启「减少动态效果」时跳过动画直接显示目标值（同样派发 oas-finish）。
• 断开连接时取消未完成的 rAF，无泄漏。