Partilhar via

Visão geral das declarações vinculativas

  • Artigo

Este tópico discute as diferentes maneiras de declarar uma vinculação.

Pré-requisitos

Antes de ler este tópico, é 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 Markup Extensions e WPF XAML.

Este tópico não aborda conceitos de vinculação de dados. Para obter uma discussão sobre conceitos de vinculação de dados, consulte Visão geral da vinculação de dados.

Declarando uma associação em XAML

Esta seção discute como declarar uma associação em XAML.

Utilização da extensão de marcação

Binding é uma extensão de marcação. Quando você usa a extensão binding para declarar uma vinculação, a declaração consiste em uma série de cláusulas seguindo a palavra-chave Binding e separadas por vírgulas (,). As cláusulas da 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 declaração de ligação na marcação de dados, elas devem ser anexadas à propriedade dependente específica de um objeto alvo. O exemplo a seguir mostra como vincular a propriedade TextBox.Text usando a extensão de ligação, especificando as propriedades Source e Path.

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

Você pode especificar a maioria das propriedades da classe Binding dessa maneira. Para mais informações sobre a extensão de vinculação, bem como para obter uma lista de propriedades de Binding que não podem ser definidas usando a extensão de vinculação, consulte a visão geral da extensão de marcação de vinculação ,.

Sintaxe do elemento objeto

A sintaxe do elemento objeto é uma alternativa à criação da declaração de vinculação. Na maioria dos casos, não há nenhuma vantagem particular em usar a extensão de marcação ou a sintaxe do elemento objeto. No entanto, nos casos em que a extensão de marcação não oferece suporte ao cenário, como quando o valor da propriedade é de um tipo que não é de cadeia de caracteres para o qual não existe conversão de tipo, você precisa usar a sintaxe do elemento objeto.

A seguir está um exemplo da sintaxe do elemento objeto e do uso da extensão de marcação.

<TextBlock Name="myconvertedtext"
  Foreground="{Binding Path=TheDate,
                       Converter={StaticResource MyConverterReference}}">
  <TextBlock.Text>
    <Binding Path="TheDate"
             Converter="{StaticResource MyConverterReference}"/>
  </TextBlock.Text>
</TextBlock>

O exemplo vincula a propriedade Foreground declarando uma associação usando a sintaxe de extensão. A declaração de vinculação para a propriedade Text usa a sintaxe do elemento object.

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

MultiBinding e PriorityBinding

MultiBinding e PriorityBinding não suportam a sintaxe da extensão XAML. Portanto, deve usar a sintaxe do elemento objeto se estiver a declarar um MultiBinding ou um PriorityBinding em XAML.

Criando uma vinculação no código

Outra maneira de especificar uma associação é definir propriedades diretamente em um objeto Binding no código. O exemplo a seguir mostra como criar um objeto Binding e especificar as propriedades no código. Neste exemplo, TheConverter é um objeto que implementa a interface IValueConverter.

private void OnPageLoaded(object sender, EventArgs e)
{
    // Make a new source, to grab a new timestamp
    MyData myChangedData = new MyData();

    // Create a new binding
    // TheDate is a property of type DateTime on MyData class
    Binding myNewBindDef = new Binding("TheDate");

    myNewBindDef.Mode = BindingMode.OneWay;
    myNewBindDef.Source = myChangedData;
    myNewBindDef.Converter = TheConverter;
    myNewBindDef.ConverterCulture = new CultureInfo("en-US");

      // myDatetext is a TextBlock object that is the binding target object
    BindingOperations.SetBinding(myDateText, TextBlock.TextProperty, myNewBindDef);
    BindingOperations.SetBinding(myDateText, TextBlock.ForegroundProperty, myNewBindDef);

    lbChooseCulture.SelectedIndex = 0;
}

 Private Sub OnPageLoaded(ByVal sender As Object, ByVal e As EventArgs)
     ' Make a new source, to grab a new timestamp
     Dim myChangedData As New MyData()

     ' Create a new binding
 ' TheDate is a property of type DateTime on MyData class
     Dim myNewBindDef As New Binding("TheDate")

     myNewBindDef.Mode = BindingMode.OneWay
     myNewBindDef.Source = myChangedData
     myNewBindDef.Converter = TheConverter
     myNewBindDef.ConverterCulture = New CultureInfo("en-US")

' myDatetext is a TextBlock object that is the binding target object
     BindingOperations.SetBinding(myDateText, TextBlock.TextProperty, myNewBindDef)
     BindingOperations.SetBinding(myDateText, TextBlock.ForegroundProperty, myNewBindDef)

     lbChooseCulture.SelectedIndex = 0
 End Sub

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

Sintaxe do caminho de vinculação

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

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

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

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

  • Os indexadores de uma propriedade podem ser especificados entre colchetes após o nome da propriedade onde o indexador é aplicado. Por exemplo, a cláusula Path=ShoppingCart[0] define a ligação ao índice que corresponde à forma como a indexação interna da sua propriedade lida com a cadeia de caracteres literal "0". Indexadores aninhados também são suportados.

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

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

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

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

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

Mecanismo de fuga

  • Dentro dos indexadores ([ ]), o caractere de acento circunflexo (^) escapa do caractere seguinte.

  • Se você definir Path em XAML, também precisará escapar (usando entidades XML) de certos caracteres que são especiais para a definição de linguagem XML:

    • Use &amp; para escapar do personagem "&".

    • Use &gt; para contornar a tag final ">".

  • Além disso, se descreveres toda a vinculação num atributo usando a sintaxe da extensão de marcação, precisarás de escapar (usando a barra invertida \) caracteres que são especiais para o analisador de extensões 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 direita (}) é o final de uma extensão de marcação.

Comportamentos padrão

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

  • É criado um conversor padrão que tenta fazer uma conversão de tipo entre o valor de origem da vinculação e o valor de destino da ligaçã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 vinculação usará a propriedade Language do objeto de destino de vinculação. Em XAML, o 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 retornada por esse contexto seja apropriada para vinculação sem exigir mais modificações de caminho, uma declaração de vinculação não pode ter nenhuma cláusula: {Binding} Esta é geralmente a maneira como uma associação é especificada para o estilo de dados, quando a vinculação incide sobre uma coleção. Para obter mais informações, consulte a seção "Objetos inteiros usados como uma fonte de vinculação" no Visão geral de fontes de vinculação.

  • O Mode padrão varia entre unidirecional e bidirecional, dependendo da propriedade de dependência que está sendo vinculada. Você sempre pode declarar o modo de vinculaçã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, usam como padrão ligações bidirecionais, enquanto a maioria das outras propriedades usa como padrão ligações unidirecionais.

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

Ver também