更改应用图标

每个应用都有一个代表它的徽标图标，并且该图标通常出现在多个位置。 例如，在 iOS 上，应用图标显示在主屏幕和整个系统中，例如在设置、通知和搜索结果中，以及App Store。 在 Android 上，应用图标显示为启动器图标，并在整个系统中显示，例如在操作栏、通知和 Google Play 商店中。 在 Windows 上，应用图标显示在“开始”菜单、任务栏、应用磁贴和 Microsoft Store 中的应用列表中。

在 .NET 多平台应用 UI (.NET MAUI) 应用项目中，可以在应用项目的单个位置指定应用图标。 在生成时，可将此图标自动调整为目标平台和设备的正确分辨率，并将其添加到应用包中。 这样就不必手动复制应用图标，并为每个平台命名应用图标。 默认情况下，.NET MAUI 不会自动调整位图 (非矢量) 图像格式的大小。

.NET MAUI 应用图标可以使用任何标准平台图像格式，包括可缩放矢量图形 (SVG) 文件。

重要

.NET MAUI 将 SVG 文件转换为可移植网络图形 (PNG) 文件。 因此，将 SVG 文件添加到 .NET MAUI 应用项目时，应从扩展名 为.png 的 XAML 或 C# 引用该文件。 对 SVG 文件的唯一引用应位于项目文件中。

在项目文件中， 项指定用于应用的图标。 只能为应用定义一个图标。 将忽略任何后续 项。

为了符合 Android 资源命名规则，应用图标文件名必须为小写，以字母字符开头和结尾，并且仅包含字母数字字符或下划线。 有关详细信息，请参阅有关 developer.android.com 的应用资源概述 。

应用定义的图标可以由单个图像组成，方法是将 文件指定为 Include 属性：

重要

.NET MAUI 仅处理项目文件中定义的第一 项。 如果要使用其他文件作为图标，请先从项目中删除现有图标，然后添加新图标。 接下来，在“解决方案资源管理器”窗格中，选择文件，然后在“属性”窗格中，将“生成操作”设置为 MauiIcon。 请考虑替换现有的图标文件，而不是将新的图标文件添加到项目。

更改图标文件后，可能需要在 Visual Studio 中清理项目。 若要清理项目，请在“解决方案资源管理器”窗格中右键单击项目文件，然后选择“清理”。 可能还需要从要测试的目标平台卸载应用。

注意

如果不清理项目并从目标平台卸载应用，则可能看不到新图标。

更改图标后，查看 特定于平台的配置 信息。

或者，应用图标可以由两个图像组成，一个图像表示背景，另一个表示前景。 由于图标已转换为 PNG 文件，因此组合应用图标将首先与背景图像分层，通常是图案或纯色的图像，后跟前景图像。 在这种情况下， Include 属性表示图标背景图像， Foreground 属性表示前景图像：

重要

必须为项指定背景图像 (Include属性) 。 前景图像 (ForegroundFile 属性) 是可选的。

.NET MAUI 跨多个平台和设备使用图标，并尝试根据每个平台和设备调整图标大小。 应用图标还用于不同的目的，例如应用的应用商店条目或安装到设备上后用于表示应用的图标。

图标的基本大小表示图像的基线密度，实际上是派生所有其他大小的 1.0 比例系数。 如果未指定基于位图的应用图标（例如 PNG 文件）的基本大小，则不会调整图像大小。 如果未指定基于矢量的应用图标（例如 SVG 文件）的基大小，则图像中指定的尺寸将用作基本大小。 若要停止调整矢量图像的大小，请将 属性设置为 Resizefalse。

下图演示了基大小如何影响图像：

上图中显示的过程遵循以下步骤：

提示

使用 SVG 图像作为图标。 SVG 图像可以升级为更大的大小，看起来仍然清晰干净。 升级时，基于位图的图像（例如 PNG 或 JPG 图像）看起来模糊。

基本大小是使用 BaseSize="W,H" 属性指定的，其中 W 是图标的宽度， H 是图标的高度。 指定为基大小的值必须可除以 8。 以下示例设置基大小：

以下示例停止自动调整基于矢量的图像的大小：

如果撰写应用图标时使用的背景图像使用透明度，则可以通过指定 Color 上的 属性来重新着色。 以下示例将应用图标的背景色设置为红色：

可以使用 格式以十六进制格式指定颜色值： #RRGGBB 或 #AARRGGBB。 的值 RR 表示红色通道、 GG 绿色通道、 BB 蓝色通道和 AA alpha 通道。 可以使用命名的 .NET MAUI 颜色，例如 Red 或 PaleVioletRed，而不是十六进制值。

注意

