211 lines
15 KiB
Markdown
211 lines
15 KiB
Markdown
# WinUI 3 / Windows App SDK 适配指南
|
||
|
||
## 目录
|
||
|
||
1. 选择方法
|
||
2. 导航与窗口外壳
|
||
3. 集合与结构化数据
|
||
4. 输入控件与表单
|
||
5. 命令与菜单
|
||
6. 反馈与临时界面
|
||
7. 常见页面模式
|
||
8. XAML 工程与版本门槛
|
||
9. 多 Tab 数据工作台映射
|
||
10. 发布验证与评审
|
||
11. 官方资料
|
||
|
||
## 1. 选择方法
|
||
|
||
根据语义和内置行为选择控件：
|
||
|
||
1. 确定用户是在导航、选择、调用、编辑、比较还是检查。
|
||
2. 优先选择已经实现预期键盘、焦点、选择、自动化和主题行为的控件。
|
||
3. 根据准确的 Windows App SDK 或 Toolkit 版本检查可用性。
|
||
4. 先自定义样式，再考虑模板；仅当交互模型不正确时才替换控件。
|
||
5. 记录第三方控件的无障碍、本地化、性能、维护和许可成本。
|
||
|
||
不要仅凭截图选择控件。两个控件可能外观相似，却向键盘和辅助技术公开不同的语义。
|
||
|
||
## 2. 导航与窗口外壳
|
||
|
||
| 意图 | 使用 | 避免 |
|
||
|---|---|---|
|
||
| 应用顶级目标位置 | `NavigationView` | 缺少 Windows 导航行为的自定义侧栏 |
|
||
| 少量静态同级视图 | `SelectorBar` 或适合内容的简单选择器 | 用文档式标签页表示无关目标位置 |
|
||
| 打开的文档或可关闭工作区 | `TabView` | 让 `NavigationView` 项目伪装成文档 |
|
||
| 分层位置路径 | `BreadcrumbBar` | 拼接文本和分隔符 |
|
||
| 分层数据 | `TreeView` | 递归嵌套 `ListView` 控件 |
|
||
| 列表与选中项 | 列表/详情模式 | 强制在模态窗口中显示所有详情 |
|
||
|
||
保持顶级导航浅、稳定且带标签。根据内容宽度、本地化、增长空间、窗口宽度和命令密度选择顶部或左侧 `NavigationView`，不要使用统一的项目数量规则。除非体验需要明确的自定义状态，否则让 `PaneDisplayMode="Auto"` 和控件阈值处理常见自适应行为。
|
||
|
||
仅当页面导航和后退堆栈符合体验时使用 `Frame`。后退导航时保留选择、筛选、滚动和未保存状态。没有可返回位置时不要显示后退按钮。
|
||
|
||
对于 Windows App SDK 1.7 或更高版本，优先使用 WinUI `TitleBar` 控件自定义标题栏，并与 `NavigationView` 协调。对于更早版本，使用受支持的 `Window.ExtendsContentIntoTitleBar` 和 `Window.SetTitleBar` 方案。保留标题按钮、拖动区域、系统菜单访问、活动/非活动外观和调整大小行为。
|
||
|
||
仅为真正并行或可分离的工作使用附加窗口，不要用它替代信息层级。定义所有者、激活、位置、关闭行为和状态同步。
|
||
|
||
## 3. 集合与结构化数据
|
||
|
||
| 需求 | 首选方案 | 说明 |
|
||
|---|---|---|
|
||
| 以文本为主的可选择集合 | `ListView` | 具有成熟的选择、分组、重排和虚拟化行为 |
|
||
| 统一的视觉磁贴 | `GridView` | 使用支持虚拟化的项目面板 |
|
||
| 灵活的列表/网格/自定义布局 | `ItemsView` | 支持布局切换并内置选择和无障碍的现代组合方式 |
|
||
| 底层自定义虚拟化布局 | `ItemsRepeater` | 选择、调用、焦点和自动化可能需要额外工程工作 |
|
||
| 层级 | `TreeView` | 支持单选和多选 |
|
||
| 简单只读行列 | 模板化 `ListView`/`ItemsView` | 提供表头和无障碍关系 |
|
||
| 完整的电子表格式编辑 | 经验证且持续维护的表格组件 | 验证键盘、UI Automation、虚拟化、排序、调整大小和编辑 |
|
||
|
||
不要用“20 行”等固定阈值决定使用 `ListView` 还是数据表格。应根据列关系、比较、排序、编辑、选择、虚拟化和键盘导航来选择。
|
||
|
||
Windows Community Toolkit `DataGrid` 文档已归档；它不是当前 WCT 8+ 的 WinUI 3 控件。对于新项目，评估当前仍在维护的方案，例如 Toolkit Labs `DataTable` 或社区 `WinUI.TableView`，并明确验证其成熟度和要求。不得静默引入依赖。
|
||
|
||
为大型或无上限集合保持虚拟化。未经测量，不要用通用面板替换虚拟化面板。提供加载、空、筛选后为空、部分数据、过期数据和加载失败状态。
|
||
|
||
选择行为应支持 Windows 约定：单击/点击选择单项，Ctrl 独立选择，Shift 范围选择，控件支持时用 Space 选择焦点项，并让可见选择状态与键盘焦点相互独立。
|
||
|
||
## 4. 输入控件与表单
|
||
|
||
| 意图 | 使用 | 重要区别 |
|
||
|---|---|---|
|
||
| 短文本或多行纯文本 | `TextBox` | 多行使用 `AcceptsReturn` 和合适的换行方式 |
|
||
| 富格式编辑 | `RichEditBox` | 不要用于普通多行文本 |
|
||
| 数值 | `NumberBox` | 仍需验证范围和领域约束 |
|
||
| 日期 | `DatePicker` 或 `CalendarDatePicker` | 在常驻选择器和紧凑日历输入间选择 |
|
||
| 时间 | `TimePicker` | 尊重区域格式 |
|
||
| 立即生效的开/关设置 | `ToggleSwitch` | 清楚标记状态 |
|
||
| 表单或批量列表中的选择 | `CheckBox` | 支持选中、未选中和可选的不确定语义 |
|
||
| 从少量可见选项中单选 | 分组的 `RadioButton` 控件 | 当空间或选项数量降低扫描效率时使用 `ComboBox` |
|
||
| 从紧凑列表中单选 | `ComboBox` | 不支持多选 |
|
||
| 多选 | `ListView`、`ItemsView`、复选列表或专用浮出控件 | 让用户能够复查已选值 |
|
||
| 有界连续值 | `Slider` | 显示当前值，并在需要时允许精确键盘输入 |
|
||
| 评分 | `RatingControl` | 仅用于真实的评分语义 |
|
||
|
||
将标签放在窄宽度、文本缩放和本地化后仍能保持清晰扫描顺序的位置。需要把独立标签关联到字段时，使用 `AutomationProperties.LabeledBy`。用文字而不是仅用颜色标记必填字段。输入前提供约束，在失焦或提交等合适边界验证，并同时说明问题和恢复方式。
|
||
|
||
不要在不说明未满足要求的情况下禁用主要操作。验证或网络失败时保留用户输入。对于长表单，定义草稿、取消、关闭和未保存更改行为。
|
||
|
||
## 5. 命令与菜单
|
||
|
||
使用 `StandardUICommand`、`XamlUICommand` 或项目的 `ICommand` 模式，只建模一次命令，再通过合适的界面公开。
|
||
|
||
| 界面 | 使用方式 |
|
||
|---|---|
|
||
| 主要页面命令 | 可见的 `Button` 或 `CommandBar` 命令 |
|
||
| 以文档为中心的应用菜单 | `MenuBar` |
|
||
| 对象特定命令 | `ContextFlyout`；富命令有帮助时优先 `CommandBarFlyout` |
|
||
| 额外或低频命令 | 次要 `CommandBar` 命令或溢出菜单 |
|
||
| 拆分默认/备选操作 | `SplitButton` |
|
||
| 仅菜单操作集 | `DropDownButton` 或 `MenuFlyout` |
|
||
| 高级用户路径 | `KeyboardAccelerator` 加工具提示/菜单快捷键文本 |
|
||
|
||
让关键命令无需悬停或手势即可发现。在上下文菜单中包含相关上下文命令，使指针、键盘、触控和辅助技术用户都有通用路径。使用访问键实现高效的 Alt 导航，使用快捷键执行重复操作。
|
||
|
||
使用“删除 3 个文件”等具体操作标签，不要只写“确定”。让破坏性命令在空间上分离并显示后果。操作常见且可恢复时提供撤销。
|
||
|
||
## 6. 反馈与临时界面
|
||
|
||
| 需求 | 使用 | 指南 |
|
||
|---|---|---|
|
||
| 内联状态、警告或可恢复错误 | `InfoBar` | 需要操作时保持可见；不要假设会自动消失 |
|
||
| 锚定到 UI 的首次使用教学 | `TeachingTip` | 谨慎展示，不要用于常规状态 |
|
||
| 阻塞式决策或不可逆后果 | `ContentDialog` | 仅当应用无法安全选择或无法提供撤销时询问 |
|
||
| 上下文选项或详情 | `Flyout` | 可解除，并与来源建立连接 |
|
||
| 确定性工作 | `ProgressBar` | 报告有意义的进度 |
|
||
| 不确定的短时等待 | `ProgressRing` | 保持周围上下文稳定 |
|
||
| 长时间/后台工作 | 页面内进度加取消/后台处理入口 | 不要让用户困在旋转指示器中 |
|
||
|
||
对于频繁的破坏性操作，优先立即完成并提供撤销，而不是反复确认。对于真正具有破坏性的对话框，让标题直接说明决策，并使用明确的按钮动词。
|
||
|
||
每个异步界面都需要成功、失败、超时、重试或替代路径；取消有意义时还需要取消策略。避免白屏和布局跳动；保留之前的内容或使用形状匹配的占位内容。
|
||
|
||
## 7. 常见页面模式
|
||
|
||
### 应用外壳
|
||
|
||
使用标题栏、顶级导航、页面标题、上下文命令和内容 Frame 或 Presenter。让标题栏拖动区域与交互式导航和搜索控件分离。
|
||
|
||
### 设置
|
||
|
||
仅在验证已安装 Toolkit 软件包后使用 Windows Community Toolkit `SettingsCard` 和 `SettingsExpander`。按用户意图分组，为不明显的后果添加说明，并让可恢复偏好立即生效。仅当更改代价高、延迟生效、涉及安全或无法安全恢复时使用“应用”、重启或确认。
|
||
|
||
### 列表/详情
|
||
|
||
在宽窗口中同时显示列表和详情。在紧凑窗口中于两者间导航，同时保留列表选择、滚动、筛选和键盘焦点。定义选中项被删除、被筛选掉或加载失败时的行为。
|
||
|
||
### 表单或编辑器
|
||
|
||
使用可预测的扫描路径，将相关控件分组，保持操作对齐一致，并为验证预留空间。明确保存状态：已保存、正在保存、未保存、冲突、离线或失败。为文档式工作提供撤销/重做。
|
||
|
||
### 空状态与错误状态
|
||
|
||
说明发生了什么、已知时说明原因，以及用户下一步能做什么。区分空状态：首次使用为空、筛选后为空、权限被拒绝、断开连接和加载失败是不同问题。
|
||
|
||
## 8. XAML 工程与版本门槛
|
||
|
||
生成 XAML 或 C# 前，读取项目文件、中央软件包属性、目标框架、Windows App SDK 与 Toolkit 版本、最低 Windows 版本及打包模型。WinUI 3 使用 `Microsoft.UI.Xaml`；`Windows.UI.Xaml`、WinUI 2 Gallery 和 UWP 示例只能作为迁移参考，不能直接复制。
|
||
|
||
版本敏感能力必须注明最低版本与回退策略。例如，WinUI `TitleBar` 控件需要 Windows App SDK 1.7 或更高版本，`SystemBackdropElement` 需要 1.6.3 或更高版本，Mica 在 Windows 10 上必须回退为可读的纯色主题表面。任何第三方控件还要记录版本、许可证、维护状态、主题、高对比度、UI Automation、键盘、虚拟化和退出方案。
|
||
|
||
- 遵循项目既有 MVVM 或代码隐藏约定，不为一个页面引入第二套架构。
|
||
- 用可复用命令统一按钮、菜单、上下文菜单和快捷键；异步命令需防重复提交。
|
||
- 在资源字典中集中管理语义颜色、文本、间距、圆角、图标与动效；运行时主题值使用 `ThemeResource`。
|
||
- 优先使用样式与组合。替换完整控件模板意味着同时承担视觉状态、输入、焦点和无障碍责任。
|
||
- 使用 `Grid` 与弹性尺寸构造响应式布局；避免深层嵌套和无法承受本地化、文本缩放的固定尺寸。
|
||
- 保持集合虚拟化，不在 UI 线程执行同步文件、网络、数据库或昂贵序列化工作。
|
||
- 长任务支持取消；导航、查询变化或窗口关闭后忽略过期结果，只把必要的最终状态更新封送回 UI 线程。
|
||
|
||
标题栏必须保留系统标题按钮、系统菜单和有效拖动区域，并验证最大化、还原、调整大小、Snap Layouts、活动/非活动、高对比度及右键系统菜单。多窗口必须明确所有者、激活、持久化位置、共享数据生命周期和对话框的 `XamlRoot`。
|
||
|
||
## 9. 多 Tab 数据工作台映射
|
||
|
||
对“顶部前置操作—中部表格—底部完成任务”的页面，使用统一页面骨架：
|
||
|
||
```text
|
||
Grid Rows="Auto,Auto,*,Auto,Auto"
|
||
页面标题/说明
|
||
CommandBar：导入、配置、刷新、筛选
|
||
状态区：InfoBar、来源摘要、校验结果
|
||
数据区：虚拟化列表/表格、加载/空/错误覆盖层
|
||
底部操作区：选择摘要、次要操作、主要生成/更新/提交
|
||
```
|
||
|
||
静态功能切换使用 `SelectorBar` 或适合内容的选择器；可关闭、可重排、具有独立工作状态的文档工作区使用 `TabView`。每个标签以稳定 ID 保存数据来源、筛选、排序、选择、勾选、滚动、验证、任务和未保存状态，不能以可见标题作为身份。
|
||
|
||
文件选择使用与项目打包模型和 Windows App SDK 版本相符的文件选择器，并在编码前验证窗口初始化要求。进行中状态优先在页面内显示；可恢复错误用 `InfoBar`；只有不可安全自动决定、不可逆或代价高的操作才使用 `ContentDialog`。普通成功以内联状态、状态栏或非阻塞通知反馈，避免统一弹出成功对话框。
|
||
|
||
## 10. 发布验证与评审
|
||
|
||
- [ ] 每个控件都匹配用户意图并公开正确语义。
|
||
- [ ] 所有 API 和依赖项都存在于项目使用的版本中。
|
||
- [ ] 已定义导航、选择、焦点和后退行为。
|
||
- [ ] 上下文命令具有无需悬停的访问路径。
|
||
- [ ] 集合虚拟化和键盘行为得到保留。
|
||
- [ ] 表单保留输入并提供可操作的验证信息。
|
||
- [ ] 对话框仅用于真正需要阻塞的决策。
|
||
- [ ] 已处理加载、空、错误、超时、取消和撤销状态。
|
||
- [ ] 主题资源可运行时更新，并覆盖浅色、深色和高对比度。
|
||
- [ ] 标题按钮、拖动区域、窗口所有权和对话框 `XamlRoot` 正确。
|
||
- [ ] 生产规模数据下的虚拟化、回收、取消和过期结果处理有效。
|
||
|
||
至少验证最低支持 Windows 与当前 Windows 11、紧凑/中等/宽窗口、贴靠和最大化、100%/125%/150%/200% 缩放、默认与增大文本、浅色/深色/高对比度、透明效果开关、键盘/鼠标及声明支持的触控、Narrator、真实与超大数据、空/错误/权限拒绝，以及辅助窗口关闭和恢复。自动测试不能替代焦点、播报、动效、文案和感知响应速度的人工评审。
|
||
|
||
按以下优先级报告问题：阻断（主要任务、数据、安全或无障碍不可用）、严重（频繁错误或主要性能/响应式问题）、中等（效率和平台一致性下降）、轻微（低影响视觉润色）。每项必须指出触发条件、用户影响和最小稳健修正。
|
||
|
||
## 11. 官方资料
|
||
|
||
- [Windows 应用控件](https://learn.microsoft.com/windows/apps/develop/ui/controls/)
|
||
- [NavigationView](https://learn.microsoft.com/windows/apps/develop/ui/controls/navigationview)
|
||
- [TabView](https://learn.microsoft.com/windows/apps/develop/ui/controls/tab-view)
|
||
- [ItemsView](https://learn.microsoft.com/windows/apps/develop/ui/controls/itemsview)
|
||
- [命令系统](https://learn.microsoft.com/windows/apps/develop/ui/controls/commanding)
|
||
- [对话框与浮出控件](https://learn.microsoft.com/windows/apps/design/controls/dialogs-and-flyouts/)
|
||
- [应用设置指南](https://learn.microsoft.com/windows/apps/design/app-settings/guidelines-for-app-settings)
|
||
- [已归档 WCT DataGrid 状态](https://learn.microsoft.com/dotnet/communitytoolkit/archive/windows/datagrid)
|
||
- [WinUI 3 概述](https://learn.microsoft.com/windows/apps/winui/winui3/)
|
||
- [标题栏自定义](https://learn.microsoft.com/windows/apps/develop/title-bar?tabs=winui3)
|
||
- [使用 XAML 的响应式布局](https://learn.microsoft.com/windows/apps/develop/ui/layouts-with-xaml)
|
||
- [Windows 应用中的材质](https://learn.microsoft.com/windows/apps/develop/ui/materials)
|
||
- [无障碍检查清单](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-checklist)
|