Vinculação de dados do Windows em profundidade

Este artigo descreve os recursos de associação de dados WinUI usando as APIs no namespace Microsoft.UI.Xaml.Data.

APIs importantes

• {x:Bind} extensão de marcação
• Classe de vinculação
• DataContext
• INotifyPropertyChanged

Introdução

A associação de dados é uma técnica que permite que a interface do usuário do seu aplicativo exiba e sincronize dados de forma eficiente. Ao separar as preocupações com dados das preocupações com a interface do usuário, ele simplifica o design do aplicativo, melhora a legibilidade e melhora a capacidade de manutenção.

Você pode usar a associação de dados para simplesmente exibir valores de uma fonte de dados quando a interface do usuário é mostrada pela primeira vez, mas não para responder a alterações nesses valores. Esse modo de vinculação é chamado de one-time e funciona bem para um valor que não muda durante o tempo de execução. Como alternativa, você pode optar por "observar" os valores e atualizar a interface do usuário quando eles forem alterados. Esse modo é chamado de unidirecional e funciona bem para dados somente leitura. Em última análise, você pode optar por observar e atualizar, para que as alterações feitas pelo usuário nos valores na interface do usuário sejam automaticamente enviadas de volta para a fonte de dados. Esse modo é chamado de bidirecional e funciona bem para dados de leitura-gravação. Eis alguns exemplos.

• Você pode usar o modo único para vincular uma imagem à foto do usuário atual.
• Você pode usar o modo unidirecional para vincular um ListView a uma coleção de artigos de notícias em tempo real agrupados por seção de jornal.
• Você pode usar o modo bidirecional para vincular um TextBox ao nome de um cliente em um formulário.

Independentemente do modo, há dois tipos de vinculação, e você normalmente declara ambos na marcação da interface do usuário. Você pode optar por usar a extensão de marcação {x:Bind} ou a extensão de marcação {Binding}. Você pode até usar uma mistura dos dois no mesmo aplicativo, mesmo no mesmo elemento da interface do usuário. {x:Bind} foi novo na UWP para Windows 10 e tem melhor desempenho. Todos os detalhes descritos neste tópico aplicam-se a ambos os tipos de vinculação, a menos que digamos explicitamente o contrário.

Aplicações de exemplo UWP que demonstram {x:Bind}

• Exemplo {x:Bind}.
• Jogo de Quiz.
• Exemplo de noções básicas da interface do usuário XAML.

Aplicações de exemplo UWP que demonstram {Binding}

• Baixe o aplicativo UWP Bookstore1 .
• Transfira a aplicação Livraria2 .

Toda encadernação envolve essas peças

• Uma fonte de ligação. Esta fonte fornece os dados para a associação. Pode ser uma instância de qualquer classe que tenha membros cujos valores você deseja exibir em sua interface do usuário.
• Um alvo vinculativo. Este alvo é um DependencyProperty do FrameworkElement na sua interface do usuário que exibe os dados.
• Um objeto de ligação. Este objeto transfere valores de dados da origem para o destino e, opcionalmente, do destino de volta para a origem. O objeto de vinculação é criado no tempo de carregamento XAML a partir da sua extensão de marcação {x:Bind} ou {Binding} .

Nas seções a seguir, você examina mais de perto a origem da vinculação, o destino da vinculação e o objeto de vinculação. As seções se vinculam juntamente com o exemplo de vinculação do conteúdo de um botão a uma propriedade de cadeia de caracteres chamada NextButtonText, que pertence a uma classe chamada HostViewModel.

Fonte de ligação

Aqui está uma implementação básica de uma classe que você pode usar como uma fonte de vinculação.

public class HostViewModel
{
    public HostViewModel()
    {
        NextButtonText = "Next";
    }

    public string NextButtonText { get; set; }
}

Essa implementação da HostViewModel, e sua propriedade NextButtonText, funcionam apenas para vinculação única. Mas as ligações unidirecionais e bidirecionais são extremamente comuns. Nesses tipos de associação, a interface do usuário é atualizada automaticamente em resposta a alterações nos valores de dados da fonte de vinculação. Para que esses tipos de vinculação funcionem corretamente, você precisa tornar sua fonte de vinculação observável para o objeto de vinculação. Portanto, no nosso exemplo, se pretender vincular unidirecionalmente ou bidirecionalmente à propriedade NextButtonText, todas as alterações que ocorrerem durante a execução no valor dessa propriedade precisam ser observáveis pelo objeto de ligação.

Uma maneira de fazer isso é derivar a classe que representa sua fonte de vinculação de DependencyObject e expor um valor de dados por meio de um DependencyProperty*. É assim que um FrameworkElement se torna observável. A FrameworkElement é uma boa fonte de ligação logo de cara.

Uma maneira mais leve de tornar uma classe observável — e necessária para classes que já têm uma classe base — é implementar System.ComponentModel.INotifyPropertyChanged. Essa abordagem envolve a implementação de um único evento chamado PropertyChanged. Um exemplo de uso HostViewModel é mostrado no código a seguir.

...
using System.ComponentModel;
using System.Runtime.CompilerServices;
...
public class HostViewModel : INotifyPropertyChanged
{
    private string nextButtonText;

    public event PropertyChangedEventHandler PropertyChanged = delegate { };

    public HostViewModel()
    {
        NextButtonText = "Next";
    }

    public string NextButtonText
    {
        get { return nextButtonText; }
        set
        {
            nextButtonText = value;
            OnPropertyChanged();
        }
    }

    public void OnPropertyChanged([CallerMemberName] string propertyName = null)
    {
        // Raise the PropertyChanged event, passing the name of the property whose value has changed.
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
    }
}

