win_ui_ux_design_skill/references/adapter-winui3.md

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 数据工作台映射

对“顶部前置操作—中部表格—底部完成任务”的页面，使用统一页面骨架：

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 应用控件
• NavigationView
• TabView
• ItemsView
• 命令系统
• 对话框与浮出控件
• 应用设置指南
• 已归档 WCT DataGrid 状态
• WinUI 3 概述
• 标题栏自定义
• 使用 XAML 的响应式布局
• Windows 应用中的材质
• 无障碍检查清单