Información general sobre declaraciones de enlacesBinding Declarations Overview

En este tema se describen las distintas formas de declarar un enlace.This topic discusses the different ways you can declare a binding.

Requisitos previosPrerequisites

Antes de leer este tema, es importante que esté familiarizado con el concepto y el uso de las extensiones de marcado.Before reading this topic, it is important that you are familiar with the concept and usage of markup extensions. Para más información sobre las extensiones de marcado, consulte Extensiones de marcado y XAML de WPF.For more information about markup extensions, see Markup Extensions and WPF XAML.

En este tema no se tratan los conceptos de enlace de datos.This topic does not cover data binding concepts. Para obtener una explicación de los conceptos de enlace de datos, consulte Información general sobre el enlace de datos.For a discussion of data binding concepts, see Data Binding Overview.

Declarar un enlace en XAMLDeclaring a Binding in XAML

En esta sección se describe cómo declarar en XAML.This section discusses how to declare a binding in XAML.

Uso de la extensión de marcadoMarkup Extension Usage

Binding es una extensión de marcado.Binding is a markup extension. Cuando se utiliza la extensión de enlace para declarar un enlace, la declaración consta de una serie de cláusulas después de la palabra clave Binding y separadas por comas (,).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 (,). Las cláusulas de la declaración de enlace pueden estar en cualquier orden y hay muchas combinaciones posibles.The clauses in the binding declaration can be in any order and there are many possible combinations. Las cláusulas son nombres=pares de valores donde Name es el nombre de la propiedad Binding y Value es el valor que se establece para la propiedad.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.

Al crear cadenas de declaración de enlace en el marcado, se adjuntará a la propiedad de dependencia concreta de un objeto de destino.When creating binding declaration strings in markup, they must be attached to the specific dependency property of a target object. En el ejemplo siguiente se muestra cómo enlazar la propiedad TextBox.Text mediante la extensión de enlace, especificando las propiedades Source y Path.The following example shows how to bind the TextBox.Text property using the binding extension, specifying the Source and Path properties.

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

Puede especificar la mayoría de las propiedades de la clase Binding de esta manera.You can specify most of the properties of the Binding class this way. Para obtener más información sobre la extensión de enlace, así como para obtener una lista de las propiedades de Binding que no se pueden establecer mediante la extensión de enlace, vea información general sobre la extensión de marcado de enlace .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 Binding Markup Extension overview.

Sintaxis de elemento de objetoObject Element Syntax

La sintaxis de elemento de objeto es una alternativa a la creación de la declaración de enlace.Object element syntax is an alternative to creating the binding declaration. En la mayoría de los casos, no hay ninguna ventaja particular para usar la extensión de marcado o la sintaxis de elemento de objeto.In most cases, there is no particular advantage to using either the markup extension or the object element syntax. Sin embargo, en aquellos casos en los que la extensión de marcado no admite el escenario, como cuando el valor de la propiedad es de un tipo que no es una cadena para la que no existe conversión de tipo, debe utilizar la sintaxis de elemento de objeto.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.

El siguiente es un ejemplo de la sintaxis de elemento de objeto y el uso de la extensión de marcado: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>

En el ejemplo se enlaza la propiedad Foreground declarando un enlace mediante la sintaxis de la extensión.The example binds the Foreground property by declaring a binding using the extension syntax. La declaración de enlace para la propiedad Text usa la sintaxis del elemento de objeto.The binding declaration for the Text property uses the object element syntax.

Para más información sobre los distintos términos, consulte Detalles de la sintaxis XAML.For more information about the different terms, see XAML Syntax In Detail.

MultiBinding y PriorityBindingMultiBinding and PriorityBinding

MultiBinding y PriorityBinding no admiten la sintaxis de la extensión XAML.MultiBinding and PriorityBinding do not support the XAML extension syntax. Por lo tanto, debe usar la sintaxis del elemento de objeto si está declarando un MultiBinding o un PriorityBinding en XAML.Therefore, you must use the object element syntax if you are declaring a MultiBinding or a PriorityBinding in XAML.

Crear un enlace mediante códigoCreating a Binding in Code

Otra manera de especificar un enlace es establecer las propiedades directamente en un Binding objeto en el código.Another way to specify a binding is to set properties directly on a Binding object in code. En el ejemplo siguiente se muestra cómo crear un objeto Binding y especificar las propiedades en el código.The following example shows how to create a Binding object and specify the properties in code. En este ejemplo, TheConverter es un objeto que implementa la interfaz IValueConverter.In this example, TheConverter is an object that implements the 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