如果未为应用图标定义背景色，则认为该背景在 iOS 和 Mac Catalyst 上是父级。 这将导致App Store Connect 验证期间出错，并且你将无法上传应用。

如果应用图标由背景 (Include) 图像和前景 (ForegroundFile) 图像组成，则可以着色前景图像。 若要对前景图像进行着色，请使用 属性指定颜色 TintColor 。 以下示例将前景图像着色为黄色：

可以使用 格式以十六进制格式指定颜色值： #RRGGBB 或 #AARRGGBB。 的值 RR 表示红色通道、 GG 绿色通道、 BB 蓝色通道和 AA alpha 通道。 可以使用命名的 .NET MAUI 颜色，例如 Red 或 PaleVioletRed，而不是十六进制值。

如果要为每个平台使用不同的图标资源或设置，请将 属性添加到Condition项，并查询特定平台。 如果满足条件，则会 处理该项。 .NET MAUI 仅使用第一个有效 项，因此应首先声明所有条件项，然后声明一个没有条件的默认 项。 以下 XML 演示如何声明 Windows 的特定图标和所有其他平台的回退图标：

可以通过将 条件中比较的值更改为以下值之一来设置目标平台：

例如，面向 Android 的条件为 Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'android'"。

虽然项目文件声明应用图标从中构成的资源，但仍需要通过引用这些应用图标来更新各个平台配置。 以下信息介绍了这些特定于平台的设置。

Android 使用的图标在 Android 清单中指定，该清单位于 Platforms\Android\AndroidManifest.xml。 节点 manifest/application 包含用于定义图标的两个属性： android:icon 和 android:roundIcon。 这两个属性的值分别遵循以下格式： @mipmap/{name} 和 @mipmap/{name}_round。 的值 {name} 派生自 .NET MAUI 项目文件的 项，特别是由 Include 特性定义的文件名，没有其路径或扩展名。

请考虑以下示例，该示例将资源 Resources\AppIcon\healthapp.png 定义为 图标：

转换后的名称（不带路径或扩展名的资源）为 healthapp。 和 android:roundIcon@mipmap/healthapp 的值android:icon分别为 和 @mipmap/healthapp_round。 Android 清单应更新为匹配 healthapp 图标：

提示

无需为图标创建新的图像文件，只需替换 .NET MAUI 模板提供的两个图像文件： 将 Resources\AppIcon\appicon.svg 替换为背景，将 Resources\AppIcon\appiconfg.svg 替换为前台。

.NET MAUI 支持在 Android 8.0 及更高版本上通过应用图标创建自适应启动器图标。 自适应启动器图标可以在不同的设备型号（包括圆形和方形）中显示为各种形状。 有关自适应图标的详细信息，请参阅 Android 开发人员指南：自适应图标。

自适应启动器图标由图标组成，使用背景层和前景层，以及可选的缩放值。 有关详细信息，请参阅 组合图标部分。 如果通过指定 ForegroundFile 属性定义了组合图标，则将生成自适应启动器图标。 以下 XML 演示如何定义用作自适应启动器图标的图标：

ForegroundScale可以选择指定 属性，以更改呈现在背景层上的前景层的缩放比例。

.NET MAUI 应用定义的应用图标用于为 iOS 和 macOS 平台生成资产目录图标集。 图标集的名称在 Info.plist 文件中定义，该文件在 iOS 上位于 Platforms\iOS\Info.plist。 对于 macOS， Info.plist 文件位于 Platforms\MacCatalyst\Info.plist。

提示

若要在 Visual Studio 中手动编辑 Info.plist 文件，请在“解决方案资源管理器”窗格中右键单击该文件，然后选择“打开方式...”。接下来，选择“XML (文本) 编辑器”，然后选择“确定”。 否则，请双击文件以在 plist 视觉对象编辑器中将其打开。

Info.plist 文件包含一个XSAppIconAssets条目，其后定义相应的节点。 此 节点的值遵循以下格式： Assets.xcassets/{name}.appiconset 的值 {name} 派生自 .NET MAUI 项目文件的 项，特别是由 Include 属性定义的文件名，不带其路径或扩展名。

请考虑以下示例，该示例将资源 Resources\AppIcon\healthapp.png 定义为图标：

转换后的名称（不带路径或扩展名的资源）为 healthapp。 清单 Assets.xcassets/healthapp.appiconset中的值为 ，如以下 XML 所示：

提示

无需为图标创建新的图像文件，只需替换 .NET MAUI 模板提供的两个图像文件： 将 Resources\AppIcon\appicon.svg 替换为背景，将 Resources\AppIcon\appiconfg.svg 替换为前台。

无需为 Windows 配置任何其他设置。

项目定义的应用图标用于生成应用的图标资产。