mirror of
https://github.com/AtomUI/AtomUI.git
synced 2026-10-19 23:30:44 +08:00
chinboy
265 lines
8.4 KiB
Markdown
265 lines
8.4 KiB
Markdown
# Notification API 参考
|
||
|
||
## 命名空间
|
||
|
||
```csharp
|
||
namespace AtomUI.Desktop.Controls;
|
||
```
|
||
|
||
AXAML 命名空间前缀：`atom`（`xmlns:atom="https://atomui.net"`）
|
||
|
||
---
|
||
|
||
## 枚举类型
|
||
|
||
### NotificationType
|
||
|
||
通知类型枚举，定义通知的语义类别和对应图标/颜色。
|
||
|
||
| 值 | 说明 |
|
||
|---|---|
|
||
| `Information` | 信息类通知（默认），蓝色图标 |
|
||
| `Success` | 成功类通知，绿色图标 |
|
||
| `Warning` | 警告类通知，黄色图标 |
|
||
| `Error` | 错误类通知，红色图标 |
|
||
|
||
### NotificationPosition
|
||
|
||
通知弹出位置枚举，控制通知在窗口中的出现位置。
|
||
|
||
| 值 | 说明 |
|
||
|---|---|
|
||
| `TopLeft` | 左上角 |
|
||
| `TopRight` | 右上角（默认） |
|
||
| `TopCenter` | 顶部居中 |
|
||
| `BottomLeft` | 左下角 |
|
||
| `BottomRight` | 右下角 |
|
||
| `BottomCenter` | 底部居中 |
|
||
|
||
---
|
||
|
||
## INotification 接口
|
||
|
||
通知数据契约，定义通知所需的全部信息。
|
||
|
||
| 属性名 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `Title` | `string` | 通知标题 |
|
||
| `Content` | `object?` | 通知正文内容 |
|
||
| `Icon` | `PathIcon?` | 自定义图标，为 `null` 时使用类型对应的默认图标 |
|
||
| `Type` | `NotificationType` | 通知类型 |
|
||
| `Expiration` | `TimeSpan` | 自动关闭时间，`TimeSpan.Zero` 表示不自动关闭 |
|
||
| `ShowProgress` | `bool` | 是否显示倒计时进度条 |
|
||
| `OnClick` | `Action?` | 通知被点击时的回调 |
|
||
| `OnClose` | `Action?` | 通知被关闭时的回调 |
|
||
|
||
---
|
||
|
||
## INotificationManager 接口
|
||
|
||
通知管理器契约。
|
||
|
||
### 方法
|
||
|
||
| 方法 | 签名 | 说明 |
|
||
|---|---|---|
|
||
| `Show` | `void Show(INotification notification, string[]? classes = null)` | 弹出一条通知。可选传入样式类名数组 |
|
||
|
||
---
|
||
|
||
## Notification 类（数据模型）
|
||
|
||
`INotification` 的默认实现，同时实现 `INotifyPropertyChanged` 支持属性变更通知。
|
||
|
||
### 构造函数
|
||
|
||
```csharp
|
||
public Notification(
|
||
string title,
|
||
object? content,
|
||
NotificationType type = NotificationType.Information,
|
||
PathIcon? icon = null,
|
||
TimeSpan? expiration = null,
|
||
bool showProgress = false,
|
||
Action? onClick = null,
|
||
Action? onClose = null)
|
||
```
|
||
|
||
| 参数 | 类型 | 默认值 | 说明 |
|
||
|---|---|---|---|
|
||
| `title` | `string` | — | 通知标题（必填） |
|
||
| `content` | `object?` | — | 通知正文内容 |
|
||
| `type` | `NotificationType` | `Information` | 通知类型 |
|
||
| `icon` | `PathIcon?` | `null` | 自定义图标 |
|
||
| `expiration` | `TimeSpan?` | `null`（实际为 5s） | 自动关闭时间，`null` 默认 5 秒，`TimeSpan.Zero` 不自动关闭 |
|
||
| `showProgress` | `bool` | `false` | 是否显示进度条 |
|
||
| `onClick` | `Action?` | `null` | 点击回调 |
|
||
| `onClose` | `Action?` | `null` | 关闭回调 |
|
||
|
||
### 公共属性
|
||
|
||
| 属性名 | 类型 | 说明 | 可写 |
|
||
|---|---|---|---|
|
||
| `Title` | `string` | 通知标题 | ✅ 触发 PropertyChanged |
|
||
| `Content` | `object?` | 通知正文内容 | ✅ 触发 PropertyChanged |
|
||
| `Icon` | `PathIcon?` | 自定义图标 | ✅ 触发 PropertyChanged |
|
||
| `ShowProgress` | `bool` | 是否显示进度条 | ✅ 触发 PropertyChanged |
|
||
| `Type` | `NotificationType` | 通知类型 | ✅ |
|
||
| `Expiration` | `TimeSpan` | 自动关闭时间 | ✅ |
|
||
| `OnClick` | `Action?` | 点击回调 | ✅ |
|
||
| `OnClose` | `Action?` | 关闭回调 | ✅ |
|
||
|
||
### 事件
|
||
|
||
| 事件名 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `PropertyChanged` | `PropertyChangedEventHandler?` | 属性变更通知（实现 `INotifyPropertyChanged`） |
|
||
|
||
---
|
||
|
||
## WindowNotificationManager 类
|
||
|
||
通知管理器控件，负责通知的生命周期管理和视觉容器。通过 `AdornerLayer` 挂载到窗口顶层。
|
||
|
||
### 构造函数
|
||
|
||
```csharp
|
||
// 无参构造，需后续手动挂载
|
||
public WindowNotificationManager()
|
||
|
||
// 传入 TopLevel 自动挂载到其 AdornerLayer
|
||
public WindowNotificationManager(TopLevel? host)
|
||
```
|
||
|
||
### 公共属性（StyledProperty）
|
||
|
||
| 属性名 | 类型 | 默认值 | 说明 |
|
||
|---|---|---|---|
|
||
| `Position` | `NotificationPosition` | `NotificationPosition.TopRight` | 通知弹出位置 |
|
||
| `MaxItems` | `int` | `5` | 最大同时可见通知数，超出时自动关闭最早的通知 |
|
||
| `IsPauseOnHover` | `bool` | `true` | 鼠标悬停时是否暂停自动关闭计时 |
|
||
| `IsMotionEnabled` | `bool` | 跟随全局 Token `EnableMotion` | 是否启用出入动画（共享属性） |
|
||
|
||
### 方法
|
||
|
||
| 方法 | 签名 | 说明 |
|
||
|---|---|---|
|
||
| `Show` | `void Show(INotification notification, string[]? classes = null)` | 弹出一条通知 |
|
||
| `Dispose` | `void Dispose()` | 释放资源，从 AdornerLayer 移除，停止所有定时器 |
|
||
|
||
### 实现的接口
|
||
|
||
| 接口 | 说明 |
|
||
|---|---|
|
||
| `INotificationManager` | 提供 `Show()` 方法 |
|
||
| `IMotionAwareControl` | 提供 `IsMotionEnabled` 属性 |
|
||
| `IDisposable` | 支持资源释放 |
|
||
|
||
### 模板部件
|
||
|
||
| 部件名 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `PART_Items` | `Panel` | 通知卡片容器（实际为 `ReversibleStackPanel`） |
|
||
|
||
---
|
||
|
||
## NotificationCard 类
|
||
|
||
单条通知的可视化控件，继承自 `ContentControl`。
|
||
|
||
### 公共属性（StyledProperty / DirectProperty）
|
||
|
||
| 属性名 | 类型 | 默认值 | 说明 |
|
||
|---|---|---|---|
|
||
| `Title` | `string` | — | 通知标题文本 |
|
||
| `Content` | `object?` | `null` | 通知正文内容（继承自 `ContentControl`） |
|
||
| `Icon` | `PathIcon?` | `null` | 通知图标，`null` 时使用类型对应的默认图标 |
|
||
| `NotificationType` | `NotificationType` | `Information` | 通知类型，影响图标和颜色 |
|
||
| `Expiration` | `TimeSpan?` | `null` | 剩余关闭时间，`null` 为不自动关闭 |
|
||
| `IsShowProgress` | `bool` | `false` | 是否显示倒计时进度条 |
|
||
| `IsClosing` | `bool`（只读） | `false` | 是否正在关闭（退出动画播放中） |
|
||
| `IsClosed` | `bool` | `false` | 是否已关闭 |
|
||
| `IsMotionEnabled` | `bool` | 跟随全局 Token `EnableMotion` | 是否启用出入动画 |
|
||
|
||
### 方法
|
||
|
||
| 方法 | 签名 | 说明 |
|
||
|---|---|---|
|
||
| `Close` | `void Close()` | 触发通知关闭（播放退出动画后移除） |
|
||
|
||
### 事件
|
||
|
||
| 事件名 | 类型 | 路由策略 | 说明 |
|
||
|---|---|---|---|
|
||
| `NotificationClosed` | `EventHandler<RoutedEventArgs>` | Bubble | 通知关闭完成后触发 |
|
||
|
||
### 模板部件
|
||
|
||
| 部件名 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `PART_CloseButton` | `IconButton` | 关闭按钮 |
|
||
| `BaseMotionActor.MotionActorPart` | `BaseMotionActor` | 动画执行器 |
|
||
|
||
---
|
||
|
||
## 伪类（Pseudo-Classes）
|
||
|
||
### NotificationCard 伪类
|
||
|
||
NotificationCard 支持以下伪类，可在样式选择器中使用：
|
||
|
||
#### 通知类型伪类（标准）
|
||
|
||
| 伪类 | 常量 | 触发条件 |
|
||
|---|---|---|
|
||
| `:error` | `StdPseudoClass.Error` | `NotificationType == Error` |
|
||
| `:information` | `StdPseudoClass.Information` | `NotificationType == Information` |
|
||
| `:success` | `StdPseudoClass.Success` | `NotificationType == Success` |
|
||
| `:warning` | `StdPseudoClass.Warning` | `NotificationType == Warning` |
|
||
|
||
#### 位置伪类
|
||
|
||
| 伪类 | 常量 | 触发条件 |
|
||
|---|---|---|
|
||
| `:topleft` | `NotificationPseudoClass.TopLeft` | `Position == TopLeft` |
|
||
| `:topright` | `NotificationPseudoClass.TopRight` | `Position == TopRight` |
|
||
| `:topcenter` | `NotificationPseudoClass.TopCenter` | `Position == TopCenter` |
|
||
| `:bottomleft` | `NotificationPseudoClass.BottomLeft` | `Position == BottomLeft` |
|
||
| `:bottomright` | `NotificationPseudoClass.BottomRight` | `Position == BottomRight` |
|
||
| `:bottomcenter` | `NotificationPseudoClass.BottomCenter` | `Position == BottomCenter` |
|
||
|
||
### WindowNotificationManager 伪类
|
||
|
||
| 伪类 | 常量 | 触发条件 |
|
||
|---|---|---|
|
||
| `:topleft` | `NotificationPseudoClass.TopLeft` | `Position == TopLeft` |
|
||
| `:topright` | `NotificationPseudoClass.TopRight` | `Position == TopRight` |
|
||
| `:topcenter` | `NotificationPseudoClass.TopCenter` | `Position == TopCenter` |
|
||
| `:bottomleft` | `NotificationPseudoClass.BottomLeft` | `Position == BottomLeft` |
|
||
| `:bottomright` | `NotificationPseudoClass.BottomRight` | `Position == BottomRight` |
|
||
| `:bottomcenter` | `NotificationPseudoClass.BottomCenter` | `Position == BottomCenter` |
|
||
|
||
---
|
||
|
||
## 实现的接口
|
||
|
||
### IMotionAwareControl
|
||
|
||
```csharp
|
||
public bool IsMotionEnabled { get; set; }
|
||
```
|
||
|
||
`WindowNotificationManager` 和 `NotificationCard` 均实现此接口，控制出入动画的启用/禁用。`IsMotionEnabled` 的默认值跟随全局 `SharedToken.EnableMotion`。
|
||
|
||
### IDisposable（仅 WindowNotificationManager）
|
||
|
||
```csharp
|
||
public void Dispose()
|
||
```
|
||
|
||
调用 `Dispose()` 后：
|
||
- 停止所有定时器（过期检测、清理队列）
|
||
- 清空通知列表和清理队列
|
||
- 从 `AdornerLayer` 移除自身
|
||
- 取消窗口事件订阅
|