Si el objeto que se va a enlazar es un FrameworkElement o un FrameworkContentElement, puede llamar al método SetBinding en el objeto directamente en lugar de utilizar BindingOperations.SetBinding.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. Para obtener un ejemplo, consulte Crear un enlace mediante código.For an example, see Create a Binding in Code.

Sintaxis de la ruta de enlaceBinding Path Syntax

Use la propiedad Path para especificar el valor de origen al que desea enlazar:Use the Path property to specify the source value you want to bind to:

  • En el caso más simple, el valor de la propiedad Path es el nombre de la propiedad del objeto de origen que se va a usar para el enlace, como Path=PropertyName.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.

  • Las subpropiedades de una propiedad se pueden especificar mediante una sintaxis similar C#a la de.Subproperties of a property can be specified by a similar syntax as in C#. Por ejemplo, la cláusula Path=ShoppingCart.Order define el enlace a la subpropiedad Order del objeto o la propiedad ShoppingCart.For instance, the clause Path=ShoppingCart.Order sets the binding to the subproperty Order of the object or property ShoppingCart.

  • Para enlazar a una propiedad adjunta, coloque paréntesis alrededor de esta propiedad.To bind to an attached property, place parentheses around the attached property. Por ejemplo, para enlazar a la propiedad adjunta DockPanel.Dock, la sintaxis es Path=(DockPanel.Dock).For example, to bind to the attached property DockPanel.Dock, the syntax is Path=(DockPanel.Dock).

  • Los indizadores de una propiedad pueden especificarse entre corchetes después del nombre de la propiedad donde se aplica el indizador.Indexers of a property can be specified within square brackets following the property name where the indexer is applied. Por ejemplo, la cláusula Path=ShoppingCart[0] establece el enlace al índice que se corresponde a cómo la indización interna de la propiedad administra la cadena literal "0".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". También se admiten indizadores anidados.Nested indexers are also supported.

  • Los indizadores y las subpropiedades se pueden combinar en una cláusula Path; por ejemplo, Path=ShoppingCart.ShippingInfo[MailingAddress,Street]..Indexers and subproperties can be mixed in a Path clause; for example, Path=ShoppingCart.ShippingInfo[MailingAddress,Street].

  • Dentro de los indexadores puede tener varios parámetros de indizador separados por comas (,).Inside indexers you can have multiple indexer parameters separated by commas (,). El tipo de cada parámetro se puede especificar entre paréntesis.The type of each parameter can be specified with parentheses. Por ejemplo, puede tener Path="[(sys:Int32)42,(sys:Int32)24]", donde sys está asignado al espacio de nombres System.For example, you can have Path="[(sys:Int32)42,(sys:Int32)24]", where sys is mapped to the System namespace.

  • Cuando el origen es una vista de colección, el elemento actual se puede especificar con una barra diagonal (/).When the source is a collection view, the current item can be specified with a slash (/). Por ejemplo, la cláusula Path=/ establece el enlace con el elemento actual de la vista.For example, the clause Path=/ sets the binding to the current item in the view. Cuando el origen es una colección, esta sintaxis especifica el elemento actual de la vista de colección predeterminada.When the source is a collection, this syntax specifies the current item of the default collection view.

  • Los nombres de propiedad y las barras diagonales se pueden combinar para atravesar propiedades que son colecciones.Property names and slashes can be combined to traverse properties that are collections. Por ejemplo, Path=/Offices/ManagerName especifica el elemento actual de la colección de origen, que contiene una propiedad Offices que también es una colección.For example, Path=/Offices/ManagerName specifies the current item of the source collection, which contains an Offices property that is also a collection. Su elemento actual es un objeto que contiene una propiedad ManagerName.Its current item is an object that contains a ManagerName property.

  • Opcionalmente, se puede usar una ruta de acceso de punto (.) para enlazar con el origen actual.Optionally, a period (.) path can be used to bind to the current source. Por ejemplo, Text="{Binding}" es equivalente a Text="{Binding Path=.}".For example, Text="{Binding}" is equivalent to Text="{Binding Path=.}".

