From d0fcf8a255a486f831aea778260b291d6347093d Mon Sep 17 00:00:00 2001
From: Aybrea <wrenchou22@gmail.com>
Date: Wed, 20 Nov 2024 20:54:11 +0800
Subject: [PATCH] feat: new component CountTo

---
 packages/varlet-ui/src/count-to/CountTo.vue   |  46 ++++---
 packages/varlet-ui/src/count-to/countTo.less  |   2 -
 packages/varlet-ui/src/count-to/docs/en-US.md | 112 ++++++++++++++++++
 packages/varlet-ui/src/count-to/docs/zh-CN.md | 112 ++++++++++++++++++
 .../varlet-ui/src/count-to/example/index.vue  |  32 ++++-
 .../src/count-to/example/locale/en-US.ts      |   9 +-
 .../src/count-to/example/locale/zh-CN.ts      |  10 +-
 packages/varlet-ui/src/count-to/props.ts      |  32 ++++-
 packages/varlet-ui/types/countTo.d.ts         |  24 +++-
 packages/varlet-ui/types/index.d.ts           |   2 +
 10 files changed, 354 insertions(+), 27 deletions(-)
 delete mode 100644 packages/varlet-ui/src/count-to/countTo.less

diff --git a/packages/varlet-ui/src/count-to/CountTo.vue b/packages/varlet-ui/src/count-to/CountTo.vue
index 0c9252cd063..468aed3518b 100644
--- a/packages/varlet-ui/src/count-to/CountTo.vue
+++ b/packages/varlet-ui/src/count-to/CountTo.vue
@@ -1,15 +1,12 @@
 <template>
   <div :class="n()">
-    <div :style="{ transform: `translateX(${value}px)` }">{{ value }}: {{ state }}</div>
-    <button @click="start">Start</button>
-    <button @click="pause">Pause</button>
-    <button @click="reset">Reset</button>
+    <slot v-bind="numberData"> {{ numberData.value }} </slot>
   </div>
 </template>
 
 <script lang="ts">
-import { computed, defineComponent } from 'vue'
-import { props } from './props'
+import { defineComponent, computed, onMounted } from 'vue'
+import { props, type NumberData } from './props'
 import { createNamespace } from '../utils/components'
 import { useMotion } from '@varlet/use'
 import { floor } from '@varlet/shared'
