> Leaf UI 0.8.1 · Package: @ifhover/leaf-ui · Source: 435bab23cad7d343653d9b63b049c0b0601eeefb
> Browser documentation: https://ifhover.github.io/leaf-ui/components/statistic.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt.

# Statistic 统计数值

展示指标数值和倒计时。数字首次显示时默认从 0 递增或递减到目标值，后续变化从当前显示值平滑过渡到新目标。

## 基础用法


总收入

¥12,856.80

增长率

12.5%

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/statistic/basic.tsx"
import { Space, Statistic } from '@ifhover/leaf-ui';

import { ArrowUp } from 'lucide-react';

export function StatisticBasic() {
  return (
    <Space size={32} wrap>
      <Statistic title={'总收入'} value={12856.8} precision={2} prefix="¥" />
      <Statistic
        title={'增长率'}
        value={12.5}
        precision={1}
        prefix={<ArrowUp size={20} />}
        suffix="%"
      />
    </Space>
  );
}
```

展开代码

## 数值动画

使用 `initialValue` 设置首次动画的起点，默认动画时长为 1000 毫秒，可通过 `duration` 调整。连续点击增加或减少时，动画从当前显示值继续；点击重播会重新挂载示例，从 1,000 开始。


收入

¥1,286.50

增加减少从 1,000 重播

animation.tsx

复制代码

```tsx lineNumbers file="../../src/examples/statistic/animation.tsx"
import { Button, Space, Statistic } from '@ifhover/leaf-ui';

import { useState } from 'react';

export function StatisticAnimation() {
  const [value, setValue] = useState(1286.5);
  const [replay, setReplay] = useState(0);
  return (
    <Space direction="vertical" size={20}>
      <Statistic
        key={replay}
        title={'收入'}
        value={value}
        initialValue={1000}
        precision={2}
        prefix="¥"
      />
      <Space wrap>
        <Button onClick={() => setValue((current) => current + 500)}>
          {'增加'}
        </Button>
        <Button variant="outline" onClick={() => setValue((current) => current - 500)}>
          {'减少'}
        </Button>
        <Button variant="outline" onClick={() => setReplay((current) => current + 1)}>
          {'从 1,000 重播'}
        </Button>
      </Space>
    </Space>
  );
}
```

展开代码

设置 `animation={false}` 或 `duration={0}` 可立即显示目标值。动画遵循区域动效速度、`ConfigProvider` 的 `theme.motion` 和系统减少动态效果偏好。`loading` 结束后才开始动画；仅有限的 `number` 值参与动画，字符串和非有限数值直接展示，`formatter` 会接收动画中的数值。服务端先输出目标值，客户端挂载后开始动画。倒计时保持即时更新。

## 倒计时


距离活动开始

01:00:00

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/statistic/basic.tsx"
import { Countdown } from '@ifhover/leaf-ui';

import { useState } from 'react';

export function StatisticCountdown() {
  const [deadline] = useState(() => Date.now() + 3600000);
  return <Countdown title={'距离活动开始'} value={deadline} />;
}
```

展开代码

## Statistic API

| 属性             | 类型                                       | 默认值    | 说明                                   |
| -------------- | ---------------------------------------- | ------ | ------------------------------------ |
| `title`        | `ReactNode`                              | —      | 标题内容。                                |
| `value`        | `number \| string`                       | —      | 必需。受控值。                              |
| `precision`    | `number`                                 | —      | 小数位数。                                |
| `grouping`     | `boolean`                                | `true` | 启用本地化数字分组。                           |
| `prefix`       | `ReactNode`                              | —      | 前置内容。                                |
| `suffix`       | `ReactNode`                              | —      | 后置内容。                                |
| `formatter`    | `(value: number \| string) => ReactNode` | —      | 自定义指标数值的展示。                          |
| `loading`      | `boolean`                                | —      | 展示加载状态。                              |
| `animation`    | `boolean`                                | `true` | 启用数值变化动画。                            |
| `initialValue` | `number`                                 | `0`    | 首次动画的起始值，后续变化从当前显示值开始。               |
| `duration`     | `number`                                 | `1000` | 默认动效速度下的动画时长（毫秒），随区域动效时长缩放；0 表示立即更新。 |

## Countdown API

| 属性                 | 类型                            | 默认值          | 说明                                |
| ------------------ | ----------------------------- | ------------ | --------------------------------- |
| `title`            | `ReactNode`                   | —            | 标题内容。                             |
| `prefix`           | `ReactNode`                   | —            | 前置内容。                             |
| `suffix`           | `ReactNode`                   | —            | 后置内容。                             |
| `loading`          | `boolean`                     | —            | 展示加载状态。                           |
| `value`            | `number \| Date`              | —            | 必需。截止时间的 Date 或毫秒时间戳。             |
| `format`           | `string`                      | `'HH:mm:ss'` | DD、HH、mm、ss、SSS 格式，其中 HH 可展示累计小时。 |
| `onFinish`         | `() => void`                  | —            | 完成时调用一次。                          |
| `onChange`         | `(remaining: number) => void` | —            | 值发生变化时调用。                         |
| `initialRemaining` | `number`                      | —            | SSR 首屏使用的剩余毫秒数，客户端挂载后按截止时间更新。     |

## 类型与交互

组装可复用配置时，可导入对应的属性和数据类型。

```ts
import type { StatisticProps, CountdownProps } from '@ifhover/leaf-ui';
```

为仅展示图标的操作提供可访问名称。交互控件支持键盘操作，并跟随 ConfigProvider 的主题和减少动画设置。