.NET MAUI中CollectionView无法显示图片的问题排查与解决

问题 #

我正在开发一个.NET MAUI应用，尝试在CollectionView中显示图片列表，但按照文档操作后图片仍无法显示。相关代码与信息如下：

MainPage.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="Maui.NFT.Marketplace.MainPage">

    <ContentPage.Resources>
        <DataTemplate x:Key="ImageTemplate">
            <Image Source="{Binding .}"
                   Aspect="AspectFit"
                   HorizontalOptions="Fill"
                   WidthRequest="137"
                   HeightRequest="137">
                <Image.Clip>
                    <RoundRectangleGeometry
                        Rect="0,0,137,137"
                        CornerRadius="16" />
                </Image.Clip>
            </Image>       
        </DataTemplate>

        <Style TargetType="CollectionView">
            <Setter Property="ItemTemplate" Value="{StaticResource ImageTemplate}"/>
            <Setter Property="ItemsLayout">
                <LinearItemsLayout
                    Orientation="Horizontal"
                    ItemSpacing="14"/>
            </Setter>
        </Style>
    </ContentPage.Resources>

    <Grid>
        <CollectionView ItemsSource="{Binding ImageList}"/>
    </Grid>
</ContentPage>

MainPage.xaml.cs #

namespace Maui.NFT.Marketplace
{
    public partial class MainPage : ContentPage
    {
        public List<string> ImageList { get; set; }

        public MainPage()
        {
            InitializeComponent();
            GenerateData();
            BindingContext = this;
        }

        private void GenerateData()
        {
            ImageList = new List<string>();

            for (var i = 1; i <= 18; i++)
            {
                ImageList.Add($"ima{i.ToString("00")}.png");
            }
        }
    }
}

项目结构与图片属性 #

• 图片ima01.png至ima18.png存放在根目录下的Resources\Images文件夹中
• 每张图片的Build Action设置为Content，Copy to Output Directory设置为Copy if newer

问题现象 #

CollectionView显示了正确的条目数量（18个），但图片未显示，仅显示空白占位。已确认BindingContext设置正确，图片路径列表已正常填充。

已尝试操作 #

• 验证图片已正确纳入项目且属性设置无误
• 检查输出目录确认图片已被复制
• 简化XAML与代码后置文件，专注于显示单个CollectionView
• 确认输出控制台无加载图片相关的错误或警告

期望效果 #

图片能在CollectionView中正常显示，用提供的图片填充界面。

解决方案 #

问题核心在于图片的资源管理方式不符合.NET MAUI的预期逻辑，以下是两种高效的修复方案：

方案1：使用.NET MAUI推荐的图片资源类型（优先选择） #

1. 选中所有ima01.png至ima18.png文件，右键打开属性面板
2. 将Build Action从Content修改为MauiImage，保持Copy to Output Directory为Copy if newer
3. 无需修改任何代码，直接重新编译运行即可。

原理：当图片设置为MauiImage时，.NET MAUI会自动将其作为嵌入式资源管理，框架会处理跨平台的路径适配，直接使用文件名就能正确加载图片。

方案2：保留Content类型，修正路径引用 #

如果需要继续使用Content的Build Action，需要补充完整的文件系统路径：

1. 修改GenerateData方法，拼接完整路径：

private void GenerateData()
{
    ImageList = new List<string>();
    // 获取输出目录下的图片文件夹路径
    var imageDir = Path.Combine(AppContext.BaseDirectory, "Resources", "Images");
    
    for (var i = 1; i <= 18; i++)
    {
        ImageList.Add(Path.Combine(imageDir, $"ima{i.ToString("00")}.png"));
    }
}

2. 重新编译运行，图片即可正常显示。

原理：设置为Content的图片会被复制到输出目录的Resources/Images子文件夹中，此时必须使用完整的文件系统路径才能让Image控件找到并加载图片。

内容的提问来源于stack exchange，提问作者Júlia Santana