O que são declarações vinculativas?

Normalmente, os desenvolvedores declaram as associações diretamente na marcação XAML dos elementos da interface do usuário aos quais desejam associar dados. No entanto, você também pode declarar associações no código. Este artigo descreve como declarar associações no XAML e no código.

Pré-requisitos

Antes de ler este artigo, é importante que você esteja familiarizado com o conceito e o uso de extensões de marcação. Para obter mais informações sobre extensões de marcação, consulte Extensões de Marcação e XAML do WPF.

Este artigo não aborda conceitos de associação de dados. Para obter uma discussão sobre conceitos de associação de dados, consulte a visão geral da associação de dados.

Declarar uma ligação no XAML

Binding é uma extensão da marcação. Quando você usa a extensão de associação para declarar uma associação, a declaração consiste em uma série de cláusulas seguindo a Binding palavra-chave e separadas por vírgulas (,). As cláusulas na declaração vinculativa podem estar em qualquer ordem e há muitas combinações possíveis. As cláusulas são pares Nome=Valor, em que Nome é o nome da propriedade Binding e Valor é o valor que você está definindo para a propriedade.

Ao criar cadeias de caracteres de declaração de vinculação na marcação, elas devem ser anexadas à propriedade de dependência específica de um objeto de destino. O exemplo a seguir mostra como associar a propriedade TextBox.Text usando a extensão de associação, especificando as propriedades Source e Path.

<TextBlock Text="{Binding Source={StaticResource myDataSource}, Path=Name}"/>

O exemplo anterior usa um tipo de objeto de dados simples de Person. O snippet a seguir é o código para esse objeto:

class Person
{
    public string Name { get; set; }
    public DateTime Birthdate { get; set; }
}

Public Class Person

    Public Property Name As String
    Public Property Birthdate As DateTime
    
End Class

Você pode especificar a maioria das propriedades da Binding classe dessa maneira. Para obter mais informações sobre a extensão de associação e para obter uma lista de Binding propriedades que não podem ser definidas usando a extensão de associação, consulte a visão geral da Extensão de Marcação de Associação (.NET Framework ).

Para obter um exemplo sobre como criar uma associação em XAML, consulte Como criar uma associação de dados.

Sintaxe do elemento object

A sintaxe do elemento object é uma alternativa para criar a declaração de associação. Na maioria dos casos, não há nenhuma vantagem específica em usar a extensão de marcação ou a sintaxe do elemento de objeto. No entanto, quando a extensão de marcação não dá suporte ao seu cenário, como quando o valor da propriedade é de um tipo que não é de cadeia de caracteres para o qual não existe nenhuma conversão de tipo, você precisa usar a sintaxe do elemento de objeto.

A seção anterior demonstrou como associar a uma extensão XAML. O exemplo a seguir demonstra fazer a mesma associação, mas usa a sintaxe do elemento de objeto:

<TextBlock>
    <TextBlock.Text>
        <Binding Source="{StaticResource myDataSource}" Path="Name"/>
    </TextBlock.Text>
</TextBlock>

Para obter mais informações sobre os diferentes termos, consulte Sintaxe XAML em detalhes (.NET Framework).

MultiBinding e vinculação por prioridade

MultiBinding e PriorityBinding não apoiam a sintaxe da extensão XAML. É por isso que você deve usar a sintaxe do elemento de objeto se estiver declarando um MultiBinding ou um PriorityBinding em XAML.

Criar uma associação no código

Outra maneira de especificar uma associação é definir propriedades diretamente em um Binding objeto no código e, em seguida, atribuir a associação a uma propriedade. O exemplo a seguir mostra como criar um Binding objeto no código.