Agora a NextButtonText propriedade é observável. Quando você cria uma associação unidirecional ou bidirecional para essa propriedade (mostraremos como mais tarde), o objeto de vinculação resultante se inscreve no PropertyChanged evento. Quando esse evento é gerado, o manipulador do objeto de vinculação recebe um argumento contendo o nome da propriedade que foi alterada. É assim que o objeto de vinculação sabe qual valor da propriedade deve ser lido novamente.

Para que você não precise implementar o padrão mostrado anteriormente várias vezes, se estiver usando C#, você pode derivar da BindableBase classe base que encontrará no exemplo QuizGame (na pasta "Comum"). Aqui está um exemplo de como isso parece.

public class HostViewModel : BindableBase
{
    private string nextButtonText;

    public HostViewModel()
    {
        NextButtonText = "Next";
    }

    public string NextButtonText
    {
        get { return nextButtonText; }
        set { SetProperty(ref nextButtonText, value); }
    }
}

Gerar o PropertyChanged evento com um argumento de String.Empty ou null indica que todas as propriedades não indexadoras no objeto devem ser relidas. Você pode gerar o evento para indicar que as propriedades do indexador no objeto foram alteradas usando um argumento de "Item[indexer]" para indexadores específicos (onde indexador é o valor do índice) ou um valor de "Item[]" para todos os indexadores.

Você pode tratar uma fonte de associação como um único objeto cujas propriedades contêm dados ou como uma coleção de objetos. No código C#, você pode ligar uma vez a um objeto que implementa List<T> para exibir uma coleção que não muda em tempo de execução. Para uma coleção observável (observando quando os itens são adicionados e removidos da coleção), faça uma ligação unidirecional a ObservableCollection<T>. Para vincular às suas próprias classes de coleção, use as orientações na tabela a seguir.

Você pode vincular controles de lista a fontes de dados arbitrariamente grandes e ainda obter alto desempenho usando carregamento incremental. Por exemplo, você pode vincular controles de lista aos resultados da consulta de imagem do Bing sem ter que carregar todos os resultados de uma só vez. Em vez disso, você carrega apenas alguns resultados imediatamente e carrega resultados adicionais conforme necessário. Para dar suporte ao carregamento incremental, você deve implementar ISupportIncrementalLoading em uma fonte de dados que ofereça suporte a notificações de alteração de coleção. Quando o mecanismo de vinculação de dados solicita mais dados, sua fonte de dados deve fazer as solicitações apropriadas, integrar os resultados e, em seguida, enviar as notificações apropriadas para atualizar a interface do usuário.

Destino vinculativo

Nos dois exemplos a seguir, a Button.Content propriedade é o destino de ligação. Seu valor é definido como uma extensão de marcação que declara o objeto de ligação. O primeiro exemplo mostra {x:Bind}, e o segundo exemplo mostra {Binding}. Declarar ligações na marcação é o caso comum porque é conveniente, legível e permite o uso de ferramentas. Mas se precisar, você pode evitar a marcação e criar imperativamente (programaticamente) uma instância da classe Binding .

<Button Content="{x:Bind ...}" ... />

<Button Content="{Binding ...}" ... />

Se estiver a usar C++/WinRT, deve adicionar o atributo BindableAttribute a qualquer classe em tempo de execução que pretenda utilizar com a extensão de marcação {Binding}.

Objeto de vinculação declarado usando {x:Bind}

Antes de redigir a sua marcação {x:Bind}, precisa expor a classe de origem de vinculação dentro da classe que representa a sua página de marcação. Adicione uma propriedade (do tipo HostViewModel , neste caso) à sua MainWindow classe de janela.

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

Depois de adicionar a propriedade, você pode examinar mais de perto a marcação que declara o objeto de vinculação. O exemplo a seguir usa o mesmo Button.Content destino de vinculação que você viu na seção "Destino de vinculação" anteriormente. Mostra o destino de vinculação que está a ser ligado à propriedade HostViewModel.NextButtonText.

<!-- MainWindow.xaml -->
<Window x:Class="DataBindingInDepth.MainWindow" ... >
    <Button Content="{x:Bind Path=ViewModel.NextButtonText, Mode=OneWay}" ... />
</Window>

Observe o valor especificado para Path. A janela interpreta esse valor em seu próprio contexto. Nesse caso, o caminho começa fazendo referência à ViewModel propriedade que você acabou de adicionar à MainWindow página. Essa propriedade retorna uma HostViewModel instância, para que você possa pontilhar nesse objeto para acessar a HostViewModel.NextButtonText propriedade. Você especifica Mode para substituir o padrão {x:Bind} de uma vez.

A propriedade Path oferece suporte a uma variedade de opções de sintaxe para vinculação a propriedades aninhadas, propriedades anexadas e indexadores inteiros e de cadeia de caracteres. Para saber mais, veja Sintaxe de caminho de propriedade. A associação a indexadores de cadeia de caracteres oferece o efeito de vincular a propriedades dinâmicas sem ter que implementar ICustomPropertyProvider. Para outras configurações, consulte {x:Bind} markup extension.

Para ilustrar que a HostViewModel.NextButtonText propriedade é observável, adicione um Click manipulador de eventos ao botão e atualize o valor de HostViewModel.NextButtonText. Crie, execute e clique no botão para ver o valor da atualização do Content botão.

// MainWindow.xaml.cs
private void Button_Click(object sender, RoutedEventArgs e)
{
    ViewModel.NextButtonText = "Updated Next button text";
}

DataTemplate e x:DataType

Dentro de um DataTemplate (quer você o use como um modelo de item, um modelo de conteúdo ou um modelo de cabeçalho), o valor de Path não é interpretado no contexto da janela. Ao invés disso, funciona no contexto do objeto de dados que está a modelar. Quando você usa {x:Bind} em um modelo de dados, você pode validar suas associações em tempo de compilação e gerar código eficiente para elas. Para fazer isso, o DataTemplate precisa declarar o tipo de seu objeto de dados usando x:DataType. O exemplo a seguir pode ser usado como o ItemTemplate de um controle de itens vinculado a uma coleção de SampleDataGroup objetos.

