Resumo de Declaração de Associações

This topic discusses the different ways you can declare a binding.

Este tópico contém as seguintes seções.

• Prerequisites
• Declaring a Binding in XAML
• Creating a Binding in Code
• Binding Path Syntax
• Default Behaviors
• Tópicos relacionados

Prerequisites

Before reading this topic, it is important that you are familiar with the concept and usage of markup extensions. For more information about markup extensions, see As extensões de marcação e o WPF XAML.

This topic does not cover data binding concepts. For a discussion of data binding concepts, see Revisão de Associação de Dados.

Declaring a Binding in XAML

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

Markup Extension Usage

Binding is a markup extension. When you use the binding extension to declare a binding, the declaration consists of a series of clauses following the Binding keyword and separated by commas (,). The clauses in the binding declaration can be in any order and there are many possible combinations. The clauses are Name=Value pairs where Name is the name of the Binding property and Value is the value you are setting for the property.

When creating binding declaration strings in markup, they must be attached to the specific dependency property of a target object. O exemplo a seguir mostra como ligar o TextBox.Text propriedade usando a extensão de ligação, especificando a Source e Path Propriedades.

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

You can specify most of the properties of the Binding class this way. For more information about the binding extension as well as for a list of Binding properties that cannot be set using the binding extension, see the Ligação de marcação de extensão overview.

Object Element Syntax

Object element syntax is an alternative to creating the binding declaration. In most cases, there is no particular advantage to using either the markup extension or the object element syntax. However, in cases which the markup extension does not support your scenario, such as when your property value is of a non-string type for which no type conversion exists, you need to use the object element syntax.

The following is an example of both the object element syntax and the markup extension usage:

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

The example binds the Foreground property by declaring a binding using the extension syntax. The binding declaration for the Text property uses the object element syntax.

For more information about the different terms, see Sintaxe XAML em detalhes.

MultiBinding and PriorityBinding

MultiBindinge PriorityBinding não oferecem suporte a sintaxe de extensão XAML. Portanto, você deve usar a sintaxe de elemento de objeto se você estiver declarando um MultiBinding ou PriorityBinding em XAML.

Creating a Binding in Code

Another way to specify a binding is to set properties directly on a Binding object in code. O exemplo a seguir mostra como criar um Binding de objeto e especificar as propriedades no código. Neste exemplo, TheConverter é um objeto que implementa o IValueConverter interface.

    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)



...


    End Sub

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



...


}

If the object you are binding is a FrameworkElement or a FrameworkContentElement you can call the SetBinding method on your object directly instead of using BindingOperations.SetBinding. For an example, see Como: Criar uma associação em código.

Binding Path Syntax

Use the Path property to specify the source value you want to bind to:

• In the simplest case, the Path property value is the name of the property of the source object to use for the binding, such as Path=PropertyName.

• Subproperties of a property can be specified by a similar syntax as in C#. For instance, the clause Path=ShoppingCart.Order sets the binding to the subproperty Order of the object or property ShoppingCart.

• To bind to an attached property, place parentheses around the attached property. For example, to bind to the attached property DockPanel.Dock, the syntax is Path=(DockPanel.Dock).

• Indexers of a property can be specified within square brackets following the property name where the indexer is applied. For instance, the clause Path=ShoppingCart[0] sets the binding to the index that corresponds to how your property's internal indexing handles the literal string "0". Nested indexers are also supported.

• Indexers and subproperties can be mixed in a Path clause; for example, Path=ShoppingCart.ShippingInfo[MailingAddress,Street].

• Inside indexers you can have multiple indexer parameters separated by commas (,). The type of each parameter can be specified with parentheses. For example, you can have Path="[(sys:Int32)42,(sys:Int32)24]", where sys is mapped to the System namespace.

• Quando a fonte é um modo de exibição da coleção, o item atual pode ser especificado com uma barra (/). Por exemplo, a cláusula Path=/ define a ligação para o item atual na exibição. Quando a fonte é uma coleção, esta sintaxe Especifica o item atual da exibição de coleção padrão.

• Os nomes de propriedade e de barras podem ser combinadas para atravessar as propriedades são coleções. Por exemplo, Path=/Offices/ManagerName Especifica o item atual da coleção de origem contém um Offices propriedade que é também uma coleção. O item atual é um objeto que contém um ManagerName propriedade.

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

Escaping Mechanism

• Inside indexers ([ ]), the caret character (^) escapes the next character.

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

  • Use & to escape the character "&".

  • Use > to escape the end tag ">".

• Além disso, se você descrever a ligação inteira em um atributo usando a sintaxe de extensão de marcação, você precisará de escape (usando a barra invertida \) caracteres são especiais para o WPF Analisador de extensão de marcação:

  • Backslash (\) is the escape character itself.

  • The equal sign (=) separates property name from property value.

  • Comma (,) separates properties.

  • The right curly brace (}) is the end of a markup extension.

Default Behaviors

The default behavior is as follows if not specified in the declaration.

• A default converter is created that tries to do a type conversion between the binding source value and the binding target value. If a conversion cannot be made, the default converter returns null.

• If you do not set ConverterCulture, the binding engine uses the Language property of the binding target object. No XAML, esse padrão é "en-US" ou herda o valor do elemento raiz (ou qualquer elemento) da página, caso uma tenha sido explicitamente definida.

• Desde que a ligação já tem um contexto de dados (por exemplo, o contexto herdadas de dados proveniente de um elemento pai) e qualquer item ou uma coleção que está sendo retornado por esse contexto não é apropriada para a ligação sem a necessidade de modificação do caminho ainda mais, uma declaração de ligação pode ter nenhum cláusulas todo: {Binding}Isso geralmente é a maneira em que uma ligação é especificada para o estilo de dados, onde a ligação atua em uma coleção. Para obter mais informações, consulte o "todo objetos usados como uma ligação origem" seção de Visão geral sobre associação de fontes.

• The default Mode varies between one-way and two-way depending on the dependency property that is being bound. You can always declare the binding mode explicitly to ensure that your binding has the desired behavior. In general, user-editable control properties, such as TextBox.Text and RangeBase.Value, default to two-way bindings, whereas most other properties default to one-way bindings.

• The default UpdateSourceTrigger value varies between PropertyChanged and LostFocus depending on the bound dependency property as well. The default value for most dependency properties is PropertyChanged, while the TextBox.Text property has a default value of LostFocus.

Consulte também

Referência

Sintaxe de um PropertyPath XAML

Conceitos

Revisão de Associação de Dados

Otimização de desempenho: Ligação de Dados

Outros recursos

Data Binding How-to Topics

Histórico de alterações

Date	History	Motivo
Setembro de 2010	Explicado TheConverter em "Criando uma ligação no código."	Comentários do cliente.