private void Window_Loaded(object sender, RoutedEventArgs e)
{
    // Make a new data source object
    var personDetails = new Person()
    {
        Name = "John",
        Birthdate = DateTime.Parse("2001-02-03")
    };

    // New binding object using the path of 'Name' for whatever source object is used
    var nameBindingObject = new Binding("Name");

    // Configure the binding
    nameBindingObject.Mode = BindingMode.OneWay;
    nameBindingObject.Source = personDetails;
    nameBindingObject.Converter = NameConverter.Instance;
    nameBindingObject.ConverterCulture = new CultureInfo("en-US");

    // Set the binding to a target object. The TextBlock.Name property on the NameBlock UI element
    BindingOperations.SetBinding(NameBlock, TextBlock.TextProperty, nameBindingObject);
}

Private Sub Window_Loaded(sender As Object, e As RoutedEventArgs)

    ' Make a new data source object
    Dim personDetails As New Person() With {
        .Name = "John",
        .Birthdate = Date.Parse("2001-02-03")
    }

    ' New binding object using the path of 'Name' for whatever source object is used
    Dim nameBindingObject As New Binding("Name")

    ' Configure the binding
    nameBindingObject.Mode = BindingMode.OneWay
    nameBindingObject.Source = personDetails
    nameBindingObject.Converter = NameConverter.Instance
    nameBindingObject.ConverterCulture = New CultureInfo("en-US")

    ' Set the binding to a target object. The TextBlock.Name property on the NameBlock UI element
    BindingOperations.SetBinding(NameBlock, TextBlock.TextProperty, nameBindingObject)

End Sub

O código anterior define o seguinte na associação:

• Caminho de uma propriedade no objeto da fonte de dados.
• O modo da associação.
• A fonte de dados, nesse caso, uma instância de objeto simples que representa uma pessoa.
• Um conversor opcional que processa o valor proveniente do objeto de fonte de dados antes de ser atribuído à propriedade de destino.

Quando o objeto que você está associando é um FrameworkElement ou um FrameworkContentElement, você pode chamar o SetBinding método em seu objeto diretamente em vez de usar BindingOperations.SetBinding. Para obter um exemplo, consulte Como criar uma associação no código.

O exemplo anterior usa um tipo de objeto de dados simples de Person. Este é o código para esse objeto:

class Person
{
    public string Name { get; set; }
    public DateTime Birthdate { get; set; }
}

Public Class Person

    Public Property Name As String
    Public Property Birthdate As DateTime
    
End Class

Sintaxe de caminho de vinculação

Use a Path propriedade para especificar o valor de origem ao qual você deseja associar:

• No caso mais simples, o valor da Path propriedade é o nome da propriedade do objeto de origem a ser usado para a associação, como Path=PropertyName.

• As subpropriedades de uma propriedade podem ser especificadas por uma sintaxe semelhante à de C#. Por exemplo, a cláusula Path=ShoppingCart.Order define a associação à subpropriedade Order do objeto ou da propriedade ShoppingCart.

• Para associar uma propriedade anexada, coloque parênteses ao redor da propriedade anexada. Por exemplo, para associar à propriedade anexada DockPanel.Dock, a sintaxe é Path=(DockPanel.Dock).

• Indexadores de uma propriedade podem ser especificados dentro de colchetes após o nome da propriedade em que o indexador é aplicado. Por exemplo, a cláusula Path=ShoppingCart[0] define a associação ao índice que corresponde à forma como a indexação interna da sua propriedade manipula a cadeia de caracteres literal "0". Também há suporte para indexadores aninhados.

• Indexadores e subpropriedades podem ser misturados em uma Path cláusula; por exemplo, Path=ShoppingCart.ShippingInfo[MailingAddress,Street].

• Dentro dos indexadores. Você pode ter vários parâmetros de indexador separados por vírgulas (,). O tipo de cada parâmetro pode ser especificado com parênteses. Por exemplo, você pode ter Path="[(sys:Int32)42,(sys:Int32)24]", onde sys é mapeado para o System namespace.

• Quando a origem é uma exibição de coleção, o item atual pode ser especificado com uma barra (/). Por exemplo, a cláusula Path=/ define a associação ao item atual na exibição. Quando a origem é uma coleção, essa sintaxe especifica o item atual da exibição de coleção padrão.

