Windows 数据绑定概述

2025-08-27

使用 Windows App SDK 的 WinUI 应用中的数据绑定使你可以有效地将控件连接到数据源。本文介绍如何将控件绑定到单个项或将项控件绑定到项集合。你还将了解如何控制项呈现、基于所选内容实现详细信息视图以及转换要显示的数据。有关更多详细信息，请参阅深入了解数据绑定。

先决条件

本主题假定你知道如何使用 Windows 应用 SDK 创建基本 WinUI 应用。有关创建第一个 WinUI 应用的说明，请参阅 “创建 WinUI 应用”。

创建项目

创建新的 WinUI 空白应用，打包 的 C# 项目。将其命名为“快速入门”。

绑定到单个项

每个绑定都由绑定目标和绑定源组成。通常，目标是控件或其他 UI 元素的属性，源是类实例（数据模型或视图模型）的属性。此示例演示如何将控件绑定到单个项。目标是 Text 的 TextBlock 属性。源代码是一个简单类 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();
        public Recording DefaultRecording { get { return defaultRecording; } }
    }
}

接下来，从表示标记窗口的类公开绑定源类。为此，我们将类型为 RecordingViewModel 的属性添加到 MainWindow.xaml.cs。

namespace Quickstart
{
    public sealed partial class MainWindow : Window
    {
        public MainWindow()
        {
            this.InitializeComponent();
        }
        public RecordingViewModel ViewModel{ get; } = new RecordingViewModel();
    }
}

最后一布是将 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> 类，因为它实现 INotifyCollectionChanged 接口，该接口在添加或删除项时向绑定提供更改通知。但是，由于 .NET 8 及更高版本的已知 WinUI 发布模式 bug，在某些情况下可能需要使用列表<T> ，尤其是在集合是静态的且初始化后不会更改时。如果你的 UI 需要在运行时更新集合更改，请使用 ObservableCollection<T>。如果只需要显示一组固定的项目， List<T> 则足够。此外，如果希望绑定控件使用对集合中对象的属性的更改进行更新，这些对象应实现 INotifyPropertyChanged。有关详细信息，请参阅深入了解数据绑定。

备注

通过使用 List<T>，可能不会收到集合更改的更改通知。如果需要响应更改，请考虑使用 ObservableCollection<T>。在我们的示例中，我们不需要响应集合更改，因此 List<T> 已足够。

下一个示例将 ListView 绑定到 Recording 对象的集合。首先，将集合添加到视图模型。只需将这些新成员添加到 RecordingViewModel 类即可。

public class RecordingViewModel
{
    ...
    private List<Recording> recordings = new();
    public List<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 的默认实现是返回类型名称。

绑定列表视图 1

若要解决此问题，我们可以重写 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>

绑定列表视图 2

<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>

绑定列表视图 3

有关 XAML 语法的详细信息，请参阅使用 XAML创建 UI。有关控件布局的详细信息，请参阅使用 XAML定义布局。

添加详细信息视图

可以选择 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}}" ...>
...

下面是每个案例的相同结果。

绑定列表视图 4

设置或转换要显示的数据值的格式或转换

以上呈现有一个问题。 ReleaseDateTime 属性不仅是一个日期，它还是一个 DateTime。因此，它显示的精度比我们需要的要高。一种解决方案是向返回等效 Recording的 ReleaseDateTime.ToString("d") 类添加字符串属性。命名该属性 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 的实例添加为页面资源，并可在显示 TextBlock 属性的 ReleaseDateTime 的绑定中使用。

<Grid.Resources>
    ...
    <local:StringFormatter x:Key="StringFormatterValueConverter"/>
</Grid.Resources>
...
<TextBlock Text="{Binding ReleaseDateTime,
    Converter={StaticResource StringFormatterValueConverter},
    ConverterParameter=Released: \{0:d\}}"/>
...

如上所示，为了灵活地设置格式，我们使用标记通过转换器参数将格式字符串传递到转换器。在本主题所示的代码示例中，C# 值转换器使用该参数。

下面是结果。

显示具有自定义格式的日期

数据绑定

反馈

此页面是否有帮助？