.NET Maui自定义控件绑定ViewModel属性报错求助

核心问题 #

你遇到的报错是因为自定义控件DocumentPreviewCard没有为DocId、Name、ThumbnailUri定义BindableProperty。在MAUI中，要让控件支持外部数据绑定，必须将需要接收绑定的属性声明为BindableProperty，而非仅依赖内部ViewModel的ObservableProperty——XAML中你写的DocId="{Binding Id}"是试图绑定控件自身的属性，不是其内部ViewModel的属性。

解决方案步骤 #

1. 为自定义控件添加BindableProperty

修改DocumentPreviewCard的代码后置，为每个需要绑定的属性定义BindableProperty：

public partial class DocumentPreviewCard : VerticalStackLayout
{
    // 定义BindableProperty（必须为静态只读）
    public static readonly BindableProperty DocIdProperty =
        BindableProperty.Create(nameof(DocId), typeof(Guid?), typeof(DocumentPreviewCard), null);

    public static readonly BindableProperty NameProperty =
        BindableProperty.Create(nameof(Name), typeof(string), typeof(DocumentPreviewCard), string.Empty);

    public static readonly BindableProperty ThumbnailUriProperty =
        BindableProperty.Create(nameof(ThumbnailUri), typeof(string), typeof(DocumentPreviewCard), string.Empty);

    // 对应的CLR包装属性
    public Guid? DocId
    {
        get => (Guid?)GetValue(DocIdProperty);
        set => SetValue(DocIdProperty, value);
    }

    public string? Name
    {
        get => (string?)GetValue(NameProperty);
        set => SetValue(NameProperty, value);
    }

    public string? ThumbnailUri
    {
        get => (string?)GetValue(ThumbnailUriProperty);
        set => SetValue(ThumbnailUriProperty, value);
    }

    public DocumentPreviewCard()
    {
        InitializeComponent();
        // 移除这里的BindingContext赋值，避免覆盖外部传入的绑定上下文
        // BindingContext = new DocumentPreviewViewModel();
    }
}

2. 调整控件XAML的绑定路径

现在控件的XAML需要绑定到自身的属性，可通过RelativeSource指定绑定源为控件本身：

<VerticalStackLayout
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:cards="clr-namespace:XYZ.Cards"
    x:Class="XYZ.Cards.DocumentPreviewCard"
    HeightRequest="270"
    WidthRequest="180"
    Margin="15">
    <Border>
        <Border.StrokeShape>
            <RoundRectangle CornerRadius="10"/>
        </Border.StrokeShape>
        <Image x:Name="ImgThumbnail"
               HorizontalOptions="Center"
               VerticalOptions="Center">
            <Image.Source>
                <UriImageSource Uri="{Binding ThumbnailUri, Source={RelativeSource AncestorType={x:Type cards:DocumentPreviewCard}}}" />
            </Image.Source>
        </Image>
    </Border>
    <Label HorizontalTextAlignment="Center" 
           Text="{Binding Name, Source={RelativeSource AncestorType={x:Type cards:DocumentPreviewCard}}}" />
</VerticalStackLayout>

（可选）保留内部ViewModel的写法

如果你想继续使用DocumentPreviewViewModel，可以将BindableProperty的变更同步到ViewModel：

public partial class DocumentPreviewCard : VerticalStackLayout
{
    // 重复上述BindableProperty定义...

    public DocumentPreviewViewModel ViewModel { get; }

    public DocumentPreviewCard()
    {
        InitializeComponent();
        ViewModel = new DocumentPreviewViewModel();
        BindingContext = ViewModel;
    }

    // 监听BindableProperty变化，同步到ViewModel
    private static void OnDocIdChanged(BindableObject bindable, object oldValue, object newValue)
    {
        if (bindable is DocumentPreviewCard card)
        {
            card.ViewModel.DocId = (Guid?)newValue;
        }
    }

    private static void OnNameChanged(BindableObject bindable, object oldValue, object newValue)
    {
        if (bindable is DocumentPreviewCard card)
        {
            card.ViewModel.Name = (string?)newValue;
        }
    }

    private static void OnThumbnailUriChanged(BindableObject bindable, object oldValue, object newValue)
    {
        if (bindable is DocumentPreviewCard card)
        {
            card.ViewModel.ThumbnailUri = (string?)newValue;
        }
    }
}

这种情况下，控件XAML可以保留原来的绑定（因为BindingContext是ViewModel），无需修改。

关键总结 #

• MAUI自定义控件要支持外部数据绑定，必须为属性定义BindableProperty，这是控件与外部数据交互的标准方式。
• 不要在控件构造函数中硬编码BindingContext，否则会覆盖外部传入的绑定上下文（比如CollectionView中每个Item的数据源）。

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