# Message 全局提示

## 概述

全局提示（Message）用于在页面顶部居中展示轻量级的操作反馈信息，属于非阻断性反馈组件。它在操作完成后自动出现在页面顶部，短暂停留后自动消失，不打断用户的操作流程。适用于表单提交成功/失败、异步操作状态提示、系统信息通知等场景。

AtomUI 的 `Message` 控件对标 [Ant Design 5.0 Message](https://ant.design/components/message-cn) 的设计规范，在 .NET / Avalonia 平台上提供一致的全局提示体验。

---

## 设计原理

### Ant Design 的全局提示设计哲学

Ant Design 对全局提示的定位是：**「全局展示操作反馈信息，居顶部居中显示并自动消失，是一种不打断用户操作的轻量级提示方式」**。它与 Notification（通知提醒）的关键区别在于：

| 特性 | Message（全局提示） | Notification（通知提醒） |
|---|---|---|
| **位置** | 页面顶部居中 | 页面四角 |
| **内容量** | 仅文本，轻量单行 | 标题 + 详细描述 + 操作按钮 |
| **交互** | 无交互，自动消失 | 可关闭、可操作 |
| **适用场景** | 操作反馈（成功/失败/警告） | 需要用户关注的复杂通知 |

**五种消息类型**（对应不同操作结果和语义）：

| 类型 | 图标 | 设计意图 | 典型用途 |
|---|---|---|---|
| ℹ️ **Information** | `InfoCircleFilled`（蓝色） | 普通信息提示，中性语义 | 一般性操作提示、说明信息 |
| ✅ **Success** | `CheckCircleFilled`（绿色） | 操作成功确认 | 表单提交成功、保存完成 |
| ⚠️ **Warning** | `ExclamationCircleFilled`（黄色） | 警告提示，需要注意 | 操作有风险但可继续 |
| ❌ **Error** | `CloseCircleFilled`（红色） | 操作失败，需要关注 | 提交失败、网络错误 |
| 🔄 **Loading** | `LoadingOutlined`（蓝色旋转） | 异步操作进行中 | 数据加载、文件上传中 |

### AtomUI 的架构设计

AtomUI 的 Message 系统由三个核心组件协作完成：

```
WindowMessageManager（容器管理器）
  ├── 挂载在 TopLevel 的 AdornerLayer 上
  ├── 管理消息的生命周期（显示、自动关闭、最大数量控制）
  └── MessageCard（单条消息卡片）× N
       ├── 图标（根据 MessageType 自动匹配）
       ├── 文本内容
       └── 入场/出场动画（MoveUpIn / MoveUpOut）
```

**职责分离**：
- `IMessage` / `Message` — 数据模型，承载消息内容、类型、过期时间等信息
- `MessageCard` — 视觉控件，负责单条消息的渲染和动画
- `WindowMessageManager` — 容器管理器，负责消息的创建、排布和生命周期管理

---

## 功能详解

### 消息类型（MessageType）

消息类型通过 `MessageType` 枚举指定，每种类型会自动匹配对应的图标和颜色：

| 类型 | 默认图标 | 图标颜色来源 |
|---|---|---|
| `Information` | `InfoCircleFilled` | `SharedToken.ColorPrimary`（蓝色） |
| `Success` | `CheckCircleFilled` | `SharedToken.ColorSuccess`（绿色） |
| `Warning` | `ExclamationCircleFilled` | `SharedToken.ColorWarning`（黄色） |
| `Error` | `CloseCircleFilled` | `SharedToken.ColorError`（红色） |
| `Loading` | `LoadingOutlined`（旋转） | `SharedToken.ColorPrimary`（蓝色） |

### 自动关闭与过期时间

每条消息都有 `Expiration` 属性控制自动关闭时间：
- 默认值为 **5 秒**
- 设置为 `TimeSpan.Zero` 时消息不会自动关闭，需要手动调用 `Close()`
- 过期后通过 `DispatcherTimer.RunOnce` 触发关闭流程

### 最大显示数量

`WindowMessageManager.MaxItems` 控制同时可见的最大消息数量（默认为 5）。当新消息导致超出上限时，最早显示的消息会被自动关闭。

### 入场/出场动画

MessageCard 使用 `MoveUpIn` / `MoveUpOut` 动画实现消息的入场和出场效果：
- **入场**：从上方滑入 + 透明度从 0 到 1，使用 `CubicEaseOut` 缓动
- **出场**：向上滑出 + 透明度从 1 到 0，使用 `CubicEaseIn` 缓动
- 动画偏移量固定为 100px（`AnimationMaxOffsetY`）
- 动画时长由 `SharedToken.MotionDurationMid` 控制
- 可通过 `IsMotionEnabled = false` 禁用动画

### 关闭回调

通过 `Message` 构造函数的 `onClose` 参数传入关闭回调，当消息关闭（无论自动或手动）时执行。这支持链式消息——在一条消息关闭后立即显示下一条。

### 自定义图标

通过 `Message` 构造函数的 `icon` 参数可以传入自定义 `PathIcon`，覆盖默认的类型图标。

---

## 与 Ant Design 规范的对齐程度

| 特性 | Ant Design (React) | AtomUI (Avalonia) | 对齐情况 |
|---|---|---|---|
| 五种消息类型 | ✅ `info / success / warning / error / loading` | ✅ `MessageType` 枚举 | ✅ 完全对齐 |
| 顶部居中显示 | ✅ | ✅ `HorizontalAlignment="Center"` + `VerticalAlignment="Top"` | ✅ 完全对齐 |
| 自动关闭 | ✅ 默认 3 秒 | ✅ 默认 5 秒 | ⚠️ 默认时长不同 |
| 自定义图标 | ✅ `icon` 属性 | ✅ `Icon` 参数 | ✅ 对齐 |
| 关闭回调 | ✅ `onClose` | ✅ `OnClose` 回调 | ✅ 对齐 |
| Loading 类型 | ✅ | ✅ 旋转 `LoadingOutlined` 图标 | ✅ 完全对齐 |
| 自定义时长 | ✅ `duration` 参数 | ✅ `Expiration` 参数 | ✅ 对齐 |
| 最大显示数量 | ✅ `maxCount` | ✅ `MaxItems` 属性 | ✅ 对齐 |
| Promise 接口 | ✅ `message.open().then(...)` | ❌ 使用回调模式 | ⚠️ C# 无 Promise，使用 `OnClose` 回调 |
| 全局配置 | ✅ `message.config()` | ❌ 通过 `WindowMessageManager` 实例配置 | ⚠️ 实例级配置 vs 全局配置 |
| 更新消息内容 | ✅ 通过 `key` 更新 | ✅ `Message.Content` 支持 `INotifyPropertyChanged` | ⚠️ 机制不同但功能可实现 |

---

## 继承关系

### MessageCard

```
Avalonia.Controls.Primitives.TemplatedControl
  └── AtomUI.Desktop.Controls.MessageCard
        └── implements IMotionAwareControl
```

### WindowMessageManager

```
Avalonia.Controls.Primitives.TemplatedControl
  └── AtomUI.Desktop.Controls.WindowMessageManager
        ├── implements IMessageManager
        ├── implements IMotionAwareControl
        └── implements IDisposable
```

### Message（数据模型）

```
AtomUI.Desktop.Controls.Message
  ├── implements IMessage
  └── implements INotifyPropertyChanged
```

**各层级职责划分：**

| 层级 | 提供的能力 |
|---|---|
| `TemplatedControl` | 模板化控件基础设施、`OnApplyTemplate`、`CornerRadius` 等 |
| `MessageCard` | 单条消息的视觉呈现：图标自动匹配、伪类管理、入场/出场动画 |
| `WindowMessageManager` | 消息容器管理：挂载到 TopLevel、消息排布、最大数量控制、自动关闭计时器 |
| `Message` | 消息数据模型：内容、类型、过期时间、关闭回调 |

**实现的接口：**

| 接口 | 定义位置 | 控件 | 作用 |
|---|---|---|---|
| `IMessage` | `AtomUI.Desktop.Controls` | 数据模型 | 定义消息数据契约（Content、Type、Expiration、OnClose、Icon） |
| `IMessageManager` | `AtomUI.Desktop.Controls` | WindowMessageManager | 定义消息管理器契约（`Show` 方法） |
| `IMotionAwareControl` | `AtomUI.Controls` | MessageCard / WindowMessageManager | 支持动画启用/禁用控制 |
| `INotifyPropertyChanged` | `System.ComponentModel` | Message | 支持属性变更通知（Content、Icon 可动态更新） |
| `IDisposable` | `System` | WindowMessageManager | 支持资源释放（从 AdornerLayer 卸载、清理事件订阅） |

---

## 源码位置

| 层级 | 文件路径 | 说明 |
|---|---|---|
| 数据接口 | `src/AtomUI.Desktop.Controls/Message/IMessage.cs` | IMessage 消息数据契约 |
| 管理器接口 | `src/AtomUI.Desktop.Controls/Message/IMessageManager.cs` | IMessageManager 管理器契约 |
| 数据模型 | `src/AtomUI.Desktop.Controls/Message/Message.cs` | Message 消息数据实现 |
| 消息卡片 | `src/AtomUI.Desktop.Controls/Message/MessageCard.cs` | MessageCard 视觉控件 |
| 消息类型枚举 | `src/AtomUI.Desktop.Controls/Message/MessageType.cs` | MessageType 枚举 |
| 伪类常量 | `src/AtomUI.Desktop.Controls/Message/MessageCardPseudoClass.cs` | 伪类常量定义 |
| 容器管理器 | `src/AtomUI.Desktop.Controls/Message/WindowMessageManager.cs` | WindowMessageManager 容器 |
| Token 定义 | `src/AtomUI.Desktop.Controls/Message/MessageToken.cs` | 组件级 Design Token |
| 消息卡片主题 | `src/AtomUI.Desktop.Controls/Message/Themes/MessageCardTheme.axaml` | MessageCard ControlTheme |
| 容器主题 | `src/AtomUI.Desktop.Controls/Message/Themes/WindowMessageManagerTheme.axaml` | WindowMessageManager ControlTheme |
| 主题注册 | `src/AtomUI.Desktop.Controls/Message/Themes/MessageThemes.axaml` | 主题合并注册 |
| 模板常量 | `src/AtomUI.Desktop.Controls/Message/Themes/MessageThemeConstants.cs` | 模板部件名称常量 |
| Gallery 示例 | `controlgallery/AtomUIGallery/ShowCases/Views/Feedback/MessageShowCase.axaml` | 使用范例 |

---

## 模板结构

### MessageCard 模板

MessageCard 使用 `MotionActor` 包裹以支持入场/出场动画：

```
MotionActor (PART_MotionActor)                   ← 动画容器
└── Border (PART_Frame)                          ← 主框架（背景、圆角、阴影）
    └── DockPanel (PART_HeaderContainer)         ← 内容布局容器
        ├── IconPresenter (PART_IconContent)      ← 消息图标（DockPanel.Dock="Left"）
        └── SelectableTextBlock (PART_Message)   ← 消息文本（可选中复制）
```

**设计理由：**
- **MotionActor 包裹**：使整个消息卡片可以参与 Move 动画，实现滑入/滑出效果
- **SelectableTextBlock**：使用可选择文本控件，用户可以选中并复制消息内容
- **DockPanel 布局**：图标靠左固定，文本填满剩余空间

### WindowMessageManager 模板

```
ReversibleStackPanel (PART_Items)                 ← 消息堆叠容器
  ├── MessageCard                                ← 消息卡片 1
  ├── MessageCard                                ← 消息卡片 2
  └── ...
```

`ReversibleStackPanel` 支持 `ReverseOrder`，当 Position 为 `TopCenter` 时反转堆叠顺序，使最新消息出现在最上方。

### 模板部件常量

| 常量名 | 值 | 所属 | 说明 |
|---|---|---|---|
| `MessageCardThemeConstants.FramePart` | `"PART_Frame"` | MessageCard | 主框架边框 |
| `MessageCardThemeConstants.IconContentPart` | `"PART_IconContent"` | MessageCard | 图标展示器 |
| `MessageCardThemeConstants.HeaderContainerPart` | `"PART_HeaderContainer"` | MessageCard | 内容布局容器 |
| `MessageCardThemeConstants.MessagePart` | `"PART_Message"` | MessageCard | 消息文本 |
| `WindowMessageManagerThemeConstants.ItemsPart` | `"PART_Items"` | WindowMessageManager | 消息列表面板 |