winui-app

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

WinUI App

WinUI 应用

Use this skill for WinUI 3 and Windows App SDK work that needs grounded setup guidance, app bootstrap, modern Windows UX decisions, or concrete implementation patterns.

当你需要可靠的配置指南、应用启动模板、现代化Windows UX设计决策或是具体实现模式来完成WinUI 3和Windows App SDK相关工作时，可以使用本技能。

Required Flow

必要流程

Classify the task as environment/setup, new-app bootstrap, design, implementation, review, or troubleshooting.
If the task is about preparing a machine for WinUI, auditing readiness, or creating a brand new app, start with the bundled setup-and-scaffold flow in this skill before broader design, implementation, or troubleshooting work:
- Pick the app name when the request is for a new app.
- Use the exact name the user gave when it is already a safe folder name.
- If the user did not give a name, derive a short PascalCase name from the request and state what you chose.
- Create the project in the user's current workspace unless they asked for another location.
- Do not use
```
--force
```
  unless the user explicitly asked to overwrite existing files.
- Run the bundled WinGet configuration from the skill directory so the relative path stays exactly
```
config.yaml
```
  :

powershell

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

Treat the configuration as intended to enable Developer Mode, install or update Visual Studio Community 2026, and install the Managed Desktop, Universal, and Windows App SDK C# components needed for WinUI development.
Assess the configuration result before continuing. Continue on success. If it fails, inspect the output instead of guessing. If the
```
winui
```
template is already available and the toolchain is usable, note the partial failure and continue. If prerequisites are still missing, stop and report the blocker clearly.
Verify the template is available before scaffolding:

powershell

dotnet new list winui

For diagnostics-only environment requests, explain that the bundled bootstrap may change the machine and get confirmation before running it. If the user declines changes, use the manual verification guidance in
```
references/foundation-environment-audit-and-remediation.md
```
and summarize readiness under
```
present
```
,
```
missing
```
,
```
uncertain
```
, and
```
recommended optional tools
```
.
For a brand new app, scaffold with
```
dotnet new winui -o <name>
```
. Add template options only when the user asked for them. Supported options:
```
-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
```
. Do not invent unsupported flags. If the user asks for packaged behavior, pass
```
--unpackaged false
```
. Otherwise keep the template default.
Verify a new scaffold by confirming the expected project file exists and running
```
dotnet build
```
against the generated
```
.csproj
```
.
Launch a newly scaffolded app through the correct path for its actual packaging model and confirm there is a real top-level window instead of relying only on the launcher process exit code.

Read
```
references/_sections.md
```
, then load only the reference files that match the task.
Make the packaging model explicit before creating or refactoring the app. Default to packaged for Store-like product workflows and Visual Studio deploy/F5 flows. Default to unpackaged when the user expects repeatable CLI build-and-run loops or direct
```
.exe
```
launches after each change.
When the task is an opaque XAML compiler failure such as
```
MSB3073
```
or
```
XamlCompiler.exe
```
, read
```
references/foundation-template-first-recovery.md
```
and simplify back toward the current
```
dotnet new winui
```
scaffold for the chosen packaging model before inventing custom recovery structure.
For any work that creates or changes a WinUI app, make a complete but minimal edit set, then build the app and run it before responding to the user. Do this by default even when the user did not explicitly ask for verification. If a running app instance locks the output while more work remains, stop it, rebuild, relaunch, and continue verification. When the work is complete and launch verification succeeds, leave the final verified app instance running for the user unless they explicitly asked you not to.
Treat launch verification as incomplete until the app shows objective success signals such as a responsive top-level window, expected window title, or other clear startup behavior. A spawned process by itself is not enough.
Prefer Microsoft Learn for requirements, API expectations, and platform guidance.
Prefer WinUI Gallery for concrete control usage, shell composition, and design details.
Prefer WindowsAppSDK-Samples for scenario-level APIs such as windowing, lifecycle, notifications, deployment, and custom controls.
Build toward WinUI and Fluent guidance first. Treat native WinUI shells, controls, interactions, and control chrome as the default implementation path.
For grouped command surfaces such as document actions, editor formatting, view toggles, or page-level toolbars, favor a native
```
CommandBar
```
or other stock WinUI command surface before building a custom row with
```
Grid
```
,
```
StackPanel
```
,
```
Border
```
, or ad hoc button groupings.
Do not invent app-specific controls, bespoke component libraries, or custom chrome to replace stock WinUI behavior unless the user explicitly asks for that customization, the existing product design system already requires it, or a verified platform gap leaves no clean native option.
When customization is needed, first compose, template, or restyle built-in WinUI controls and system resources before adding CommunityToolkit dependencies or authoring a new custom control.
Use CommunityToolkit only when built-in WinUI controls or helpers do not cover the need cleanly.
Support both light and dark mode by default. Treat single-theme output as an exception that requires an explicit user request or an existing product constraint.
Use theme-aware resources, system brushes, and WinUI styling hooks instead of hard-coded light-only or dark-only colors when building or revising UI.
Make scroll ownership explicit for collection layouts. When a page already scrolls vertically, do not assume a nested
```
GridView
```
or other scroll-owning collection will still render a horizontal poster rail correctly.
Do not add extra
```
Border
```
wrappers around sections, lists, or cards unless the border is doing distinct work that the contained control or parent surface does not already provide. Avoid "double-card" compositions where a section
```
Border
```
wraps child items that already render as cards.
Treat responsiveness as a shell-plus-page problem, not only a control-resize problem. Plan explicit wide, medium, and phone-width behavior for navigation, padding, content density, and footer/tool regions, and simplify or hide nonessential UI as width shrinks.

