.NET MAUI 单项目功能与资源管理详解

.NET 多平台应用程序 UI（.NET MAUI）单项目将针对 Android、iOS、macOS 和 Windows 等平台的特定开发体验抽象化，整合为单一共享项目，从而提供简化且一致的跨平台开发体验。不论目标平台为何，.NET MAUI 单项目都具备以下功能：

• 以 Android、iOS、macOS、Tizen 和 Windows 为目标的单一共享项目。
• 简化了运行 .NET MAUI 应用程序的调试目标选取。
• 单一项目中的共享资源文件。
• 单一应用程序指令清单，用于指定应用程序标题、标识符和版本。
• 按需访问平台特定的 API 和工具。
• 单一跨平台应用程序进入点。

.NET MAUI 单项目通过多重目标启用，并使用 SDK 样式项目。

资源文件

跨平台应用程序开发的资源管理传统上较为复杂，因为每个平台都有自己的资源管理方法。例如，每个平台都有不同的图像需求，通常需要为每个图像创建多个分辨率版本，导致图像必须在不同分辨率上重复多次，且在不同平台上使用不同的文件名和文件夹惯例。

.NET MAUI 单项目允许资源文件存储在单一位置，同时在各平台上使用。这包括字体、图像、应用程序图标、启动显示画面、原始资产和 CSS 文件，用于设置 .NET MAUI 应用程序的样式。每个图像资源文件作为来源图像，每个平台在构建时会从中生成所需分辨率的图像。

注意：.NET MAUI 单项目中目前不支持 iOS 资产目录。

资源文件通常应放在 .NET MAUI 应用程序项目的 Resources 文件夹中，或 Resources 文件夹的子文件夹中，并且必须正确设置其构建动作。下表显示了每种资源文件类型的构建动作：

注意：XAML 文件也存储在 .NET MAUI 应用程序项目中，并在项目和项目模板创建时自动指派 MauiXaml 构建动作。但通常只有 XAML 资源字典会放在应用程序项目的 Resources 文件夹中。

将资源文件添加到 .NET MAUI 应用程序项目时，会在项目文件中创建资源的对应项目（CSS 文件除外）。Resources 文件夹通常包含子文件夹，用于不同类型的资源，如图像、字体和原始资产。

如果资源已添加到正确的 Resources 子文件夹，则资源文件的构建动作会自动设置正确。

您可以编辑应用程序的项目文件，为每种资源类型指定 Resources 文件夹的子文件夹：

<ItemGroup>
    <!-- Images -->
    <MauiImage Include="Resources\Images\*" />

    <!-- Fonts -->
    <MauiFont Include="Resources\Fonts\*" />

    <!-- Raw assets -->
    <MauiAsset Include="Resources\Raw\*" />
</ItemGroup>

通配符（*）表示文件夹内的所有文件都会被视作指定的资源类型。此外，也可以包含子文件夹中的所有文件：

<ItemGroup>
    <!-- Images -->
    <MauiImage Include="Resources\Images\**\*" />
</ItemGroup>

在此示例中，双通配符（**）指定 Images 文件夹可以包含子文件夹。因此，<MauiImage Include="Resources\Images\**\*" /> 指定 Resources\Images 文件夹中的任何文件，或 Images 文件夹的任何子文件夹，都会用作来源图像，每个平台从中生成所需分辨率的图像。

平台特定资源会覆盖其共享资源对应项目。例如，如果 Android 特定图像位于 Platform\Android\Resources\drawable-xhdpi\logo.png，并且您也提供了共享的 Resources\Images\logo.svg 图像，则可缩放矢量图形（SVG）文件将用于生成所需的 Android 图像，但已存在平台特定图像的 XHDPI 图像除外。

应用程序图标

将图像拖曳到项目的 Resources\AppIcon 文件夹，即可将应用程序图标添加到您的应用程序项目，其构建动作会自动设置为 MauiIcon。这会在项目文件中创建对应的项目：

<MauiIcon Include="Resources\AppIcon\appicon.svg" />

在构建阶段，应用程序图标会调整为目标平台和设备正确的大小。调整大小的应用程序图标随后会添加到应用程序包中。应用程序图标的大小会调整为多个分辨率，因为它们有多个用途，包括代表设备上的应用程序和应用商店中的应用程序。

图像

将图像拖曳到项目的 Resources\Images 文件夹，即可将图像添加到您的应用程序项目，其构建动作会自动设置为 MauiImage。这会在项目文件中创建对应的项目：

<MauiImage Include="Resources\Images\logo.svg" />

在构建阶段，图像可以调整为目标平台和设备的正确分辨率。生成的图像随后会添加到应用程序包中。

字体

将 True 类型格式（TTF）或开放类型字体（OTF）字体拖曳到项目的 Resources\Fonts 文件夹，即可将其添加到您的应用程序项目，其构建动作会自动设置为 MauiFont。这会在项目文件中为每个字体创建对应的项目：

