win_ui_ux_design_skill/references/engineering-validation.md

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 概述
• 标题栏自定义
• NavigationView 标题栏集成
• 使用 XAML 的响应式布局
• ListView 与 GridView
• Windows 应用中的材质
• 无障碍检查清单