winui-app

WinUI 应用

对于需要可靠设置指导、应用引导、现代 Windows UX 设计决策或具体实现模式的 WinUI 3 和 Windows App SDK 工作，请使用此技能。

必需流程

1. 将任务归类为环境/设置、新应用引导、设计、实现、审查或故障排查。
2. 如果任务涉及为 WinUI 准备计算机、检查就绪情况或创建全新应用，请先使用此技能中附带的设置与脚手架流程，然后再开展更广泛的设计、实现或故障排查工作：
   • 如果请求是创建新应用，请选择应用名称。
   • 如果用户提供的名称已是安全的文件夹名称，请使用该名称。
   • 如果用户没有提供名称，请根据请求拟定一个简短的 PascalCase 名称，并说明所选名称。
   • 除非用户要求使用其他位置，否则请在用户当前的工作区中创建项目。
   • 除非用户明确要求覆盖现有文件，否则不要使用 --force。
   • 从技能目录运行附带的 WinGet 配置，以确保相对路径始终为 config.yaml：

winget configure -f config.yaml --accept-configuration-agreements --disable-interactivity

• 将此配置视为用于启用开发人员模式、安装或更新 Visual Studio Community 2026，以及安装 WinUI 开发所需的 Managed Desktop、Universal 和 Windows App SDK C# 组件。
• 继续之前先评估配置执行结果。成功则继续。如果失败，请检查输出，不要猜测。如果 winui 模板已可用且工具链可正常使用，请说明部分失败的情况并继续。如果仍缺少先决条件，请停止并清楚说明阻碍。
• 创建脚手架之前，请确认模板可用：

dotnet new list winui

• 对于仅诊断环境的请求，请说明捆绑的引导程序可能会更改计算机，并在运行前征得确认。如果用户拒绝更改，请使用 references/foundation-environment-audit-and-remediation.md 中的手动验证指南，并在 present、missing、uncertain 和 recommended optional tools 项下概述就绪情况。
• 对于全新应用，使用 dotnet new winui -o <name> 创建脚手架。仅在用户提出要求时添加模板选项。支持的选项：-f|--framework net10.0|net9.0|net8.0、-slnx|--use-slnx、-cpm|--central-pkg-mgmt、-mvvm|--use-mvvm、-imt|--include-mvvm-toolkit、-un|--unpackaged、-nsf|--no-solution-file、--force。不要臆造不受支持的标志。如果用户要求打包行为，请传入 --unpackaged false。否则保留模板默认值。
• 验证新创建的脚手架：确认预期的项目文件存在，并针对生成的 .csproj 运行 dotnet build。
• 根据新创建应用的实际打包模型，通过正确路径启动应用，并确认存在真实的顶层窗口，不要仅依赖启动器进程的退出代码。

3. 阅读 references/_sections.md，然后仅加载与任务匹配的参考文件。
4. 创建或重构应用前，明确打包模型。对于类似 Store 的产品工作流和 Visual Studio 部署/F5 流程，默认使用已打包模式。对于用户希望反复通过命令行构建和运行，或每次更改后直接启动 .exe 的情况，默认使用未打包模式。
5. 遇到诸如 MSB3073 或 XamlCompiler.exe 这样的不透明 XAML 编译器错误时，请阅读 references/foundation-template-first-recovery.md，并针对选定的打包模型，优先简化回当前的 dotnet new winui 脚手架，而不是臆造自定义恢复结构。
6. 对于任何创建或更改 WinUI 应用的工作，请完成一套完整但精简的编辑，然后构建并运行应用，再回复用户。默认执行此操作，即使用户未明确要求验证。如果运行中的应用实例锁定了输出文件，而仍有工作要做，请停止该实例，重新构建、启动并继续验证。工作完成且启动验证成功后，除非用户明确要求不要这样做，否则让最终验证通过的应用实例继续运行，供用户使用。
7. 只有在应用显示出客观的成功信号（例如响应正常的顶层窗口、预期的窗口标题或其他明确的启动行为）后，才能认为启动验证已完成。仅仅创建出进程并不足够。
8. 对于要求、API 预期和平台指南，优先参考 Microsoft Learn。
9. 对于具体的控件用法、外壳组合和设计细节，优先参考 WinUI Gallery。
10. 对于窗口管理、生命周期、通知、部署和自定义控件等场景级 API，优先参考 WindowsAppSDK-Samples。
11. 优先遵循 WinUI 和 Fluent 指南。默认采用原生 WinUI 外壳、控件、交互和控件外观。
12. 对于文档操作、编辑器格式设置、视图切换或页面级工具栏等分组命令区域，应优先使用原生 CommandBar 或其他标准 WinUI 命令区域，而不是用 Grid、StackPanel、Border 或临时拼凑的按钮组构建自定义行。
13. 除非用户明确要求自定义、现有产品设计系统已有要求，或经验证的平台缺口导致没有合适的原生选项，否则不要臆造应用专属控件、专有组件库或自定义外观来替代标准 WinUI 行为。
14. 如有自定义需求，应先组合、模板化或重新设置内置 WinUI 控件和系统资源的样式，再添加 CommunityToolkit 依赖或编写新的自定义控件。
15. 只有在内置 WinUI 控件或辅助工具无法妥善满足需求时，才使用 CommunityToolkit。
16. 默认同时支持浅色和深色模式。单主题输出应作为例外，仅在用户明确要求或现有产品约束的情况下采用。
17. 构建或调整 UI 时，使用适配主题的资源、系统画刷和 WinUI 样式挂钩，避免使用仅适用于浅色或深色模式的硬编码颜色。
18. 对集合布局明确指定滚动所有权。如果页面已经进行纵向滚动，不要假定嵌套的 GridView 或其他拥有滚动功能的集合仍能正确呈现水平海报栏。
19. 除非 Border 能实现其所含控件或父级表面无法提供的独特作用，否则不要在区块、列表或卡片外额外添加 Border 包装。避免“卡片套卡片”的组合，即区块 Border 包裹的子项本身已经以卡片形式呈现。
20. 将响应式设计视为外壳与页面共同承担的问题，而不只是控件缩放问题。应针对宽屏、中等宽度和手机宽度，明确规划导航、内边距、内容密度以及页脚/工具区域的行为，并在宽度变窄时简化或隐藏非必要 UI。

