AtomUI/docs/controls/desktop/feedback/message/implementation.md

# Message 桌面版实现原理

本文档描述 Message 桌面版的内部实现范围、源码职责、状态流、生命周期、资源边界和维护规则。公共设计与 API 契约见 [Message 桌面版架构设计](overview.md)，共用堆叠与计时算法见 [Feedback 堆叠基础设施](../../../../architecture/systems/control-infrastructure/feedback-stack.md)，变化记录见 [Message Changelog](changelog.md)。涉及控件 Token 的实现应同时阅读 [Message Token 设计](token.md)。

## 1. 实现定位

本文档覆盖 Message 的控件实现、主题接入、状态同步和 Gallery 可见维护边界。具体属性注册、默认值、绘制细节和 AXAML selector 仍应直接阅读源码；本文只记录维护者必须理解的稳定结构和不变量。

## 2. 源码文件结构

主要源码文件：

- `src/AtomUI.Desktop.Controls/Message/IMessage.cs`
- `src/AtomUI.Desktop.Controls/Message/IMessageManager.cs`
- `src/AtomUI.Desktop.Controls/Message/Message.cs`
- `src/AtomUI.Desktop.Controls/Message/MessageCard.cs`
- `src/AtomUI.Desktop.Controls/Message/MessageCard.SemanticParts.cs`
- `src/AtomUI.Desktop.Controls/Message/MessageCardPseudoClass.cs`
- `src/AtomUI.Desktop.Controls/Message/MessageCardToken.cs`
- `src/AtomUI.Desktop.Controls/Message/MessageType.cs`
- `src/AtomUI.Desktop.Controls/Message/Themes/MessageCardTheme.axaml`
- `src/AtomUI.Desktop.Controls/Message/Themes/WindowMessageManagerTheme.axaml`
- `src/AtomUI.Desktop.Controls/Message/WindowMessageManager.cs`
- `src/AtomUI.Desktop.Controls/Primitives/FeedbackStack/FeedbackStackPresenter.cs`
- `src/AtomUI.Desktop.Controls/Primitives/FeedbackStack/FeedbackStackPanel.cs`
- `src/AtomUI.Desktop.Controls/Primitives/FeedbackStack/FeedbackLifetimeScheduler.cs`
- `src/AtomUI.Desktop.Controls/Primitives/FeedbackStack/FeedbackCardMotion.cs`
- `src/AtomUI.Desktop.Controls/Primitives/FeedbackStack/FeedbackCardMotionCoordinator.cs`
- `src/AtomUI.Desktop.Controls/Primitives/FeedbackStack/IFeedbackStackItem.cs`
- `src/AtomUI.Desktop.Controls/Message/WindowMessageManager.SemanticParts.cs`
- `src/AtomUI.Core/MotionScene/MotionExecutionState.cs`

职责边界：

- 控件主文件保留 public/protected API、Avalonia 属性注册、事件和主要生命周期入口。
- Theme 文件负责静态视觉结构、template part、selector 和资源绑定。
- Token 文件只提供组件视觉变量，不保存实例状态。
- Gallery 文件只展示用法和示例，不作为运行时逻辑 owner。

## 3. 核心类职责

- `Message`：控件核心或内部协作类型，维护 public surface 与主题可观察行为。
- `MessageCard`：控件核心或内部协作类型，维护 public surface 与主题可观察行为。
- `MessageCardToken`：internal 控件 Token scope，负责从全局 token 派生控件语义变量。
- `WindowMessageManager`：拥有稳定卡片集合、public Stack 配置、TopLevel host、生命周期调度与用户回调清理。
- `WindowFeedbackLayer`：作为窗口反馈 manager 的宿主，按最近成功提交的 `Show` 原子移动直接 manager 子项；不拥有卡片、
  scheduler 或用户回调。