Mecanismo de escapeEscaping Mechanism

  • Dentro de los indizadores ([ ]), el carácter de intercalación (^) realiza el escape del carácter siguiente.Inside indexers ([ ]), the caret character (^) escapes the next character.

  • Si establece Path en XAML, también necesitará usar como escape (mediante entidades XML) determinados caracteres que son especiales para la definición del lenguaje XML:If you set Path in XAML, you also need to escape (using XML entities) certain characters that are special to the XML language definition:

    • Use &amp; para realizar el escape del carácter "&".Use &amp; to escape the character "&".

    • Use &gt; para realizar el escape de la etiqueta final ">".Use &gt; to escape the end tag ">".

  • Además, si describe el enlace completo en un atributo mediante la sintaxis de extensión de marcado, deberá realizar el escape (con la barra diagonal inversa \) de los caracteres que son especiales para el analizador de extensión de marcado WPFWPF:Additionally, if you describe the entire binding in an attribute using the markup extension syntax, you need to escape (using backslash \) characters that are special to the WPFWPF markup extension parser:

    • La barra diagonal inversa (\) es el mismo carácter de escape.Backslash (\) is the escape character itself.

    • El signo igual (=) separa el nombre de propiedad del valor de propiedad.The equal sign (=) separates property name from property value.

    • La coma (,) separa las propiedades.Comma (,) separates properties.

    • La llave de cierre (}) es el final de una extensión de marcado.The right curly brace (}) is the end of a markup extension.

Comportamientos predeterminadosDefault Behaviors

El comportamiento predeterminado es el siguiente si no se especifica en la declaración.The default behavior is as follows if not specified in the declaration.

  • Se crea un convertidor predeterminado que intenta realizar una conversión de tipos entre el valor de origen de enlace y el valor de destino del enlace.A default converter is created that tries to do a type conversion between the binding source value and the binding target value. Si no se puede realizar una conversión, el convertidor predeterminado devuelve null.If a conversion cannot be made, the default converter returns null.

  • Si no se establece ConverterCulture, el motor de enlace utiliza la propiedad Language del objeto de destino de enlace.If you do not set ConverterCulture, the binding engine uses the Language property of the binding target object. En XAML, tiene como valor predeterminado "en-US" o hereda el valor de elemento raíz (o cualquier elemento) de la página, si se ha establecido explícitamente.In XAML, this defaults to "en-US" or inherits the value from the root element (or any element) of the page, if one has been explicitly set.

  • Siempre que el enlace ya tenga un contexto de datos (por ejemplo, el contexto de datos heredado procedente de un elemento primario) y con independencia de que el elemento o la colección que se devuelve en ese contexto sea apropiado para el enlace sin necesitar una modificación adicional de la ruta, una declaración de enlace no puede tener ninguna cláusula: {Binding} suele ser la manera en que se especifica un enlace para los estilos de datos, donde el enlace se actúa sobre una colección.As long as the binding already has a data context (for instance, the inherited data context coming from a parent element), and whatever item or collection being returned by that context is appropriate for binding without requiring further path modification, a binding declaration can have no clauses at all: {Binding} This is often the way a binding is specified for data styling, where the binding acts upon a collection. Para más información, consulte la sección "Utilizar objetos completos como origen de enlace" en Información general sobre orígenes de enlaces.For more information, see the "Entire Objects Used as a Binding Source" section in the Binding Sources Overview.

  • La Mode predeterminada varía en función de la propiedad de dependencia que se está enlazando.The default Mode varies between one-way and two-way depending on the dependency property that is being bound. Siempre puede declarar explícitamente el modo de enlace para asegurarse de que el enlace tiene el comportamiento deseado.You can always declare the binding mode explicitly to ensure that your binding has the desired behavior. En general, las propiedades de control que puede modificar el usuario, como TextBox.Text y RangeBase.Value, tienen como valor predeterminado enlaces bidireccionales, mientras que la mayoría de las demás propiedades tienen como valor predeterminado enlaces unidireccionales.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.

  • El valor UpdateSourceTrigger predeterminado varía entre PropertyChanged y LostFocus en función de la propiedad de dependencia enlazada.The default UpdateSourceTrigger value varies between PropertyChanged and LostFocus depending on the bound dependency property as well. El valor predeterminado de la mayoría de las propiedades de dependencia es PropertyChanged, mientras que la propiedad TextBox.Text tiene un valor predeterminado de LostFocus.The default value for most dependency properties is PropertyChanged, while the TextBox.Text property has a default value of LostFocus.

Vea tambiénSee also