• Nomes de propriedades e barras podem ser combinados para percorrer propriedades que são coleções. Por exemplo, Path=/Offices/ManagerName especifica o item atual da coleção de origem, que contém uma Offices propriedade que também é uma coleção. Seu item atual é um objeto que contém a propriedade ManagerName.

• Opcionalmente, um caminho de ponto (.) pode ser usado para associar à origem atual. Por exemplo, Text="{Binding}" é equivalente a Text="{Binding Path=.}".

Mecanismo de escape

• Dentro dos indexadores ([ ]), o caractere de cursor (^) escapa do próximo caractere.

• Se você definir Path em XAML, também precisará escapar (usando entidades XML) certos caracteres que são especiais para a definição da língua XML.

  • Use & para escapar do caractere "&".

  • Use > para escapar da marca final ">".

• Além disso, se você descrever toda a associação em um atributo usando a sintaxe de extensão de marcação, será necessário escapar (usando barra invertida) caracteres \que são especiais para o analisador de extensão de marcação do WPF:

  • Barra invertida (\) é o próprio caractere de escape.

  • O sinal de igual (=) separa o nome da propriedade do valor da propriedade.

  • A vírgula (,) separa as propriedades.

  • A chave de fechamento direita (}) é o fim de uma extensão de marcação.

Direção da vinculação

Use a Binding.Mode propriedade para especificar a direção da associação. Os seguintes modos são as opções disponíveis para atualizações de associação:

Para obter mais informações, consulte a BindingMode enumeração.

O exemplo a seguir mostra como definir a Mode propriedade:

<TextBlock Name="IncomeText" Text="{Binding Path=TotalIncome, Mode=OneTime}" />

Para detectar alterações de origem (aplicáveis às associações OneWay e TwoWay), a origem deve implementar um mecanismo de notificação de alteração de propriedade adequado, como INotifyPropertyChanged. Para obter mais informações, consulte Fornecendo notificações de alteração.

Para TwoWay ou OneWayToSource associações, você pode controlar o tempo das atualizações de origem definindo a UpdateSourceTrigger propriedade. Para obter mais informações, consulte UpdateSourceTrigger.

Comportamentos padrão

O comportamento padrão é o seguinte se não for especificado na declaração:

• Um conversor padrão é criado que tenta fazer uma conversão de tipo entre o valor de origem de associação e o valor de destino de associação. Se uma conversão não puder ser feita, o conversor padrão retornará null.

• Se você não definir ConverterCulture, o mecanismo de associação usará a Language propriedade do objeto de destino de associação. No XAML, esse padrão é en-US ou herda o valor do elemento raiz (ou qualquer elemento) da página, se um tiver sido definido explicitamente.

• Desde que a associação já tenha um contexto de dados (por exemplo, o contexto de dados herdado proveniente de um elemento pai) e qualquer item ou coleção que esteja sendo retornado por esse contexto é apropriado para associação sem a necessidade de modificação de caminho adicional, uma declaração de associação não pode ter nenhuma cláusula: {Binding}. Geralmente, essa é a maneira como uma associação é especificada para o estilo de dados, em que a associação atua em uma coleção. Para obter mais informações, consulte Como usar objetos inteiros como uma origem de associação.

• O padrão Mode varia entre unidirecional e bidirecional, dependendo da propriedade de dependência que está sendo vinculada. Você sempre pode declarar o modo de associação explicitamente para garantir que sua associação tenha o comportamento desejado. Em geral, as propriedades de controle editáveis pelo usuário, como TextBox.Text e RangeBase.Value, têm como padrão associações bidirecionais, mas a maioria das outras propriedades tem como padrão associações unidirecionais.

• O valor padrão UpdateSourceTrigger varia entre PropertyChanged e LostFocus dependendo da propriedade de dependência associada também. O valor padrão para a maioria das propriedades de dependência é PropertyChanged, enquanto a TextBox.Text propriedade tem um valor padrão de LostFocus.

Consulte também

• visão geral da associação de dados
• Visão geral das fontes de associação
• Como criar uma associação de dados
• Sintaxe XAML do PropertyPath (.NET Framework)