<DataTemplate x:Key="SimpleItemTemplate" x:DataType="data:SampleDataGroup">
    <StackPanel Orientation="Vertical" Height="50">
      <TextBlock Text="{x:Bind Title}"/>
      <TextBlock Text="{x:Bind Description}"/>
    </StackPanel>
  </DataTemplate>

Objetos digitados fracamente em seu caminho

Suponha que você tenha um tipo chamado SampleDataGroup que implementa uma propriedade string chamada Title. Você também tem uma propriedade MainWindow.SampleDataGroupAsObject do tipo object, mas na verdade retorna uma instância de SampleDataGroup. A associação <TextBlock Text="{x:Bind SampleDataGroupAsObject.Title}"/> resulta em um erro de compilação porque a Title propriedade não é encontrada no tipo object. Para corrigir este erro, adicione um casting na sua sintaxe Path como esta: <TextBlock Text="{x:Bind ((data:SampleDataGroup)SampleDataGroupAsObject).Title}"/>. Aqui está outro exemplo onde Element é declarado como object mas é na verdade um TextBlock: <TextBlock Text="{x:Bind Element.Text}"/>. Um elenco corrige o problema: <TextBlock Text="{x:Bind ((TextBlock)Element).Text}"/>.

Se os dados forem carregados de forma assíncrona

