feat(n-number-animation): add format prop

CHANGELOG.en-US.md

@@ -1,5 +1,13 @@
 # CHANGELOG
 
+## NEXT_VERSION
+
+`NEXT_VERSION`
+
+### Features
+
+- `n-number-animation` adds `format` prop, closes [#7174](https://github.com/tusen-ai/naive-ui/issues/7174)
+
 ## 2.43.1
 
 `2025-09-15`

CHANGELOG.zh-CN.md

@@ -1,5 +1,13 @@
 # CHANGELOG
 
+## NEXT_VERSION
+
+`NEXT_VERSION`
+
+### Features
+
+- `n-number-animation` 添加 `format` 属性，关闭 [#7174](https://github.com/tusen-ai/naive-ui/issues/7174)
+
 ## 2.43.1
 
 `2025-09-15`

src/number-animation/demos/enUS/format.demo.vue

@@ -0,0 +1,53 @@
+<markdown>
+# Custom Format
+
+Use the `format` property to customize the format of the number.
+  </markdown>
+
+<script lang="ts" setup>
+import type { NumberAnimationInst } from 'naive-ui'
+import { ref } from 'vue'
+
+const numberAnimationInstRef1 = ref<NumberAnimationInst | null>(null)
+const numberAnimationInstRef2 = ref<NumberAnimationInst | null>(null)
+
+function handleClick() {
+  numberAnimationInstRef1.value?.play()
+  numberAnimationInstRef2.value?.play()
+}
+
+function formatNumber(value: number): string {
+  const v = (value / 1000).toFixed(0)
+  return `${v.toString().replace(/(\d)(?=(\d{4})+(?!\d))/g, '$1,')}k`
+}
+
+function formatVideoViews(value: number): string {
+  return `${value.toString().replace(/(\d)(?=(\d{4})+(?!\d))/g, '$1,')}次`
+}
+</script>
+
+<template>
+  <n-flex>
+    <n-statistic label="Fans" tabular-nums>
+      <n-number-animation
+        ref="numberAnimationInstRef1"
+        :from="0"
+        :to="869825"
+        :format="formatNumber"
+      />
+    </n-statistic>
+    <n-statistic label="Video Views" tabular-nums>
+      <n-number-animation
+        ref="numberAnimationInstRef2"
+        :from="0"
+        :to="10000000000"
+        :format="formatVideoViews"
+      />
+    </n-statistic>
+  </n-flex>
+  <n-space vertical>
+    <n-button @click="handleClick">
+      Play
+    </n-button>
+  </n-space>
+</template>

src/number-animation/demos/enUS/index.demo-entry.md

@@ -9,6 +9,7 @@ basic.vue
 precision.vue
 separator.vue
 intl.vue
+format.vue
 finish.vue
 ```
 
@@ -21,6 +22,7 @@ finish.vue
 | active | `boolean` | `true` | Whether to play the animation. | 2.23.2 |
 | duration | `number` | `3000` | The duration of | 2.23.2 |
 | from | `number` | `0` | Start value of the animation | 2.23.2 |
+| format | `(value: number) => string` | `undefined` | Custom formatter for the integer part | NEXT_VERSION |
 | locale | `string` | Follows config provider. | Language of the number. | 2.24.2 |
 | precision | `number` | `0` | Decimal precision of the displayed value. | 2.23.2 |
 | show-separator | `boolean` | `false` | Whether to show separator. | 2.23.2 |

src/number-animation/demos/zhCN/format.demo.vue

@@ -0,0 +1,53 @@
+<markdown>
+# 自定义格式化
+
+使用 `format` 属性自定义数值
+</markdown>
+
+<script lang="ts" setup>
+import type { NumberAnimationInst } from 'naive-ui'
+import { ref } from 'vue'
+
+const numberAnimationInstRef1 = ref<NumberAnimationInst | null>(null)
+const numberAnimationInstRef2 = ref<NumberAnimationInst | null>(null)
+
+function handleClick() {
+  numberAnimationInstRef1.value?.play()
+  numberAnimationInstRef2.value?.play()
+}
+
+function formatNumber(value: number): string {
+  const v = (value / 1000).toFixed(0)
+  return `${v.toString().replace(/(\d)(?=(\d{4})+(?!\d))/g, '$1,')}k`
+}
+
+function formatVideoViews(value: number): string {
+  return `${value.toString().replace(/(\d)(?=(\d{4})+(?!\d))/g, '$1,')}次`
+}
+</script>
+
+<template>
+  <n-flex>
+    <n-statistic label="粉丝数" tabular-nums>
+      <n-number-animation
+        ref="numberAnimationInstRef1"
+        :from="0"
+        :to="869825"
+        :format="formatNumber"
+      />
+    </n-statistic>
+    <n-statistic label="视频播放量" tabular-nums>
+      <n-number-animation
+        ref="numberAnimationInstRef2"
+        :from="0"
+        :to="10000000000"
+        :format="formatVideoViews"
+      />
+    </n-statistic>
+  </n-flex>
+  <n-space vertical>
+    <n-button @click="handleClick">
+      播放
+    </n-button>
+  </n-space>
+</template>

src/number-animation/demos/zhCN/index.demo-entry.md

@@ -9,6 +9,7 @@ basic.vue
 precision.vue
 separator.vue
 intl.vue
+format.vue
 finish.vue
 ```
 
@@ -21,6 +22,7 @@ finish.vue
 | active | `boolean` | `true` | 是否开始动画 | 2.23.2 |
 | duration | `number` | `3000` | 动画持续时间 | 2.23.2 |
 | from | `number` | `0` | 数值动画起始值 | 2.23.2 |
+| format | `(value: number) => string` | `undefined` | 自定义格式化数值函数 | NEXT_VERSION |
 | locale | `string` | 跟随 config provider | 国际化的语言 | 2.24.2 |
 | precision | `number` | `0` | 精度，保留小数点后几位 | 2.23.2 |
 | show-separator | `boolean` | `false` | 是否显示分隔符 | 2.23.2 |

src/number-animation/src/NumberAnimation.tsx

@@ -1,13 +1,7 @@
 import type { PropType } from 'vue'
 import type { ExtractPublicPropTypes } from '../../_utils'
 import { round } from 'lodash-es'
-import {
-  computed,
-  defineComponent,
-  onMounted,
-  ref,
-  watchEffect
-} from 'vue'
+import { computed, defineComponent, onMounted, ref, watchEffect } from 'vue'
 import { useLocale } from '../../_mixins'
 import { tween } from './utils'
 
@@ -31,6 +25,7 @@ export const numberAnimationProps = {
     type: Number,
     default: 2000
   },
+  format: Function as PropType<(value: number) => string>,
   onFinish: Function as PropType<() => void>
 }
 
@@ -91,9 +86,13 @@ export default defineComponent({
         .formatToParts(0.5)
         .find(part => part.type === 'decimal')
         ?.value
-      const integer = props.showSeparator
-        ? numberFormatter.format(Number(splitValue[0]))
-        : splitValue[0]
+
+      const intValue = Number(splitValue[0])
+      const integer = props.format
+        ? props.format(intValue)
+        : props.showSeparator
+          ? numberFormatter.format(intValue)
+          : splitValue[0]
       const decimal = splitValue[1]
       return {
         integer,