.NET MAUI应用加载长时间显示沙漏且iOS背景图不显示问题排查

问题场景与代码实现 #

在.NET MAUI的ContentView中，通过ScrollView嵌套Grid，结合自定义BackgroundImageView展示背景图，核心代码如下：

XAML布局代码 #

<ScrollView HorizontalOptions="StartAndExpand">
    <Grid RowDefinitions="Auto">

        <views:BackgroundImageView x:Name="BackgroundImage" VerticalOptions="Start"/>

        <Grid RowDefinitions="Auto, Auto, *">

            <!-- Border 1:  Custom Picker Control for Saved Store Name and Save-Button -->
            <Border Grid.Row="0" Style="{StaticResource BorderStyleView}">
                <Grid ColumnDefinitions="*, Auto" Margin="15">
                    <picker:CustomPickerControl Grid.Column="0" Text="{Binding SelectedSavedStoreName, Mode=TwoWay}" Placeholder="Saved Store..." BorderColor="{x:StaticResource Gray400}" Padding="0, 0, 25, 0" Margin="5, 0, 0, 0"/>

                    <!--Save Button-->
                    <Button Grid.Column="1" Text="Save" HeightRequest="35" WidthRequest="100" FontAutoScalingEnabled="True" VerticalOptions="FillAndExpand" Padding="15, 7, 15, 10"/>
                </Grid>
            </Border>

        </Grid>

    </Grid>
</ScrollView>

后台代码（设置背景图高度） #

protected override void OnSizeAllocated(double width, double height)
{
    base.OnSizeAllocated(width, height);

    if (BackgroundImage == null)
    {
        return;
    }

#if IOS
    if (height > 0)
    {
        BackgroundImage.HeightRequest = height * 0.7;
    }
#endif
#if ANDROID
    if (height > width)
    {
        BackgroundImage.HeightRequest = height * 0.7;
    }
    else
    {
        BackgroundImage.HeightRequest = height;
    }
#endif
}

遇到的具体问题 #

1. 打开BackgroundImageView.xaml时，提示Invalid Value for property 'Source': radiant_gradient.png，但对应的svg文件确实存在于..\Resources\Images\目录中。
2. 应用启动后长时间显示加载状态（沙漏），iOS端背景图最终无法显示；实际应用中虽能显示背景图，但同样存在启动卡顿问题。

问题原因分析 #

1. 图片Source无效提示的原因 #

• 资源类型不匹配：提示中引用的是radiant_gradient.png，但实际文件是svg格式，若BackgroundImageView中Image的Source直接写了.png后缀，会导致MAUI无法找到对应资源。
• 资源Build Action未正确设置：svg文件需将Build Action设置为MauiImage，否则MAUI不会将其作为图片资源打包，导致加载失败。
• 资源路径或命名问题：MAUI对图片资源的引用不支持相对路径（如..\），需直接使用资源名；同时要确保文件名大小写匹配，iOS对文件名大小写敏感。

2. 应用启动卡顿（长时间沙漏）的原因 #

• OnSizeAllocated频繁触发重绘：OnSizeAllocated会在布局初始化、屏幕旋转、控件尺寸变化时多次调用，每次调用都修改BackgroundImage.HeightRequest，会触发多次布局重计算，导致主线程阻塞，出现加载卡顿。
• 图片加载阻塞主线程：若svg文件尺寸较大，或MAUI对svg的解码处理未在后台线程执行，会占用主线程资源，延长启动时间。
• 布局嵌套层级冗余：当前布局中ScrollView嵌套两层Grid，且外层Grid的RowDefinitions设为Auto，可能导致布局计算复杂度提升，加重卡顿。

3. iOS端背景图无法显示的原因 #

• 布局时机问题：iOS中仅在height>0时设置HeightRequest，但OnSizeAllocated首次调用时height可能尚未正确初始化，导致HeightRequest未被设置，BackgroundImageView因高度为0而不可见。
• iOS对svg的兼容性问题：部分svg特性（如复杂渐变）在iOS的MAUI实现中可能存在兼容性问题，导致图片加载失败。
• 资源大小写问题：iOS文件系统区分大小写，若BackgroundImageView中引用的资源名与实际svg文件名大小写不一致，会导致加载失败。

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