Visão geral da associação de dados do Windows

Este tópico mostra como associar um controle (ou outro elemento da IU) a um único item ou um controle de itens a uma coleção de itens em um aplicativo do SDK de Aplicativo do Windows. Este tópico também mostra como controlar a renderização de itens, implementar uma exibição de detalhes com base em uma seleção e converter dados para exibição. Para obter mais informações detalhadas, consulte Vinculação de dados em detalhes.

Pré-requisitos

Este tópico pressupõe que você saiba como criar um aplicativo básico do SDK de Aplicativo do Windows. Para saber como criar seu primeiro aplicativo do SDK de Aplicativo do Windows, confira Criar seu primeiro projeto do WinUI 3 (SDK de Aplicativo do Windows).

Criar o projeto

Crie um projeto C# de Aplicativo em branco empacotado (WinUI 3 na Área de Trabalho). Nomeie-o como "Início rápido".

Associação a um único item

Cada associação consiste em um destino da associação e uma origem de associação. Normalmente, o destino é uma propriedade de um controle ou outro elemento de interface do usuário, e a origem é uma propriedade de uma instância de classe (um modelo de dados ou um modelo de exibição). Este exemplo mostra como associar um controle a um único item. O destino é a propriedade Text de um TextBlock. A origem é uma instância de uma classe simples denominada Recording que representa uma gravação de áudio. Primeiro, vamos examinar a classe.

Adicione uma classe ao projeto e nomeie-a 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; } }
    }
}

Em seguida, exponha a classe da fonte de associação da classe que representa a janela de marcação. Para isso, adicione uma propriedade do tipo RecordingViewModel a MainWindow.xaml.cs.

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

A última parte é associar um TextBlock à propriedade ViewModel.DefaultRecording.OneLineSummary.

<Window x:Class="Quickstart.MainWindow" ... >
    <Grid>
        <TextBlock Text="{x:Bind ViewModel.DefaultRecording.OneLineSummary}"
    HorizontalAlignment="Center"
    VerticalAlignment="Center"/>
    </Grid>
</Window>

Consulte o resultado.

Associação a uma coleção de itens

Um cenário comum é associar a uma coleção de objetos comerciais. Em C#, a classe genérica ObservableCollection<T> é uma boa escolha de coleção para a associação de dados porque ela implementa as interfaces INotifyPropertyChanged e INotifyCollectionChanged. Essas interfaces fornecem notificação de alteração para associações quando itens são adicionados ou removidos ou uma propriedade da lista muda. Se você quiser que os controles associados sejam atualizados com alterações em propriedades de objetos na coleção, o objeto comercial também deve implementar INotifyPropertyChanged. Para obter mais informações, consulte Vinculação de dados em detalhes.

O exemplo seguinte associa ListView a uma coleção de objetos Recording. Vamos começar adicionando a coleção ao nosso modelo de exibição. Basta adicionar esses novos membros à classe 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) });
    }
}

E, em seguida, associar uma ListView à propriedade ViewModel.Recordings.

<Window x:Class="Quickstart.MainWindow" ... >
    <Grid>
        <ListView ItemsSource="{x:Bind ViewModel.Recordings}"
        HorizontalAlignment="Center" VerticalAlignment="Center"/>
    </Grid>
</Window>

Ainda não fornecemos um modelo de dados para a classe Recording, portanto o melhor que a estrutura da IU pode fazer é chamar ToString para cada item na ListView. A implementação padrão do ToString é retornar o nome do tipo.

Para corrigir isso, podemos substituir ToString para retornar o valor de OneLineSummary ou podemos fornecer um modelo de dados. A opção de modelo de dados é uma solução mais comum e flexível. Você especifica um modelo de dados usando a propriedade ContentTemplate de um controle de conteúdo ou a propriedade ItemTemplate de um controle de itens. Aqui estão duas maneiras de criar um modelo de dados para Recording com uma ilustração do resultado.

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

Para obter mais informações sobre a sintaxe XAML, consulte Criar uma interface do usuário com XAML. Para obter mais informações sobre o layout de controle, consulte Definir layouts com XAML.

Adicionando uma visão de detalhes

Você pode optar por exibir todos os detalhes dos objetos Recording nos itens ListView. Mas isso ocupa muito espaço. Em vez disso, você pode mostrar apenas dados suficientes no item para identificá-lo e, em seguida, quando o usuário fizer uma seleção, pode exibir todos os detalhes do item selecionado em um componente separado da interface do usuário conhecido como o modo de exibição de detalhes. Além disso, esse esquema também é conhecido como um modo de exibição mestre/detalhado, ou um modo de exibição de lista/detalhes.

Há duas maneiras de lidar com isso. Você pode associar o modo de exibição de detalhes à propriedade SelectedItem do ListView. Ou você pode usar CollectionViewSource e, nesse caso, associar ListView e o modo de exibição de detalhes a CollectionViewSource (o que cuida do item atualmente selecionado por você). As duas técnicas são mostradas abaixo e geram os mesmos resultados (exibidos na ilustração).

Observação

Até agora neste tópico só usamos a extensão de marcação {x:Bind}, mas ambas as técnicas mostradas abaixo requerem a extensão de marcação {Binding} mais flexível (mas menos eficiente).

Primeiro, a técnica SelectedItem. Para um aplicativo C#, a única alteração necessária é na marcação.

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

Para a técnica CollectionViewSource, primeiro adicione um CollectionViewSource como um recurso de página.

<Window.Resources>
    <CollectionViewSource x:Name="RecordingsCollection" Source="{x:Bind ViewModel.Recordings}"/>
</Window.Resources>

E, em seguida, ajuste as associações no ListView (que não precisa mais ser chamado) e no modo de exibição de detalhes para usar o CollectionViewSource. Observe que, associando o modo de exibição de detalhes diretamente a CollectionViewSource, você está indicando que deseja associar ao item atual em associações em que o caminho não pode ser encontrado na coleção em si. Não é necessário especificar a propriedade CurrentItem como o caminho para a associação, embora você possa fazer isso se houver ambiguidade.

...
<ListView ItemsSource="{Binding Source={StaticResource RecordingsCollection}}">
...
<StackPanel DataContext="{Binding Source={StaticResource RecordingsCollection}}" ...>
...

E aqui está o resultado idêntico em cada caso.

Formatação ou conversão de valores de dados para exibição

Há um pequeno problema com a renderização acima. A propriedade ReleaseDateTime não é somente uma data, mas um DateTime. Devido a isso, ela é exibida com mais precisão do que o necessário. Uma solução é adicionar uma propriedade de cadeia de caracteres à classe Recording, que retorna o equivalente de ReleaseDateTime.ToString("d"). Nomear essa propriedade como ReleaseDate indica que ela retorna uma data, não uma data e hora. Chamar ReleaseDateAsString indica ainda mais que ela retorna uma string.

Uma solução mais flexível é usar algo conhecido como um conversor de valor. Consulte um exemplo de como criar seu próprio conversor de valor. Adicione o código abaixo ao arquivo de código-fonte 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();
    }
}

Agora, podemos adicionar uma instância de StringFormatter como um recurso de página e usá-la na associação de TextBlock, que exibe a propriedade ReleaseDateTime.

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

Como podemos ver acima, para garantir a flexibilidade de formatação, usamos a marcação para passar uma cadeia de caracteres de formato ao conversor por meio do parâmetro do conversor. No exemplo de código mostrado neste tópico, o conversor de valor C# usa esse parâmetro.

Consulte o resultado.

Confira também

• Vinculação de dados