As classes parciais para as suas janelas geram código para suporte {x:Bind} em tempo de compilação. Você pode encontrar esses arquivos em sua obj pasta, com nomes como (para C#) <view name>.g.cs. O código gerado inclui um manipulador para o evento Loading da janela. Esse "handler" chama o método Initialize numa classe gerada que representa as ligações da janela. Initialize chama Update para começar a mover dados entre a origem de ligação e o alvo. Loading é levantado imediatamente antes da primeira medida passar da janela ou do controle do usuário. Se os dados forem carregados de forma assíncrona, talvez não estejam prontos no momento Initialize em que forem chamados. Depois de carregar os dados, pode forçar as vinculações únicas a inicializarem chamando this.Bindings.Update();. Se você só precisa de ligações únicas para dados carregados de forma assíncrona, é muito mais barato inicializá-las dessa maneira do que ter ligações unidirecionais e ouvir as alterações. Se seus dados não sofrerem alterações refinadas e provavelmente serão atualizados como parte de uma ação específica, você poderá fazer suas associações uma única vez e forçar uma atualização manual a qualquer momento com uma chamada para Update.

Objeto de vinculação declarado usando {Binding}

Se utilizares C++/WinRT, adiciona o atributo BindableAttribute a qualquer classe de tempo de execução à qual pretendes vincular-te quando utilizares a extensão de marcação {Binding}. Para usar {x:Bind}, você não precisa desse atributo.

// HostViewModel.idl
// Add this attribute:
[Microsoft.UI.Xaml.Data.Bindable]
runtimeclass HostViewModel : Microsoft.UI.Xaml.Data.INotifyPropertyChanged
{
    HostViewModel();
    String NextButtonText;
}

Por padrão, {Binding} pressupõe que você está vinculando ao DataContext da janela de marcação. Portanto, defina o DataContext da sua janela para ser uma instância da sua classe de origem de vinculação (do tipo HostViewModel neste caso). O exemplo a seguir mostra a marcação que declara o objeto de ligação. Ele usa o mesmo Button.Content destino de vinculação utilizado anteriormente na seção "Destino de vinculação" e estabelece ligação à propriedade HostViewModel.NextButtonText.

<Window xmlns:viewmodel="using:DataBindingInDepth" ... >
    <Window.DataContext>
        <viewmodel:HostViewModel x:Name="viewModelInDataContext"/>
    </Window.DataContext>
    ...
    <Button Content="{Binding Path=NextButtonText}" ... />
</Window>

// MainWindow.xaml.cs
private void Button_Click(object sender, RoutedEventArgs e)
{
    viewModelInDataContext.NextButtonText = "Updated Next button text";
}

Observe o valor especificado para Path. DataContext da janela interpreta esse valor, que neste exemplo é definido como uma instância de HostViewModel. O caminho faz referência à HostViewModel.NextButtonText propriedade. Você pode omitir Mode, porque o padrão {Binding} de unidirecional funciona aqui.

O valor padrão de DataContext para um elemento da interface do usuário é o valor herdado de seu pai. Você pode substituir esse padrão definindo DataContext explicitamente, que por sua vez é herdado por filhos por padrão. Definir DataContext explicitamente um elemento é útil quando você deseja ter várias associações que usam a mesma fonte.

Um objeto de associação tem uma Source propriedade, que assume como padrão o DataContext do elemento da interface do usuário no qual a associação é declarada. Você pode substituir esse padrão definindo Source, RelativeSourceou ElementName explicitamente na vinculação (consulte {Binding} para obter detalhes).

Dentro de um DataTemplate, o DataContext é definido automaticamente para o objeto de dados que está sendo modelado. O exemplo a seguir pode ser usado como o ItemTemplate de um controlo de itens vinculado a uma coleção de qualquer tipo que tenha propriedades de strings nomeadas Title e Description.

<DataTemplate x:Key="SimpleItemTemplate">
    <StackPanel Orientation="Vertical" Height="50">
      <TextBlock Text="{Binding Title}"/>
      <TextBlock Text="{Binding Description"/>
    </StackPanel>
  </DataTemplate>

A propriedade Path oferece suporte a uma variedade de opções de sintaxe para vinculação a propriedades aninhadas, propriedades anexadas e indexadores inteiros e de cadeia de caracteres. Para saber mais, veja Sintaxe de caminho de propriedade. A associação a indexadores de cadeia de caracteres oferece o efeito de vincular a propriedades dinâmicas sem ter que implementar ICustomPropertyProvider. A propriedade ElementName é útil para a vinculação de elemento a elemento. A propriedade RelativeSource tem vários usos, um dos quais é como uma alternativa mais poderosa para a vinculação de modelo dentro de um ControlTemplate. Para outras configurações, consulte {Binding} markup extension e a classe Binding .

E se a origem e o destino não forem do mesmo tipo?

Se você quiser controlar a visibilidade de um elemento da interface do usuário com base no valor de uma propriedade booleana, ou se quiser renderizar um elemento da interface do usuário com uma cor que seja uma função do intervalo ou tendência de um valor numérico, ou se quiser exibir um valor de data e/ou hora em uma propriedade de elemento da interface do usuário que espera uma cadeia de caracteres, então você precisa converter valores de um tipo para outro. Há casos em que a solução certa é expor outra propriedade do tipo certo da sua classe de origem de vinculação e manter a lógica de conversão encapsulada e testável lá. Mas essa solução não é flexível ou escalável quando você tem grandes números ou grandes combinações de propriedades de origem e destino. Nesse caso, você tem algumas opções:

• Se estiver usando {x:Bind} , então você pode vincular diretamente a uma função para fazer essa conversão
• Ou você pode especificar um conversor de valor que é um objeto projetado para executar a conversão

Conversores de valor

Aqui está um conversor de valor, adequado para uma ligação única ou unidirecional, que converte um valor DateTime em um string valor que contém o mês. A classe implementa IValueConverter.

public class DateToStringConverter : IValueConverter
{
    // Define the Convert method to convert a DateTime value to 
    // a month string.
    public object Convert(object value, Type targetType, 
        object parameter, string language)
    {
        // value is the data from the source object.
        DateTime thisDate = (DateTime)value;
        int monthNum = thisDate.Month;
        string month;
        switch (monthNum)
        {
            case 1:
                month = "January";
                break;
            case 2:
                month = "February";
                break;
            default:
                month = "Month not found";
                break;
        }
        // Return the value to pass to the target.
        return month;
    }

    // ConvertBack is not implemented for a OneWay binding.
    public object ConvertBack(object value, Type targetType, 
        object parameter, string language)
    {
        throw new NotImplementedException();
    }
}

E aqui está como você consome esse conversor de valor em sua marcação de objeto de vinculação.

<UserControl.Resources>
  <local:DateToStringConverter x:Key="Converter1"/>
</UserControl.Resources>
...
<TextBlock Grid.Column="0" 
  Text="{x:Bind ViewModel.Month, Converter={StaticResource Converter1}}"/>
<TextBlock Grid.Column="0" 
  Text="{Binding Month, Converter={StaticResource Converter1}}"/>

O mecanismo de vinculação chama os métodos Convert e ConvertBack se o parâmetro Converter for definido para a ligação. Quando os dados são passados da origem, o mecanismo de vinculação chama Convert e passa os dados retornados para o destino. Quando os dados são passados do destino (para uma ligação bidirecional), o mecanismo de vinculação chama ConvertBack e passa os dados retornados para a origem.

O conversor também tem parâmetros opcionais: ConverterLanguage, que permite especificar o idioma a ser usado na conversão, e ConverterParameter, que permite passar um parâmetro para a lógica de conversão. Para obter um exemplo que usa um parâmetro conversor, consulte IValueConverter.

Para exibir um valor padrão a ser usado sempre que a fonte de vinculação não puder ser resolvida, defina a FallbackValue propriedade no objeto de vinculação na marcação. Isso é útil para lidar com erros de conversão e formatação. Também é útil vincular a propriedades de origem que podem não existir em todos os objetos em uma coleção acoplada de tipos heterogêneos.

Se você vincular um controle de texto a um valor que não seja uma cadeia de caracteres, o mecanismo de vinculação de dados converterá o valor em uma cadeia de caracteres. Se o valor for um tipo de referência, o mecanismo de vinculação de dados recuperará o valor da cadeia de caracteres chamando ICustomPropertyProvider.GetStringRepresentation ou IStringable.ToString , se disponível, e chamará Object.ToString. Observe, no entanto, que o mecanismo de vinculação ignorará qualquer ToString implementação que oculte a implementação de classe base. Em vez disso, as implementações de subclasse devem substituir o método de classe ToString base. Da mesma forma, em idiomas nativos, todos os objetos gerenciados parecem implementar ICustomPropertyProvider e IStringable. No entanto, todas as chamadas para GetStringRepresentation e IStringable.ToString são roteadas para Object.ToString ou uma substituição desse método, e nunca para uma nova ToString implementação que oculta a implementação de classe base.

Vinculação de função em {x:Bind}

{x:Bind} permite que a etapa final em um caminho de vinculação seja uma função. Use esse recurso para executar conversões ou criar associações que dependem de mais de uma propriedade. Para obter mais informações, consulte Funções em x:Bind.

Vinculação de elemento a elemento

Você pode vincular a propriedade de um elemento XAML à propriedade de outro elemento XAML. Veja um exemplo de como essa ligação aparece na marcação de código.

<TextBox x:Name="myTextBox" />
<TextBlock Text="{x:Bind myTextBox.Text, Mode=OneWay}" />

Dicionários de recursos com {x:Bind}

A extensão de marcação {x:Bind} depende da geração de código, por isso precisa de um arquivo code-behind contendo um construtor que chama InitializeComponent (para inicializar o código gerado). Para reutilizar o dicionário de recursos, instancie seu tipo (para que InitializeComponent seja chamado) em vez de referenciar seu nome de arquivo. Aqui está um exemplo do que fazer se você tiver um dicionário de recursos existente e quiser usá-lo {x:Bind} .

<!-- TemplatesResourceDictionary.xaml -->
<ResourceDictionary
    x:Class="ExampleNamespace.TemplatesResourceDictionary"
    .....
    xmlns:examplenamespace="using:ExampleNamespace">
    
    <DataTemplate x:Key="EmployeeTemplate" x:DataType="examplenamespace:IEmployee">
        <Grid>
            <TextBlock Text="{x:Bind Name}"/>
        </Grid>
    </DataTemplate>
</ResourceDictionary>

// TemplatesResourceDictionary.xaml.cs
using Microsoft.UI.Xaml.Data;
 
namespace ExampleNamespace
{
    public partial class TemplatesResourceDictionary
    {
        public TemplatesResourceDictionary()
        {
            InitializeComponent();
        }
    }
}

<!-- MainWindow.xaml -->
<Window x:Class="ExampleNamespace.MainWindow"
    ....
    xmlns:examplenamespace="using:ExampleNamespace">

    <Window.Resources>
        <ResourceDictionary>
            .... 
            <ResourceDictionary.MergedDictionaries>
                <examplenamespace:TemplatesResourceDictionary/>
            </ResourceDictionary.MergedDictionaries>
        </ResourceDictionary>
    </Window.Resources>
</Window>

Misturando {x:Bind} e {Binding} em um estilo reutilizável

O exemplo anterior mostrou como usar {x:Bind} em DataTemplates. Você também pode criar estilos reutilizáveis que combinam as extensões de marcação {x:Bind} e {Binding}. Essa combinação é útil quando você deseja vincular algumas propriedades a valores conhecidos em tempo de compilação usando {x:Bind} e outras propriedades a valores DataContext de tempo de execução usando {Binding}.

O exemplo a seguir mostra como criar um estilo Button reutilizável que usa ambas as abordagens de vinculação:

TemplatesResourceDictionary.xaml

<!-- TemplatesResourceDictionary.xaml -->
<ResourceDictionary
    x:Class="ExampleNamespace.TemplatesResourceDictionary"
    .....
    xmlns:examplenamespace="using:ExampleNamespace">
    
    <!-- DataTemplate using x:Bind -->
    <DataTemplate x:Key="EmployeeTemplate" x:DataType="examplenamespace:IEmployee">
        <Grid>
            <TextBlock Text="{x:Bind Name}"/>
        </Grid>
    </DataTemplate>
    
    <!-- Style that mixes x:Bind and Binding -->
    <Style x:Key="CustomButtonStyle" TargetType="Button">
        <Setter Property="Background" Value="{Binding ButtonBackgroundBrush}"/>
        <Setter Property="Foreground" Value="{Binding ButtonForegroundBrush}"/>
        <Setter Property="FontSize" Value="16"/>
        <Setter Property="Margin" Value="4"/>
        <Setter Property="Template">
            <Setter.Value>
                <ControlTemplate TargetType="Button">
                    <Border x:Name="RootBorder"
                            Background="{TemplateBinding Background}"
                            BorderBrush="{TemplateBinding BorderBrush}"
                            BorderThickness="{TemplateBinding BorderThickness}"
                            CornerRadius="4">
                        <StackPanel Orientation="Horizontal" 
                                    HorizontalAlignment="Center"
                                    VerticalAlignment="Center">
                            <!-- x:Bind to a static property or page-level property -->
                            <Ellipse Width="8" Height="8" 
                                     Fill="{x:Bind DefaultIndicatorBrush}" 
                                     Margin="0,0,8,0"/>
                            <!-- Binding to DataContext -->
                            <ContentPresenter x:Name="ContentPresenter"
                                              Content="{TemplateBinding Content}"
                                              Foreground="{TemplateBinding Foreground}"
                                              FontSize="{TemplateBinding FontSize}"/>
                        </StackPanel>
                        <VisualStateManager.VisualStateGroups>
                            <VisualStateGroup x:Name="CommonStates">
                                <VisualState x:Name="Normal"/>
                                <VisualState x:Name="PointerOver">
                                    <VisualState.Setters>
                                        <!-- Binding to DataContext for hover color -->
                                        <Setter Target="RootBorder.Background" 
                                                Value="{Binding ButtonHoverBrush}"/>
                                    </VisualState.Setters>
                                </VisualState>
                                <VisualState x:Name="Pressed">
                                    <VisualState.Setters>
                                        <!-- x:Bind to a compile-time known resource -->
                                        <Setter Target="RootBorder.Background" 
                                                Value="{x:Bind DefaultPressedBrush}"/>
                                    </VisualState.Setters>
                                </VisualState>
                            </VisualStateGroup>
                        </VisualStateManager.VisualStateGroups>
                    </Border>
                </ControlTemplate>
            </Setter.Value>
        </Setter>
    </Style>
</ResourceDictionary>

TemplatesResourceDictionary.xaml.cs

// TemplatesResourceDictionary.xaml.cs
using Microsoft.UI;
using Microsoft.UI.Xaml;
using Microsoft.UI.Xaml.Data;
using Microsoft.UI.Xaml.Media;
 
namespace ExampleNamespace
{
    public partial class TemplatesResourceDictionary
    {
        public TemplatesResourceDictionary()
        {
            InitializeComponent();
        }
        
        // Properties for x:Bind - these are compile-time bound
        public SolidColorBrush DefaultIndicatorBrush { get; } = 
            new SolidColorBrush(Colors.Green);
            
        public SolidColorBrush DefaultPressedBrush { get; } = 
            new SolidColorBrush(Colors.DarkGray);
    }
}

Uso em MainWindow.xaml com um ViewModel que fornece valores de tempo de execução:

<!-- MainWindow.xaml -->
<Window x:Class="ExampleNamespace.MainWindow"
    ....
    xmlns:examplenamespace="using:ExampleNamespace">

    <Window.Resources>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>
                <examplenamespace:TemplatesResourceDictionary/>
            </ResourceDictionary.MergedDictionaries>
        </ResourceDictionary>
    </Window.Resources>

    <Grid>
        <Grid.DataContext>
            <examplenamespace:ButtonThemeViewModel/>
        </Grid.DataContext>
        
        <StackPanel Margin="20">
            <!-- These buttons use the mixed binding style -->
            <Button Content="Save" Style="{StaticResource CustomButtonStyle}"/>
            <Button Content="Cancel" Style="{StaticResource CustomButtonStyle}"/>
        </StackPanel>
    </Grid>
</Window>

ButtonThemeViewModel.cs (o DataContext que fornece valores de vinculação de tempo de execução):

using System.ComponentModel;
using Microsoft.UI;
using Microsoft.UI.Xaml.Media;

namespace ExampleNamespace
{
    public class ButtonThemeViewModel : INotifyPropertyChanged
    {
        private SolidColorBrush _buttonBackgroundBrush = new SolidColorBrush(Colors.LightBlue);
        private SolidColorBrush _buttonForegroundBrush = new SolidColorBrush(Colors.DarkBlue);
        private SolidColorBrush _buttonHoverBrush = new SolidColorBrush(Colors.LightCyan);

        public SolidColorBrush ButtonBackgroundBrush
        {
            get => _buttonBackgroundBrush;
            set
            {
                _buttonBackgroundBrush = value;
                PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(nameof(ButtonBackgroundBrush)));
            }
        }

        public SolidColorBrush ButtonForegroundBrush
        {
            get => _buttonForegroundBrush;
            set
            {
                _buttonForegroundBrush = value;
                PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(nameof(ButtonForegroundBrush)));
            }
        }

        public SolidColorBrush ButtonHoverBrush
        {
            get => _buttonHoverBrush;
            set
            {
                _buttonHoverBrush = value;
                PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(nameof(ButtonHoverBrush)));
            }
        }

        public event PropertyChangedEventHandler PropertyChanged;
    }
}

