项目设置

2025-09-03

在开始对应用进行编码之前，我们将快速了解 Visual Studio 项目并处理某些项目设置。当 Visual Studio 创建 WinUI 3 项目时，会生成几个重要的文件夹和代码文件。可以在 Visual Studio 的“解决方案资源管理器”窗格中看到这些文件：

解决方案资源管理器显示 Visual Studio 中 WinUI 3 项目的文件。

此处列出的项是主要与之交互的项目。这些文件有助于配置并运行 WinUI 3 应用。每个文件都有不同的用途，如下所述：

Assets 文件夹

此文件夹包含应用的徽标、图像和其他媒体资产。它开始填充应用的徽标的占位符文件。此徽标代表你的应用在 Windows 开始菜单、Windows 任务栏以及发布应用时Microsoft应用商店中的应用。
App.xaml 和 App.xaml.cs

该文件 App.xaml 包含应用范围的 XAML 资源，例如颜色、样式或模板。该文件 App.xaml.cs 通常包含实例化和激活应用程序窗口的代码。在此项目中，它指向 MainWindow 类。
MainWindow.xaml 和 MainWindow.xaml.cs

这些文件表示应用的窗口。
Package.appxmanifest

此程序包清单文件允许你配置发布者信息、徽标、处理器体系结构和其他详细信息，以确定应用在 Microsoft 应用商店中的显示方式。

XAML 文件和分部类

可扩展应用程序标记语言 （XAML）是一种声明性语言，可以初始化对象和设置对象的属性。可以在声明性 XAML 标记中创建可见的 UI 元素。然后，可以为每个 XAML 文件（通常称为 代码隐藏 文件）关联单独的代码文件，该文件可以响应事件并作最初在 XAML 中声明的对象。

通常有两个文件，其中包含任何 XAML 文件、 .xaml 文件本身和相应的代码隐藏文件，该文件是 解决方案资源管理器中的子项。

该文件 .xaml 包含定义应用 UI 的 XAML 标记。类名使用 x:Class 特性声明。
代码文件包含你创建的代码以与 XAML 标记交互，以及对方法的 InitializeComponent 调用。类定义为 .partial class

生成项目时， InitializeComponent 将调用该方法以分析 .xaml 文件并生成与代码 partial class 联接的代码以创建完整类。

在文档中了解详细信息：

更新 MainWindow

项目 MainWindow 附带的类是 XAML Window 类的子类，用于定义应用的 shell。应用的窗口有两个部分：

窗口的 客户端 部分是内容所在的位置。
非客户端部分由 Windows作系统控制。它包括标题栏，标题控件（最小/最大/关闭按钮）、应用图标、标题和拖动区域。它还包括窗口外侧的框架。

若要使 WinUI Notes 应用符合 Fluent Design 指南，需要对它进行一些修改 MainWindow。首先，将 Mica 材料作为窗口背景应用。 Mica 是一种不透明、动态的材料，它结合了主题和桌面壁纸来绘制窗口的背景。然后，你将应用的内容扩展到标题栏区域，并将系统标题栏替换为 XAML 标题栏控件。这样可以更好地利用空间，并让你更好地控制设计，同时提供标题栏所需的所有功能。

你还将添加框架作为窗口的内容。该 Frame 类适用于 Page 类，使你可以在应用中的内容页面之间导航。你将在后面的步骤中添加页面。

小窍门

可以从 GitHub 存储库下载或查看本教程的代码。若要查看此步骤中的代码，请参阅此提交：备注页 - 初始。

双击MainWindow.xaml中的将其打开。

在开始标记和结束<Window.. > 标记之间，使用以下代码替换任何现有 XAML：

<Window.SystemBackdrop>
    <MicaBackdrop Kind="Base"/>
</Window.SystemBackdrop>