- `FeedbackStackPresenter`：消费稳定 ItemsSource，管理整体 hover 和 Message 静态背板状态。
- `FeedbackStackPanel`：按共享几何契约测量和排列，不拥有内容或生命周期。
- `FeedbackLifetimeScheduler`：按单调 deadline 调度有限时长项；空闲时没有活动 timer。
- `FeedbackCardMotion`：把 Message 的 Position 归一为 64 DIP translate/fade 和统一 Ant easing，不改变 card scale。
- `FeedbackCardMotionCoordinator`：协调当前 actor 的进入/退出状态、取消和完成提交，并在 retemplate、detach、dispose 时同步解除 transition 引用。

核心协作规则：

- 控件实例是 public API 和运行时状态 owner。
- Template part 是视觉协作对象，生命周期必须受 `OnApplyTemplate` 或模板加载流程管理。
- 数据对象、选项对象、任务对象或节点对象只保存业务数据，不应反向持有不可释放的视觉对象。
- 弹层、窗口、计时器、异步 loader 和全局管理器必须有明确关闭、解绑或释放路径。

## 4. 状态与数据流

Message 的状态流遵循下面路径：

```text
Public API / ItemsSource / Command / Event
  -> 控件实例状态
  -> internal state / effective state / pseudo-class
  -> template part property / AXAML selector
  -> renderer / popup / adorner / Gallery observable behavior
```

源码中的状态入口按以下语义维护：

- 内容与数据：`Show`、`MaxItems`、`Message`、`MessageType`、`Icon`。
- Stack 与生命周期：`IsStackEnabled`、`StackThreshold`、`IsPauseOnHover`、`IMessage.Expiration`、`DestroyAll()`；Stack
  只参与视觉投影和实际 hover 暂停，不能改写或替代展示时长。
- 交互与状态：`IsClosed`、`IsClosing`、`IsMotionEnabled`。
- 视觉与布局：`Position`。

`IsClosing` 和 `IsClosed` 是 MessageCard 的 public 业务状态。卡片拥有一个共享 `FeedbackCardMotionCoordinator`；协调器分别
以 `MotionExecutionState` 约束进入和退出阶段，按 `Idle -> Pending -> Playing -> Completing -> Idle` 推进。关闭/禁用状态与
模板重套用都进入同一控制器；旧 actor 的执行会被取消且 completion 失效，当前 actor 立即接管目标状态。播放中的 Position /
Duration 变化不重启同一 actor，新值从下一次 motion 生效；Completing 只负责提交一次 `IsClosed=true`。

维护要求：

- 外部设置的 Avalonia 属性必须在模板应用前后保持一致。
- 集合、选择、展开、过滤、分页、上传任务或异步 loader 必须能处理 reset、replace 和 clear。
- 伪类和 internal state 必须从单一 owner 推导，避免双向同步导致循环更新。
- overview.md 的 API 契约说明应与源码实际状态流一致。

## 5. 生命周期与模板接入

生命周期规则：

- 构造阶段只注册必要状态，不依赖 template part。
- 模板应用时获取 part、建立事件订阅和绑定，并先释放旧 part 订阅。
- manager 的卡片 collection 在模板之外创建并保持稳定；新 `PART_Items` 只重新绑定该 collection，旧 presenter 立即解绑。
- 带宿主 manager 的跨 manager 层级只由 host layer 的直接子项顺序表达；激活使用 collection `Move`，不得通过
  `Remove` + `Add` 触发 detach/attach，也不得覆盖 manager/card 的 `ZIndex`。
- manager 首次 attach 前允许 `Show`，卡片进入稳定集合，有限时长登记保持暂停。detach 时先暂停 scheduler，
  并在视觉树级联完成后确认是否仍离树：持续离树关闭当时卡片，同轮重新入树的 host 迁移保留队列。
- `Dispose` 解绑 presenter 的集合与 hover 事件、释放 scheduler 和每张 card 的 owner/回调，再移除宿主层及安全区订阅。
  模板重套用仅更换 presenter，不重新创建卡片。
