Windows 数据绑定概述
本主题介绍如何将控件（或其他 UI 元素）绑定到单个项，或将项控件绑定到 Windows 应用 SDK 应用中的项集合。 此外，我们还演示如何控制项的呈现、基于所选内容实现详细信息视图，以及转换要显示的数据。 有关更多详细信息，请参阅深入了解数据绑定。
先决条件
本主题假定你知道如何创建基本的 Windows 应用 SDK 应用。 有关创建第一个 Windows 应用 SDK 应用的说明，请参阅 创建第一个 WinUI 3 （Windows 应用 SDK） 项目。
创建项目
创建一个新的“打包的空白应用(桌面版 WinUI 3)”C# 项目。 将其命名为“快速入门”。
绑定到单个项目
每个绑定都由绑定目标和绑定源组成。 通常，目标是控件或其他 UI 元素的属性，源是类实例（数据模型或视图模型）的属性。 此示例演示如何将控件绑定到单个项。 目标是 TextBlock 的 Text 属性。 源代码是一个简单类 Recording 的实例，该类用于表示音频录制。 我们先来看一下类。
向项目添加新类，并将类命名为 Recording。
namespace Quickstart
{
public class Recording
{
public string ArtistName { get; set; }
public string CompositionName { get; set; }
public DateTime ReleaseDateTime { get; set; }
public Recording()
{
ArtistName = "Wolfgang Amadeus Mozart";
CompositionName = "Andante in C for Piano";
ReleaseDateTime = new DateTime(1761, 1, 1);
}
public string OneLineSummary
{
get
{
return $"{CompositionName} by {ArtistName}, released: "
+ ReleaseDateTime.ToString("d");
}
}
}
public class RecordingViewModel
{
private Recording defaultRecording = new Recording();
public Recording DefaultRecording { get { return defaultRecording; } }
}
}
接下来，从表示标记窗口的类公开绑定源类。 为此，我们将类型为 RecordingViewModel 的属性添加到 MainWindow.xaml.cs。
namespace Quickstart
{
public sealed partial class MainWindow : Window
{
public MainWindow()
{
this.InitializeComponent();
ViewModel = new RecordingViewModel();
}
public RecordingViewModel ViewModel{ get; set; }
}
}
最后一布是将 TextBlock 绑定到 ViewModel.DefaultRecording.OneLineSummary 属性。
<Window x:Class="Quickstart.MainWindow" ... >
<Grid>
<TextBlock Text="{x:Bind ViewModel.DefaultRecording.OneLineSummary}"
HorizontalAlignment="Center"
VerticalAlignment="Center"/>
</Grid>
</Window>
下面是结果。
绑定到项目集合
一个常见情形是绑定到业务对象的集合。 在 C# 中，泛型 ObservableCollection<T> 类是数据绑定的良好集合选择，因为它实现了 INotifyPropertyChanged 和 INotifyCollectionChanged 接口。 当添加或删除项或列表本身的属性发生更改时，这些接口会向绑定提供更改通知。 如果希望绑定控件随集合中对象的属性更改而更新，业务对象还应实现 INotifyPropertyChanged。 有关详细信息，请参阅深入了解数据绑定。
下一个示例将 ListView 绑定到 Recording 对象的集合。 首先，将集合添加到视图模型。 只需将这些新成员添加到 RecordingViewModel 类即可。
public class RecordingViewModel
{
...
private ObservableCollection<Recording> recordings = new ObservableCollection<Recording>();
public ObservableCollection<Recording> Recordings{ get{ return recordings; } }
public RecordingViewModel()
{
recordings.Add(new Recording(){ ArtistName = "Johann Sebastian Bach",
CompositionName = "Mass in B minor", ReleaseDateTime = new DateTime(1748, 7, 8) });
recordings.Add(new Recording(){ ArtistName = "Ludwig van Beethoven",
CompositionName = "Third Symphony", ReleaseDateTime = new DateTime(1805, 2, 11) });
recordings.Add(new Recording(){ ArtistName = "George Frideric Handel",
CompositionName = "Serse", ReleaseDateTime = new DateTime(1737, 12, 3) });
}
}
然后将 ListView 绑定到 ViewModel.Recordings 属性。
<Window x:Class="Quickstart.MainWindow" ... >
<Grid>
<ListView ItemsSource="{x:Bind ViewModel.Recordings}"
HorizontalAlignment="Center" VerticalAlignment="Center"/>
</Grid>
</Window>
我们尚未为 Recording 类提供数据模板，因此 UI 框架可以做的最好是针对 ListView中的每个项调用 ToString。 ToString 的默认实现是返回类型名称。
若要解决此问题，我们可以重写 ToString 以返回 OneLineSummary的值，也可以提供数据模板。 数据模板选项是更常见的解决方案，也是更灵活的解决方案。 通过使用内容控件的 ContentTemplate 属性或项控件的 ItemTemplate 属性来指定数据模板。 这里有两种方法设计 Recording 的数据模板，并附有结果示意图。
<ListView ItemsSource="{x:Bind ViewModel.Recordings}"
HorizontalAlignment="Center" VerticalAlignment="Center">
<ListView.ItemTemplate>
<DataTemplate x:DataType="local:Recording">
<TextBlock Text="{x:Bind OneLineSummary}"/>
</DataTemplate>
</ListView.ItemTemplate>
</ListView>
<ListView ItemsSource="{x:Bind ViewModel.Recordings}"
HorizontalAlignment="Center" VerticalAlignment="Center">
<ListView.ItemTemplate>
<DataTemplate x:DataType="local:Recording">
<StackPanel Orientation="Horizontal" Margin="6">
<SymbolIcon Symbol="Audio" Margin="0,0,12,0"/>
<StackPanel>
<TextBlock Text="{x:Bind ArtistName}" FontWeight="Bold"/>
<TextBlock Text="{x:Bind CompositionName}"/>
</StackPanel>
</StackPanel>
</DataTemplate>
</ListView.ItemTemplate>
</ListView>
有关 XAML 语法的详细信息，请参阅 使用 XAML创建 UI。 有关控件布局的详细信息，请参阅 使用 XAML定义布局。
添加详细信息视图
可以选择 ListView 项中显示 Recording 对象的所有详细信息。 但这占用了很多空间。 相反，你可以在项目中显示足够的数据来标识它，然后在用户做出选择时，可以在称为详细信息视图的单独 UI 中显示所选项的所有详细信息。 这种排列方式也称为主视图/详细信息视图或列表/详细信息视图。
有两种方法可以解决此问题。 可以将详细信息视图绑定到 ListView的 SelectedItem 属性。 或者，可以使用 CollectionViewSource，在此种情况下将 ListView 和详细信息视图同时绑定到 CollectionViewSource（这将为你处理当前选定的项目）。 下面显示了这两种技术，它们都给出了相同的结果（如图所示）。
备注
到目前为止，在本主题中，我们只使用了 {x：Bind} 标记扩展，但下面显示的两种技术都需要更灵活（但性能较低的）{Binding} 标记扩展。
首先介绍的是 SelectedItem 技术。 对于 C# 应用程序，唯一必要的更改是代码标记。
<Window x:Class="Quickstart.MainWindow" ... >
<Grid>
<StackPanel HorizontalAlignment="Center" VerticalAlignment="Center">
<ListView x:Name="recordingsListView" ItemsSource="{x:Bind ViewModel.Recordings}">
<ListView.ItemTemplate>
<DataTemplate x:DataType="local:Recording">
<StackPanel Orientation="Horizontal" Margin="6">
<SymbolIcon Symbol="Audio" Margin="0,0,12,0"/>
<StackPanel>
<TextBlock Text="{x:Bind CompositionName}"/>
</StackPanel>
</StackPanel>
</DataTemplate>
</ListView.ItemTemplate>
</ListView>
<StackPanel DataContext="{Binding SelectedItem, ElementName=recordingsListView}"
Margin="0,24,0,0">
<TextBlock Text="{Binding ArtistName}"/>
<TextBlock Text="{Binding CompositionName}"/>
<TextBlock Text="{Binding ReleaseDateTime}"/>
</StackPanel>
</StackPanel>
</Grid>
</Window>
对于 CollectionViewSource 技术，请先将 CollectionViewSource 添加为顶级 Grid 的资源。
<Grid.Resources>
<CollectionViewSource x:Name="RecordingsCollection" Source="{x:Bind ViewModel.Recordings}"/>
</Grid.Resources>
注意
WinUI 中的 Window 类没有 Resources 属性。 可以改为将 CollectionViewSource 添加到顶级 Grid（或 StackPanel 等其他父 UI 元素）元素中。 如果在 Page 中工作，则可以将 CollectionViewSource 添加到 Page.Resources。
然后，在 ListView（无需再对其进行命名）和详细信息视图上调节绑定，以使用 CollectionViewSource。 请注意，如果将详细信息视图直接绑定到 CollectionViewSource，即表示你希望绑定到绑定中的当前项目，其中在集合本身上无法找到路径。 无需将 CurrentItem 属性指定为绑定的路径，但如果存在任何歧义，则可以执行此操作。
...
<ListView ItemsSource="{Binding Source={StaticResource RecordingsCollection}}">
...
<StackPanel DataContext="{Binding Source={StaticResource RecordingsCollection}}" ...>
...
下面是每个案例的相同结果。
设置或转换要显示的数据值的格式
以上呈现有一个问题。 ReleaseDateTime 属性不仅是一个日期，它还是一个 DateTime。 因此，它显示的精度比我们需要的要高。 一种解决方案是向返回等效 ReleaseDateTime.ToString("d")的 Recording 类添加字符串属性。 命名该属性 ReleaseDate 将指示它返回日期，而不是日期和时间。 将其命名 ReleaseDateAsString 会进一步指示它返回字符串。
更灵活的解决方案是使用称为值转换器的东西。 下面是有关如何创作自己的值转换器的示例。 将下面的代码添加到 Recording.cs 源代码文件。
public class StringFormatter : Microsoft.UI.Xaml.Data.IValueConverter
{
// This converts the value object to the string to display.
// This will work with most simple types.
public object Convert(object value, Type targetType,
object parameter, string language)
{
// Retrieve the format string and use it to format the value.
string formatString = parameter as string;
if (!string.IsNullOrEmpty(formatString))
{
return string.Format(formatString, value);
}
// If the format string is null or empty, simply
// call ToString() on the value.
return value.ToString();
}
// No need to implement converting back on a one-way binding
public object ConvertBack(object value, Type targetType,
object parameter, string language)
{
throw new NotImplementedException();
}
}
现在，我们可以将 StringFormatter 的实例添加为页面资源，并可在显示 ReleaseDateTime 属性的 TextBlock 的绑定中使用。
<Grid.Resources>
...
<local:StringFormatter x:Key="StringFormatterValueConverter"/>
</Grid.Resources>
...
<TextBlock Text="{Binding ReleaseDateTime,
Converter={StaticResource StringFormatterValueConverter},
ConverterParameter=Released: \{0:d\}}"/>
...
如上所示，为了灵活地设置格式，我们使用标记通过转换器参数将格式字符串传递到转换器。 在本主题所示的代码示例中，C# 值转换器使用该参数。
下面是结果。