将任务归类为环境/配置、新应用启动、设计、实现、评审或问题排查。
如果任务是为设备配置WinUI开发环境、审计环境就绪状态或是创建全新应用，在开展后续设计、实现或问题排查工作前，先使用本技能内置的配置与项目初始化流程：
- 当需求是创建新应用时选定应用名称。
- 如果用户提供的名称已经是合法的文件夹名称，直接使用该名称。
- 如果用户未提供名称，从需求中提取一个简短的PascalCase格式名称，并告知用户你选定的名称。
- 除非用户指定其他路径，否则在用户当前工作区创建项目。
- 除非用户明确要求覆盖现有文件，否则不要使用
```
--force
```
  参数。
- 运行本技能目录下内置的WinGet配置文件，保持相对路径为
```
config.yaml
```
  ：

powershell

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

该配置的作用是启用开发者模式、安装或更新Visual Studio Community 2026，以及安装WinUI开发所需的托管桌面、通用平台和Windows App SDK C#组件。
继续后续操作前先评估配置结果，配置成功则继续。如果配置失败，检查输出信息而非盲目猜测。如果
```
winui
```
模板已可用且工具链可正常使用，说明配置部分失败，可以继续操作。如果仍缺少必要依赖，停止操作并清晰告知用户阻碍项。
初始化项目前验证模板是否可用：

powershell

dotnet new list winui

对于仅诊断环境的需求，先告知用户内置的启动流程可能会修改设备配置，获得用户确认后再运行。如果用户拒绝修改设备，使用
```
references/foundation-environment-audit-and-remediation.md
```
中的手动验证指南，按「已就绪」、「缺失」、「不确定」、「推荐的可选工具」分类汇总环境准备状态。
对于全新应用，使用
```
dotnet new winui -o <名称>
```
初始化项目。仅当用户明确要求时添加模板参数，支持的参数包括：
```
-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
```
来验证新项目初始化是否成功。
根据应用实际的打包模型使用正确路径启动新初始化的应用，确认存在正常的顶层窗口，不要仅依赖启动进程的退出代码判断是否启动成功。