- Gallery 页面分别惰性创建普通示例 manager 与 Stack 示例 manager；页面 detach 时两者都必须 `Dispose()` 并清空引用。
- 控件卸载、弹层关闭、窗口关闭、集合替换或 container recycle 时释放事件订阅和资源宿主。
- DynamicResource、TokenResourceBinder 或 C# binding 必须有明确 owner 和释放点。
- Browser 和 Desktop 宿主下的主题加载顺序不得影响 public API 语义。

稳定 template part 接入点：

- `PART_Frame`：承载根视觉、边框、背景或尺寸基线。
- `PART_HeaderContainer`：稳定模板协作入口，重命名前必须同步主题和实现。
- `PART_IconContent`：展示图标、状态图标或操作图标。
- `PART_Items`：`ItemsControl` 级稳定入口，承载共享 presenter 和 panel；不能再由 manager 直接修改 `Panel.Children`。
- `PART_Message`：稳定模板协作入口，重命名前必须同步主题和实现。

## 6. 交互与事件处理

Message 的交互事件应从输入源收敛到控件级语义事件：

- Pointer、keyboard、focus 和 command 事件不应绕过 Avalonia 基础控件语义。
- 没有弹层职责的路径不应引入额外 popup 或全局输入捕获。
- 集合类路径必须稳定处理 container prepare、clear、过滤、分组和虚拟化回收。
- 值提交或命令触发必须保持继承控件的事件顺序。

稳定事件路径包括 `MessageClosed`。事件参数和触发时机属于兼容边界。

## 7. 内部算法与关键流程

维护者需要重点关注以下流程：

- API 默认值到 effective state 的归一。
- Template part 重新应用时的状态回放。
- 主题资源、Token 和 SharedToken 计算后的视觉更新。
- ItemsSource、selection、checked、expanded、filter、paging 或 upload task 的集合同步。
- 动效启停、初始加载阶段 transition 抑制和卸载取消。
- MessageCard 的关闭请求、模板状态回放和最终 `IsClosed` 提交必须经过同一个关闭动效执行状态流。
- MessageCard 的内容 actor 使用共享 Feedback motion；按 Position 从对应边缘平移 64 DIP 并插值 opacity，退出反向执行，
  scale 全程为 `1`。actor 进入/退出与外层队列位置 transform 不得写入同一属性。
- 入场和退出通过同一 motion 执行入口交接 actor；复用同一个 actor 时，取消请求之后必须等待旧 motion 的异步清理完成，
  才能写入新目标。新模板的不同 actor 可以立即启动。等待期间仍响应当前执行的取消，重套模板、detach 或 dispose
  不得留下继续启动旧执行的回调。
- FeedbackStackPanel 把展开位置表达为相对稳定顶部/底部锚点的 transform，使新增、移除和 Stack 切换只更新目标
  transform；不得先改写屏幕位置再通过 Dispatcher 执行补偿动画。motion-disabled 时直接排列可见终态，并保持隐藏项
  的有效展开 Bounds，以避免无意义的 transform 属性写入和 layout-invalid 重试。
- `Show` 在 UI thread 同步创建并登记卡片，加入稳定 collection 后更新 MaxItems 和 Stack 投影；不使用延迟队列重新取得旧模板的 children。
- Stack 判定使用活动项数量严格大于有效阈值；Message 折叠只保留最新真实卡片可见，并由 AXAML 中两个静态背板表达深度。
- 背板在展开期间仍跟随最新活动卡片的尺寸，通过 opacity 与 RenderTransform 的快速过渡表达显隐；收拢时不能从零
  重新增长宽度。两层背板由零尺寸 Panel 叠放，不参与队列 extent 或命中；顶部、底部锚定及宽度变化过渡遵循共享几何契约。
- 生命周期调度只保存 deadline / remaining 与 card 协作引用。有限时长项无论 Stack 是否开启都登记 deadline；零时长项
  不创建登记。只有 lifecycle detach 或实际 hover 才能暂停，折叠状态自身不能暂停。继续和 deadline 到期由一个
  manager 级 scheduler 完成，不为每项创建 timer。
- scheduler 在本次唤醒结束时清空扫描临时列表，关闭回调完成后读取最新单调时刻再安排下一次唤醒；空闲 manager 不得
  因复用列表保留已关闭卡片，也不得把回调耗时再次计入后续 deadline。
