Visão geral de declarações de associação

  • Artigo

Este tópico discute as diferentes maneiras que você pode declarar uma associaçã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 Extensões de marcação e XAML WPF.

Este tópico não aborda os conceitos de vinculação de dados. Para 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.

Uso da extensão de marcação

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 após a palavra-chave Binding separadas por vírgulas (,). As cláusulas na declaração da associação podem estar em qualquer ordem e há várias combinações possíveis. As cláusulas são =pares Name Value em que Name é o Binding nome da propriedade e Value é o valor que você está definindo para a propriedade.

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

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

Você pode especificar a Binding maioria das propriedades da classe dessa maneira. Para obter mais informações sobre a extensão de vinculação, bem como para obter uma lista de propriedades 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 Binding vinculação.

Sintaxe de elemento de objeto

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

Este é um exemplo de sintaxe de elemento de 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 declarando uma associação usando a Foreground sintaxe de extensão. A declaração de vinculação para a propriedade usa a Text sintaxe do elemento objeto.

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

MultiBinding e PriorityBinding

MultiBinding e PriorityBinding não oferecem suporte à sintaxe de extensão XAML. Portanto, você deve usar a sintaxe do elemento object se estiver declarando um ou um MultiBindingPriorityBinding em XAML.

Criar uma associação em código

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

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 ou um FrameworkElementFrameworkContentElement , você poderá chamar o SetBinding método diretamente no objeto em vez de usar BindingOperations.SetBinding. Para obter um exemplo, consulte Criar uma associação em código.

Sintaxe do caminho de associação

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

  • No caso mais simples, o valor da propriedade é o Path 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 à do C#. Por exemplo, a cláusula Path=ShoppingCart.Order define a associação com a subpropriedade Order do objeto ou da propriedade ShoppingCart.

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

  • Os indexadores de uma propriedade podem ser especificados dentro de colchetes após o nome da propriedade na qual o indexador é aplicado. Por exemplo, a cláusula Path=ShoppingCart[0] define a associação ao índice que corresponde a como a indexação interna de sua propriedade lida com a cadeia de caracteres literal "0". Os indexadores aninhados também têm suporte.

  • Os indexadores e as subpropriedades podem ser combinados em uma cláusula Path. 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]", em que sys é mapeado para o namespace System.

  • Quando a fonte é 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 no modo de exibição. Quando a fonte é uma coleção, essa sintaxe especifica o item atual da exibição de coleção padrão.

  • Barras e nomes de propriedade podem ser combinados para percorrer as 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. O item atual é um objeto que contém uma propriedade ManagerName.

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

Mecanismo de escape

  • Dentro dos indexadores ([]), o caractere de acento circunflexo (^) pula o próximo caractere.

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

    • Use &amp; para pular o caractere "&".

    • Use &gt; para escapar da tag final ">".

  • Além disso, se você descrever toda a associação em um atributo usando a sintaxe de extensão de marcação, precisará escapar (usando barra invertida \) caracteres que são especiais para o analisador de extensão de marcação 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 será o seguinte se não for especificado na declaração.

  • É criado um conversor padrão que tenta fazer uma conversão de tipos entre o valor de origem de associação e o valor de destino de associação. Se a conversão não puder ser realizada, o conversor padrão retornará null.

  • Se você não definir ConverterCulture, o mecanismo de vinculação usará a Language propriedade do objeto de destino de vinculaçã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.

  • Contanto que a associação já tenha um contexto de dados (por exemplo, o contexto de dados herdados vem de um elemento pai) e qualquer item ou coleção que esteja sendo retornado por aquele contexto seja apropriado para a associação sem novas modificação do caminho, uma declaração de associação não poderá ter nenhuma cláusula: {Binding}. Essa geralmente é a maneira que uma associação é especificada para estilos de dados, em que a associação age em uma coleção. Para obter mais informações, consulte a seção "Todos os objetos usados como uma origem de associação" em Visão geral das origens da 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 e RangeBase.Value, têm como padrão as associações bidirecionais, enquanto a maioria das outras propriedades tem como TextBox.Text padrão as associações unidirecionais.

  • O valor padrão UpdateSourceTrigger também varia entre PropertyChanged e LostFocus dependendo 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.

Confira também