阅读
```
references/_sections.md
```
，仅加载与任务匹配的参考文件。
创建或重构应用前明确打包模型：面向应用商店类产品流程和Visual Studio部署/F5流程默认使用打包模式；当用户需要可复现的CLI构建运行循环或是每次修改后直接启动
```
.exe
```
时，默认使用非打包模式。
如果任务是处理无明确报错的XAML编译器故障，比如
```
MSB3073
```
或
```
XamlCompiler.exe
```
相关错误，先阅读
```
references/foundation-template-first-recovery.md
```
，回退到当前
```
dotnet new winui
```
对应打包模型的初始化模板结构，不要自行设计自定义修复结构。
对于任何创建或修改WinUI应用的工作，先提交完整且最小的修改集，然后构建并运行应用后再回复用户。即使用户没有明确要求验证，也默认执行该流程。如果仍有工作待完成时运行的应用实例锁定了输出文件，停止应用、重新构建、重新启动后继续验证。当工作完成且启动验证通过后，保持最终验证通过的应用实例运行，除非用户明确要求不要运行。
只有当应用出现明确的成功信号（比如响应正常的顶层窗口、符合预期的窗口标题、其他清晰的启动行为）时，才判定启动验证完成，仅生成进程不足以判定启动成功。
优先参考Microsoft Learn获取需求、API预期行为和平台指南。
优先参考WinUI Gallery获取具体的控件用法、shell组合和设计细节。
优先参考WindowsAppSDK-Samples获取场景级API用法，比如窗口管理、生命周期、通知、部署和自定义控件相关内容。
优先遵循WinUI和Fluent设计指南，默认使用原生WinUI shell、控件、交互和控件外观作为实现路径。
对于分组命令界面，比如文档操作、编辑器格式化、视图切换或是页面级工具栏，优先使用原生
```
CommandBar
```
或其他内置WinUI命令组件，不要自行使用
```
Grid
```
、
```
StackPanel
```
、
```
Border
```
或临时按钮组构建自定义行。
不要虚构应用专属控件、定制组件库或自定义外观来替代内置WinUI行为，除非用户明确要求自定义、现有产品设计系统已有相关要求，或是已验证存在平台缺口，没有合适的原生选项。
需要自定义时，先对内置WinUI控件和系统资源进行组合、模板化或重写样式，再考虑添加CommunityToolkit依赖或是开发新的自定义控件。
仅当内置WinUI控件或辅助工具无法清晰满足需求时，再使用CommunityToolkit。
默认同时支持浅色和深色模式，仅当用户明确要求或现有产品存在约束时，才使用单主题输出。
构建或修改UI时，使用主题感知资源、系统画笔和WinUI样式钩子，不要硬编码仅适用于浅色或深色模式的颜色。
明确集合布局的滚动归属。如果页面已经支持垂直滚动，不要默认嵌套的
```
GridView
```
或其他自带滚动的集合组件可以正常渲染横向海报栏。
不要为区块、列表或卡片额外添加
```
Border
```
包裹，除非该边框能提供内部控件或父层表面没有的明确作用。避免出现区块
```
Border
```
包裹本身已经是卡片样式的子元素的「双重卡片」结构。
把响应式适配视为shell加页面的共同问题，而不仅是控件缩放问题。为导航、内边距、内容密度、页脚/工具区域明确规划宽屏、中屏、手机宽度下的行为，宽度缩小时简化或隐藏非必要UI。

Common Routes

常见场景指引

Request	Read first
Check whether this PC can build WinUI apps	`references/foundation-environment-audit-and-remediation.md`
Install missing WinUI prerequisites	`references/foundation-environment-audit-and-remediation.md`
Start a new packaged or unpackaged app	`references/foundation-setup-and-project-selection.md`
Recover from opaque XAML compiler or startup failures while staying anchored to the template scaffold	`references/foundation-template-first-recovery.md`
Build, run, or verify that a WinUI app actually launched	`references/build-run-and-launch-verification.md`
Review app structure, pages, resources, and bindings	`references/foundation-winui-app-structure.md`
Choose shell, navigation, title bar, or multi-window patterns	`references/shell-navigation-and-windowing.md`
Choose controls or responsive layout patterns	`references/controls-layout-and-adaptive-ui.md`
Apply Mica, theming, typography, icons, or Fluent styling	`references/styling-theming-materials-and-icons.md`
Improve accessibility, keyboarding, or localization	`references/accessibility-input-and-localization.md`
Diagnose responsiveness or UI-thread performance	`references/performance-diagnostics-and-responsiveness.md`
Decide whether to use CommunityToolkit	`references/community-toolkit-controls-and-helpers.md`
Handle lifecycle, notifications, or deployment	`references/windows-app-sdk-lifecycle-notifications-and-deployment.md`
Run a review checklist	`references/testing-debugging-and-review-checklists.md`