常见路径

请求	首先阅读
检查这台电脑是否可以构建 WinUI 应用	references/foundation-environment-audit-and-remediation.md
安装缺失的 WinUI 先决条件	references/foundation-environment-audit-and-remediation.md
启动新的打包或未打包应用	references/foundation-setup-and-project-selection.md
在依托模板脚手架的同时，从不透明的 XAML 编译器或启动故障中恢复	references/foundation-template-first-recovery.md
构建、运行或验证 WinUI 应用是否实际启动	references/build-run-and-launch-verification.md
查看应用结构、页面、资源和绑定	references/foundation-winui-app-structure.md
选择外壳、导航、标题栏或多窗口模式	references/shell-navigation-and-windowing.md
选择控件或响应式布局模式	references/controls-layout-and-adaptive-ui.md
应用 Mica、主题、排版、图标或 Fluent 样式	references/styling-theming-materials-and-icons.md
改进无障碍、键盘操作或本地化	references/accessibility-input-and-localization.md
诊断响应性或 UI 线程性能	references/performance-diagnostics-and-responsiveness.md
决定是否使用 CommunityToolkit	references/community-toolkit-controls-and-helpers.md
处理生命周期、通知或部署	references/windows-app-sdk-lifecycle-notifications-and-deployment.md
执行审核清单	references/testing-debugging-and-review-checklists.md

环境规则

• 不要猜测机器是否已准备好进行 WinUI 开发。请进行验证。
• 对于全新设置、修复和首个项目脚手架，请使用此技能中捆绑的设置与脚手架流程，而不是委派给其他技能。
• 将此技能目录中的 config.yaml 视为捆绑引导流程的唯一事实来源。
• 对不确定的环境信号，应明确表示不确定，不要视为成功。
• 如果任务仅限于审核，且用户拒绝更改机器，请使用 references/foundation-environment-audit-and-remediation.md 中的手动验证指南，并明确说明不确定的信号，不要暗示已成功。
• 如果缺少 config.yaml，请明确说明，并改用 Microsoft 官方工作流，不要假装捆绑流程存在。
• 将环境就绪情况、打包方式选择和应用启动验证作为彼此独立的检查。通过其中一项并不能证明其他项也已通过。
• 对含糊不清的启动结果应按失败处理。如果应用没有明确打开，请继续调试。
• 创建或编辑 WinUI 应用后，不要在构建成功时就停止。请启动应用、确认客观的启动行为，并在交还控制权前让最终验证过的应用实例保持运行，除非用户明确要求不要运行。

参考规则

• 以 C# 作为主要路径。仅在差异具有实质影响时提及 C++ 或 C++/WinRT。
• 保留现有代码库的约定，不要强行套用通用示例结构。
• 除非用户明确要求单一主题结果，或产品本身已强制使用单一主题，否则应用 UI 默认支持浅色和深色模式。
• 优先使用内置 WinUI 控件和系统样式挂钩，再考虑添加 CommunityToolkit 依赖、自定义控件或应用专属的界面系统。
• 将控件、主题、外壳、滚动、响应性、打包和恢复方面的详细指导放在相应的参考文件中，不要在此处重复这些规则。