Neste exemplo:

• {Binding} é usado para propriedades que dependem do DataContext (ButtonBackgroundBrush, ButtonForegroundBrush, ButtonHoverBrush)
• {x:Bind} é usado para propriedades que são conhecidas em tempo de compilação e pertencem ao próprio ResourceDictionary (DefaultIndicatorBrush, DefaultPressedBrush)
• O estilo é reutilizável e você pode aplicá-lo a qualquer botão
• A temática de tempo de execução é possível através do DataContext enquanto ainda se beneficia do desempenho de {x:Bind} elementos estáticos

Vinculação de eventos e ICommand

{x:Bind} suporta um recurso chamado vinculação de eventos. Com esse recurso, você pode especificar o manipulador para um evento usando uma ligação. Esse recurso é uma opção adicional para manipular eventos, além de manipular eventos com um método no arquivo code-behind. Suponha que você tenha um ListViewDoubleTapped manipulador de eventos em sua MainWindow classe.

public sealed partial class MainWindow : Window
{
    ...
    public void ListViewDoubleTapped()
    {
        // Handle double-tapped logic
    }
}

Você pode vincular um evento DoubleTapped de ListView a um método na MainWindow como este.

<ListView DoubleTapped="{x:Bind ListViewDoubleTapped}" />

Você não pode usar métodos sobrecarregados para manipular um evento com essa técnica. Além disso, se o método que manipula o evento tiver parâmetros, todos eles devem ser atribuíveis a partir dos tipos de todos os parâmetros do evento, respectivamente. Neste caso, ListViewDoubleTapped não está sobrecarregado e não tem parâmetros (mas ainda assim seria válido mesmo se levasse dois object parâmetros).