- `MaxItems` 淘汰先固定本批最旧活动项，再按创建顺序请求关闭；同步关闭或回调修改集合不得改变已选批次。
- `Show` 在 UI thread 同步创建卡片并加入稳定 collection，随后在生命周期登记、MaxItems 淘汰及其潜在用户回调之前激活
  当前宿主 manager；重入到其他 manager 的后续 `Show` 必须保留为最终栈顶。
- `DestroyAll()` 固定调用时的卡片批次并倒序请求关闭；回调中新建的卡片不属于外层批次，manager dispose 后停止请求。
  正在关闭项不会重复关闭，清理仍由 card 的 `MessageClosed` 单一路径提交。
- Gallery Stack 示例每次只同步创建一个零时长 Information 消息，并复用一个递增序号；Enabled 与 Threshold 直接更新
  Stack 示例 manager 的现有投影，`DestroyAll()` 只清空该 manager 且不重置序号。普通示例 manager 保持运行时默认
  `IsStackEnabled=false`，因此 Stack 示例配置不能泄漏到其他示例。配置行按 NumericUpDown 的行高垂直居中各子组，
  `BadgeText="v6.1.9"` 交由 ShowCaseItem 的既有 RibbonBadge 模板呈现，不创建专用角标视觉。

实现文档不逐行解释私有方法。若某个私有算法成为稳定维护入口，应在本节补充算法不变量，而不是把代码复述为说明书。

## 8. 资源、性能与 AOT 边界

资源和 AOT 约束：

- 不通过运行时反射扫描 public API、Token 或 Gallery 示例数据。
- 不把可静态声明的模板结构迁移到 C# 动态创建。
- 异步加载、上传、弹层和窗口生命周期必须能取消或释放。
- 缓存对象必须与控件、窗口、弹层或数据 owner 生命周期一致。
- Source generator 生成文件不手工编辑；需要修改时改输入源或 generator。

性能边界：

- manager、ItemsControl 与 card collection 在 Stack 切换和重套模板之间保持稳定。
- manager 已位于反馈层末尾时，宿主激活只做一次 O(1) 尾项比较；切换 manager 时只对直接 manager 子项执行一次索引查找
  和一次 collection `Move`。不得扫描 card、分配临时集合、创建 timer/任务/订阅或保存额外 manager 引用。
- `MeasureOverride` / `ArrangeOverride` 不允许 LINQ、临时数组、闭包或逐帧 transform 创建。
- 稳态布局必须复用缓存 transform；目标变化最多创建一个 transform 并交给 transition 插值，不增加逐帧 managed 回调。
- 没有有限时长活动项时 scheduler 不保持活动 timer；没有 Notification 进度需求时只安排最近 deadline。
- Gallery Stack 示例的零时长消息不创建 scheduler entry、异步循环、取消令牌或逐项 timer；两个示例 manager 都只在
  第一次实际操作时创建，并在页面 detach 时释放。
- 折叠背板由 AXAML 静态创建，不随 show 次数增加视觉对象。
- 性能修改必须使用同一 Message 场景比较基线与优化后的 mean、median、P95，并证明主要指标无可测量回退。

## 9. 维护不变量

维护 Message 时不得破坏：

- Public API、默认值、事件顺序和 Gallery 可观察行为。
- Template part 名称、ControlTheme key、伪类和资源 key。
- 旧 template part、事件订阅、Popup/Flyout/Window host 和 collection view 的释放路径。
- Light/Dark、Browser/Desktop 和不同 SizeType 下的主题一致性。
- 控件文档、源码 public surface、Token 类型或生成数据与源码契约的一致性。
- `IsClosing` / `IsClosed` public 状态不得与 internal `MotionExecutionState` 合并；重复调度不得创建并行退出动效。
- `MaxItems <= 0` 必须保持无限语义；Stack 不能通过提前关闭旧项模拟折叠。
- Stack 不能隐式把有限时长改为永久展示，也不能在未 hover 时暂停 scheduler；Gallery 的永久 Stack 示例必须通过
  `Expiration=TimeSpan.Zero` 显式表达。
