AtomUI/docs/Desktop.Controls/Notifications/NotificationsAPI.md

Notification API 参考

命名空间

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 支持属性变更通知。

构造函数

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 挂载到窗口顶层。

构造函数

// 无参构造，需后续手动挂载
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

public bool IsMotionEnabled { get; set; }

WindowNotificationManager 和 NotificationCard 均实现此接口，控制出入动画的启用/禁用。IsMotionEnabled 的默认值跟随全局 SharedToken.EnableMotion。

IDisposable（仅 WindowNotificationManager）

public void Dispose()

调用 Dispose() 后：

• 停止所有定时器（过期检测、清理队列）
• 清空通知列表和清理队列
• 从 AdornerLayer 移除自身
• 取消窗口事件订阅