@@ -19,33 +16,46 @@ const { name, n } = createNamespace('count-to')
 export default defineComponent({
   name,
   props,
-  setup() {
+  setup(props) {
     const {
       value: _value,
       state,
       start,
       pause,
-      reset,
+      reset: _reset,
     } = useMotion({
-      from: 0,
-      to: 200,
-      duration: 2000,
+      from: Number(props.from),
+      to: Number(props.to),
+      duration: Number(props.duration),
+      timingFunction: props.timingFunction,
+      onFinished: props.onFinished,
     })
 
-    const value = computed(() => floor(_value.value))
+    const numberData = computed<NumberData>(() => ({
+      value: floor(_value.value),
+      state: state.value,
+    }))
+
+    onMounted(() => {
+      if (props.autoStart) {
+        start()
+      }
+    })
+
+    function reset() {
+      _reset()
+      if (props.autoStart) {
+        start()
+      }
+    }
 
     return {
+      numberData,
       n,
       start,
       pause,
       reset,
-      state,
-      value,
     }
   },
 })
 </script>
-
-<style lang="less">
-@import './countTo';
-</style>
diff --git a/packages/varlet-ui/src/count-to/countTo.less b/packages/varlet-ui/src/count-to/countTo.less
deleted file mode 100644
index 84273c1554b..00000000000
--- a/packages/varlet-ui/src/count-to/countTo.less
+++ /dev/null
@@ -1,2 +0,0 @@
-.var-count-to {
-}
diff --git a/packages/varlet-ui/src/count-to/docs/en-US.md b/packages/varlet-ui/src/count-to/docs/en-US.md
index e69de29bb2d..8f0ef79f368 100644
--- a/packages/varlet-ui/src/count-to/docs/en-US.md
+++ b/packages/varlet-ui/src/count-to/docs/en-US.md
@@ -0,0 +1,112 @@
+# Number Animation
+
+### Introduction
+
+Display a number animation transitioning from a start value to a target value.
+
+### Basic Usage
+
+The `from` and `to` attributes specify the start and target values.
+
+```html
+<template>
+  <var-count-to :from="0" :to="123456" />
+</template>
+```
+
+### Custom Duration
+
+The `duration` attribute specifies the animation duration in milliseconds.
+
+```html
+<template>
+  <var-count-to :from="0" :to="123456" :duration="100000" />
+</template>
+```
+
+### Custom Styles
+
+The default scoped slot exposes the `state` and `value` properties, allowing you to customize styles through the slot.
+
+```html
+<template>
+  <var-count-to :from="0" :to="123456">
+    <template #default="{ state, value }">
+      <i>{{ state }}: {{ value.toLocaleString() }}</i>
+    </template>
+  </var-count-to>
+</template>
+```
+
+### Custom Animation Curve
+
+The `timing-function` attribute specifies the animation curve.
+
+```html
+<template>
+  <var-count-to :from="0" :to="123456" :timing-function="(t) => 1 - Math.pow(1 - t, 2)" />
+</template>
+```
+
+### Manual Control
+
+Use `ref` to get countTo instance, you can call the `start`, `pause`, and `reset` methods.
+
+```html
+<script setup>
+  import { ref } from 'vue'
+
+  const countToRef = ref()
+</script>
+
+<template>
+  <var-count-to :from="0" :to="123456" ref="countToRef" :auto-start="false" />
+  <var-row style="margin-top: 10px">
+    <var-button-group>
+      <var-button @click="countToRef.start()">{{ t('startText') }}</var-button>
+      <var-button @click="countToRef.pause()">{{ t('pauseText') }}</var-button>
+      <var-button @click="countToRef.reset()">{{ t('resetText') }}</var-button>
+    </var-button-group>
+  </var-row>
+</template>
+```
+
+## API
+
+### Properties
+
+| Property     | Description                              | Type               | Default | --- |
+| ------------ | ---------------------------------------- | ------------------ | ------- | --- |
+| `from`       | Start value                              | _number \| string_ | `0`     |
+| `to`         | Target value                             | _number \| string_ | `0`     |
+| `duration`   | Animation duration (ms)                  | _number \| string_ | `30000` |
+| `auto-start` | Whether to start animation automatically | _boolean_          | `true`  |
+
+### Events
+
+| Event Name | Description                   | Callback Parameters |
+| ---------- | ----------------------------- | ------------------- |
+| `finished` | Triggered when animation ends | `-`                 |
+
+### Slots
+
+| Slot Name | Description    | Parameters               |
+| --------- | -------------- | ------------------------ |
+| `default` | Custom content | `numberData: NumberData` |
+
+### NumberData Format
+
+| Name    | Description            | Type                                               |
+| ------- | ---------------------- | -------------------------------------------------- |
+| `value` | Current value          | `number`                                           |
+| `state` | Current playing state | `'running' \| 'paused' \| 'pending' \| 'finished'` |
+
+### Methods
+
+Use ref to get CountTo instance and call instance methods.
+
+| Method  | Description                                                                          | arguments | Return |
+| ------- | ------------------------------------------------------------------------------------ | --------- | ------ |
+| `start` | Start the animation                                                                  | `-`       | `-`    |
+| `pause` | Pause the animation                                                                  | `-`       | `-`    |
+| `reset` | Reset the animation. If `auto-start` is `true`, the animation will restart automatically | `-`       | `-`    |
diff --git a/packages/varlet-ui/src/count-to/docs/zh-CN.md b/packages/varlet-ui/src/count-to/docs/zh-CN.md
index e69de29bb2d..5d478d00ec4 100644
--- a/packages/varlet-ui/src/count-to/docs/zh-CN.md
+++ b/packages/varlet-ui/src/count-to/docs/zh-CN.md
@@ -0,0 +1,112 @@
+# 数字动画
+
+### 介绍
+
+用于展示起始数值到目标数值的数字动画。
+
+### 基本使用
+
+通过 `from` 和 `to` 属性可以指定起始数值和目标数值。
+
+```html
+<template>
+  <var-count-to :from="0" :to="123456" />
+</template>
+```
+
+### 自定义时长
+
+通过 `duration` 属性可以指定动画时长（单位为毫秒）。
+
+```html
+<template>
+  <var-count-to :from="0" :to="123456" :duration="100000" />
+</template>
+```
+
+### 自定义样式
+
+默认作用域插槽暴露了 `state` 和 `value` 两个属性，可以通过插槽自定义样式。
+
+```html
+<template>
+  <var-count-to :from="0" :to="123456">
+    <template #default="{ state, value }">
+      <i>{{ state }}: {{ value.toLocaleString() }}</i>
+    </template>
+  </var-count-to>
+</template>
+```
+
+### 自定义动画曲线
+
+通过 `timing-function` 属性可以指定动画曲线。
+
+```html
+<template>
+  <var-count-to :from="0" :to="123456" :timing-function="(t) => 1 - Math.pow(1 - t, 2)" />
+</template>
+```
+
+### 手动控制
+
+通过 ref 获取到组件实例后，可以调用 `start`、`pause`、`reset` 方法。
+
+```html
+<script setup>
+  import { ref } from 'vue'
+
+  const countToRef = ref()
+</script>
+
+<template>
+  <var-count-to :from="0" :to="123456" ref="countToRef" :auto-start="false" />
+  <var-row style="margin-top: 10px">
+    <var-button-group>
+      <var-button @click="countToRef.start()">{{ t('startText') }}</var-button>
+      <var-button @click="countToRef.pause()">{{ t('pauseText') }}</var-button>
+      <var-button @click="countToRef.reset()">{{ t('resetText') }} </var-button>
+    </var-button-group>
+  </var-row>
+</template>
+```
+
+## API
+
+### 属性
+
+| 参数         | 说明                       | 类型               | 默认值  |
+| ------------ | -------------------------- | ------------------ | ------- |
+| `from`       | 起始值                     | _number \| string_ | `0`     |
+| `to`         | 目标值                     | _number \| string_ | `0`     |
+| `duration`   | 动画持续时间（单位：毫秒） | _number \| string_ | `30000` |
+| `auto-start` | 是否自动开始播放动画       | _boolean_          | `true`  |
+
+### 事件
+
+| 事件名     | 说明           | 回调参数 |
+| ---------- | -------------- | -------- |
+| `finished` | 动画结束时触发 | `-`      |
+
+### 插槽
+
+| 插槽名    | 说明       | 参数                     |
+| --------- | ---------- | ------------------------ |
+| `default` | 自定义内容 | `numberData: NumberData` |
+
+### NumberData 格式
+
+| 名称    | 说明         | 类型                                               |
+| ------- | ------------ | -------------------------------------------------- |
+| `value` | 当前数值     | `number`                                           |
+| `state` | 当前播放状态 | `'running' \| 'paused' \| 'pending' \| 'finished'` |
+
+### 方法
+
+通过 ref 可以获取到 CountDown 实例并调用实例方法.
+
+| 方法名  | 说明                                                      | 参数 | 返回值 |
+| ------- | --------------------------------------------------------- | ---- | ------ |
+| `start` | 开始倒计时                                                | `-`  | `-`    |
+| `pause` | 暂停倒计时                                                | `-`  | `-`    |
+| `reset` | 重设动画，若 `auto-start` 为 `true`，重设后会自动开始播放 | `-`  | `-`    |
diff --git a/packages/varlet-ui/src/count-to/example/index.vue b/packages/varlet-ui/src/count-to/example/index.vue
index 6acdf74149a..6e72c37db0a 100644
--- a/packages/varlet-ui/src/count-to/example/index.vue
+++ b/packages/varlet-ui/src/count-to/example/index.vue
@@ -1,11 +1,37 @@
 <script setup>
 import { watchLang, AppType } from '@varlet/cli/client'
-import { use } from './locale'
+import { t, use } from './locale'
+import { ref } from 'vue'
+
+const countToRef = ref()
 
 watchLang(use)
 </script>
 
 <template>
-  <app-type>Mobile phone example code</app-type>
-  <var-count-to />
+  <app-type>{{ t('basicUsage') }}</app-type>
+  <var-count-to :from="0" :to="123456" />
+
+  <app-type>{{ t('customDuration') }}</app-type>
+  <var-count-to :from="0" :to="123456" :duration="10000" />
+
+  <app-type>{{ t('customStyle') }}</app-type>
+  <var-count-to :from="0" :to="123456">
+    <template #default="{ state, value }">
+      <i>{{ state }}: {{ value.toLocaleString() }}</i>
+    </template>
+  </var-count-to>
+
+  <app-type>{{ t('customAnimationCurve') }}</app-type>
+  <var-count-to :from="0" :to="123456" :timing-function="(t) => 1 - Math.pow(1 - t, 2)" />
+
+  <app-type>{{ t('manualControl') }}</app-type>
+  <var-count-to :from="0" :to="123456" ref="countToRef" :auto-start="false" />
+  <var-row style="margin-top: 10px">
+    <var-button-group>
+      <var-button @click="countToRef.start()">{{ t('startText') }}</var-button>
+      <var-button @click="countToRef.pause()">{{ t('pauseText') }}</var-button>
+      <var-button @click="countToRef.reset()">{{ t('resetText') }} </var-button>
+    </var-button-group>
+  </var-row>
 </template>
diff --git a/packages/varlet-ui/src/count-to/example/locale/en-US.ts b/packages/varlet-ui/src/count-to/example/locale/en-US.ts
index cbec61de2fa..c108c2ba6c9 100644
--- a/packages/varlet-ui/src/count-to/example/locale/en-US.ts
+++ b/packages/varlet-ui/src/count-to/example/locale/en-US.ts
@@ -1,3 +1,10 @@
 export default {
-  // Example locale
+  basicUsage: 'Basic Usage',
+  customDuration: 'Custom Duration',
+  customStyle: 'Custom Style',
+  manualControl: 'Manual Control',
+  customAnimationCurve: 'Custom Animation Curve',
+  startText: 'Start',
+  pauseText: 'Pause',
+  resetText: 'Reset',
 }
diff --git a/packages/varlet-ui/src/count-to/example/locale/zh-CN.ts b/packages/varlet-ui/src/count-to/example/locale/zh-CN.ts
index cbec61de2fa..d719e0fd6b7 100644
--- a/packages/varlet-ui/src/count-to/example/locale/zh-CN.ts
+++ b/packages/varlet-ui/src/count-to/example/locale/zh-CN.ts
@@ -1,3 +1,11 @@
 export default {
-  // Example locale
+  basicUsage: '基本使用',
+  customDuration: '自定义时长',
+  customStyle: '自定义样式',
+  manualControl: '手动控制',
+  customAnimationCurve: '自定义动画曲线',
+  startText: '开始',
+  pauseText: '暂停',
+  resetText: '重置',
+  autoStart: '自动开始',
 }
diff --git a/packages/varlet-ui/src/count-to/props.ts b/packages/varlet-ui/src/count-to/props.ts
index 455f4337f46..7ce65b05516 100644
--- a/packages/varlet-ui/src/count-to/props.ts
+++ b/packages/varlet-ui/src/count-to/props.ts
@@ -1 +1,31 @@
-export const props = {}
+import { PropType } from 'vue'
+
+export type NumberData = {
+  value: number
+  state: 'running' | 'paused' | 'pending' | 'finished'
+}
+
+export const props = {
+  from: {
+    type: [String, Number],
+    default: 0,
+  },
+  to: {
+    type: [String, Number],
+    default: 0,
+  },
+  duration: {
+    type: [String, Number],
+    default: 3000,
+  },
+  autoStart: {
+    type: Boolean,
+    default: true,
+  },
+  timingFunction: {
+    type: Function as PropType<(v: number) => number>,
+  },
+  onFinished: {
+    type: Function as PropType<() => void>,
+  },
+}
diff --git a/packages/varlet-ui/types/countTo.d.ts b/packages/varlet-ui/types/countTo.d.ts
index 091866ad7c4..e3ab55ca05e 100644
--- a/packages/varlet-ui/types/countTo.d.ts
+++ b/packages/varlet-ui/types/countTo.d.ts
@@ -2,12 +2,34 @@ import { VarComponent, BasicAttributes, SetPropsDefaults } from './varComponent'
 
 export declare const countToProps: Record<keyof CountToProps, any>
 
-export interface CountToProps extends BasicAttributes {}
+export interface CountToNumberData {
+  value: number
+  state: 'running' | 'paused' | 'pending' | 'finished'
+}
+
+export interface CountToProps extends BasicAttributes {
+  from: string | number
+  to: string | number
+  duration: string | number
+  autoStart: boolean
+  timingFunction?: PropType<(v: number) => number>
+  onFinished?: PropType<() => void>
+}
 
 export class CountTo extends VarComponent {
   static setPropsDefaults: SetPropsDefaults<CountToProps>
 
   $props: CountToProps
+
+  $slots: {
+    default(data: CountToNumberData): VNode[]
+  }
+
+  start(): void
+
+  pause(): void
+
+  reset(): void
 }
 
 export class _CountToComponent extends CountTo {}
diff --git a/packages/varlet-ui/types/index.d.ts b/packages/varlet-ui/types/index.d.ts
index 2f4d764fd5e..4baa019bfb0 100644
--- a/packages/varlet-ui/types/index.d.ts
+++ b/packages/varlet-ui/types/index.d.ts
@@ -28,6 +28,7 @@ export * from './collapse'
 export * from './collapseItem'
 export * from './collapseTransition'
 export * from './context'
+export * from './countTo'
 export * from './countdown'
 export * from './counter'
 export * from './datePicker'
@@ -125,6 +126,7 @@ declare module 'vue' {
     VarCollapseItem: typeof import('@varlet/ui')['_CollapseItemComponent']
     VarCollapseTransition: typeof import('@varlet/ui')['_CollapseTransitionComponent']
     VarContext: typeof import('@varlet/ui')['_ContextComponent']
+    VarCountTo: typeof import('@varlet/ui')['_CountToComponent']
     VarCountdown: typeof import('@varlet/ui')['_CountdownComponent']
     VarCounter: typeof import('@varlet/ui')['_CounterComponent']
     VarDatePicker: typeof import('@varlet/ui')['_DatePickerComponent']