- template detach、rehost、DestroyAll、用户回调异常与 dispose 均必须释放 scheduler entry、presenter、host 订阅、card owner 与 delegate。

## 10. 测试与验证

推荐验证：

- `CloseMotionExecutionTests` 验证关闭属性变化与模板重套用同时请求退出动效时只启动一次 motion，并只提交一次
  `IsClosed=true`。
- Feedback motion 测试验证 64 DIP 方向、scale 恒等、完整时长 opacity 插值、Ant ease-in-out 参数以及取消后旧 actor
  不提交 completion。
- `FeedbackCardMotionCoordinatorTests` 使用真实 actor 与可控时钟验证六种 Position 的入场中关闭，旧入场清理后退出目标
  保持到完整时长结束，且关闭只完成一次。
- `FeedbackStackPanelTests` 覆盖阈值边界、最新项顺序、Message 背板、hover gap、运行时配置和 Top/Bottom 几何。
- `MessageStackAnimationTests` 用可控动画时钟验证背板在卡片收拢期间淡入、hover 反转连续、内容宽度变化、motion / Stack
  开关，以及空队列和展开队列不被透明背板扩高。
- `FeedbackLifetimeSchedulerTests` 以可控时钟覆盖最近 deadline、剩余时长、普通/Stack 暂停、空闲停表及关闭回调耗时后的重调度；
  `WeakReference` 用例验证 scheduler 保持存活时，最后一批已到期或已在关闭的项也能回收。
- manager 测试覆盖 Stack 开启但未 hover 的有限时长消息保持计时登记且未暂停，以及零时长 Stack 消息不创建 scheduler。
- `FeedbackManagerStackTests` 覆盖无动画批量淘汰的最旧优先顺序，以及关闭回调中的 Dispose、嵌套 DestroyAll 和新增消息；
  `WeakReference` 用例验证 manager dispose 后的 manager、presenter、card 与回调 owner 对象图释放；跨 manager 激活还必须
  覆盖 A/B/A 顺序、Notification 混合宿主、栈顶无操作快路径、单次 collection Move 和零 attach/detach。
- Gallery 行为测试覆盖普通与 Stack 示例 manager 隔离、Stack 控件初值、运行时切换、交替文案、局部 DestroyAll 和 detach 释放。
- 纯文档改动运行 `git diff --check` 并检查相对链接。
- 控件 API 或行为变更运行对应 `tests/AtomUI.Desktop.Controls.Tests` 或专用包测试。
- DataGrid 相关变更运行 `tests/AtomUI.Desktop.Controls.DataGrid.Tests`。
- Gallery 示例或源码片段变更运行 `tests/AtomUIGallery.Tests`。
- AOT、生成器或动态数据路径变更按 Gallery NativeAOT 发布流程验证。

## 11. Semantic Part 接入

Message 公开两个 owner 的 Semantic Part：`MessageCard`（notice）与 `WindowMessageManager`（list）。声明集中在与
owner 同目录的 `MessageCard.SemanticParts.cs` 与 `WindowMessageManager.SemanticParts.cs`，owner 本体保持 partial。
公共契约与逐 Part 说明见 [Message Semantic Part 契约](semantic-part.md)。

### 11.1 Descriptor 与 marker

| Owner | Part | SelectorClass | SelectorRoute | ContractType | 声明位置 |
| --- | --- | --- | --- | --- | --- |
| `MessageCard` | `wrapper` | `semantic-wrapper` | `/template/ .semantic-wrapper` | `DockPanel` | `MessageCardTheme.axaml` 内 `DockPanel#PART_HeaderContainer` |
| `MessageCard` | `icon` | `semantic-icon` | `/template/ .semantic-icon` | `IconPresenter`（`AtomUI.Controls.IconPresenter`） | `MessageCardTheme.axaml` 内 `IconPresenter#PART_IconContent` |
| `MessageCard` | `title` | `semantic-title` | `/template/ .semantic-title` | `Avalonia.Controls.SelectableTextBlock` | `MessageCardTheme.axaml` 内 `SelectableTextBlock#PART_Message` |
| `WindowMessageManager` | `listContent` | `semantic-list-content` | `/template/ .semantic-list-content` | `ItemsControl` | `WindowMessageManagerTheme.axaml` 内 `FeedbackStackPresenter#PART_Items` |