<MauiFont Include="Resources\Fonts\OpenSans-Regular.ttf" />

在构建阶段，字体会复制到应用程序包中。

启动显示画面

将图像拖曳到项目的 Resources\Splash 文件夹，即可将启动显示画面添加到您的应用程序项目，其构建动作会自动设置为 MauiSplashScreen。这会在项目文件中创建对应的项目：

<ItemGroup>
  <MauiSplashScreen Include="Resources\Splash\splashscreen.svg" />
</ItemGroup>

在构建阶段，启动显示画面图像的大小会调整为目标平台和设备的正确大小。调整大小的启动显示画面随后会添加到应用程序包中。

原始资产

原始资产文件，如 HTML、JSON 和视频，可以通过将其拖曳到项目的 Resources\Raw 文件夹添加到您的应用程序项目，其构建动作会自动设置为 MauiAsset。这会在项目文件中为每个资产创建对应的项目：

<MauiAsset Include="Resources\Raw\index.html" />

然后，控件可以按需使用原始资产：

<WebView Source="index.html" />

在构建阶段，原始资产会复制到应用程序包中。如需停用资产打包的相关信息，请参阅相关文档。

CSS 文件

.NET MAUI 应用程序可以使用级联样式表（CSS）文件部分设置样式。CSS 文件可以拖曳到项目的任何文件夹，并在属性窗口中将其构建动作设置为 MauiCss，以添加到您的应用程序项目。

CSS 文件必须先由 StyleSheet 类加载，才能添加到 ResourceDictionary：

<Application ...>
    <Application.Resources>
        <StyleSheet Source="/Resources/styles.css" />
    </Application.Resources>
</Application>

应用程序清单

每个平台都使用自己的原生应用程序指令清单文件来指定应用程序标题、标识符、版本等信息。.NET MAUI 单项目允许您在项目文件的单一位置指定此通用应用程序数据。

若要指定项目的共享应用程序指令清单数据，请在方案资源管理器中打开项目的快捷方式菜单，然后选择属性。接着，您可以在 MAUI 共享 > 常规中指定应用程序标题、标识符和版本。

在构建阶段，共享应用程序指令清单数据会与原生应用程序指令清单文件中的平台特定数据合并，以生成应用程序包的指令清单文件。

平台特定代码

.NET MAUI 应用程序项目包含 Platform 文件夹，每个子文件夹代表 .NET MAUI 可以锁定的平台。

每个平台的文件夹包含平台特定的资源，以及在该平台上启动应用程序的代码。

构建时，构建系统只会在针对特定平台构建时，包含来自每个文件夹的代码。例如，当您为 Android 构建时，Platform\Android 文件夹中的文件会内置到应用程序包中，但其他 Platform 文件夹中的文件则不会。此方法使用多重目标，从单一项目以多个平台为目标。多重目标可以结合部分类部分方法，从跨平台代码调用原生平台功能。

除了这个默认的多重目标方法之外，.NET MAUI 应用程序也可以根据您自己的文件名和文件夹准则进行多重目标。这使您构建 .NET MAUI 应用程序项目时，不必将平台代码放入 Platform 文件夹的子文件夹中。

多重目标也可以与条件编译结合，让代码以特定平台为目标：

#if ANDROID
                  handler.PlatformView.SetBackgroundColor(Colors.Red.ToPlatform());
#elif IOS
                  handler.PlatformView.BackgroundColor = Colors.Red.ToPlatform();
                  handler.PlatformView.BorderStyle = UIKit.UITextBorderStyle.Line;
#elif WINDOWS
                  handler.PlatformView.Background = Colors.Red.ToPlatform();
#endif

应用程序进入点

虽然 Platform 文件夹包含平台特定代码以在每个平台上启动应用程序，但 .NET MAUI 应用程序具有单一跨平台应用程序进入点。每个平台进入点都会在应用程序项目中的静态 MauiProgram 类上调用 CreateMauiApp 方法，并返回 MauiApp，这是您应用程序的进入点。

MauiProgram 类至少必须提供应用程序来执行：

namespace MyMauiApp;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>();

        return builder.Build();
    }
}

App 类衍生自 Application 类：

namespace MyMauiApp;

public class App : Application
{
    public App()
    {
        InitializeComponent();

        MainPage = new AppShell();
    }
}

在上述示例中，MainPage 属性设置为 AppShell 对象。AppShell 是描述应用程序视觉层次的 Shell 子类。

namespace MyMauiApp;

public class App : Application
{
    public App()
    {
        InitializeComponent();
    }

    protected override Window CreateWindow(IActivationState? activationState)
    {
        return new Window(new AppShell());
    }
}

在上述示例中，创建新的 Window，其初始内容设置为 AppShell 对象。AppShell 是描述应用程序视觉层次的 Shell 子类。