mirror of
https://github.com/AtomUI/AtomUI.git
synced 2026-10-19 15:20:25 +08:00
chinboy
169 lines
6.2 KiB
Markdown
169 lines
6.2 KiB
Markdown
# Statistic API 参考
|
||
|
||
## 命名空间
|
||
|
||
```csharp
|
||
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 加载中状态 |
|