如何在Windows平台的.NET MAUI中通过XAML设置菜单栏图标

一、先确保图片资源配置正确 #

这是图标显示的基础，别忽略：

• 将图标图片放入项目的Resources\Images目录
• 选中图片，在属性面板设置：
  • 生成操作：MauiImage
  • 复制到输出目录：如果较新则复制

二、AppShell中Flyout项的图标设置 #

针对Shell的侧边栏菜单，直接使用文件名或字体图标即可，Windows平台对FlyoutIcon的支持需要注意路径准确性：

本地图片图标写法 #

<FlyoutItem Title="主页" FlyoutIcon="home.png">
    <ShellContent ContentTemplate="{DataTemplate local:MainPage}" />
</FlyoutItem>

字体图标写法（推荐，适配性更强） #

先在MauiProgram.cs注册字体：

builder.ConfigureFonts(fonts =>
{
    fonts.AddFont("FontAwesome6Free-Solid.otf", "FontAwesome");
});

再在XAML中使用：

<FlyoutItem Title="设置">
    <FlyoutItem.FlyoutIcon>
        <FontImageSource FontFamily="FontAwesome" Glyph="&#xf013;" Color="#333333" />
    </FlyoutItem.FlyoutIcon>
    <ShellContent ContentTemplate="{DataTemplate local:SettingsPage}" />
</FlyoutItem>

三、页面内MenuItem的图标设置 #

对于页面工具栏或嵌套在Flyout中的MenuItem，Windows平台建议显式指定图片源类型，避免加载失败：

页面ToolbarItem示例 #

<ContentPage.ToolbarItems>
    <ToolbarItem Text="添加">
        <ToolbarItem.IconImageSource>
            <FileImageSource FileName="add.png" />
        </ToolbarItem.IconImageSource>
    </ToolbarItem>
</ContentPage.ToolbarItems>

Flyout内嵌套MenuItem示例 #

<FlyoutItem Title="数据工具">
    <MenuItem Text="导出数据" IconImageSource="export.png" Command="{Binding ExportCommand}" />
    <MenuItem Text="导入数据" IconImageSource="import.png" Command="{Binding ImportCommand}" />
</FlyoutItem>

四、Windows平台特殊适配要点 #

• 图片尺寸：优先使用24×24、32×32等适配高DPI的尺寸，避免模糊或不显示
• 高DPI修复：如果图标仍不显示，在Platforms\Windows\App.xaml.cs中添加高DPI适配代码：

protected override void OnLaunched(LaunchActivatedEventArgs args)
{
    base.OnLaunched(args);
    Microsoft.Maui.Handlers.WindowHandler.Mapper.AppendToMapping(nameof(IWindow), (handler, view) =>
    {
        var nativeWindow = handler.PlatformView;
        nativeWindow.Activate();
        nativeWindow.DpiChanged += (s, e) => handler.UpdateLayout();
    });
}

• 排查技巧：检查输出窗口的加载错误日志，确认图片路径、文件名是否完全匹配（MAUI跨平台建议统一小写文件名）

内容的提问来源于stack exchange，提问作者the_yaz2000