A técnica de vinculação de eventos é semelhante à implementação e consumo de comandos. Um comando é uma propriedade que retorna um objeto que implementa a interface ICommand . { x:Bind} e {Binding} funcionam com comandos. Para que você não precise implementar o padrão de comando várias vezes, você pode usar a DelegateCommand classe auxiliar que você encontra no exemplo UWP do QuizGame (na pasta "Comum").

Vinculação a uma coleção de pastas ou arquivos

Você pode usar as APIs no namespace Windows.Storage para recuperar dados de pastas e arquivos em seus aplicativos SDK de aplicativos Windows empacotados. No entanto, os vários GetFilesAsyncmétodos , GetFoldersAsynce GetItemsAsync não retornam valores que são adequados para ligação a controles de lista. Em vez disso, você deve vincular aos valores de retorno dos métodos GetVirtualizedFilesVector, GetVirtualizedFoldersVector e GetVirtualizedItemsVector da classe FileInformationFactory . O exemplo de código a seguir do exemplo de UWP StorageDataSource e GetVirtualizedFilesVector mostra o padrão de uso típico. Lembre-se de declarar o recurso picturesLibrary no manifesto do pacote do aplicativo e confirme se há imagens na pasta Biblioteca de imagens.

protected override void OnNavigatedTo(NavigationEventArgs e)
{
    var library = Windows.Storage.KnownFolders.PicturesLibrary;
    var queryOptions = new Windows.Storage.Search.QueryOptions();
    queryOptions.FolderDepth = Windows.Storage.Search.FolderDepth.Deep;
    queryOptions.IndexerOption = Windows.Storage.Search.IndexerOption.UseIndexerWhenAvailable;

    var fileQuery = library.CreateFileQueryWithOptions(queryOptions);

    var fif = new Windows.Storage.BulkAccess.FileInformationFactory(
        fileQuery,
        Windows.Storage.FileProperties.ThumbnailMode.PicturesView,
        190,
        Windows.Storage.FileProperties.ThumbnailOptions.UseCurrentScale,
        false
        );

    var dataSource = fif.GetVirtualizedFilesVector();
    this.PicturesListView.ItemsSource = dataSource;
}

