.NET MAUI iOS端ToolbarItem不可见问题技术求助

问题现象 #

在ContentPage中添加ToolbarItem后，Android端运行正常，但iOS（iPhone SE第二代）出现两个异常：

• 菜单文本可点击但无法显示
• 图标在Android端正常展示，iOS端完全不可见

提供的XAML代码如下：

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
         xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
         x:Class="MauiApp7.MainPage">
<ContentPage.ToolbarItems>
    <ToolbarItem Text="Test" Clicked="OnTestClicked" />
</ContentPage.ToolbarItems>
<ScrollView>
    <VerticalStackLayout
        Padding="30,0"
        Spacing="25">
        <Image
            Source="dotnet_bot.png"
            HeightRequest="185"
            Aspect="AspectFit"
            SemanticProperties.Description="dot net bot in a race car number eight" />

        <Label
            Text="Hello, World!"
            Style="{StaticResource Headline}"
            SemanticProperties.HeadingLevel="Level1" />

        <Label
            Text="Welcome to &#10;.NET Multi-platform App UI"
            Style="{StaticResource SubHeadline}"
            SemanticProperties.HeadingLevel="Level2"
            SemanticProperties.Description="Welcome to dot net Multi platform App U I" />

        <Button
            x:Name="CounterBtn"
            Text="Click me" 
            SemanticProperties.Hint="Counts the number of times you click"
            Clicked="OnCounterClicked"
            HorizontalOptions="Fill" />
    </VerticalStackLayout>
</ScrollView>

解决方案 #

1. 文本不显示：显式设置Order与Priority属性 #

iOS导航栏对ToolbarItem的布局逻辑和Android存在差异，纯文本项默认会被折叠到更多菜单中，且可能因布局规则导致文本不渲染。通过设置以下属性可强制文本显示在主导航栏：

<ToolbarItem Text="Test" 
             Clicked="OnTestClicked"
             Order="Primary"
             Priority="0" />

• Order="Primary"：指定该工具栏项属于主显示区域
• Priority="0"：设置优先级，数值越小越靠前展示

2. 图标不显示：适配iOS资源规则 #

如果添加图标后iOS端不可见，需检查以下几点：

• 资源格式与尺寸：iOS要求图标提供多分辨率版本（@1x、@2x、@3x），推荐使用SVG格式让MAUI自动适配，或提供对应尺寸的PNG文件，放在Resources/Images目录，并在项目文件中标记为MauiImage：

  <MauiImage Include="Resources\Images\test_icon.png" />
  

• 图标颜色适配：iOS导航栏图标默认使用模板模式，需确保图标为单色并支持色调变更，可显式设置：

  <ToolbarItem Text="Test" 
               Clicked="OnTestClicked"
               IconImageSource="test_icon.png"
               IsTemplate="True"
               TextColor="White" />
  

• 资源路径正确性：避免仅使用Android专属的drawable目录资源，确保资源放在MAUI共享资源或iOS专属资源目录中

3. 额外排查点 #

• 检查iOS项目Info.plist的状态栏样式，避免文本颜色与导航栏背景色重叠导致视觉上不可见
• 升级到最新稳定版.NET MAUI，旧版本存在ToolbarItem的iOS渲染已知bug

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