.NET MAUI CollectionView中图片加载失败问题排查

我在.NET MAUI的CollectionView中加载图片时遇到不显示的问题。图片需根据是否已下载，从URL或本地磁盘获取。我在QueryApi方法中创建ForecastData对象后更新图片路径，CollectionView能正常加载文本信息，但天气描述下方的100x100天气图标无法显示。

这种方式在单个天气对象的页面中可行，但在CollectionView中失效。我希望运行时获取图标而非编译时嵌入。

页面XAML代码 #

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="WeatherApp.Pages.ForecastWeatherPage"
             Title="5-Day Forecast">

    <VerticalStackLayout Margin="20"
                         Spacing="40">

        <Entry Placeholder="ZIP"
               Text="{Binding ZipCode}"
               MaxLength="5"
               WidthRequest="200"
               HeightRequest="40"
               HorizontalOptions="Center"
               VerticalOptions="Center"
               ClearButtonVisibility="WhileEditing" />
        <Label x:Name="CityLabel"
               FontSize="40"
               HorizontalOptions="Center"
               TextColor="Gray"
               Text="{Binding CityName}" />

        <CollectionView ItemsSource="{Binding WeatherForecast}"
                        ItemsLayout="HorizontalList"
                        HorizontalScrollBarVisibility="Always">
            <CollectionView.ItemTemplate>
                <DataTemplate>
                    <VerticalStackLayout    Margin="20"
                                            Spacing="40">
                        <Label x:Name="WeatherDescriptionLabel"
                               FontSize="Medium"
                               HorizontalOptions="Center"
                               TextColor="SlateGray"
                               Text="{Binding WeatherDescription}" />
                        <Image Source="{Binding WeatherImagePath}"
                               Aspect="AspectFit"
                               MaximumHeightRequest="100"
                               MaximumWidthRequest="100" />
                    </VerticalStackLayout>
                </DataTemplate>
            </CollectionView.ItemTemplate>
        </CollectionView>
    </VerticalStackLayout>
</ContentPage>

ViewModel代码 #

using WeatherApp.Services;
using WeatherApp.Models.ForecastWeatherModel;
using ForecastData = WeatherApp.Models.WeatherDataObject;
using System.Collections.ObjectModel;
using WeatherApp.Pages;

namespace WeatherApp.ViewModels
{
    public class ForecastWeatherViewModel : BaseViewModel
    {

        private string zipCode;
        private string cityName;

        private Root weatherForecastRoot;

        public ObservableCollection<ForecastData> WeatherForecast { get; private set; } = new ObservableCollection<ForecastData>();
        
        public ForecastWeatherViewModel()
        {
            weatherForecastRoot = new Root();
            zipCode = string.Empty;
            cityName = "Please Enter Zip Code";
        }

        public string ZipCode
        {
            get => zipCode;
            set
            {
                SetProperty(ref zipCode, value);
                if (zipCode.Length == 5)
                {
                    QueryApi();
                }
            }
        }
        public string CityName
        {
            get => cityName;
            set
            {
                SetProperty(ref cityName, value);
            }
        }
        private async void QueryApi()
        {
            if (int.TryParse(zipCode, out var convertedZipCode))
            {
                weatherForecastRoot = await ApiService.GetWeatherForecast(convertedZipCode);
                
                if (weatherForecastRoot != null)
                {
                    CityName = weatherForecastRoot.city.name;
                    
                    List<ForecastData> preparationList = new List<ForecastData>();

                    foreach(var weatherReport in weatherForecastRoot.list)
                    {
                        foreach(var report in weatherReport.weather)
                        {
                            ForecastData weatherDataObject = new ForecastData(report.description, report.icon);

                            if (!FileService.isIconDownloaded(weatherDataObject.WeatherIcon))
                            {
                                byte[] imageByteArray = await ApiService.GetWeatherImageFromIconCode(weatherDataObject.WeatherIcon);
                                weatherDataObject.WeatherImagePath = FileService.SaveIconToAppData(imageByteArray, weatherDataObject.WeatherIcon);
                            }
                            else
                            {
                                weatherDataObject.WeatherImagePath = FileService.GetIconPath(weatherDataObject.WeatherIcon);
                            }
                            preparationList.Add(weatherDataObject);
                        }
                    }
                    WeatherForecast = new ObservableCollection<ForecastData>(preparationList);
                    OnPropertyChanged(nameof(WeatherForecast));
                }
                else
                {
                    CityName = "Cannot locate city/region by zip code";
                }
            }
        }
    }
}

问题排查与解决方案 #

1. 确保ForecastData实现INotifyPropertyChanged #

单个页面可行但CollectionView失效，核心原因是ForecastData类未实现INotifyPropertyChanged接口。创建对象后设置WeatherImagePath时，CollectionView无法感知属性变化，导致图片源未更新。

修改WeatherDataObject类：

public class WeatherDataObject : INotifyPropertyChanged
{
    private string _weatherImagePath;
    public string WeatherImagePath
    {
        get => _weatherImagePath;
        set
        {
            if (_weatherImagePath != value)
            {
                _weatherImagePath = value;
                OnPropertyChanged(nameof(WeatherImagePath));
            }
        }
    }

    // 其他属性与构造函数保持不变

    public event PropertyChangedEventHandler PropertyChanged;
    protected void OnPropertyChanged(string propertyName)
    {
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
    }
}

2. 验证本地图片路径格式 #

MAUI加载本地图片需符合平台路径要求：

• 确保FileService.SaveIconToAppData和FileService.GetIconPath返回绝对路径，或给路径添加file:///前缀（跨平台兼容）。
• 更稳妥的方式是直接使用ImageSource类型属性替代字符串路径：

  private ImageSource _weatherImage;
  public ImageSource WeatherImage
  {
      get => _weatherImage;
      set
      {
          if (_weatherImage != value)
          {
              _weatherImage = value;
              OnPropertyChanged(nameof(WeatherImage));
          }
      }
  }
  

  赋值时直接创建ImageSource：

  // 下载后设置
  var localPath = FileService.SaveIconToAppData(imageByteArray, weatherDataObject.WeatherIcon);
  weatherDataObject.WeatherImage = ImageSource.FromFile(localPath);
  
  // 已存在时直接加载
  weatherDataObject.WeatherImage = ImageSource.FromFile(FileService.GetIconPath(weatherDataObject.WeatherIcon));
  

  同时XAML中绑定改为{Binding WeatherImage}。

3. 调试路径正确性 #

在设置图片路径后，打印路径并验证文件是否存在：

var path = FileService.GetIconPath(weatherDataObject.WeatherIcon);
Debug.WriteLine($"图片路径：{path}，文件是否存在：{File.Exists(path)}");

内容的提问来源于stack exchange，提问作者Gnome-Improvement713