Normalmente, utiliza-se esta abordagem para criar uma visualização somente de leitura de informações sobre arquivos e pastas. Você pode criar ligações bidirecionais para as propriedades de arquivo e pasta, por exemplo, para permitir que os usuários classifiquem uma música em uma exibição de música. No entanto, as alterações não são mantidas até que você chame o método apropriado SavePropertiesAsync (por exemplo, MusicProperties.SavePropertiesAsync). Você deve cometer alterações quando o item perder o foco, porque essa ação dispara uma redefinição de seleção.

Observe que a vinculação bidirecional usando essa técnica funciona apenas com locais indexados, como Música. Você pode determinar se um local está indexado chamando o método FolderInformation.GetIndexedStateAsync .

Observe também que um vetor virtualizado pode retornar null para alguns itens antes de preencher seu valor. Por exemplo, você deve verificar antes null de usar o valor SelectedItem de um controle de lista vinculado a um vetor virtualizado ou usar SelectedIndex em vez disso.

Vinculação a dados agrupados por uma chave

Se você pegar uma coleção simples de itens (livros, por exemplo, representados por uma BookSku classe) e agrupar os itens usando uma propriedade comum como chave (a BookSku.AuthorName propriedade, por exemplo), o resultado será chamado de dados agrupados. Quando você agrupa dados, eles não são mais uma coleção simples. Dados agrupados são uma coleção de objetos de grupo, onde cada objeto de grupo tem:

• uma chave, e
• Uma coleção de itens cuja propriedade corresponde a essa chave.

Para tomar o exemplo de livros novamente, o resultado do agrupamento dos livros por nome de autor resulta em uma coleção de grupos de nomes de autores onde cada grupo tem:

• uma chave, que é um nome de autor, e
• Uma coleção dos BookSku objetos cuja AuthorName propriedade corresponde à chave do grupo.

Em geral, para exibir uma coleção, você vincula o ItemsSource de um controle de itens (como ListView ou GridView) diretamente a uma propriedade que retorna uma coleção. Se essa é uma coleção simples de itens, então você não precisa fazer nada de especial. Mas se for uma coleção de objetos de grupo (como é quando se vincula a dados agrupados), então você precisa dos serviços de um objeto intermediário chamado CollectionViewSource que fica entre o controle de itens e a fonte de vinculação. Você vincula o CollectionViewSource à propriedade que retorna dados agrupados e vincula o controle items ao CollectionViewSource. Um valor agregado extra de um CollectionViewSource é que ele mantém o controle do item atual, para que você possa manter mais de um controle de itens sincronizado, vinculando-os todos ao mesmo CollectionViewSource. Você também pode acessar o item atual programaticamente por meio da propriedade ICollectionView.CurrentItem do objeto retornado pela propriedade CollectionViewSource.View .

Para ativar o recurso de agrupamento de um CollectionViewSource, defina IsSourceGrouped como true. Se você também precisa definir a propriedade ItemsPath depende exatamente de como você cria seus objetos de grupo. Há duas maneiras de criar um objeto de grupo: o padrão "is-a-group" e o padrão "has-a-group". No padrão "is-a-group", o objeto group deriva de um tipo de coleção (por exemplo, ), portanto, List<T>o objeto group na verdade é o próprio grupo de itens. Com este padrão, você não precisa definir ItemsPath. No padrão "has-a-group", o objeto group tem uma ou mais propriedades de um tipo de coleção (como ), portanto List<T>, o grupo "tem um" grupo de itens na forma de uma propriedade (ou vários grupos de itens na forma de várias propriedades). Com esse padrão, você precisa definir ItemsPath o nome da propriedade que contém o grupo de itens.

O exemplo a seguir ilustra o padrão "has-a-group" (tem-um-grupo). A classe window tem uma propriedade chamada DataContext, que retorna uma instância de nosso modelo de exibição. O CollectionViewSource se liga à Authors propriedade do modelo de exibição (Authors é a coleção de objetos de grupo) e também especifica que é a Author.BookSkus propriedade que contém os itens agrupados. Finalmente, o GridView está vinculado ao CollectionViewSource, e tem seu estilo de grupo definido para que ele possa renderizar os itens em grupos.

<Window.Resources>
    <CollectionViewSource
    x:Name="AuthorHasACollectionOfBookSku"
    Source="{x:Bind ViewModel.Authors}"
    IsSourceGrouped="true"
    ItemsPath="BookSkus"/>
</Window.Resources>
...
<GridView
ItemsSource="{x:Bind AuthorHasACollectionOfBookSku}" ...>
    <GridView.GroupStyle>
        <GroupStyle
            HeaderTemplate="{StaticResource AuthorGroupHeaderTemplateWide}" ... />
    </GridView.GroupStyle>
</GridView>

Você pode implementar o padrão "is-a-group" de duas maneiras. Uma maneira é criar sua própria aula em grupo. Derive a classe de List<T> (onde T é o tipo dos itens). Por exemplo, public class Author : List<BookSku>. A segunda maneira é usar uma expressão LINQ para criar dinamicamente objetos de grupo (e uma classe de grupo) a partir de valores de propriedade semelhantes dos itens BookSku . Essa abordagem, mantendo apenas uma lista simples de itens e agrupando-os em tempo real, é típica de um aplicativo que acessa dados de um serviço de nuvem. Você tem a flexibilidade de agrupar livros por autor ou por gênero (por exemplo) sem precisar de aulas de grupo especiais, como Autor e Gênero.

O exemplo a seguir ilustra o padrão "is-a-group" usando LINQ. Desta vez, agrupamos os livros por gênero, exibidos com o nome do gênero nos cabeçalhos do grupo. Esse agrupamento é indicado pelo caminho da propriedade "Key" em referência ao valor da chave do grupo.

