在 .NET MAUI 中，双向绑定通常被理解为界面控件与数据对象之间的双向同步：用户在输入控件中的修改会写回 ViewModel 属性，而当 ViewModel 属性发生变化时，界面也会自动刷新。与其他单方向绑定相比，双向绑定不仅是展示链路，更是交互链路。它的实现依赖数据上下文 BindingContext、数据对象对 INotifyPropertyChanged 接口的实现，以及绑定表达式中明确的 Mode 设置。下面从默认绑定模式、手写通知属性、CommunityToolkit.Mvvm 简化以及更新时机几个角度展开说明。
1. MAUI 中的绑定模式与默认 TwoWay 行为
MAUI 的 Binding 类提供五种模式：Default、OneWay、OneTime、OneWayToSource 和 TwoWay。Default 并非固定为 OneWay 或 TwoWay，而是由目标控件属性自身的元数据决定。例如 <Entry> 的 Text 属性允许用户直接编辑，因此默认模式为 TwoWay；<Label> 的 Text 通常只用于展示，默认模式则是 OneWay。
理解默认模式有助于避免不必要的回写。若目标属性是 Slider.Value、Switch.IsToggled、DatePicker.Date 等交互属性，默认大多采用 TwoWay。而 Button.Text、Image.Source 等一般不需要从用户输入回写，默认采用 OneWay。如果在绑定表达式中不写 Mode，MAUI 会按照目标属性的默认模式处理；显式写上 Mode=TwoWay 则让意图更清晰，也能覆盖某些默认不是双向但确实需要回写的场景。
从链路角度看，TwoWay 包含两条通知路径。第一条是控件到 ViewModel：用户修改 Entry 内容时，绑定引擎会把控件新值赋给 ViewModel 属性；第二条是 ViewModel 到控件：当 ViewModel 属性通过 setter 或业务逻辑更新时，必须发出 PropertyChanged 通知，绑定引擎收到后才会刷新控件。缺少其中任何一条路径，都不能称为完整的双向绑定。
2. 手写 INotifyPropertyChanged 实现回写与刷新
实现 ViewModel 是最常见的入口。先创建一个 PersonViewModel 类，实现 System.ComponentModel.INotifyPropertyChanged 接口，并在 Name 属性的 setter 中比对旧值和新值，值确实变化后再触发 PropertyChanged 事件。这样当 Entry 把新文本写回 Name 属性时，setter 会发出通知，关联的 Label 或其他展示控件就会同步更新。
XAML 端的配置并不复杂。可以在 ContentPage 中直接创建 BindingContext，例如使用 <ContentPage.BindingContext> 和 <vm:PersonViewModel />，或者在后置代码中赋值 BindingContext = new PersonViewModel();。然后在 <Entry> 的 Text 属性上写绑定表达式，显式指定 Mode=TwoWay。虽然 Entry.Text 默认已经是 TwoWay，但显式声明可以让绑定意图更加明确。
完整的 ViewModel 代码示例如下。
using System.ComponentModel;
using System.Runtime.CompilerServices;
namespace Demo.ViewModels;
public class PersonViewModel : INotifyPropertyChanged
{
private string _name = string.Empty;
public string Name
{
get => _name;
set
{
if (_name != value)
{
_name = value;
OnPropertyChanged();
}
}
}
public event PropertyChangedEventHandler? PropertyChanged;
private void OnPropertyChanged([CallerMemberName] string? propertyName = null)
{
PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
}
}
如果不想在 XAML 中配置，也可以在代码文件中通过 Binding 对象创建同样的绑定。主要步骤是新建 Binding 实例，设置 Path 和 Mode，然后调用控件的 SetBinding 方法。这种方式适合动态构建界面或根据业务条件调整绑定模式。
var entry = new Entry();
var binding = new Binding
{
Path = "Name",
Mode = BindingMode.TwoWay
};
entry.SetBinding(Entry.TextProperty, binding);
无论哪种方式，只要 PropertyChanged 触发正常，输入框输入“张三”后，显示姓名的 Label 会自动变为“当前姓名：张三”；如果在代码中执行 vm.Name = "李四";，Entry 和 Label 也会同时更新。
3. 使用 CommunityToolkit.Mvvm 减少样板代码
手写 INotifyPropertyChanged 每次都要声明字段、属性、事件和通知方法，属性一多代码量就会迅速膨胀。CommunityToolkit.Mvvm 提供了源生成器方案，通过 partial class 和特性标注自动生成带通知的属性。在项目中安装 CommunityToolkit.Mvvm 包后，可以让 ViewModel 继承 ObservableObject，并对私有字段添加 ObservableProperty 特性。
using CommunityToolkit.Mvvm.ComponentModel;
namespace Demo.ViewModels;
public partial class PersonViewModel : ObservableObject
{
[ObservableProperty]
private string name = string.Empty;
}
源生成器会根据私有字段 name 自动生成公开属性 Name，并在 setter 中处理通知逻辑。开发者在 XAML 中仍然可以使用 {Binding Name, Mode=TwoWay}。这种方式的优势不只是少写代码，更重要的是避免手写 setter 时忘记调用 PropertyChanged，或者因为字符串属性名拼写错误导致通知失效。对于中大型项目，推荐优先采用此方案。
4. 更新时机控制与常见绑定故障排查
双向绑定并非任何时候都需要在每次按键时立即回写。例如搜索输入框，可能希望用户按回车或输入完成后才触发搜索逻辑，而不是每输入一个字符就更新数据源。MAUI 的 Binding 对象提供了 UpdateSourceEventName 属性，可以把默认的 TextChanged 回写时机改成 Completed。示例中 UpdateSourceEventName=Completed 表示用户完成输入并触发 Completed 事件时才写回 Remark 属性。
<Entry Text="{Binding Remark, Mode=TwoWay, UpdateSourceEventName=Completed}" />
需要留意的是，UpdateSourceEventName 只影响控件到 ViewModel 的回写方向，不会影响 ViewModel 到控件的刷新方向。也就是说，代码中修改 Remark 属性仍然会即时刷新 Entry 显示，因为该方向由 PropertyChanged 通知驱动。
排查双向绑定失效时，可以先按四个方向检查：一是页面或控件的 BindingContext 是否已正确赋值，二是绑定表达式中 Path 和属性名是否与 ViewModel 完全一致，三是 ViewModel 属性 setter 是否真正触发了 PropertyChanged，四是目标控件属性是否支持可写，若目标属性只有 getter 则无法完成回写。调试级别设为详细时，Visual Studio 输出窗口也会给出绑定错误提示，例如找不到属性、路径解析失败或类型转换异常，这些信息通常能直接定位问题。
MAUI双向绑定TwoWay BindingC# MAUI修改时间：2026-09-02 19:47:18