Ant Design Statistic 统计数值组件完全指南格式化、倒计时与源码级实现原理【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design导读Statistic统计数值是 Ant Design 中专门用于展示单个或一组关键数字的数据展示组件常见于数据看板、运营后台的指标卡、Dashboard 顶部统计条等场景。它内置了千分位分组、小数精度、自定义前缀/后缀、加载态骨架屏等能力并附带Statistic.Countdown倒计时子组件可用于活动开抢、考试倒计时、任务截止提醒等场景。本文以 components/statistic/index.zh-CN.md 为骨架结合其源码实现Statistic.tsx、Number.tsx、Countdown.tsx、utils.ts与单元测试完整讲解每个 API 的实际行为与底层格式化算法帮助你从会用进阶到懂原理、能排查、可定制。何时使用按照官方文档的定义Statistic 适用于两类典型场景突出展示数字当页面需要让某个或某组数字成为视觉焦点时如今日订单量 12,345用 Statistic 可以在排版、字号、色彩上直接突出数值本体。带描述的统计类数据需要标题 数值 单位/前后缀结构化展示统计信息时Statistic 提供了固定的标题区title与数值区content分层天然适合指标卡布局。基本用法与 Statistic API 详解Statistic 本身是一个展示型组件核心 API 在 Statistic.tsx 的StatisticReactProps接口中定义。官方 API 表格如下字段与文档一致参数说明类型默认值版本decimalSeparator设置小数点string.formatter自定义数值展示(value) ReactNode-groupSeparator设置千分位标识符string,loading数值是否加载中booleanfalse4.8.0precision数值精度number-prefix设置数值的前缀ReactNode-suffix设置数值的后缀ReactNode-title数值的标题ReactNode-value数值内容string | number-valueStyle设置数值区域的样式CSSProperties-从源码看除了表格列出的属性StatisticProps还扩展了HTMLAriaDataAttributes支持aria-*与data-*透传到根节点见 aria-data-attrs.ts同时它还接受prefixCls、className、rootClassName、style、valueRender、onMouseEnter、onMouseLeave等通用属性。一个最基础的使用示例来源于 demo/basic.tsximport { Button, Col, Row, Statistic } from antd; const App: React.FC () ( Row gutter{16} Col span{12} Statistic titleActive Users value{112893} / /Col Col span{12} Statistic titleAccount Balance (CNY) value{112893} precision{2} / Button style{{ marginTop: 16 }} typeprimary Recharge /Button /Col Col span{12} Statistic titleActive Users value{112893} loading / /Col /Row ); export default App;value字符串与数字的兼容value的类型是string | number。从 utils.ts 中可以看到它被定义为export type valueType number | string。组件内部默认value 0即不传时显示 0。测试 index.test.tsx 验证了两种非数字边界value-直接原样渲染出-valuebamboo直接渲染字符串bamboo。也就是说非法数字不会报错而是按原字符串透传展示这一行为由 Number.tsx 中的正则校验兜底。title / valueStyle结构化的展示层级title渲染在${prefixCls}-title节点valueStyle作用于${prefixCls}-content数值内容容器见 Statistic.tsx。在指标卡场景中常用valueStyle配合前缀/后缀箭头表达涨跌语义参见 demo/card.tsxCard bordered{false} Statistic titleActive value{11.28} precision{2} valueStyle{{ color: #3f8600 }} prefix{ArrowUpOutlined /} suffix% / /Card Card bordered{false} Statistic titleIdle value{9.3} precision{2} valueStyle{{ color: #cf1322 }} prefix{ArrowDownOutlined /} suffix% / /Card涨绿跌红是金融看板最常见的语义化配色Statistic 通过valueStyle直接控制数值颜色即可实现无需额外的样式覆写。数值格式化原理千分位、小数与精度是如何算出来的这是 Statistic 最有技术含量的一部分。当不传formatter时数值格式化由 Number.tsx 内部的默认逻辑完成核心是一段正则const cells val.match(/^(-?)(\d*)(\.(\d))?$/);如果匹配失败非数字则原样输出字符串匹配成功则拆分为符号、整数部分、小数部分三个分组依次处理千分位分组对整数部分执行int.replace(/\B(?(\d{3})(?!\d))/g, groupSeparator)即从右向左每三位插入一个groupSeparator。默认是,可替换为空格、下划线甚至任意字符串——测试 index.test.tsx 就用groupSeparator__TEST__验证了1128被格式化为1__TEST__128。精度处理当precision为数字时对小数部分执行decimal.padEnd(precision, 0).slice(0, precision)不足补零、超出截断实现保留指定位数小数precision支持负数负数时小数部分被完全截断-1112893.1212配precision{-1}显示为-1,112,893同样有测试用例覆盖。符号与小数点负号单独保留在整数 span 中小数部分拼接decimalSeparator后输出。整数部分与小数部分分别渲染为.ant-statistic-content-value-int与.ant-statistic-content-value-decimal两个 span方便后续按需定制样式例如小数部分用更浅的颜色。从样式文件 style/index.ts 可以看到.ant-statistic-content-value被设置了direction: ltr这意味着即使页面处于 RTL 方向数字本身依然按从左到右阅读避免阿拉伯文/希伯来文环境下数字被镜像排版——这是组件层面一个很细节的国际化处理。自定义 formatter接管数值渲染实现数字滚动动画当内置格式化无法满足需求时formatter允许你完全接管数值节点的渲染签名是(value) ReactNode。官方演示 demo/animated.tsx 展示了如何借助react-countup实现数字滚动动画import CountUp from react-countup; import type { StatisticProps } from antd; const formatter: StatisticProps[formatter] (value) ( CountUp end{value as number} separator, / ); Statistic titleActive Users value{112893} formatter{formatter} /在源码层面Number.tsx 中typeof formatter function时直接valueNode formatter(value)绕开所有内置格式化逻辑。因此 formatter 拥有绝对控制权不仅可以做动画也可以拼接富文本节点、图标甚至任意 ReactNode。需要注意的是formatter 与precision、groupSeparator是互斥的——一旦传入 formatter后两者不再生效因为默认格式算法被整体替换。Countdown 内部也正是利用了这一机制它把自定义的倒计时格式化函数作为formatter传入 Statistic见 Countdown.tsx。prefix / suffix单位与前后缀的排版细节prefix与suffix分别渲染在数值前后的独立 span 中。官方演示 demo/unit.tsxStatistic titleFeedback value{1128} prefix{LikeOutlined /} / Statistic titleUnmerged value{93} suffix/ 100 /从源码看prefix 渲染为${prefixCls}-content-prefixsuffix 渲染为${prefixCls}-content-suffixStatistic.tsx。样式上二者都是inline-block且通过marginInlineEnd: marginXXS与marginInlineStart: marginXXS与数值保持间距。注意这里用的是逻辑属性marginInlineEnd/Start在 RTL 下会自动镜像保证布局方向正确。loading 加载态内置 Skeleton 骨架屏loading属性自 4.8.0 引入用于数据异步获取时的骨架屏占位。实现上 Statistic 复用了 Skeleton 组件渲染时用Skeleton paragraph{false} loading{loading}包裹数值内容Statistic.tsx并额外给骨架屏加了${prefixCls}-skeleton类与paddingTop: padding的间距样式。对应测试index.test.tsx验证loadingtrue时渲染出.ant-skeleton节点且数值内容.ant-statistic-content不渲染loadingfalse时骨架屏消失、数值正常展示。标题title在加载中依然保留符合指标卡标题常驻、数值占位的常见交互。Statistic.Countdown 倒计时组件API 一览Statistic.Countdown是挂载在 Statistic 上的复合子组件见 index.tsx 中的(Statistic as CompoundedStatistic).Countdown CountdownAPI 表格与官方文档一致参数说明类型默认值版本format格式化倒计时展示参考 dayjsstringHH:mm:ssprefix设置数值的前缀ReactNode-suffix设置数值的后缀ReactNode-title数值的标题ReactNode-value数值内容number-valueStyle设置数值区域的样式CSSProperties-onFinish倒计时完成时触发() void-onChange倒计时时间变化时触发(value: number) void-4.16.0定时刷新与生命周期Countdown 的实现Countdown.tsx相当精巧它通过setInterval每1000 / 30毫秒约 33ms即 30fps触发一次forceUpdate驱动数值以接近动画级的流畅度刷新每 tick 会调用onChange?.(timestamp - Date.now())上报剩余毫秒数因此onChange在倒计时进行中会被高频触发适合在外部同步显示剩余 xx 秒之类的文案当剩余时间小于当前时间时调用stopTimer()触发onFinish并清理定时器React.useEffect以value为依赖目标时间变化时重建定时器卸载时清理定时器避免内存泄漏若传入的value时间戳已经早于当前时间倒计时已过期syncTimer中的timestamp Date.now()判断会直接跳过不启动定时器、不触发onFinish——测试 index.test.tsx 专门验证了时间已过不回调与正常结束触发 onFinish两个分支。format 格式串与底层格式化算法format默认HH:mm:ss语义参考 dayjs 的时间格式。但注意它并不是真正调用 dayjs 来格式化而是在 utils.ts 中用formatTimeStr自己实现的模板替换算法const timeUnits: [string, number][] [ [Y, 1000 * 60 * 60 * 24 * 365], // 年 [M, 1000 * 60 * 60 * 24 * 30], // 月近似 30 天 [D, 1000 * 60 * 60 * 24], // 天 [H, 1000 * 60 * 60], // 时 [m, 1000 * 60], // 分 [s, 1000], // 秒 [S, 1], // 毫秒 ];算法要点按Y/M/D/H/m/s/S的优先级依次把剩余时长整除出对应单位的值并从总量中扣除模板中连续的同名字母会被替换为对应数值并用padStart(len, 0)按字母个数补零——这就是H不补零与HH补零到两位的区别HH:mm:ss:SSS会输出到毫秒支持[文本]转义D [天] H [时]中的[天]、[时]会被保留为字面文本。测试用例验证了formatTimeStr(1000 * 60 * 60 * 24, D [Day])返回1 Day。因此formatD 天 H 时 m 分 s 秒可以输出2 天 11 时 28 分 09 秒这样的中文倒计时见 demo/countdown.tsx。官方演示还展示了const deadline Date.now() 1000 * 60 * 60 * 24 * 2 1000 * 30; // 2 天 30 秒后 Countdown titleCountdown value{deadline} onFinish{onFinish} / Countdown titleMillion Seconds value{deadline} formatHH:mm:ss:SSS / Countdown titleDay Level value{deadline} formatD 天 H 时 m 分 s 秒 / Countdown titleCountdown value{Date.now() 10 * 1000} onChange{onChange} /value除了时间戳毫秒数也兼容可被new Date(value)解析的时间字符串测试中使用了 dayjs 对象的toISOString()结果getTime统一将其转为毫秒时间戳。主题变量Design Token定制Statistic 支持通过ConfigProvider的主题 token 体系进行定制。当前版本的组件级 token 定义在 style/index.ts 中Token说明默认值来源titleFontSize标题字体大小fontSizecontentFontSize内容数值字体大小fontSizeHeading3官方演示 demo/component-token.tsx 展示了用法ConfigProvider theme{{ components: { Statistic: { titleFontSize: 20, contentFontSize: 20, }, }, }} {/* Statistic 组件树 */} /ConfigProvider从样式生成逻辑看标题默认使用colorTextDescription次要文字色与titleFontSize数值默认使用colorTextHeading标题文字色与contentFontSize且数值字体走全局fontFamily。token 定义文件同时被 components/theme/interface/components.ts 引用纳入整个 antd 主题系统的ComponentToken联合类型可与其他组件的 token 一起集中配置。更多源码细节与验证RTL 支持direction rtl时根节点会追加${prefixCls}-rtl类测试通过rtlTest(Statistic)统一验证无障碍透传aria-*与data-*属性会通过pickAttrs提取后透传到根div测试中验证了data-abc、aria-label、role均能正确落位index.test.tsx交互事件onMouseEnter/onMouseLeave绑定在根节点Statistic 与 Countdown 均支持组件挂载Statistic.Countdown直接挂载在Statistic上作为静态属性无需额外 import演示与测试资产完整 demo 位于 components/statistic/demobasic、unit、animated、card、countdown、component-token 六个示例对应快照测试与行为测试位于 components/statistic/tests是理解组件行为边界的第一手资料。综上Statistic 虽然是一个小而美的展示组件但其内部的正则数值拆分、模板化倒计时格式串、30fps 定时刷新、Skeleton 加载态以及 Design Token 定制覆盖了数据展示场景中从格式化到异步加载再到主题适配的完整链路。理解这些实现细节后你既可以在日常开发中精准选用 API也可以在遇到千分位异常、精度截断或倒计时格式问题时快速定位到根因。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考