using System.Linq;
...
private IOrderedEnumerable<IGrouping<string, BookSku>> genres;

public IOrderedEnumerable<IGrouping<string, BookSku>> Genres
{
    get
    {
        if (genres == null)
        {
            genres = from book in bookSkus
                     group book by book.genre into grp
                     orderby grp.Key
                     select grp;
        }
        return genres;
    }
}

Lembre-se de que, ao usar {x:Bind} com modelos de dados, você precisa indicar o tipo ao qual está sendo vinculado definindo um x:DataType valor. Se o tipo for genérico, você não poderá expressá-lo na marcação, então você precisará usar {Binding} em vez disso no modelo de cabeçalho de estilo de grupo.

    <Grid.Resources>
        <CollectionViewSource x:Name="GenreIsACollectionOfBookSku"
        Source="{x:Bind Genres}"
        IsSourceGrouped="true"/>
    </Grid.Resources>
    <GridView ItemsSource="{x:Bind GenreIsACollectionOfBookSku}">
        <GridView.ItemTemplate x:DataType="local:BookTemplate">
            <DataTemplate>
                <TextBlock Text="{x:Bind Title}"/>
            </DataTemplate>
        </GridView.ItemTemplate>
        <GridView.GroupStyle>
            <GroupStyle>
                <GroupStyle.HeaderTemplate>
                    <DataTemplate>
                        <TextBlock Text="{Binding Key}"/>
                    </DataTemplate>
                </GroupStyle.HeaderTemplate>
            </GroupStyle>
        </GridView.GroupStyle>
    </GridView>

Um controle SemanticZoom é uma ótima maneira de seus usuários visualizarem e navegarem por dados agrupados. O aplicativo de exemplo UWP Bookstore2 ilustra como usar o SemanticZoom. Nessa aplicação, pode ver uma lista de livros agrupados por autor (a vista ampliada) ou pode reduzir para ver uma lista de atalhos de autores (a vista reduzida). A lista de atalhos permite uma navegação muito mais rápida do que percorrer a lista de livros. As visualizações ampliadas e reduzidas são, na verdade ListView , ou GridView controles vinculados ao mesmo CollectionViewSource.

Ao vincular a dados hierárquicos, como subcategorias dentro de categorias, você pode optar por exibir os níveis hierárquicos em sua interface do usuário com uma série de controles de itens. Uma seleção em um controle de itens determina o conteúdo dos controles de itens subsequentes. Você pode manter as listas sincronizadas vinculando cada lista a seu próprio CollectionViewSource e vinculando as CollectionViewSource instâncias em uma cadeia. Essa configuração é chamada de exibição mestre/detalhes (ou lista/detalhes). Para saber mais, veja Como vincular a dados hierárquicos e criar uma exibição mestre/detalhes.

Diagnosticar e depurar problemas de vinculação de dados

Sua marcação de vinculação contém os nomes das propriedades (e, para C#, às vezes campos e métodos). Portanto, ao renomear uma propriedade, você também precisa alterar qualquer vinculação que faça referência a ela. Se você esquecer de fazer isso, criará um bug de vinculação de dados e seu aplicativo não compilará ou não será executado corretamente.

Os objetos de ligação que {x:Bind} e {Binding} criam são em grande parte equivalentes funcionalmente. Mas {x:Bind} tem informações de tipo para a fonte de ligação, e gera código-fonte em tempo de compilação. Com {x:Bind}, você obtém o mesmo tipo de deteção de problemas que obtém com o resto do código. Essa deteção inclui validação em tempo de compilação das suas expressões de vinculação e definindo pontos de interrupção para depuração no código-fonte gerado como classe parcial da sua página. Você pode encontrar essas classes nos arquivos em sua obj pasta, com nomes como (para C#) <view name>.g.cs). Se você tiver um problema com uma associação, ative Interromper exceções não tratadas no depurador do Microsoft Visual Studio. O depurador interrompe a execução nesse ponto, e você pode depurar o que deu errado. O código gerado por {x:Bind} segue o mesmo padrão para cada parte do gráfico de nós de origem de ligação, e você pode usar as informações na janela Pilha de chamadas para ajudar a determinar a sequência de chamadas que levaram ao problema.

{Binding} não tem informações de tipo para a fonte de ligação. Mas quando você executa seu aplicativo com o depurador anexado, todos os erros de associação aparecem nas janelas Falhasde vinculação de saída e XAML no Visual Studio. Para obter mais informações sobre erros de vinculação de depuração no Visual Studio, consulte Diagnóstico de vinculação de dados XAML.

Criando ligações no código

Você também pode conectar elementos da interface do usuário a dados usando código de procedimento em vez de XAML. Para fazer isso, crie um novo objeto Binding , defina as propriedades apropriadas e chame FrameworkElement.SetBinding ou BindingOperations.SetBinding. Criar associações programaticamente é útil quando você deseja escolher os valores de propriedade de vinculação em tempo de execução ou compartilhar uma única associação entre vários controles. No entanto, não é possível alterar os valores da propriedade de vinculação depois de chamar SetBinding.

O exemplo a seguir mostra como implementar uma associação no código.

<TextBox x:Name="MyTextBox" Text="Text"/>

// Create an instance of the MyColors class 
// that implements INotifyPropertyChanged.
var textcolor = new MyColors();

// Brush1 is set to be a SolidColorBrush with the value Red.
textcolor.Brush1 = new SolidColorBrush(Colors.Red);

// Set the DataContext of the TextBox MyTextBox.
MyTextBox.DataContext = textcolor;

// Create the binding and associate it with the text box.
var binding = new Binding { Path = new PropertyPath("Brush1") };
MyTextBox.SetBinding(TextBox.ForegroundProperty, binding);

Comparação de recursos {x:Bind} e {Binding}

Consulte também

• Visão geral da vinculação de dados
• Vinculação de dados e MVVM