前端UI组件设计系统【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址https://gitcode.com/gh_mirrors/ant/ant-design点击查看免费下载导读Statistic是 Ant Designant-design中用于展示统计数字的轻量级数据展示组件它解决的核心问题是如何把一组原始数字以专业、一致、可读的方式呈现在页面上。本文基于官方英文文档components/statistic/index.en-US.md结合仓库内真实源码Statistic.tsx、Countdown.tsx、Number.tsx、utils.ts与官方示例demo完整覆盖 Statistic 的全部 API 参数、数值格式化原理、loading 占位、Statistic.Countdown倒计时子组件的实现机制以及通过 Design Token 定制组件样式的方法。读完本文你将能熟练地在业务中展示带千分位、小数精度、前后缀修饰的统计数字并实现毫秒级刷新的倒计时。何时使用When To Use官方文档给出了两个典型的使用场景当你想突出展示某些数据时When want to highlight some data例如首页仪表盘中的今日活跃用户订单总额等核心指标当你想展示带有描述性说明的统计数据时When want to display statistic data with description例如账户余额CNY、未合并 PR/ 100这类数值 说明文案的组合展示。从组件定位上看Statistic 属于Data Display数据展示分组它本身不负责取数、不做动画、不管理异步状态只专注把一个值渲染成一个统计数字区块。与Card、Descriptions等组件组合使用即可搭建出常见的数据卡片详见官方示例 card.tsx。快速上手两个基础示例基础用法Basic官方第一个示例basic.tsx展示了 Statistic 的最小可用形态import React from react; import { 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;这个示例同时覆盖了三个核心用法直接展示数值、用precision{2}保留两位小数、用loading在数据未就绪时显示骨架屏占位。其中loading的实现非常巧妙——在源码 Statistic.tsx 中数值内容整体被包在Skeleton paragraph{false} loading{loading}内因此加载态复用的是 Ant Design 自身Skeleton组件的能力开发者无需额外引入占位逻辑。单位与前缀后缀Unit官方第二个示例unit.tsx演示了prefix与suffix的用法import React from react; import { LikeOutlined } from ant-design/icons; import { Col, Row, Statistic } from antd; const App: React.FC () ( Row gutter{16} Col span{12} Statistic titleFeedback value{1128} prefix{LikeOutlined /} / /Col Col span{12} Statistic titleUnmerged value{93} suffix/ 100 / /Col /Row ); export default App;prefix常用于放图标如ant-design/icons中的LikeOutlinedsuffix常用于放单位如%、/ 100。在源码渲染层面前缀和后缀分别被包裹在statistic-content-prefix与statistic-content-suffix两个 span 中Statistic.tsx并各自拥有marginInlineEnd/marginInlineStart的间距见样式源码 style/index.tsRTL 场景下间距会自动镜像无需额外适配。API 全解析Statistic官方文档为Statistic定义了以下属性均需继承 Common props 中的通用属性PropertyDescriptionTypeDefaultVersiondecimalSeparator小数点符号string.formatter自定义数值展示逻辑(value) ReactNode-groupSeparator千分位分组符号string,loadingStatistic 的加载状态booleanfalse4.8.0precision输入数值的精度小数位数number-prefix数值前缀节点ReactNode-suffix数值后缀节点ReactNode-title展示标题ReactNode-value展示的数值string | number-valueStyle设置数值区域的样式CSSProperties-formatter 自定义格式化formatter是最灵活的扩展点类型为(value) ReactNode即传入原始值、返回任意 ReactNode。从源码 Number.tsx 可以看到内部实现逻辑只要formatter是函数就直接采用函数返回值作为数值节点跳过内置的格式化流程。这意味着你可以用 formatter 接入任何第三方动画库如react-countup、自定义千分位规则甚至渲染一个组件。官方动画示例animated.tsx就是通过 formatter 接入react-countup实现数字滚动动画的import React from react; import type { StatisticProps } from antd; import { Col, Row, Statistic } from antd; import CountUp from react-countup; const formatter: StatisticProps[formatter] (value) ( CountUp end{value as number} separator, / ); const App: React.FC () ( Row gutter{16} Col span{12} Statistic titleActive Users value{112893} formatter{formatter} / /Col Col span{12} Statistic titleAccount Balance (CNY) value{112893} precision{2} formatter{formatter} / /Col /Row ); export default App;内置数值格式化原理当不传formatter时组件走内置格式化流程Number.tsx其步骤可以概括为正则拆分用/^(-?)(\d*)(\.(\d))?$/把value拆成符号、整数部分、小数部分三段如果匹配失败如非法数值、单独的-则原样输出字符串保证组件对脏数据不抛错。千分位分组用int.replace(/\B(?(\d{3})(?!\d))/g, groupSeparator)在整数部分插入groupSeparator默认,所以112893会渲染为112,893。精度补位当precision是数字时对小数部分执行decimal.padEnd(precision, 0).slice(0, precision)Number.tsx不足位补0、超出位截断实现四舍五入以外的补零/截断效果最终拼接decimalSeparator默认.作为小数点。分块渲染整数部分与小数部分分别渲染为带statistic-content-value-int与statistic-content-value-decimal类名的 spanNumber.tsx因此 CSS 可以对整数和小数分别做样式定制比如小数部分字号调小。注意样式源码中statistic-content-value设置了direction: ltrstyle/index.ts保证阿拉伯语、希伯来语等 RTL 环境下数字本身仍按左到右阅读。valueStyle 与 valueRendervalueStyle直接透传到数值容器 div 的style上Statistic.tsx最常见的用途是改颜色、字号或加粗。官方卡片示例card.tsx中用它实现涨绿跌红Card 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此外源码还额外暴露了未写入官方表格的两个属性valueRender?: (node) ReactNode用于包裹/替换数值节点倒计时内部即用它去掉 title 属性见下文以及onMouseEnter/onMouseLeave鼠标事件这些属于内部扩展能力日常使用以官方表格为准。Statistic.Countdown 倒计时Statistic通过复合组件模式挂载了子组件Countdownindex.tsx 中的(Statistic as CompoundedStatistic).Countdown Countdown;因此使用方式是Statistic.Countdown ...或const { Countdown } Statistic;。官方 API 表格如下PropertyDescriptionTypeDefaultVersionformat格式遵循 dayjs 风格stringHH:mm:ssprefix数值前缀节点ReactNode-suffix数值后缀节点ReactNode-title展示标题ReactNode-value目标倒计时截止时间number-valueStyle设置数值区域样式CSSProperties-onFinish时间归零时触发() void-onChange时间变化时触发(value: number) void-4.16.0倒计时实现机制从源码 Countdown.tsx 可以完整还原它的工作原理刷新频率const REFRESH_INTERVAL 1000 / 30;约 33ms即每秒刷新约 30 次。这就是为什么倒计时能显示毫秒级变化——配合formatHH:mm:ss:SSS即可看到毫秒跳动。定时器逻辑syncTimer中先比较getTime(value)截止时间戳与Date.now()只有当截止时间在未来时才启动setInterval每个 tick 内执行forceUpdate()强制重渲染并回调onChange?.(timestamp - Date.now())一旦timestamp Date.now()立即调用stopTimer()清除定时器并回调onFinish?.()Countdown.tsx。依赖重跑useEffect以[value]为依赖value变化时会重建定时器并在卸载时清理避免内存泄漏Countdown.tsx。格式化逻辑Countdown 注入自己的formatter内部调用utils.ts中的formatCountdown先计算Math.max(target - Date.now(), 0)的剩余毫秒再交给formatTimeStr按Y/M/D/H/m/s/S七级时间单位逐级取整utils.ts。值得说明的是倒计时实际上并不依赖 dayjs 运行时format只是借用 dayjs 的格式符号约定Y年、M月、D天、H时、m分、s秒、S毫秒并用padStart按模板中字母重复次数补零如HH补足两位。转义能力formatTimeStr支持[方括号]转义——方括号内的文本会被提取出来原样保留不会当作格式符[utils.ts](https://link.gitcode.com/i/193018859011ae848803961b7fd4fa73#L38-L40, L54-L59)因此可以写出D 天 H 时 m 分 s 秒这类混合中文的格式。倒计时示例官方示例countdown.tsx演示了截止时间、毫秒格式、中文格式与回调的组合import React from react; import type { CountdownProps } from antd; import { Col, Row, Statistic } from antd; const { Countdown } Statistic; const deadline Date.now() 1000 * 60 * 60 * 24 * 2 1000 * 30; // 也支持传 dayjs 对象 const onFinish: CountdownProps[onFinish] () { console.log(finished!); }; const onChange: CountdownProps[onChange] (val) { if (typeof val number 4.95 * 1000 val val 5 * 1000) { console.log(changed!); } }; const App: React.FC () ( Row gutter{16} Col span{12} Countdown titleCountdown value{deadline} onFinish{onFinish} / /Col Col span{12} Countdown titleMillion Seconds value{deadline} formatHH:mm:ss:SSS / /Col Col span{24} style{{ marginTop: 32 }} Countdown titleDay Level value{deadline} formatD 天 H 时 m 分 s 秒 / /Col Col span{12} Countdown titleCountdown value{Date.now() 10 * 1000} onChange{onChange} / /Col /Row ); export default App;示例中的注释 Dayjs is also OK 提示value除了传时间戳数字也可以传 dayjs 对象getTime会经new Date(value).getTime()统一转成毫秒时间戳见 Countdown.tsx。onChange的回调参数是剩余毫秒数timestamp - Date.now()示例中借此在剩余 5 秒附近打印日志可用于倒计时即将结束的预警交互。通过 Design Token 定制样式Statistic 的样式由 cssinjs 驱动style/index.ts组件暴露了 2 个 Component TokenToken说明默认值来源titleFontSize标题字体大小全局fontSizecontentFontSize数值内容字体大小全局fontSizeHeading3默认值在prepareComponentToken中定义style/index.ts标题沿用正文fontSize数值内容则放大到三级标题字号fontSizeHeading3这正是数值比标题更醒目视觉层次的技术来源。自定义方式是在ConfigProvider的theme.components.Statistic中覆盖 token。官方调试示例component-token.tsx演示如下import React from react; import { Button, Col, ConfigProvider, Row, Statistic } from antd; const App: React.FC () ( ConfigProvider theme{{ components: { Statistic: { titleFontSize: 20, contentFontSize: 20, }, }, }} Row gutter{16} Col span{12} Statistic titleActive Users value{112893} / /Col {/* ...其他 Statistic 实例... */} /Row /ConfigProvider ); export default App;同时样式源码中的关键视觉规则还包括标题使用描述色colorTextDescription并带marginBottom: marginXXS数值使用标题色colorTextHeading且使用全局fontFamilystyle/index.ts——这意味着修改全局主题色即可同步影响 Statistic无需单独配置。使用建议与注意事项综合官方文档、源码与示例给出以下实战建议数据未就绪务必用loadingStatistic 在loading为 true 时渲染无段落的 Skeleton 占位Statistic.tsx避免接口返回前出现0或闪烁该属性自 4.8.0 起可用。格式化优先用内置能力千分位groupSeparator、小数位precision、小数点符号decimalSeparator三件套足以覆盖绝大多数数字展示需求只有需要动画或完全自定义渲染时才动用formatter。倒计时value传未来时间戳value表示截止时刻而非剩余时长如果传入的时间已过期syncTimer判定timestamp Date.now()不成立定时器根本不会启动Countdown.tsx页面会静止显示00:00:00。善用onChange做临界态onChange每秒回调约 30 次适合在剩余时间进入某阈值如 5 秒时高亮提醒最终归零只触发一次onFinish两者职责互补。组合布局Statistic 常与Card、Row/Col组合成指标卡片官方示例 card.tsx 提供了可直接套用的涨绿跌红模板。扩展阅读组件官方文档中/英components/statistic/index.en-US.md、components/statistic/index.zh-CN.md组件核心实现Statistic.tsx、Number.tsx、Countdown.tsx、utils.ts组件入口与类型导出components/statistic/index.tsx样式与 Token 定义components/statistic/style/index.ts官方全部示例components/statistic/demobasic / unit / animated / card / countdown / component-token主题定制总入口components/config-provider/index.tsx赞分享前端UI组件设计系统【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址https://gitcode.com/gh_mirrors/ant/ant-design点击查看免费下载相关推荐Ant Design Statistic 组件完全指南数字统计、格式化与倒计时/计时器实战Ant Design Statistic 组件完全指南数字统计、格式化与倒计时/计时器实战 Statistic统计数值是 Ant Design 中用于突前端UI组件设计系统Ant Design Statistic 组件完全指南统计数值、倒计时/正计时与语义化定制Ant Design Statistic 组件完全指南统计数值、倒计时/正计时与语义化定制 导读本文以 components/statistic/index前端UI组件设计系统Element UI 的 Statistic 统计数值组件数值格式化与倒计时实战指南Element UI 的 Statistic 统计数值组件数值格式化与倒计时实战指南 本指南以 Element UIVue.js 2.0 UI Toolki前端UI组件设计系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考