前端UI组件设计系统【免费下载链接】ant-design-vue An enterprise-class UI components based on Ant Design and Vue. 项目地址https://gitcode.com/gh_mirrors/an/ant-design-vue点击查看免费下载Statistic 是 ant-design-vue 中用于“展示统计数值”的数据展示组件核心场景包括高亮关键数据如用户数、账户余额以及为数据附加标题、前后缀等描述信息。本文以 components/statistic/index.en-US.md 为骨架结合仓库内 Statistic.tsx、Countdown.tsx、Number.tsx、utils.ts 等源码与测试用例完整讲解 Statistic 的 API 参数、数字格式化原理、倒计时实现机制并给出可复制的实战示例。组件定位与适用场景Statistic统计数值是一个轻量的数据展示组件不承载交互逻辑只负责把“一个数值 一段描述”以清晰、美观的方式渲染出来。官方文档给出的适用场景非常聚焦当你想高亮展示某个数据时例如页面顶部的核心指标当你需要用文字描述来辅助解释统计数据时例如“今日新增用户”配上具体数字。在 ant-design-vue 中Statistic 通过两种形态对外提供能力Statistic普通统计数值和Statistic.Countdown倒计时。两者的注册与导出定义在 components/statistic/index.tsStatistic.Countdown Countdown; Statistic.install function (app: App) { app.component(Statistic.name, Statistic); app.component(Statistic.Countdown.name, Statistic.Countdown); return app; };因此你可以通过a-statistic与a-statistic-countdown两个全局组件名直接使用也可以import Statistic from ant-design-vue/es/statistic按需引入。Statistic 基础 API 全表以下为官方文档 components/statistic/index.en-US.md 中的完整属性表结合 Statistic.tsx 中的statisticProps()定义做了补充说明属性说明类型默认值decimalSeparator小数点分隔符string.formatter自定义数值显示逻辑v-slot | ({value}) VNode-groupSeparator千分位分组分隔符string,precision数值精度小数位数number-prefix数值的前缀节点string | v-slot-suffix数值的后缀节点string | v-slot-title展示的标题string | v-slot-value展示的数值string | number-valueStyle设置数值的 CSS 样式style-源码中的默认值定义于 Statistic.tsxprops: initDefaultProps(statisticProps(), { decimalSeparator: ., groupSeparator: ,, loading: false, })注意源码中statisticProps()还额外暴露了format、valueRender、loading等属性loading用于在数值加载期间展示 Skeleton 骨架屏文档主表未列出但属于源码支持的能力。最基本的使用来自官方示例 components/statistic/demo/basic.vuetemplate a-row a-col :span12 a-statistic titleActive Users :value112893 stylemargin-right: 50px / /a-col a-col :span12 a-statistic titleAccount Balance (CNY) :precision2 :value112893 / /a-col /a-row /template渲染结果中title会输出为.ant-statistic-title元素数值部分输出为.ant-statistic-content-value。通过valueStyle可以直接控制数值的字体颜色、字号等样式。深入源码数字是如何被格式化渲染的Statistic 的数值渲染核心在 Number.tsx 的StatisticNumber函数式组件中它完整体现了decimalSeparator、groupSeparator、precision三个属性的底层实现逻辑const val String(value); const cells val.match(/^(-?)(\d*)(\.(\d))?$/); if (!cells) { // 非法数字原样输出 valueNode val; } else { const negative cells[1]; let int cells[2] || 0; let decimal cells[4] || ; // 千分位分组 int int.replace(/\B(?(\d{3})(?!\d))/g, groupSeparator); // 精度补齐/截断 if (typeof precision number) { decimal decimal.padEnd(precision, 0).slice(0, precision 0 ? precision : 0); } if (decimal) { decimal ${decimalSeparator}${decimal}; } ... }由此可以总结出三条可验证的行为规则非法数值原样输出正则/^(-?)(\d*)(\.(\d))?$/匹配不通过时如传入bamboo直接按字符串渲染。这一点有测试用例佐证components/statistic/tests/index.test.js 中it(not a number)断言输出bamboo。千分位分隔符可自定义分组通过正则\B(?(\d{3})(?!\d))实现groupSeparator会替换默认的,。测试 index.test.js 传入groupSeparator: __TEST__断言1128渲染为1__TEST__128。precision 同时做补零与截断padEnd(precision, 0)负责小数位不足时补零slice(0, precision)负责超出时截断。负数通过cells[1]捕获的负号原样保留测试 index.test.js 覆盖了-112893.12345配合precision: 2的场景。另外整数部分与小数部分会被拆分为.ant-statistic-content-value-int与.ant-statistic-content-value-decimal两个独立 span方便针对整数和小数做差异化样式。使用 prefix / suffix 附加单位与图标prefix和suffix用来在数值前后附加描述性内容比如单位、百分比、图标等。它们既支持字符串也支持插槽v-slot插槽渲染时会被放入.ant-statistic-content-prefix/.ant-statistic-content-suffix容器中。参考官方示例 components/statistic/demo/unit.vuetemplate a-row :gutter16 a-col :span12 a-statistic titleFeedback :value1128 stylemargin-right: 50px template #suffix like-outlined / /template /a-statistic /a-col a-col :span12 a-statistic titleUnmerged :value93 template #suffix span/ 100/span /template /a-statistic /a-col /a-row /template script langts setup import { LikeOutlined } from ant-design/icons-vue; /script在卡片场景中常配合valueStyle做红绿涨跌配色见 components/statistic/demo/card.vuea-statistic titleFeedback :value11.28 :precision2 suffix% :value-style{ color: #3f8600 } template #prefix arrow-up-outlined / /template /a-statistic从 Statistic.tsx 的实现可以看到title、prefix、suffix三个属性的取值顺序均为“属性优先、插槽兜底”const title props.title ?? slots.title?.(); const prefix props.prefix ?? slots.prefix?.(); const suffix props.suffix ?? slots.suffix?.();自定义 formatter 完全掌控数值渲染当内置的数字格式化无法满足需求时例如要显示“xx 天”或货币符号可以通过formatter属性完全接管数值节点的渲染。formatter的类型为v-slot | ({value}) VNode。在 Number.tsx 中当formatter是函数时会跳过所有内置格式化逻辑if (typeof formatter function) { valueNode formatter({ value }); }对应的测试 index.test.js 验证了调用约定——formatter会收到形如{ value: 1128 }的对象参数其返回值将作为数值内容渲染。在 Statistic.tsx 中插槽形式同样被归一化为Formatter类型props.formatter ?? (slots.formatter as unknown as Formatter)所以以下两种写法等价!-- 属性函数写法 -- a-statistic titleActive Users :value112893 :formatter(d) ${d.value}k / !-- 插槽写法 -- a-statistic titleActive Users :value112893 template #formatter{ value } span{{ value }}k/span /template /a-statisticFormatter的类型定义位于 utils.ts支持false、number、countdown或自定义函数四种取值。Statistic.Countdown 倒计时 API 全表Statistic.Countdown继承Statistic的全部能力用于渲染一个实时递减的倒计时。官方文档 API 表如下属性说明类型默认值format格式化模板遵循 dayjs 风格stringHH:mm:ssprefix数值的前缀节点string | v-slot-suffix数值的后缀节点string | v-slot-title展示的标题string | v-slot-value目标倒计时截止时间number | dayjs-valueStyle设置数值的 CSS 样式style-倒计时事件事件名说明回调参数finish倒计时结束时触发() void源码 Countdown.tsx 中countdownProps()在继承statisticProps()的基础上额外声明了onFinish与onChange两个事件对应模板中的finish与change其中onChange会周期性返回剩余毫秒数countdownId.value setInterval(() { statistic.value.$forceUpdate(); if (timestamp Date.now()) { emit(change, timestamp - Date.now()); } syncTimer(); }, REFRESH_INTERVAL);REFRESH_INTERVAL 1000 / 30约 33ms这保证了毫秒级格式如SSS也能平滑刷新。计时器生命周期由 Countdown.tsx 中的onMounted/onUpdated/onBeforeUnmount管理挂载与每次更新时调用syncTimer()决定启停卸载时stopTimer()清理setInterval并判断是否已到时间、从而触发finish事件。倒计时实战示例来自官方示例 components/statistic/demo/countdown.vuetemplate a-row :gutter16 a-col :span12 a-statistic-countdown titleCountdown :valuedeadline finishonFinish / /a-col a-col :span12 a-statistic-countdown titleMillion Seconds :valuedeadline formatHH:mm:ss:SSS / /a-col a-col :span24 stylemargin-top: 32px a-statistic-countdown titleDay Level :valuedeadline formatD 天 H 时 m 分 s 秒 / /a-col /a-row /template script langts setup const onFinish () { console.log(finished!); }; const deadline Date.now() 1000 * 60 * 60 * 24 * 2 1000 * 30; /scriptvalue传入时间戳Date.now() ...或 dayjs 对象均可源码中通过new Date(value).getTime()统一转为毫秒时间戳。format 模板语法与转义规则format遵循 dayjs 风格支持Y年、M月、D天、H时、m分、s秒、S毫秒七种时间单位。时间单位到毫秒的换算关系定义在 utils.ts 的timeUnits数组中例如D对应1000 * 60 * 60 * 24毫秒。核心计算函数formatTimeStrutils.ts有两点值得注意模板中字符重复次数决定补零宽度例如HH会把小时补成两位09H则不补零9。测试 index.test.js 使用固定时间dayjs().add(2,d).add(11,h).add(28,m).add(9,s).add(3,ms)验证了H:m:s→59:28:9、HH:mm:ss→59:28:09、HH:mm:ss:SSS→59:28:09:003等映射关系。方括号[]支持转义输出字面量想输出“天”“时”等单位文字需要包在方括号里。例如formatD 天 H 时 m 分 s 秒中的“天 / 时 / 分 / 秒”都会被原样保留。这是因为实现先用/\[[^\]]*]/g提取括号内容到keepList模板替换完时间单位后再把括号内容回填。测试 index.test.js 验证了formatTimeStr(1000 * 60 * 60 * 24, D [Day])输出1 Day。倒计时配合插槽的进阶用法Statistic.Countdown同样支持title、prefix、suffix插槽可组合 Tooltip、图标等元素实现更丰富的展示参考官方示例 components/statistic/demo/countdown-slot.vuea-statistic-countdown :valuedeadline finishonFinish template #title spanCountdown/span a-tooltip placementright template #title spanhurry up!/span /template question-circle-two-tone stylemargin-left: 5px / /a-tooltip /template /a-statistic-countdown a-statistic-countdown titleMillion Seconds countdown :valuedeadline formatHH:mm:ss:SSS template #prefix spanTheres only/span /template template #suffix spanleft for the end./span /template /a-statistic-countdown在 Countdown.tsx 的渲染逻辑中Countdown本质上把自身包装成Statistic的子级它透传所有 props剔除onFinish/onChange两个事件并通过formatter注入内部倒计时格式化函数formatCountdown该函数调用 utils.ts 的formatCountdown——计算目标时间 - 当前时间的差值并交给formatTimeStr渲染。这种“组合而非重写”的结构让 Countdown 自动继承 Statistic 的标题、前缀、后缀、样式等全部能力。测试覆盖行为契约一览Statistic 组件的测试集中在 components/statistic/tests/index.test.js可作为行为契约参考mountTestStatistic 与 Countdown 均能正常挂载渲染自定义 formatterformatter({ value: 1128 })被调用返回值93渲染为.ant-statistic-content-value内容groupSeparator自定义千分位分隔符生效非数字值字符串原样输出负数 precision-112893.12345配合precision: 2正常渲染并匹配快照Countdown 各 format固定时间下H:m:s、HH:mm:ss、HH:mm:ss:SSS、DD-HH:mm:ss的输出均符合预期测试通过 MockDate 固定当前时间见 index.test.js转义D [Day]输出1 Day。小结Statistic 是 ant-design-vue 中“小而精”的展示组件decimalSeparator、groupSeparator、precision三个属性构成了内置数字格式化能力formatter提供了完全自定义的出口prefix/suffix/title支持字符串与插槽双形态Statistic.Countdown则通过组合模式复用其全部能力以约 33ms 的刷新周期驱动倒计时渲染并通过finish/change事件暴露结束与剩余时间的回调。需要继续深入源码的读者可以依次阅读 Statistic.tsx、Number.tsx、Countdown.tsx 与 utils.ts官方示例位于 components/statistic/demo 目录basic / unit / card / countdown / countdown-slot 五个场景。赞分享前端UI组件设计系统【免费下载链接】ant-design-vue An enterprise-class UI components based on Ant Design and Vue. 项目地址https://gitcode.com/gh_mirrors/an/ant-design-vue点击查看免费下载相关推荐Ant Design Statistic 组件完全指南数字展示、格式化与倒计时实战Ant Design Statistic 组件完全指南数字展示、格式化与倒计时实战 导读 Statistic 是 Ant Designant design前端UI组件设计系统Ant Design Statistic 组件完全指南统计数值、倒计时/正计时与语义化定制Ant Design Statistic 组件完全指南统计数值、倒计时/正计时与语义化定制 导读本文以 components/statistic/index前端UI组件设计系统Ant Design Statistic 组件完全指南数字统计、格式化与倒计时/计时器实战Ant Design Statistic 组件完全指南数字统计、格式化与倒计时/计时器实战 Statistic统计数值是 Ant Design 中用于突前端UI组件设计系统上一篇emilianJR/chilloutmix_NiPrunedFp32Fix多模态学习跨领域知识整合下一篇Foundry测试钩子终极指南掌握setup与teardown的5个实用技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考