`root` 由生成器隐式加入 descriptor，不要求 `.semantic-root` marker。四个非 root Part 都是 owner 自身
`ControlTheme` 的静态模板节点，因此显式声明 `RuntimeCreated=false`，生成器按 owner 主题资产（derived/本体
Theme.axaml）做 marker 数量与 `ContractType` 兼容性静态校验，无需跨模板豁免。

marker 使用模板静态 class 属性语法书写，值是静态 `True`：

```xml
<DockPanel Name="PART_HeaderContainer" Classes.semantic-wrapper="True" LastChildFill="True">
```

`title` 的节点类型必须与 `ContractType` 精确一致：主题中无前缀的 `SelectableTextBlock` 解析为
`Avalonia.Controls.SelectableTextBlock`；AtomUI 的 `atom:SelectableTextBlock` 是另一类型，二者不可混用，否则
生成器 `ATOMUIGEN033` 类型不兼容校验会拒绝该 Part。

### 11.2 运行时创建路径

Message 没有任何运行时创建的 Part：

- `MessageCard` 由 `WindowMessageManager.Show` 以 `new MessageCard { ... }` 创建，但其模板由自身
  `ControlTheme` 实例化，三个卡片级 marker 都随模板静态就位，root 为隐式 owner。
- `WindowMessageManager` 有两个 public 构造：`WindowMessageManager(TopLevel? host)` 与无参 `WindowMessageManager()`。
  传入 host 时经 `InstallFromTopLevel` 挂到 TopLevel 反馈层并投影安全区外边距；传 `null` 或使用无参构造时控件不安装
  到任何层，作为普通可放置控件由调用方放进自己的视觉树（上游把 list 改为内联容器的等价物），两种路径都在模板应用后
  取得 `PART_Items`；`listContent` marker 静态声明在 manager 模板内。

卡片实例本身不携带任何 semantic class；`Show(IMessage, string[]? classes)` 的 `classes` 参数只追加用户业务 class，不参与
Semantic Part 身份。因此卡片增删、`MaxItems` 清理与超时/手动关闭只影响实例数量，不改变 marker 结构。

### 11.3 生命周期与布局

- MessageCard 模板重套用时重新取得 actor，旧执行取消、旧模板节点释放；marker 随新模板重建。
- manager 的稳定卡片集合与 scheduler 不依赖 presenter 实例。持续 detach 的延后关闭和 `Dispose` 的最终清理
  遵循第 5 节生命周期规则；同轮 host 迁移不清空集合。
- `wrapper` 是 DockPanel，icon 停靠左侧、title 填充，间距来自 `MessageIconMargin`。
- `listContent` 实际为 `FeedbackStackPresenter`，公共 `ContractType` 为 `ItemsControl`。其内部 panel 维护项间距和
  堆叠布局；应用通过生成 Style 定制尺寸、对齐，不能访问内部间距 API。
- `Grid#PART_StackHost.Margin` 绑定 owner `Padding`，默认取 `MessageTopMargin`。六种 Position 在模板应用和属性
  修改时更新，StackHost 按方位紧贴队列，两个静态背板不增加 host 的 extent 或 hover 命中范围。

### 11.4 性能与 AOT

- 四个 marker 在模板初始化时各执行一次 `Classes.Set`，不建立 Binding 或持久订阅。
- 默认主题不消费 `.semantic-*`；未声明用户 Semantic Style 时不创建独立 selector activator。
- descriptor、`StyleType`、Part 常量与 XML namespace 映射全部由生成器静态产生，不引入反射、程序集扫描或运行时
  AXAML 解析。