win_ui_ux_design_skill/references/controls-and-patterns.md

# WinUI 控件与桌面端模式

## 目录

1. 选择方法
2. 导航与窗口外壳
3. 集合与结构化数据
4. 输入控件与表单
5. 命令与菜单
6. 反馈与临时界面
7. 常见页面模式
8. 控件评审检查清单
9. 官方资料

## 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. 控件评审检查清单

- [ ] 每个控件都匹配用户意图并公开正确语义。
- [ ] 所有 API 和依赖项都存在于项目使用的版本中。
- [ ] 已定义导航、选择、焦点和后退行为。
- [ ] 上下文命令具有无需悬停的访问路径。
- [ ] 集合虚拟化和键盘行为得到保留。
- [ ] 表单保留输入并提供可操作的验证信息。
- [ ] 对话框仅用于真正需要阻塞的决策。
- [ ] 已处理加载、空、错误、超时、取消和撤销状态。

## 9. 官方资料

- [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)