<Grid>
    <Grid.RowDefinitions>
        <!-- Title Bar -->
        <RowDefinition Height="Auto" />
        <!-- App Content -->
        <RowDefinition Height="*" />     
    </Grid.RowDefinitions>
    <TitleBar x:Name="AppTitleBar"
              Title="WinUI Notes">
        <TitleBar.IconSource>
            <FontIconSource Glyph="&#xF4AA;"/>
        </TitleBar.IconSource>
    </TitleBar>

    <!-- App content -->
    <Frame x:Name="rootFrame" Grid.Row="1"/>
</Grid>

通过按 Ctrl + S、单击工具栏中的“保存”图标或选择菜单>“保存 MainPage.xaml”来保存文件。

如果目前不了解所有这些 XAML 标记的作用，请不要担心。构建应用 UI 的其余部分时，我们将更详细地介绍 XAML 概念。

注释

在此标记中，你将看到两种不同的方法在 XAML 中设置属性。第一种和最短方法是使用 XAML 属性语法，如下所示： <object attribute="value"> 这非常适用于简单值，例如 <MicaBackdrop Kind="Base"/>。但它仅适用于 XAML 分析程序知道如何将字符串转换为预期值类型的值。

如果属性值更为复杂，或者 XAML 分析程序不知道如何转换该值，则必须使用 属性元素语法 来创建对象。喜欢这个：

<object ... >
    <object.property>
        value
    </object.property>
</object>

例如，若要设置属性 Window.SystemBackdrop ，必须使用属性元素语法并显式创建 MicaBackdrop 元素。但是，可以使用简单的属性语法来设置 MicaBackdrop.Kind 属性。

<Window ... >
   <Window.SystemBackdrop>
       <MicaBackdrop Kind="Base"/>
   </Window.SystemBackdrop>
    ...
</Window>

在 MainWindow.xaml、 <Window.SystemBackdrop>中 <Grid.RowDefinitions>，并且 <TitleBar.IconSource> 包含必须使用属性元素语法设置的复杂值。

在文档中了解详细信息：

XAML 语法指南

如果现在运行应用，你将看到已添加的 XAML TitleBar 元素，但它将位于系统标题栏下方，该栏仍在显示。

显示系统标题栏和自定义标题栏的空 WinUI Notes 应用窗口。

需要编写一些代码来完成替换系统标题栏。

打开 MainWindow.xaml.cs。可以通过三种方式打开（或任何 XAML 文件）的代码隐藏 MainWindow.xaml ：
- MainWindow.xaml如果文件处于打开状态并且是正在编辑的活动文档，请按 F7。
- MainWindow.xaml如果文件处于打开状态并且正在编辑的活动文档，请在文本编辑器中右键单击并选择“查看代码”。
- 使用 解决方案资源管理器 展开 MainWindow.xaml 条目，显示 MainWindow.xaml.cs 文件。双击文件以将其打开。
在构造函数中 MainWindow，在调用 InitializeComponent以下代码后添加以下代码：
```
public MainWindow()
{
    this.InitializeComponent();

    // ↓ Add this. ↓
    // Hide the default system title bar.
    ExtendsContentIntoTitleBar = true;
    // Replace system title bar with the WinUI TitleBar.
    SetTitleBar(AppTitleBar);
    // ↑ Add this. ↑
}
```
ExtendsContentIntoTitleBar 属性隐藏默认的系统标题栏，并将应用 XAML 扩展到该区域。然后，调用 SetTitleBar 会告知系统将指定的AppTitleBar XAML 元素（）视为应用的标题栏。
通过按 F5、单击工具栏中的“调试”按钮或选择菜单“开始>”来生成并运行项目。

现在运行应用时，你将看到一个空窗口，其中包含 mica 背景和已替换系统标题栏的 XAML 标题栏。

标题栏中带有图标和应用名称的空 WinUI Notes 应用窗口。

继续执行步骤 2 - 添加备注页

反馈

此页面是否有帮助？

通过

项目设置

XAML 文件和分部类

更新 MainWindow

反馈

其他资源