# WinUI 工程实现与验证

## 目录

1. 版本与依赖门槛
2. XAML 与状态架构
3. 窗口化与响应式实现
4. 性能与异步行为
5. 实现评审
6. 发布测试矩阵
7. 严重程度模型
8. 官方资料

## 1. 版本与依赖门槛

生成 XAML 或 C# 前：

1. 阅读项目文件、中央软件包属性、目标框架、目标/最低 Windows 版本和已安装软件包。
2. 准确确定 Windows App SDK 和 Windows Community Toolkit 版本。
3. 检查项目是已打包还是未打包，以及是否使用单项目 MSIX。
4. 在当前 Microsoft 文档中验证建议的 API；对于控件，还要在 WinUI 3 Gallery 中验证。
5. 在建议中记录最低版本和回退行为。

WinUI 3 使用 `Microsoft.UI.Xaml`。将使用 `Windows.UI.Xaml`、WinUI 2 Gallery 或 UWP 特有 API 的示例视为迁移参考，而不是可直接复制的代码。

版本敏感指南示例：

- WinUI `TitleBar` 控件需要 Windows App SDK 1.7 或更高版本；
- `SystemBackdropElement` 需要 Windows App SDK 1.6.3 或更高版本；
- Mica 需要 Windows 11，在 Windows 10 回退为纯色主题表面；
- Windows Community Toolkit `DataGrid` 已归档，并非 WCT 8+ 的 WinUI 3 控件。

对于任何第三方控件，记录软件包、版本、许可证、维护状态、支持的 Windows 版本、主题/高对比度行为、UI Automation 支持、键盘模型、本地化、虚拟化和退出方案。

## 2. XAML 与状态架构

- 遵循项目现有的 MVVM 或代码隐藏约定；不要为一个界面引入第二套架构。
- 当同一操作出现在按钮、菜单、上下文菜单和快捷键中时，将用户操作表示为可复用命令。
- 根据场景明确表示视图状态：空闲、加载、内容、空、筛选后为空、错误、离线/过期、权限被拒绝和部分结果。
- 在资源字典中集中管理语义颜色、文本样式、间距、几何、图标大小和动效。
- 需要在应用运行时变化的值使用 `ThemeResource`；仅当不需要运行时主题更新时使用 `StaticResource`。
- 需要自定义 Token 时，在主题字典中放置浅色、深色和高对比度映射。
- 优先使用样式和组合，不要复制完整控件模板。自定义模板将承担所有视觉和无障碍状态的实现责任。
- 一致使用 `x:Bind` 或项目既有的绑定方式。为可编辑值明确绑定模式和更新时间。
- 结构化布局使用 Grid 和弹性尺寸；避免深层嵌套面板，以及会破坏本地化或文本缩放的固定尺寸。
- 让视觉顺序与阅读和 Tab 顺序一致。

不要用 UI 线程调度掩盖不合理的异步所有权。只封送真正需要 UI 线程的最终状态更新，并确保视图仍然存在。

## 3. 窗口化与响应式实现

### 标题栏

保留系统标题按钮和系统菜单。沿应用画布顶部定义拖动区域，将交互式子元素排除在拖动区域外，并测试活动/非活动外观。验证最大化、还原、调整大小、Snap Layouts、触控、右键系统菜单和高对比度。

项目版本支持时，优先使用平台 `TitleBar` 控件。与 `NavigationView` 一起使用时，让一个组件负责后退和窗格切换行为，不要显示重复按钮。

### 响应式布局

从安全的紧凑布局开始，再添加较宽的视觉状态。使用有效窗口/内容宽度。双向测试每个转换并保留：

- 选择和键盘焦点；
- 滚动位置和展开状态；
- 输入和验证状态；
- 命令可用性；
- 无障碍阅读顺序。

如果重排或重新定位已足够，不要在每次调整大小时替换整个可视化树。对昂贵的大小调整工作进行防抖，不要只因为窗口跨越断点就重建数据集合。

### 多窗口

定义所有权、激活、持久化位置、最小尺寸、关闭确认和共享数据生命周期。确保命令作用于活动文档/窗口上下文，并让对话框具有正确的 XamlRoot/所有者。

## 4. 性能与异步行为

