opc/win_ui_ux_design_skill
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add Chinese localization

Browse Source
This commit is contained in:
QiuSW
2026-07-18 17:40:25 +08:00
parent 07c63cb565
commit 2ed513bc25
6 changed files with 465 additions and 465 deletions
Download Patch File Download Diff File Expand all files Collapse all files
references/engineering-validation.md
+104 -104
View File
@@ -1,143 +1,143 @@
# WinUI engineering and validation
# WinUI 工程实现与验证
## Contents
## 目录
1. Version and dependency gates
2. XAML and state architecture
3. Windowing and responsive implementation
4. Performance and async behavior
5. Implementation review
6. Release test matrix
7. Severity model
8. Official sources
1. 版本与依赖门槛
2. XAML 与状态架构
3. 窗口化与响应式实现
4. 性能与异步行为
5. 实现评审
6. 发布测试矩阵
7. 严重程度模型
8. 官方资料
## 1. Version and dependency gates
## 1. 版本与依赖门槛
Before generating XAML or C#:
生成 XAML 或 C# 前：
1. Read the project file, central package props, target framework, target/min Windows versions, and installed packages.
2. Identify the Windows App SDK and Windows Community Toolkit versions exactly.
3. Check whether the project is packaged or unpackaged and whether it uses single-project MSIX.
4. Verify the proposed API in current Microsoft documentation and, for controls, the WinUI 3 Gallery.
5. Record minimum-version and fallback behavior in the recommendation.
1. 阅读项目文件、中央软件包属性、目标框架、目标/最低 Windows 版本和已安装软件包。
2. 准确确定 Windows App SDK 和 Windows Community Toolkit 版本。
3. 检查项目是已打包还是未打包，以及是否使用单项目 MSIX。
4. 在当前 Microsoft 文档中验证建议的 API；对于控件，还要在 WinUI 3 Gallery 中验证。
5. 在建议中记录最低版本和回退行为。
Use `Microsoft.UI.Xaml` for WinUI 3. Treat examples using `Windows.UI.Xaml`, WinUI 2 Gallery, or UWP-specific APIs as migration inputs, not copy-ready code.
WinUI 3 使用 `Microsoft.UI.Xaml`。将使用 `Windows.UI.Xaml`、WinUI 2 Gallery 或 UWP 特有 API 的示例视为迁移参考，而不是可直接复制的代码。
Examples of version-sensitive guidance:
版本敏感指南示例：
- the WinUI `TitleBar` control requires Windows App SDK 1.7 or later;
- `SystemBackdropElement` requires Windows App SDK 1.6.3 or later;
- Mica requires Windows 11 and falls back to a solid theme surface on Windows 10;
- Windows Community Toolkit `DataGrid` is archived and not a WCT 8+ WinUI 3 control.
- 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 控件。
For any third-party control, document package, version, license, maintenance status, supported Windows versions, theme/high-contrast behavior, UI Automation support, keyboard model, localization, virtualization, and escape plan.
对于任何第三方控件，记录软件包、版本、许可证、维护状态、支持的 Windows 版本、主题/高对比度行为、UI Automation 支持、键盘模型、本地化、虚拟化和退出方案。
## 2. XAML and state architecture
## 2. XAML 与状态架构
- Follow the project's MVVM or code-behind conventions; do not introduce a second architecture for one screen.
- Represent user actions as reusable commands when the same action appears in buttons, menus, context menus, and accelerators.
- Keep view state explicit: idle, loading, content, empty, filtered empty, error, offline/stale, permission denied, and partial result as applicable.
- Centralize semantic colors, type styles, spacing, geometry, icon sizes, and motion in resource dictionaries.
- Use `ThemeResource` for values that must change while the app is running and `StaticResource` only when runtime theme updates are not required.
- Put light, dark, and high-contrast mappings in theme dictionaries when custom tokens are necessary.
- Prefer styles and composition over copying full control templates. A custom template inherits responsibility for every visual and accessibility state.
- Use `x:Bind` or the project's established binding approach consistently. Make binding mode and update timing explicit for editable values.
- Use Grid and flexible sizing for structured layouts; avoid deep nested panels and fixed sizes that break localization or text scaling.
- Keep visual order aligned with reading and tab order.
- 遵循项目现有的 MVVM 或代码隐藏约定；不要为一个界面引入第二套架构。
- 当同一操作出现在按钮、菜单、上下文菜单和快捷键中时，将用户操作表示为可复用命令。
- 根据场景明确表示视图状态：空闲、加载、内容、空、筛选后为空、错误、离线/过期、权限被拒绝和部分结果。
- 在资源字典中集中管理语义颜色、文本样式、间距、几何、图标大小和动效。
- 需要在应用运行时变化的值使用 `ThemeResource`；仅当不需要运行时主题更新时使用 `StaticResource`。
- 需要自定义 Token 时，在主题字典中放置浅色、深色和高对比度映射。
- 优先使用样式和组合，不要复制完整控件模板。自定义模板将承担所有视觉和无障碍状态的实现责任。
- 一致使用 `x:Bind` 或项目既有的绑定方式。为可编辑值明确绑定模式和更新时间。
- 结构化布局使用 Grid 和弹性尺寸；避免深层嵌套面板，以及会破坏本地化或文本缩放的固定尺寸。
- 让视觉顺序与阅读和 Tab 顺序一致。
Do not write UI-thread dispatching as a substitute for sound async ownership. Marshal only the final state update that truly requires the UI thread and ensure the view is still alive.
不要用 UI 线程调度掩盖不合理的异步所有权。只封送真正需要 UI 线程的最终状态更新，并确保视图仍然存在。
## 3. Windowing and responsive implementation
## 3. 窗口化与响应式实现
### Title bar
### 标题栏
Keep system caption buttons and the system menu. Define a drag region along the top edge, exclude interactive children from drag regions, and test active/inactive appearance. Verify maximize, restore, resize, Snap Layouts, touch, right-click system menu, and high contrast.
保留系统标题按钮和系统菜单。沿应用画布顶部定义拖动区域，将交互式子元素排除在拖动区域外，并测试活动/非活动外观。验证最大化、还原、调整大小、Snap Layouts、触控、右键系统菜单和高对比度。
Prefer the platform `TitleBar` control when the project version supports it. When using `NavigationView` with that control, let one component own back and pane-toggle behavior rather than showing duplicate buttons.
项目版本支持时，优先使用平台 `TitleBar` 控件。与 `NavigationView` 一起使用时，让一个组件负责后退和窗格切换行为，不要显示重复按钮。
### Responsive layout
### 响应式布局
Start with a safe compact layout and add wider visual states. Use effective window/content width. Test each transition in both directions and preserve:
从安全的紧凑布局开始，再添加较宽的视觉状态。使用有效窗口/内容宽度。双向测试每个转换并保留：
- selection and keyboard focus;
- scroll position and expanded state;
- input and validation state;
- command availability;
- accessible reading order.
- 选择和键盘焦点；
- 滚动位置和展开状态；
- 输入和验证状态；
- 命令可用性；
- 无障碍阅读顺序。
Avoid replacing the whole visual tree on every resize if a reflow or reposition is sufficient. Debounce expensive resize-driven work and never rebuild data collections solely because the window crossed a breakpoint.
如果重排或重新定位已足够，不要在每次调整大小时替换整个可视化树。对昂贵的大小调整工作进行防抖，不要只因为窗口跨越断点就重建数据集合。
### Multi-window
### 多窗口
Define ownership, activation, persisted placement, minimum size, close confirmation, and shared data lifetime. Ensure commands act on the active document/window context and that dialogs have the correct XamlRoot/owner.
定义所有权、激活、持久化位置、最小尺寸、关闭确认和共享数据生命周期。确保命令作用于活动文档/窗口上下文，并让对话框具有正确的 XamlRoot/所有者。
## 4. Performance and async behavior
## 4. 性能与异步行为
- Keep collection virtualization enabled and measure with realistic data, images, templates, and grouping.
- Prefer `ListView`, `GridView`, or `ItemsView` behavior before low-level `ItemsRepeater` customization.
- Decode images near their rendered size, avoid loading full-resolution assets for thumbnails, and cancel work for recycled items.
- Avoid synchronous file, network, database, or expensive serialization work on the UI thread.
- Make async commands idempotent or prevent duplicate invocation while work is active.
- Support cancellation for long operations and ignore stale results after navigation, search-query changes, or window close.
- Show immediate command feedback. Delay large skeleton/progress transitions just enough to avoid flicker for near-instant work, while never leaving the UI apparently frozen.
- Keep previous usable content visible during refresh when safe; distinguish refresh from first load.
- Animate opacity and transforms where possible; avoid layout-heavy animation across large trees.
- Defer expensive secondary content until requested, but do not lazy-load controls required for keyboard order or core task comprehension without a plan.
- Measure startup, navigation, resize, input latency, scroll smoothness, memory growth, and recovery from device/theme changes.
- 保持集合虚拟化，并使用真实数据、图像、模板和分组进行测量。
- 在底层自定义 `ItemsRepeater` 前，优先使用 `ListView`、`GridView` 或 `ItemsView` 的行为。
- 按接近渲染尺寸解码图像，避免为缩略图加载全分辨率资源，并取消已回收项目的工作。
- 避免在 UI 线程上执行同步文件、网络、数据库或昂贵的序列化工作。
- 让异步命令具备幂等性，或在工作进行时阻止重复调用。
- 支持取消长时间操作；导航、搜索查询变化或窗口关闭后忽略过期结果。
- 立即提供命令反馈。对接近瞬时完成的工作，可轻微延迟大型骨架屏/进度过渡以避免闪烁，但绝不能让 UI 看起来冻结。
- 安全时在刷新期间保留之前可用的内容；区分刷新和首次加载。
- 尽可能为不透明度和变换设置动画；避免对大型可视化树使用引发布局的动画。
- 将昂贵的次要内容延迟到请求时加载，但没有明确方案时，不要延迟加载键盘顺序或核心任务理解所需的控件。
- 测量启动、导航、调整大小、输入延迟、滚动流畅度、内存增长，以及设备/主题变化后的恢复。
## 5. Implementation review
## 5. 实现评审
Check correctness before visual polish:
先检查正确性，再评审视觉润色：
- [ ] Namespace, APIs, package versions, and minimum OS are valid.
- [ ] The project builds without introducing warnings in the changed scope.
- [ ] Commands cannot double-submit and failures preserve user work.
- [ ] Every data surface has loading, empty, error, and retry behavior as needed.
- [ ] Virtualization, recycling, and cancellation work with production-scale data.
- [ ] Theme resources update at runtime and custom tokens cover high contrast.
- [ ] Layout survives compact width, long strings, text scaling, and display scaling.
- [ ] Focus, selection, accessible names, roles, states, and announcements are correct.
- [ ] Caption controls, drag regions, dialogs, and multi-window ownership behave correctly.
- [ ] Destructive actions use undo or confirmation proportional to consequence.
- [ ] 命名空间、API、软件包版本和最低操作系统有效。
- [ ] 项目能够构建，且未在修改范围内引入警告。
- [ ] 命令不会重复提交，失败时保留用户工作。
- [ ] 每个数据界面根据需要具有加载、空、错误和重试行为。
- [ ] 虚拟化、回收和取消能处理生产规模数据。
- [ ] 主题资源在运行时更新，自定义 Token 覆盖高对比度。
- [ ] 布局能够承受紧凑宽度、长字符串、文本缩放和显示缩放。
- [ ] 焦点、选择、无障碍名称、角色、状态和播报正确。
- [ ] 标题按钮、拖动区域、对话框和多窗口所有权行为正确。
- [ ] 破坏性操作使用与后果成比例的撤销或确认。
## 6. Release test matrix
## 6. 发布测试矩阵
Test representative combinations rather than one happy-path machine:
测试代表性组合，而不是只测试一台理想机器：
| Dimension | Minimum coverage |
| 维度 | 最低覆盖范围 |
|---|---|
| Windows | minimum supported OS plus current Windows 11 |
| Window | supported minimum, small `<=640` epx, medium `641–1007`, large `>=1008`, snapped, maximized |
| Scale | common 100%, 125%, 150%, 200% display scales and monitor transitions |
| Text | default and increased Windows text size |
| Theme | light, dark, high contrast; transparency on and off |
| Input | keyboard only, mouse, touch/pen when claimed |
| Assistive tech | Narrator, Magnifier, Accessibility Insights/Inspect |
| Content | empty, one item, realistic data, very large data, long localized strings, failures |
| Environment | slow storage/network, offline, permission denied, RDP or material fallback where relevant |
| Lifecycle | suspend/close if applicable, reopen, upgrade, secondary-window close, crash-safe data recovery |
| Windows | 最低支持的操作系统和当前 Windows 11 |
| 窗口 | 支持的最小尺寸、小 `<=640` epx、中 `641–1007`、大 `>=1008`、贴靠、最大化 |
| 缩放 | 常见的 100%、125%、150%、200% 显示缩放和显示器切换 |
| 文本 | 默认和增大的 Windows 文本大小 |
| 主题 | 浅色、深色、高对比度；透明效果开启和关闭 |
| 输入 | 仅键盘、鼠标，以及产品声明支持时的触控/笔 |
| 辅助技术 | Narrator、放大镜、Accessibility Insights/Inspect |
| 内容 | 空、单项、真实数据、超大数据、长本地化字符串、失败 |
| 环境 | 慢速存储/网络、离线、权限被拒绝、相关时的 RDP 或材质回退 |
| 生命周期 | 适用时的挂起/关闭、重新打开、升级、辅助窗口关闭、崩溃安全的数据恢复 |
Automate stable checks, but keep human review for Narrator flow, focus visibility, touch comfort, motion, wording, hierarchy, and perceived responsiveness.
自动执行稳定检查，但为 Narrator 流程、焦点可见性、触控舒适度、动效、文案、层级和感知响应速度保留人工评审。
## 7. Severity model
## 7. 严重程度模型
Use this order when reviewing a design or implementation:
评审设计或实现时使用以下顺序：
| Severity | Definition | Examples |
| 严重程度 | 定义 | 示例 |
|---|---|---|
| Blocker | Prevents a primary task, excludes an input/accessibility mode, loses data, or uses an unavailable API | keyboard trap, clipped save button, archived control assumed present |
| Major | Causes frequent error, disorientation, inaccessible content, or severe responsive/performance failure | broken focus return, nonvirtualized large list, unreadable dark mode |
| Moderate | Slows tasks or creates inconsistent Windows behavior with a workaround | hidden contextual command, weak empty state, inconsistent selection |
| Minor | Polish issue with little task impact | spacing drift, inconsistent icon weight, unnecessary shadow |
| 阻断 | 阻止主要任务、排除某种输入/无障碍方式、丢失数据或使用不可用 API | 键盘陷阱、保存按钮被裁切、假设已归档控件仍存在 |
| 严重 | 导致频繁错误、迷失方向、内容不可访问，或严重的响应式/性能问题 | 焦点返回错误、大型列表未虚拟化、深色模式不可读 |
| 中等 | 降低任务效率，或产生虽有替代方案但不一致的 Windows 行为 | 隐藏上下文命令、空状态薄弱、选择行为不一致 |
| 轻微 | 对任务影响很小的润色问题 | 间距偏差、图标字重不一致、不必要的阴影 |
For each finding, cite the screen/control, trigger condition, user impact, and smallest robust correction. Avoid vague feedback such as “make it more modern.”
每项发现都要指出界面/控件、触发条件、用户影响和最小稳健修正方案。避免“让它更现代”等模糊反馈。
## 8. Official sources
## 8. 官方资料
- [WinUI 3 overview](https://learn.microsoft.com/windows/apps/winui/winui3/)
- [Title bar customization](https://learn.microsoft.com/windows/apps/develop/title-bar?tabs=winui3)
- [NavigationView title bar integration](https://learn.microsoft.com/windows/apps/develop/ui/controls/navigationview)
- [Responsive layouts with XAML](https://learn.microsoft.com/windows/apps/develop/ui/layouts-with-xaml)
- [ListView and GridView](https://learn.microsoft.com/windows/apps/develop/ui/controls/listview-and-gridview)
- [Materials in Windows apps](https://learn.microsoft.com/windows/apps/develop/ui/materials)
- [Accessibility checklist](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-checklist)
- [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)