需求	优先参考文档
检查当前PC是否可以构建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`
选择shell、导航、标题栏或多窗口模式	`references/shell-navigation-and-windowing.md`
选择控件或响应式布局模式	`references/controls-layout-and-adaptive-ui.md`
应用云母效果、主题、排版、图标或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`

Environment Rules

环境规则

Do not guess whether the machine is ready for WinUI development. Verify it.
Use the bundled setup-and-scaffold flow in this skill for fresh setup, remediation, and first-project scaffolding instead of delegating to another skill.
Treat
```
config.yaml
```
in this skill directory as the bundled bootstrap source of truth.
Treat uncertain environment signals as uncertain, not as success.
If the task is audit-only and the user declines machine changes, use the manual verification guidance in
```
references/foundation-environment-audit-and-remediation.md
```
and keep uncertain signals explicit instead of implying success.
If
```
config.yaml
```
is missing, say so clearly and fall back to the official Microsoft workflow instead of pretending the bundled path exists.
Keep environment readiness, packaging choice, and application startup verification as separate checks. Passing one does not prove the others.
Fail closed on ambiguous launch results. If the app did not clearly open, keep debugging.
After creating or editing a WinUI app, do not stop at a successful build. Launch the app, confirm objective startup behavior, and leave the final verified app instance running before returning control to the user unless they explicitly say not to run it.

不要猜测设备是否已就绪可用于WinUI开发，要进行验证。
全新配置、修复环境和首次项目初始化时使用本技能内置的配置与项目初始化流程，不要调用其他技能。
把本技能目录下的
```
config.yaml
```
作为内置启动配置的唯一可信源。
不确定的环境信号就标记为不确定，不要判定为成功。
如果任务仅为环境审计且用户拒绝修改设备，使用
```
references/foundation-environment-audit-and-remediation.md
```
中的手动验证指南，明确标记不确定的信号，不要暗示配置成功。
如果
```
config.yaml
```
缺失，明确告知用户，回退到微软官方工作流，不要假装内置路径存在。
把环境就绪状态、打包选择、应用启动验证作为独立检查项，一项通过不代表其他项也正常。
启动结果不明确时判定为失败，如果应用没有明确打开，继续调试。
创建或修改WinUI应用后，不要仅停留在构建成功的阶段。启动应用、确认明确的启动行为，保持最终验证通过的应用实例运行后再将控制权交还给用户，除非用户明确要求不要运行应用。

Reference Rules

参考规则

Keep C# as the primary path. Mention C++ or C++/WinRT only when the difference is material.
Preserve the conventions of an existing codebase instead of forcing a generic sample structure onto it.
Treat WinUI design guidance and native controls as the baseline. Do not drift into bespoke component systems or app-specific replacements for standard controls unless the user explicitly requests them or the existing codebase already depends on them.
Support light and dark mode by default for app UI work unless the user explicitly asks for a single-theme result or the product already enforces one.
Favor built-in WinUI controls and system styling hooks before adding CommunityToolkit dependencies, custom controls, or app-specific surface systems.
Put detailed control, theming, shell, scrolling, responsiveness, packaging, and recovery guidance in the matching reference files instead of duplicating those rules here.

默认使用C#作为主要开发路径，仅当差异会产生实质影响时才提及C++或C++/WinRT。
保留现有代码库的约定，不要强制套用通用示例结构。
以WinUI设计指南和原生控件为基准，不要自行设计定制组件系统或是用应用专属实现替代标准控件，除非用户明确要求或是现有代码库已经依赖相关实现。
应用UI工作默认支持浅色和深色模式，除非用户明确要求单主题结果或是产品已经强制使用单主题。
优先使用内置WinUI控件和系统样式钩子，再考虑添加CommunityToolkit依赖、自定义控件或应用专属界面系统。
把控件、主题、shell、滚动、响应式、打包、修复相关的详细指南放在对应的参考文件中，不要在此处重复规则。