- 保持集合虚拟化，并使用真实数据、图像、模板和分组进行测量。
- 在底层自定义 `ItemsRepeater` 前，优先使用 `ListView`、`GridView` 或 `ItemsView` 的行为。
- 按接近渲染尺寸解码图像，避免为缩略图加载全分辨率资源，并取消已回收项目的工作。
- 避免在 UI 线程上执行同步文件、网络、数据库或昂贵的序列化工作。
- 让异步命令具备幂等性，或在工作进行时阻止重复调用。
- 支持取消长时间操作；导航、搜索查询变化或窗口关闭后忽略过期结果。
- 立即提供命令反馈。对接近瞬时完成的工作，可轻微延迟大型骨架屏/进度过渡以避免闪烁，但绝不能让 UI 看起来冻结。
- 安全时在刷新期间保留之前可用的内容；区分刷新和首次加载。
- 尽可能为不透明度和变换设置动画；避免对大型可视化树使用引发布局的动画。
- 将昂贵的次要内容延迟到请求时加载，但没有明确方案时，不要延迟加载键盘顺序或核心任务理解所需的控件。
- 测量启动、导航、调整大小、输入延迟、滚动流畅度、内存增长，以及设备/主题变化后的恢复。

## 5. 实现评审

先检查正确性，再评审视觉润色：

- [ ] 命名空间、API、软件包版本和最低操作系统有效。
- [ ] 项目能够构建，且未在修改范围内引入警告。
- [ ] 命令不会重复提交，失败时保留用户工作。
- [ ] 每个数据界面根据需要具有加载、空、错误和重试行为。
- [ ] 虚拟化、回收和取消能处理生产规模数据。
- [ ] 主题资源在运行时更新，自定义 Token 覆盖高对比度。
- [ ] 布局能够承受紧凑宽度、长字符串、文本缩放和显示缩放。
- [ ] 焦点、选择、无障碍名称、角色、状态和播报正确。
- [ ] 标题按钮、拖动区域、对话框和多窗口所有权行为正确。
- [ ] 破坏性操作使用与后果成比例的撤销或确认。

## 6. 发布测试矩阵

测试代表性组合，而不是只测试一台理想机器：

| 维度 | 最低覆盖范围 |
|---|---|
| Windows | 最低支持的操作系统和当前 Windows 11 |
| 窗口 | 支持的最小尺寸、小 `<=640` epx、中 `641–1007`、大 `>=1008`、贴靠、最大化 |
| 缩放 | 常见的 100%、125%、150%、200% 显示缩放和显示器切换 |
| 文本 | 默认和增大的 Windows 文本大小 |
| 主题 | 浅色、深色、高对比度；透明效果开启和关闭 |
| 输入 | 仅键盘、鼠标，以及产品声明支持时的触控/笔 |
| 辅助技术 | Narrator、放大镜、Accessibility Insights/Inspect |
| 内容 | 空、单项、真实数据、超大数据、长本地化字符串、失败 |
| 环境 | 慢速存储/网络、离线、权限被拒绝、相关时的 RDP 或材质回退 |
| 生命周期 | 适用时的挂起/关闭、重新打开、升级、辅助窗口关闭、崩溃安全的数据恢复 |

自动执行稳定检查，但为 Narrator 流程、焦点可见性、触控舒适度、动效、文案、层级和感知响应速度保留人工评审。

## 7. 严重程度模型

评审设计或实现时使用以下顺序：

| 严重程度 | 定义 | 示例 |
|---|---|---|
| 阻断 | 阻止主要任务、排除某种输入/无障碍方式、丢失数据或使用不可用 API | 键盘陷阱、保存按钮被裁切、假设已归档控件仍存在 |
| 严重 | 导致频繁错误、迷失方向、内容不可访问，或严重的响应式/性能问题 | 焦点返回错误、大型列表未虚拟化、深色模式不可读 |
| 中等 | 降低任务效率，或产生虽有替代方案但不一致的 Windows 行为 | 隐藏上下文命令、空状态薄弱、选择行为不一致 |
| 轻微 | 对任务影响很小的润色问题 | 间距偏差、图标字重不一致、不必要的阴影 |

每项发现都要指出界面/控件、触发条件、用户影响和最小稳健修正方案。避免“让它更现代”等模糊反馈。

## 8. 官方资料

- [WinUI 3 概述](https://learn.microsoft.com/windows/apps/winui/winui3/)
- [标题栏自定义](https://learn.microsoft.com/windows/apps/develop/title-bar?tabs=winui3)
- [NavigationView 标题栏集成](https://learn.microsoft.com/windows/apps/develop/ui/controls/navigationview)
- [使用 XAML 的响应式布局](https://learn.microsoft.com/windows/apps/develop/ui/layouts-with-xaml)
- [ListView 与 GridView](https://learn.microsoft.com/windows/apps/develop/ui/controls/listview-and-gridview)
- [Windows 应用中的材质](https://learn.microsoft.com/windows/apps/develop/ui/materials)
- [无障碍检查清单](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-checklist)