Taro 数字滚动组件

背景

作者前段时间在搭建公司的小程序模板仓库 taro3.x + tailwindcss + zustand 小程序开发 | 掘金。结果发现了一些项目所用组件库 @antmjs/vantui 的bug。当时自己试着修复一下提下pr，结果维护团队响应太快了🤣自己修好上去了。自己就这么失去了第一次提pr的机会......不服气的我就去翻了issue，想着一定得提一个上去，结果让我看到了可以增加一个数字滚动组件么 · Issue #632

我祁厅长都发话了，一年了都没给落实吗😡？于是我简单了解了一下，发现现有的Taro组件库好像都没找到有数字滚动这个组件。最后实在隔壁家的 uView | CountTo 数字滚动找到了。

uni有的，我们taro怎么能没有。看了一下API，和现在流行的数字滚动组件类似，都是基于 CountUp.js 设计的。原本看CountUp.js的源码功能很多，无从下手。这下有了uView的现成作业抄就简单多了🫡。于是我总算是完成了我这"艰难"的pr之旅。下文介绍的是我单独抽出来的组件，可以直接复制代码到自己的项目中使用。

简介

Taro-Countup-React是一个基于@tarojs/components封装的支持React框架写法的Taro数字滚动组件。

该组件适用于需要平滑滚动数字到指定值的场景，支持自定义滚动时间、缓动效果、小数位数显示、千分位分隔符等功能。通过 ref 选择器，你可以方便地控制组件的开始、暂停、继续和重置操作。

API设计和实现原理参考自 react-countup 和 uView | CountTo 数字滚动，可以直接复制到Taro v3/v4项目中使用。因为完全基于Taro自带的组件库开发，理论上支持Taro支持的所有端（不过作者只测试了h5、微信和支付宝小程序）。

代码仓库

HyaCiovo/taro-countup-react

效果

在线演示

作者懒得搞，等什么时候pr过了✅，会把组件库演示文档上的链接放过来😁。

代码演示

基本用法

通过startVal设置开始值，endVal设置结束值

tsx 复制代码

<CountUp startVal={30} endVal={500} />

设置滚动相关参数

通过duration设置从开始直到结束值整个滚动过程所需的时间，单位毫秒
通过useEasing设置在滚动快结束的时候，是否放慢滚动的速度，给用户更好的视觉效果

tsx 复制代码

<CountUp startVal={30} endVal={500} duration={2000} useEasing={false} />

是否显示小数位

通过decimals设置显示的小数位，在滚动过程中，小数位会一起变化。如果startVal和endVal是带小数的，应该设置decimals为startVal和endVal一样的小数位数值，如endVal为 500.55，那么decimals应该设置为2。

tsx 复制代码

<CountUp startVal={30} endVal={500.55} decimals={2} />

千分位分隔符

通过separator配置千分位分隔符，默认为空字符串，可以设置英文逗号","，此参数表现为endVal值超过1000时，比如为"1234"，那么会变成"1,234"。

tsx 复制代码

<CountUp endVal={1500} separator=',' />

手动控制

通过 ref 选择器获取到组件实例后，可以调用start、pause、resume、reset方法。

tsx 复制代码

/* eslint-disable */
import react from 'react'
import { View, Button } from '@tarojs/components'

export default function Demo() {
  const CountToRef = react.useRef<any>()
  const handleFinish = () => {
    console.log('count finish')
  }

  return (
    <View>
      <CountTo
        startVal={30}
        endVal={500}
        ref={CountToRef}
        onFinish={handleFinish}
      />
      <View>
        <Button onClick={() => CountToRef.current?.start()} >开始</Button>
        <Button onClick={() => CountToRef.current?.pause()} >暂停</Button>
        <Button onClick={() => CountToRef.current?.resume()} >继续</Button>
        <Button onClick={() => CountToRef.current?.reset()} >重置</Button>
      </View>
    </View>
  )
}

效果

API

ICountToRef

参数	说明	类型
start	autoplay 为 false 时，通过此方法启动滚动	* () => void *
pause	暂停滚动	* () => void *
resume	暂停后重新开始滚动(从暂停前的值开始滚动)	* () => void *
reset	重设至初始值	* () => void *

CountToProps

参数	说明	类型	默认值	必填
startVal	滚动开始值	* number *	0	`false`
endVal	滚动结束值	* number *	0	`false`
duration	滚动过程所需的时间，单位毫秒	* number *	3000	`false`
autoStart	是否自动开始滚动	* boolean *	true	`false`
decimals	要显示的小数位数	* number ¦ string *	0	`false`
decimal	十进制分隔	* string *	.	`false`
prefix	前缀	* string ¦ ReactNode *	-	`false`
suffix	后缀	* string ¦ ReactNode *	-	`false`
useEasing	是否缓动结束滚动	* boolean *	true	`false`
separator	千分位分隔符	* string *	-	`false`
onFinish	滚动结束时触发	* () => void *	-	`false`
ref	数字滚动实例	* React.MutableRefObject< ¦ ICountToRef ¦ undefined > *	-	`false`

最后

希望我的组件能帮到大家，欢迎各位 JY 来仓库点点 star ✨ 、提提 pr💫！