AtomUI/docs/Desktop.Controls/Statistic/StatisticAPI.md

Statistic API 参考

命名空间

namespace AtomUI.Desktop.Controls;

AXAML 命名空间前缀：atom（xmlns:atom="https://atomui.net"）

---

AbstractStatistic（抽象基类）

所有统计数值控件（Statistic、TimerStatistic）的公共基类，继承自 HeaderedContentControl。

公共属性（StyledProperty）

属性名	类型	默认值	说明
DecimalSeparator	string	"."	小数点分隔符
GroupSeparator	string	","	千分位分隔符
Precision	int	0	小数精度（保留几位小数，0 表示整数）
IsLoading	bool	false	是否显示加载骨架屏（Skeleton 占位）
ValuePrefixAddOn	object?	null	数值前缀装饰（可以是文本、图标等任意内容）
ValuePrefixAddOnTemplate	IDataTemplate?	null	前缀内容的数据模板
ValueSuffixAddOn	object?	null	数值后缀装饰（可以是单位文本、图标等）
ValueSuffixAddOnTemplate	IDataTemplate?	null	后缀内容的数据模板
ContentForeground	IBrush?	由 Token 控制（ColorTextHeading）	数值区域前景色
ContentFontSize	double	由 Token 控制（FontSizeHeading3）	数值区域字体大小

继承自 HeaderedContentControl 的常用属性

属性名	类型	默认值	说明
Header	object?	null	标题内容（统计项描述文本）
HeaderTemplate	IDataTemplate?	null	标题数据模板
Content	object?	null	主内容区域（格式化后的数值文本或嵌入的 StatisticCountUp）
ContentTemplate	IDataTemplate?	null	内容数据模板
Background	IBrush?	null	背景色
CornerRadius	CornerRadius	0	圆角半径

---

Statistic（基础统计数值）

继承自 AbstractStatistic。

公共属性

属性名	类型	默认值	说明
Value	object?	null	原始数值（支持 int、long、float、double、decimal 等数值类型，也可以是字符串）

CLR 属性

属性名	类型	说明
Formatter	Func<Statistic, object?, string?>?	自定义格式化回调。设置后将优先使用此回调格式化 Value，忽略 Precision / GroupSeparator 等参数

内部属性（Internal）

属性名	类型	说明
EffectiveValue	string?	经过格式化后的最终显示值，由 GenerateEffectiveValue 计算

格式化优先级

1. 如果设置了 Content（如嵌入 StatisticCountUp）→ 直接显示 Content
2. 如果设置了 Formatter → 调用 Formatter(this, Value) 获取显示文本
3. 否则 → 使用 StatisticUtils.FormatNumber(Value, GroupSeparator, DecimalSeparator, Precision) 自动格式化

---

TimerStatistic（计时器/倒计时）

继承自 AbstractStatistic。

公共属性（StyledProperty）

属性名	类型	默认值	说明
Value	DateTime	default	目标时间。如果在未来则为倒计时模式，如果在过去则为计时模式
Format	string?	null	时间显示格式（.NET TimeSpan 格式字符串），默认为 hh:mm:ss
RefreshDuration	TimeSpan	10ms	计时器刷新间隔。减小此值可提高显示精度（如毫秒级显示需设为较小值）

CLR 属性

属性名	类型	说明
Formatter	Func<TimeSpan, string>?	自定义时间格式化回调。设置后完全自定义剩余时间的文本表示

事件

事件名	类型	说明
CountdownFinished	EventHandler?	倒计时完成时触发（剩余时间 ≤ 0），同时自动停止计时器

内部属性（Internal）

属性名	类型	说明
RemainingTime	TimeSpan	当前剩余/经过时间
RemainingTimeText	string?	格式化后的剩余时间文本

计时行为说明

• 倒计时：当 Value > DateTime.Now 时，RemainingTime = Value - DateTime.Now
• 计时：当 Value ≤ DateTime.Now 时，RemainingTime = DateTime.Now - Value
• 自动停止：当 RemainingTime ≤ TimeSpan.Zero 时，停止计时器并触发 CountdownFinished
• 生命周期管理：附加到视觉树时自动启动计时器，分离时自动停止

常用 Format 格式

格式字符串	输出示例	说明
hh\:mm\:ss (默认)	02:30:45	时:分:秒
hh\:mm\:ss\.fff	02:30:45.123	时:分:秒.毫秒
d\ \天\ h\ \时\ m\ \分\ s\ \秒	2 天 6 时 30 分 45 秒	天级中文格式

---

StatisticCountUp（数值递增动画）

继承自 TemplatedControl。设计为嵌入 Statistic.Content 中使用。

公共属性（StyledProperty）

属性名	类型	默认值	说明
EndValue	double	0	目标数值，动画将从 0 递增到此值
DecimalSeparator	string	"."	小数点分隔符
GroupSeparator	string	","	千分位分隔符
Precision	int	0	小数精度
AnimatingValue	double	0	当前动画值（由 DoubleTransition 驱动从 0 到 EndValue）

内部属性（Internal）

属性名	类型	说明
FormattedValue	string?	当前动画值经过格式化后的显示文本

动画说明

• 动画使用 DoubleTransition 过渡 AnimatingValue 属性
• 缓动曲线：ExponentialEaseOut（快速启动，缓慢到达终值）
• 动画时长：SharedToken.MotionDurationVerySlow
• 控件加载（OnLoaded）时自动将 AnimatingValue 设为 EndValue 触发动画
• 卸载（OnUnloaded）时清除 Transitions

---

伪类（Pseudo-Classes）

Statistic 家族控件的伪类较少，主要继承自 Avalonia 基础控件。

通用伪类

伪类	触发条件
:disabled	IsEnabled == false

属性选择器

选择器	说明
atom|Statistic[IsLoading=True]	加载中状态
atom|TimerStatistic[IsLoading=True]	TimerStatistic 加载中状态