Blazor中[BindProperty]为何需要匹配的EventCallback？

问题场景 #

我定义了一个Blazor内部组件Address，代码如下：

public partial class Address
{
    [BindProperty]
    [Parameter]
    public MapAddressDto? Value { get; set; }

    // 其他代码
}

在外部Razor文件中使用该组件时，使用了双向绑定语法：

<Address 
    @ref="_addressElement"
    @bind-Value="@Model.Address"
    Selected="OnAddressSelected">
</Address>

运行页面时抛出异常：

InvalidOperationException: Object of type 'LouisHowe.web.Shared.Address' does not have a property matching the name 'ValueChanged'.
Microsoft.AspNetCore.Components.Reflection.ComponentProperties.ThrowForUnknownIncomingParameterName(Type targetType, string parameterName)
...
Microsoft.AspNetCore.Razor.Runtime.TagHelpers.TagHelperRunner.<RunAsync>g__Awaited|0_0(Task task, TagHelperExecutionContext executionContext, int i, int count)
LouisHowe.web.Pages.Pages__Host.<ExecuteAsync>b__23_1() in _Host.cshtml
+
    <component type="typeof(App)" render-mode="ServerPrerendered" param-InitialState="initialTokenState" />
Microsoft.AspNetCore.Razor.Runtime.TagHelpers.TagHelperExecutionContext.SetOutputContentAsync()
LouisHowe.web.Pages.Pages__Host.ExecuteAsync()
...

添加EventCallback<MapAddressDto> ValueChanged后，页面运行恢复正常：

public partial class Address
{
    [BindProperty]
    [Parameter]
    public MapAddressDto? Value { get; set; }

    public EventCallback<MapAddressDto> ValueChanged { get; set; }

    // 其他代码
}

观察DevExpress Blazor组件后发现，每个Value属性都对应ValueChanged事件，因此产生疑问：使用[BindProperty]时，是否必须匹配对应的EventCallback？原因是什么？

解答 #

核心结论 #

当使用Blazor的@bind-*双向绑定语法时，必须为组件的目标属性提供对应命名的EventCallback<T>，这和[BindProperty]本身无关，本质是Blazor双向绑定的机制要求。

具体原因 #

1. 双向绑定的语法糖本质
   @bind-Value="xxx"是Blazor提供的语法糖，编译后会拆解为两个逻辑：

   • 将父组件的xxx值传递给子组件的Value参数
   • 订阅子组件的ValueChanged事件，当事件触发时自动更新父组件的xxx值
     如果子组件没有暴露ValueChanged这个EventCallback<T>，Blazor无法完成事件订阅，就会抛出找不到对应属性的异常。

2. [BindProperty]的真实作用
   [BindProperty]特性的设计场景是Razor页面/组件的表单模型绑定，用于自动将表单控件的值绑定到页面级的属性上，它不会自动生成双向绑定所需的EventCallback。
   在组件参数上标记[BindProperty]其实是多余的，组件参数只需要[Parameter]特性即可。

3. 组件双向绑定的标准实现
   要实现组件的双向绑定，正确的结构应该是：

   • 一个带[Parameter]特性的属性（如Value）
   • 一个命名为[属性名]Changed的EventCallback<T>参数（如ValueChanged）
   • 当组件内部需要更新值时，调用ValueChanged.InvokeAsync(新值)通知父组件同步更新绑定变量

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