10 KiB
WinUI 控件与桌面端模式
目录
- 选择方法
- 导航与窗口外壳
- 集合与结构化数据
- 输入控件与表单
- 命令与菜单
- 反馈与临时界面
- 常见页面模式
- 控件评审检查清单
- 官方资料
1. 选择方法
根据语义和内置行为选择控件：
- 确定用户是在导航、选择、调用、编辑、比较还是检查。
- 优先选择已经实现预期键盘、焦点、选择、自动化和主题行为的控件。
- 根据准确的 Windows App SDK 或 Toolkit 版本检查可用性。
- 先自定义样式，再考虑模板；仅当交互模型不正确时才替换控件。
- 记录第三方控件的无障碍、本地化、性能、维护和许可成本。
不要仅凭截图选择控件。两个控件可能外观相似，却向键盘和辅助技术公开不同的语义。
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 和依赖项都存在于项目使用的版本中。
- 已定义导航、选择、焦点和后退行为。
- 上下文命令具有无需悬停的访问路径。
- 集合虚拟化和键盘行为得到保留。
- 表单保留输入并提供可操作的验证信息。
- 对话框仅用于真正需要阻塞的决策。
- 已处理加载、空、错误、超时、取消和撤销状态。