Statistic 统计数值
突出展示一个统计数字,例如销售额、用户数、完成率。支持千分位、固定小数位、前后缀和数值滚动动画。
引入
ts
import { NsStatistic } from '@ns/ui'
基础用法
value 是要展示的数值,title 是数值上方的标题。整数部分默认按千分位用 , 分组。
vue
<template>
<NsStatistic :value="123456" title="用户总数" />
</template>
精度
precision 设置小数位数,四舍五入,不足的位数补 0。不设时按数值本身的位数显示,很大或很小的数也不会显示成科学计数法。下面每个数值的标题就是它显示出来的样子:
vue
<template>
<NsSpace direction="vertical" align="start" size="large">
<NsSpace wrap size="large">
<NsStatistic :value="12345.6789" :precision="2" title="12,345.68" />
<NsStatistic :value="100" :precision="2" title="100.00" />
<NsStatistic :value="-1234.5" :precision="2" title="-1,234.50" />
<NsStatistic :value="99.5" :precision="0" title="precision 0:100" />
</NsSpace>
<NsSpace wrap size="large">
<NsStatistic :value="12345.6789" title="不设 precision" />
<NsStatistic :value="0.0000001" title="很小的数" />
<NsStatistic :value="123456789012345680000" title="很大的数" />
</NsSpace>
</NsSpace>
</template>
分隔符
groupSeparator 是千分位分隔符(默认 ,,传空字符串不分组),separator 是小数点分隔符(默认 .)。
vue
<template>
<NsSpace wrap size="large">
<!-- 1,234,567.89 -->
<NsStatistic :value="1234567.89" title="默认" />
<!-- 1 234 567 -->
<NsStatistic :value="1234567" group-separator=" " title="千分位用空格" />
<!-- 1234567 -->
<NsStatistic :value="1234567" group-separator="" title="不分组" />
<!-- 1.234,50 -->
<NsStatistic
:value="1234.5"
:precision="2"
group-separator="."
separator=","
title="欧洲写法"
/>
</NsSpace>
</template>
字符串数值
value 也可以传字符串:数字字符串(例如接口返回的 '1234.5')按数字格式化;非数字的字符串(例如 '--')原样显示。
vue
<template>
<NsSpace wrap size="large">
<NsStatistic value="1234.5" :precision="2" title="1,234.50" />
<NsStatistic value="-0.125" :precision="2" title="-0.13" />
<NsStatistic value="--" title="暂无数据" />
<NsStatistic value="--" suffix="%" title="非数字也带前后缀" />
</NsSpace>
</template>
标题
标题用 title 属性,也可以用 title 插槽放图标、提示等内容,插槽优先于属性。
vue
<template>
<NsSpace wrap size="large">
<NsStatistic :value="5680" title="今日访问" />
<NsStatistic :value="5680">
<template #title>
<NsSpace size="small" align="center">
<NsIcon name="users" />
<span>今日访客</span>
</NsSpace>
</template>
</NsStatistic>
</NsSpace>
</template>
前缀和后缀
prefix、suffix 传文字;需要图标或带样式的内容时用同名插槽,插槽优先于属性。
vue
<template>
<NsSpace direction="vertical" align="start" size="large">
<NsSpace wrap size="large">
<NsStatistic :value="12345" prefix="¥" title="销售额" />
<NsStatistic :value="98" suffix="%" title="满意度" />
<NsStatistic :value="1024" prefix="共" suffix="人" title="前后缀一起用" />
</NsSpace>
<NsSpace wrap size="large">
<NsStatistic :value="100" title="增长率">
<template #prefix>
<span style="color: var(--ns-color-success)">↑</span>
</template>
<template #suffix>%</template>
</NsStatistic>
<NsStatistic :value="12.5" :precision="1" title="跌幅">
<template #prefix>
<span style="color: var(--ns-color-danger)">↓</span>
</template>
<template #suffix>%</template>
</NsStatistic>
<NsStatistic :value="4.8" :precision="1" suffix="/ 5" title="评分">
<template #prefix>
<NsIcon name="star" color="var(--ns-color-warning)" />
</template>
</NsStatistic>
</NsSpace>
</NsSpace>
</template>
动画
animation 打开后,挂载时数值从 from 滚动到 value,用时 animationDuration 毫秒。之后 value 变化时,从当前显示的值过渡到新值。动画过程中按目标值的小数位数显示(设置了 precision 时按 precision),不会出现一长串小数。动画结束时触发 finish。
vue
<script setup lang="ts">
import { ref } from 'vue'
import { NsStatistic, NsButton, NsSpace } from '@ns/ui'
const value = ref(12345)
const finishCount = ref(0)
</script>
<template>
<NsSpace wrap size="large" align="center">
<NsStatistic
:value="value"
animation
:animation-duration="800"
title="订单数"
@finish="finishCount++"
/>
<NsButton @click="value += 100">加 100</NsButton>
<NsButton @click="value -= 1000">减 1000</NsButton>
</NsSpace>
<p style="margin-top: 12px">finish 触发了 {{ finishCount }} 次</p>
</template>
需要重新播放时,通过 ref 调用 startAnimation(),它总是从 from 开始;stopAnimation() 让数值停在当前显示的值。下面第一个从默认的 0 开始,第二个设了 from 为 90000、带两位小数:
vue
<script setup lang="ts">
import { ref } from 'vue'
import { NsStatistic, NsButton, NsSpace } from '@ns/ui'
import type { StatisticInstance } from '@ns/ui'
const statisticRef = ref<StatisticInstance>()
const fromRef = ref<StatisticInstance>()
const replay = () => {
statisticRef.value?.startAnimation()
fromRef.value?.startAnimation()
}
const stop = () => {
statisticRef.value?.stopAnimation()
fromRef.value?.stopAnimation()
}
</script>
<template>
<NsSpace direction="vertical" align="start" size="large">
<NsSpace wrap size="large">
<NsStatistic ref="statisticRef" :value="100000" animation title="从 0 开始" />
<NsStatistic
ref="fromRef"
:value="100000"
:from="90000"
:precision="2"
prefix="¥"
animation
title="从 90000 开始"
/>
</NsSpace>
<NsSpace wrap>
<NsButton icon="refresh" @click="replay">重新播放</NsButton>
<NsButton @click="stop">停止</NsButton>
</NsSpace>
</NsSpace>
</template>
放在卡片里
几个统计数值常常并排放在卡片里做数据概览:
vue
<template>
<div class="overview">
<NsCard>
<NsStatistic :value="8846" title="今日订单" />
</NsCard>
<NsCard>
<NsStatistic :value="126560.5" :precision="2" prefix="¥" title="今日销售额" />
</NsCard>
<NsCard>
<NsStatistic :value="68.2" :precision="1" suffix="%" title="转化率">
<template #prefix>
<span style="color: var(--ns-color-success)">↑</span>
</template>
</NsStatistic>
</NsCard>
<NsCard>
<NsStatistic value="--" title="退款数" />
</NsCard>
</div>
</template>
<style scoped>
.overview {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(180px, 1fr));
gap: var(--ns-spacing-4);
}
</style>
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| value | number | string | - | 数值。数字字符串按数字格式化,非数字字符串原样显示;NaN、Infinity、空字符串显示为空 |
| title | string | - | 标题 |
| prefix | string | - | 数值前面的文字 |
| suffix | string | - | 数值后面的文字 |
| precision | number | - | 小数位数,四舍五入并补 0。取值 0~20,超出范围时按边界处理,小数向下取整 |
| separator | string | '.' | 小数点分隔符 |
| groupSeparator | string | ',' | 千分位分隔符,传空字符串不分组 |
| animation | boolean | false | 是否开启数值动画 |
| animationDuration | number | 3000 | 动画时长(毫秒) |
| from | number | 0 | 首次动画(挂载时、调用 startAnimation() 时)的起始值;之后 value 变化时从当前值开始过渡 |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| finish | - | 一次动画播放结束时触发;没开 animation 时不触发 |
Slots
| 插槽 | 说明 |
|---|---|
| title | 标题,优先于 title 属性 |
| prefix | 数值前面的内容,优先于 prefix 属性 |
| suffix | 数值后面的内容,优先于 suffix 属性 |
方法
通过组件的 ref 调用。
| 方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
| startAnimation | - | void | 从 from 重新播放一次动画到 value |
| stopAnimation | - | void | 停止动画,显示停在当前值 |
类型
ts
import type { StatisticProps, StatisticInstance } from '@ns/ui'
interface StatisticProps {
value?: number | string
title?: string
prefix?: string
suffix?: string
precision?: number
separator?: string
groupSeparator?: string
animation?: boolean
animationDuration?: number
from?: number
}
interface StatisticInstance {
startAnimation: () => void
stopAnimation: () => void
}
注意事项
- 倒计时请用 NsCountdown,NsStatistic 没有倒计时模式。
- 设置
precision后一定显示固定位数的小数,100配precision: 2显示100.00。四舍五入后为 0 的负数(例如-0.001保留 2 位)显示0.00,不带负号。 separator是小数点分隔符,不是千分位分隔符;千分位用groupSeparator。- 动画用
requestAnimationFrame实现,组件卸载时会自动停止。 - 没有默认插槽,也没有
formatter,显示格式只能通过precision和两个分隔符控制。
优化点
- [ ] 支持更丰富的动画效果(缓动函数可配置)
- [ ] 支持数值范围显示
- [ ] 支持数值单位转换(万、亿)
- [ ] 支持
formatter或默认插槽自定义数值显示