# 统计数值

- 页面: https://jiguang132.com/zh/resources/ant-design/docs/statistic
- 资源: Ant Design (https://jiguang132.com/zh/resources/ant-design.md)
- 全部指南: https://jiguang132.com/zh/resources/ant-design/docs.md

展示统计数值。


## 何时使用 {#when-to-use}

- 当需要突出某个或某组数字时。
- 当需要展示带描述的统计类数据时使用。

## 代码演示 {#examples}


- 基本 · `basic`
- 单位 · `unit`
- 动画效果 · `animated`
- 在卡片中使用 · `card`
- 计时器 · `timer`
- 自定义语义结构的样式和类 · `style-class`


## API

通用属性参考：[通用属性](#jguang-common-props)

#### Statistic

| 参数 | 说明 | 类型 | 默认值 | 版本 | [全局配置](/components/config-provider#component-config) |
| --- | --- | --- | --- | --- | --- |
| classNames | 用于自定义 Statistic 组件内部各语义化结构的 class，支持对象或函数 | Record<[SemanticDOM](#semantic-dom), string> \| (info: { props }) => Record<[SemanticDOM](#semantic-dom), string> | - |  | 6.0.0 |
| decimalSeparator | 设置小数点 | string | `.` |  | × |
| formatter | 自定义数值展示 | (value) => ReactNode | - |  | × |
| groupSeparator | 设置千分位标识符 | string | `,` |  | × |
| loading | 数值是否加载中 | boolean | false | 4.8.0 | × |
| precision | 数值精度 | number | - |  | × |
| prefix | 设置数值的前缀 | ReactNode | - |  | × |
| styles | 用于自定义 Statistic 组件内部各语义化结构的行内 style，支持对象或函数 | Record<[SemanticDOM](#semantic-dom) , CSSProperties> \| (info: { props }) => Record<[SemanticDOM](#semantic-dom) , CSSProperties> | - |  | 6.0.0 |
| suffix | 设置数值的后缀 | ReactNode | - |  | × |
| title | 数值的标题 | ReactNode | - |  | × |
| value | 数值内容 | string \| number | - |  | × |
| ~~valueStyle~~ | 设置数值区域的样式，请使用 `styles.content` 替代 | CSSProperties | - |  | × |

#### Statistic.Countdown <Badge type="error">Deprecated</Badge>

<Antd component="Alert" title="版本 >= 5.25.0 时请使用 Statistic.Timer 作为替代方案。" type="warning" banner="true"></Antd>


| 参数 | 说明 | 类型 | 默认值 | 版本 |
| --- | --- | --- | --- | --- |
| format | 格式化倒计时展示，参考 [dayjs](https://day.js.org/) | string | `HH:mm:ss` |  |
| prefix | 设置数值的前缀 | ReactNode | - |  |
| suffix | 设置数值的后缀 | ReactNode | - |  |
| title | 数值的标题 | ReactNode | - |  |
| value | 数值内容 | number | - |  |
| valueStyle | 设置数值区域的样式 | CSSProperties | - |  |
| onFinish | 倒计时完成时触发 | () => void | - |  |
| onChange | 倒计时时间变化时触发 | (value: number) => void | - | - |

#### Statistic.Timer <Badge>5.25.0+</Badge>

| 参数 | 说明 | 类型 | 默认值 | 版本 |
| --- | --- | --- | --- | --- |
| type | 计时类型，倒计时或者正计时 | `countdown` \| `countup` | - |  |
| format | 格式化倒计时展示，参考 [dayjs](https://day.js.org/) | string | `HH:mm:ss` |  |
| prefix | 设置数值的前缀 | ReactNode | - |  |
| suffix | 设置数值的后缀 | ReactNode | - |  |
| title | 数值的标题 | ReactNode | - |  |
| value | `countdown` 模式下为目标时间，`countup` 模式下为起始时间（毫秒时间戳） | number | - |  |
| valueStyle | 设置数值区域的样式 | CSSProperties | - |  |
| onFinish | 倒计时完成时触发，指定为 `countup` 时此属性不生效 | () => void | - |  |
| onChange | 倒计时时间变化时触发 | (value: number) => void | - |  |

## Semantic DOM

Statistic 提供 `root`、`header`、`title`、`content`、`value`、`prefix` 和 `suffix` 语义化 DOM 节点。

| 语义节点 | 原生说明 | 版本 |
| --- | --- | --- |
| `root` | 根元素，包含统计数值组件的重置样式和整体容器样式 | 6.0.0 |
| `header` | 头部元素，包含下内边距和标题区域的布局样式 | 6.0.0 |
| `title` | 标题元素，包含文字颜色、字体大小等标题文字的显示样式 | 6.0.0 |
| `prefix` | 前缀元素，包含行内块显示、右外边距等前缀内容的布局样式 | 6.0.0 |
| `content` | 内容元素，包含前缀、数值、后缀的布局和对齐等内容区域样式 | 6.0.0 |
| `value` | 数值元素，包含文字颜色、字体大小、字体族等统计数值的展示样式 | 6.4.0 |
| `suffix` | 后缀元素，包含行内块显示、左外边距等后缀内容的布局样式 | 6.0.0 |

语义说明来源: `vendor/components/statistic/demo/_semantic.tsx`

## 主题变量（Design Token）{#design-token}

类型、继承关系和原生令牌声明保持固定源码原文；默认值由原生主题计算，并可能受 ConfigProvider 覆盖。本表不伪造静态默认值。

| 令牌 | 类型 | 原生说明 |
| --- | --- | --- |
| `titleFontSize` | `number` | 标题字体大小 |
| `contentFontSize` | `number \| string` | 内容字体大小 |

声明来源: `vendor/components/statistic/style/index.ts`

```ts
import type { CSSObject } from '@ant-design/cssinjs';

import { resetComponent } from '../../style';

import type { FullToken, GenerateStyle, GetDefaultToken } from '../../theme/internal';

import { genStyleHooks, mergeToken } from '../../theme/internal';

export interface ComponentToken {
  /**
   * @desc 标题字体大小
   * @descEN Title font size
   */
  titleFontSize: number;
  /**
   * @desc 内容字体大小
   * @descEN Content font size
   */
  contentFontSize: number | string;
}

interface StatisticToken extends FullToken<'Statistic'> {}
```


## 原生通用属性 {#jguang-common-props}


> Tips: 以下通用属性适用于 antd 大部分组件，不支持的组件会单独说明。

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| style | 自定义样式 | CSSProperties | - |
| className | 自定义类名 | string | - |
| rootClassName | 添加在组件最外层的 className | string | - |
| autoFocus | 自动获取焦点，仅对表单类、链接、交互容器等可聚焦元素生效 | boolean | false |


## 安装并复现示例

```bash
npm install antd@6.6.5 @ant-design/icons@6.3.4 dayjs@1.11.23
```

使用 ConfigProvider 和原生 App，并单独配置 dayjs 语言。每个示例在查看代码中列出完整源码文件和额外固定依赖。示例名称用于选择演示，不是组件通用属性。主题、语言与 SSR 初始化见资源安装指南。

## 原生类型参考

源码查看器包含未修改的原生实现和以下声明文件，继承类型仍位于原生包中。代码中的英文注释保留为源码参考。

- `vendor/components/statistic/Countdown.tsx`
- `vendor/components/statistic/Number.tsx`
- `vendor/components/statistic/Statistic.tsx`
- `vendor/components/statistic/Timer.tsx`
- `vendor/components/statistic/index.tsx`
- `vendor/components/statistic/style/index.ts`
- `vendor/components/statistic/utils.ts`

## 来源与许可

https://github.com/ant-design/ant-design/tree/4a39f54842eade4e565ab336ef6097cd7e723cdd

保留原生中英文正文与可执行示例；官网专用的嵌入章节和令牌表格在本地展开。Ant Design 使用 MIT 许可，另列依赖的许可证也需保留。上传预览禁止向外发起请求，不提供后端服务。

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt