n-count-to 数字滚动
用于统计指标、金额与带单位的数字展示。数值在同一动画进度下插值，各数字列按十进制位滚动，文字、货币符号和分隔符留在原位。
平台兼容性
| App | H5 | 微信小程序 | 支付宝小程序 | 百度小程序 | 头条小程序 | QQ小程序 |
|---|---|---|---|---|---|---|
| √ | √ | √ | × | × | × | × |
API
属性
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| start-val | 起始数值；字符串保留其中的数字和小数含义 | number / string | 0 |
| end-val | 目标数值；传字符串时原样保留格式字符和数字位数，例如 "$1,314.20" | number / string | 0 |
| duration | 从当前值到目标值的时长，毫秒；0 立即到位 | number | 2000 |
| autoplay | 挂载、重置和目标更新后自动开始；关闭时暂停 | boolean | true |
| decimals | 数值输入保留的小数位，0–10 的整数；字符串以目标模板的小数位为准 | number | 0 |
| use-easing | 使用三次缓出；false 为线性 | boolean | true |
| decimal | 数值输入的小数点字符；字符串保留原字符 | string | . |
| separator | 数值输入的千分位分隔符，留空不分组 | string | |
| font-size | 数字与格式字符的字号，px；行高须容纳字形 | number | 22 |
| color | 文字颜色，留空跟随主题 | string | |
| font-weight | 文字字重，可传 normal、bold 或数值字符串 | string | normal |
| width | 单个数字列宽度，px；0 根据数字内容自适应 | number | 0 |
| height | 滚轮每行容器高度，px；应大于字号，避免裁剪字形 | number | 32 |
| disabled | 禁用点击并降低透明度，动画继续 | boolean | false |
| highlight | 按下时降低透明度 | boolean | false |
| decoration | 文字装饰线 | none / underline / line-through | none |
| params | 点击事件携带的业务参数 | string / number | 0 |
| item-style | 数字列容器行内样式 | string | |
| text-style | 数字与格式字符文字行内样式；可设置字体和行高 | string | |
| separator-style | 格式字符文字行内样式，在 textStyle 后应用 | string | |
| custom-class | 根节点额外类名，类须定义在组件样式表内 | string | |
| custom-style | 根节点行内样式 | string |
事件
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 初始化、重置及动画值变化时触发，参数为 NCountToData | NCountToData |
| start | 开始或继续动画时触发，参数为 NCountToData | NCountToData |
| pause | 手动暂停时触发，参数为 NCountToData；页面隐藏不触发 | NCountToData |
| reset | 重置到起始值时触发，参数为 NCountToData | NCountToData |
| finish | 到达目标值时触发，每轮一次，参数为 NCountToData | NCountToData |
| click | 点击时触发，参数为 NCountToClick；disabled 拦截 | NCountToClick |
| error | 输入或尺寸无效时触发，参数为 NCountToError，停止动画 | NCountToError |
插槽
| 插槽名 | 说明 |
|---|---|
| default | 整体接管内容，参数 value 当前数值、text 当前格式文字、running 是否运行 |
方法与边界
- start() 开始或继续；运行中重复调用不重置，已完成时开始新一轮。pause() 冻结进度，resume() 仅继续未完成的进度。reset() 从当前 startVal 重建，按 autoplay 决定是否开始。current 为 NCountToData，isRunning 可读取运行状态。
- endVal、duration、useEasing 更新从当前实际进度续播；startVal 或 decimals 更新开始新一轮。样式和格式字符更新保留进度。autoplay=false 暂停；重新打开继续。
- number 输入由 decimals/decimal/separator 格式化；string 输入保留目标模板（含前导零、货币、单位），不应用这三个格式属性。字符串数字连接为一个十进制数，英文句点后数字为小数，带减号为负数；不含数字时为固定文字。金额例如 "$1,314.20" 表示 1314.20；数字字符用于滚轮，其他字符原样显示。
- 数值按所需小数位缩放后，绝对值须不超过 9007199254740991；decimals 为 0–10 的整数。时长、字号、行高和列宽须有限，时长和列宽可为零。无效输入触发 error，停止动画并保留上次有效展示；默认字号 22px / 行高 32px，使用更大字号时相应增大 height。
- 页面/应用隐藏冻结动画且取消定时器，两者均恢复后续播；卸载清理定时器。finish 每轮一次，0 时长和相同起止值立即到位。动画时显示截取到指定小数位的文字，数字列在相邻数字间连续移动；完成时精确落在目标数字。
- fontWeight 覆盖加粗能力；textStyle 可设置字体、line-height 与颜色；itemStyle 定制列容器，separatorStyle 定制固定格式字符。调整固定列宽须容纳最宽数字，文本字号与行高须能放入 height，防止裁剪。
- 禁用仅阻止点击，动画继续；click 参数包含 value/text/params。highlight 用按下透明度提供反馈，root customStyle 可定制容器。统一样式使用 --n-count-to-color / disabled-opacity / pressed-opacity。
实现说明
| 机制 | 参考做法 | 本组件做法 | 分歧理由 |
|---|---|---|---|
| 数值动画 | 起止值插值，支持递增、递减；目标更新从当前值续播 | 时间戳插值，目标变化从当前实际进度续播 | 调度延迟不累计；连续修改目标不回跳 |
| 数字滚轮 | 每个字符独立列，数字列 0–9，其他字符固定；位移加过渡 | 同一插值值按十进制位分解为数字列相位，0–9 后补 0 形成连续循环 | 保留数字滚动和格式字符，避免独立列组合出与实际插值无关的数值；统一 JS 帧循环 |
| 输入与格式 | 数值起止值和小数/千分位；滚轮另接受完整格式字符串 | endVal 为 number 时格式化；string 时逐字符保留目标模板，数字参与滚动 | 输入类型表达已有能力，无额外模式开关；前后缀、货币和分隔符无需另拼装 |
| 精度 | 数值显示指定小数；字符串原样保留位数 | 数值由 decimals 控制；字符串由模板的小数位控制，拒绝不安全的数值范围 | 避免超出 JS 精度仍显示看似精确的金额 |
| 缓动 | 可关闭缓动；三次缓出或指数缓出 | useEasing 使用三次缓出，关闭为线性 | 沿用同代实现的平滑收尾，递增和递减共用曲线 |
| 手动控制 | 开始、停止/暂停、暂停后续播 | start/pause/resume/reset；运行中重复 start 不重新计时，完成后 start 开新一轮 | 暂停和重新开始语义明确，不提供重复命名的别名 |
| 生命周期 | 帧循环结束时取消；部分实现仅处理卸载 | 页面/应用隐藏冻结动画，返回继续；卸载取消调度，生命周期钩子随实例管理 | 展示动画无需隐藏时耗电，不在后台提前完成 |
| 点击 | 点击回传文字与业务参数，禁用拦截，按下高亮 | click 回传当前 text/value/params；disabled 拦截，highlight 控制按下透明度 | 保留交互能力，禁用保持色相 |
| 字体与样式 | 专用数字字体；字号、颜色、字重、列宽高、装饰线 | 系统字体；显式样式属性、主题令牌与内部节点样式 | 不引入字体资产；滚轮行使用容器居中，文字不钉死高度 |
| 结构更新 | 位数/符号变化重建列 | key 仅包含列结构与固定字符，帧更新原地改变位移 | App 结构变化可靠重绘，逐帧不重建整组件 |