用途 本技能用于在 Avalonia 中编写和排查数据绑定相关代码,适用于编写数据绑定、编译绑定、转换器、MultiBinding、集合视图、验证以及绑定到命令等场景。
版本差异 12.0+ 默认启用编译绑定(AvaloniaUseCompiledBindingsByDefault 默认 true),不带 x:DataType 的 {Binding} 无法通过编译;编译绑定在构建时校验,不生成反射代码。可按作用域用 x:CompileBindings="False"、按绑定用 {ReflectionBinding} 或全局用 <AvaloniaUseCompiledBindingsByDefault>false</AvaloniaUseCompiledBindingsByDefault> 退出编译绑定。11.x 中编译绑定需显式开启:设置 <AvaloniaUseCompiledBindingsByDefault>true</AvaloniaUseCompiledBindingsByDefault> 或 x:CompileBindings="True";否则 {Binding} 走反射,{CompiledBinding} 需显式书写。
绑定 API(C# 代码) 11.x 使用 IBinding、InstancedBinding、new Binding("Path");12.0+ 使用 BindingBase(ReflectionBinding、CompiledBinding、TemplateBinding、IndexerBinding 派生)、BindingExpressionBase,以及 CompiledBinding.Create((Item item) => item.Value) 形式的类型化编译绑定。12 移除了 BindingPlugins,数据注解验证默认关闭(11.x 默认开启)。
绑定模式 OneWay(源→目标,源变化时更新)、TwoWay(双向)、OneTime(绑定时捕获一次)、OneWayToSource(目标→源)。Default 由属性决定,输入控件通常 TwoWay,显示控件通常 OneWay。
路径语法 支持 {Binding Name}(DataContext 属性)、{Binding Address.Street}(嵌套路径)、{Binding [0]}(索引器)、{Binding [key]}(字典索引器)、{Binding .}(DataContext 本身)、{Binding #controlName.Property}(同作用域命名控件)、{Binding $parent.Property}(最近父控件)、{Binding $parent[Window].Property}(指定类型父控件)、{Binding $parent[1].Property}(上 N 层父级)、{Binding $self.Property}(控件自身)、{Binding $root.Property}(逻辑树根)。注意 $parent、$self、#name 等特殊路径仅适用于编译绑定。
DataContext 沿逻辑树向下继承,子控件自动获得父级 DataContext(除非覆盖)。可在 XAML 中设置,也可用 Design.DataContext 提供设计时数据,或在代码隐藏中赋值。x:DataType 告知编译器 DataContext 类型,每个使用编译绑定的作用域(Window、UserControl、DataTemplate)都必须声明。
转换器 内置转换器位于 Avalonia.Data.Converters:BooleanToVisibilityConverter、StringConverters.IsNullOrEmpty、StringConverters.IsNotNullOrEmpty、ObjectConverters.IsNull、ObjectConverters.IsNotNull、FuncValueConverter<TIn,TOut>。FuncValueConverter 可用内联 lambda,无需单独类。自定义转换器实现 IValueConverter(Convert/ConvertBack),可注册为资源并用 StaticResource 引用,支持 ConverterParameter。
MultiBinding 用 MultiBinding 配合 StringFormat 合并多值;也可实现 IMultiValueConverter。12.0+ 中 FuncMultiValueConverter 的 lambda 参数为 IReadOnlyList<TIn>(11.x 为 IEnumerable<TIn>),可直接索引 values[0]。
回退值 TargetNullValue 在绑定值为 null 时显示;FallbackValue 在绑定完全失败(路径缺失、异常)时显示。
集合绑定 ListBox、DataGrid 通过 ItemsSource 绑定集合。排序和过滤可使用 DataGridCollectionView,添加 SortDescriptions 并设置 Filter;不使用时可用计算属性重新暴露过滤后的集合并触发 PropertyChanged。
数据验证 在属性 setter 中抛出 DataValidationException 可暴露错误;12.0+ 默认关闭数据注解验证,但 setter 异常和 INotifyDataErrorInfo 仍然生效。AvaloniaObject 的 DirectProperty 可通过 enableDataValidation: true 自动报告错误(12.0+)。用内置 DataValidationErrors 控件显示错误,或通过 DataValidationErrors.GetErrors(control) 获取。
命令绑定 Command 绑定到 ICommand 属性,可配合 CommandParameter。可结合 CommunityToolkit.Mvvm 的 [RelayCommand] 或 ReactiveUI 的 ReactiveCommand。Command 必须绑定属性,不能直接绑定方法名。
ItemTemplate 作用域 集合中每个项拥有自己的 DataContext,需在 DataTemplate 上声明 x:DataType。
调试 可对单个绑定启用 diag:Binding.DebugMode=True,或设置 TraceLevel=Verbose。12.0+ 使用 AvaloniaUI.DiagnosticsSupport 包并调用 this.AttachDeveloperTools();11.x 使用 Avalonia.Diagnostics 包并调用 this.AttachDevTools()。DevTools(Debug 构建下 F12)的 Data Context 面板显示 DataContext 层级和属性值,输出窗口会给出绑定错误警告。
常见错误 缺少 x:DataType 导致编译绑定构建失败;绑定非公有成员(编译绑定要求公有属性);未实现 INotifyPropertyChanged 导致更新被静默丢弃;误用 OneTime 期望更新;在 12 代码中写 new Binding(...)/IBinding(应使用 ReflectionBinding/CompiledBinding 和 BindingBase);依赖 12 中已移除或默认关闭的 BindingPlugins 与隐式注解验证;混用 {Binding} 与 {CompiledBinding}(两者相同,应通过 x:CompileBindings=False 显式退出);在编译绑定作用域中使用反射绑定路径;将 Command 绑定到方法名而非 ICommand 属性。
限制 本文所述内容以绑定机制、语法与调试为主,未提供 NuGet 版本要求之外的安装步骤、性能数据或平台兼容性细节;相关事实暂未提供。