¿Qué son las declaraciones vinculantes?

Normalmente, los desarrolladores declaran los enlaces directamente en el marcado XAML de los elementos de la interfaz de usuario a los que quieren enlazar datos. Sin embargo, también puede declarar enlaces en el código. En este artículo se describe cómo declarar enlaces tanto en XAML como en código.

Prerrequisitos

Antes de leer este artículo, es importante que esté familiarizado con el concepto y el uso de extensiones de marcado. Para obtener más información sobre las extensiones de marcado, consulta Extensiones de marcado y XAML de WPF.

En este artículo no se tratan los conceptos de enlace de datos. Para obtener una explicación de los conceptos de enlace de datos, consulte Introducción al enlace de datos.

Declaración de un enlace en XAML

Binding es una extensión de marcado. Cuando se usa la extensión de enlace para declarar un enlace, la declaración consta de una serie de cláusulas después de la Binding palabra clave y separadas por comas (,). Las cláusulas en la declaración vinculante pueden estar en cualquier orden y hay muchas combinaciones posibles. Las cláusulas son pares Nombre=valor , donde Name es el nombre de la Binding propiedad y Value es el valor que se va a establecer para la propiedad.

Cuando se crean cadenas de declaraciones de enlace en el marcado, deben adjuntarse a la propiedad de dependencia específica del objeto de destino. En el ejemplo siguiente se muestra cómo enlazar la TextBox.Text propiedad mediante la extensión de enlace, especificando las Source propiedades y Path .

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

En el ejemplo anterior se usa un tipo de objeto de datos simple de Person. El fragmento de código siguiente es el código de ese 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

Puede especificar la mayoría de las propiedades de la Binding clase de esta manera. Para obtener más información sobre la extensión de enlace y para obtener una lista de Binding propiedades que no se pueden establecer mediante la extensión de enlace, consulte la información general sobre la extensión de marcado de enlace (.NET Framework).

Para obtener un ejemplo sobre cómo crear un enlace en XAML, consulta Cómo crear un enlace de datos.

Sintaxis del elemento Object

La sintaxis del elemento object es una alternativa a la creación de la declaración de enlace. En la mayoría de los casos, no hay ninguna ventaja específica al usar la extensión de código o la sintaxis del elemento de objeto. Sin embargo, cuando la extensión de marcado no admite su escenario, como cuando el valor de propiedad es de un tipo que no es de cadena para el que no existe ninguna conversión de tipos, debe usar la sintaxis del elemento de objeto.

En la sección anterior se mostró cómo enlazar con una extensión XAML. En el ejemplo siguiente se muestra cómo realizar el mismo enlace, pero se usa la sintaxis del elemento object:

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

Para obtener más información sobre los distintos términos, consulta Sintaxis XAML en detalle (.NET Framework).

MultiBinding y PriorityBinding

MultiBinding y PriorityBinding no admiten la sintaxis de la extensión XAML. Por eso debes usar la sintaxis del elemento de objeto si estás declarando un MultiBinding o un PriorityBinding en XAML.

Creación de un enlace en el código

Otra manera de especificar un enlace es establecer propiedades directamente en un Binding objeto en el código y, a continuación, asignar el enlace a una propiedad. En el ejemplo siguiente se muestra cómo crear un Binding objeto en el 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

El código anterior estableció lo siguiente en el enlace:

• Ruta de acceso de la propiedad en el objeto de origen de datos.
• Modo del enlace.
• El origen de datos, en este caso, una instancia de objeto simple que representa a una persona.
• Convertidor opcional que procesa el valor procedente del objeto de origen de datos antes de asignarlo a la propiedad de destino.

Cuando el objeto que está enlazando es un FrameworkElement o un FrameworkContentElement, puede llamar directamente al método SetBinding en su objeto en lugar de usar BindingOperations.SetBinding. Para obtener un ejemplo, vea Cómo: Crear una vinculación en código.

En el ejemplo anterior se usa un tipo de objeto de datos simple de Person. A continuación se muestra el código de ese 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

Sintaxis de ruta de vinculación

Use la Path propiedad para especificar el valor de origen al que desea enlazar:

• En el caso más sencillo, el valor de la propiedad Path es el nombre de la propiedad del objeto de origen que se va a usar para la vinculación, como Path=PropertyName.

• Las subpropiedades de una propiedad se pueden especificar mediante una sintaxis similar a en C#. Por ejemplo, la cláusula Path=ShoppingCart.Order establece el enlace a la subpropiedad Order del objeto o propiedad ShoppingCart.

• Para enlazar a una propiedad adjunta, coloque paréntesis alrededor de la propiedad adjunta. Por ejemplo, para enlazar a la propiedad DockPanel.Dockadjunta , la sintaxis es Path=(DockPanel.Dock).

• Los indexadores de una propiedad se pueden especificar entre corchetes después del nombre de propiedad donde se aplica el indexador. Por ejemplo, la cláusula Path=ShoppingCart[0] establece el enlace al índice que corresponde al modo en que la indexación interna de la propiedad controla la cadena literal "0". También se admiten indexadores anidados.

• Los indizadores y las subpropiedades se pueden mezclar en una Path cláusula; por ejemplo, Path=ShoppingCart.ShippingInfo[MailingAddress,Street].

• Dentro de los indexadores. Puede tener varios parámetros de indexador separados por comas (,). El tipo de cada parámetro se puede especificar entre paréntesis. Por ejemplo, puede tener Path="[(sys:Int32)42,(sys:Int32)24]", donde sys está asignado al System namespace.

• Cuando el origen es una vista de colección, el elemento actual se puede especificar con una barra diagonal (/). Por ejemplo, la cláusula Path=/ establece la vinculación al elemento actual de la vista. Cuando el origen es una colección, esta sintaxis especifica el elemento actual de la vista de colección predeterminada.

• Los nombres de propiedad y las barras diagonales se pueden combinar para recorrer las propiedades que son colecciones. Por ejemplo, Path=/Offices/ManagerName especifica el elemento actual de la colección de origen, que contiene una Offices propiedad que también es una colección. Su elemento actual es un objeto que contiene una ManagerName propiedad .

• Opcionalmente, se puede usar una ruta de punto (.) para conectar con el origen actual. Por ejemplo, Text="{Binding}" equivale a Text="{Binding Path=.}".

Mecanismo de escape

• Dentro de los indizadores ([ ]), el carácter de intercalación (^) escapa al carácter siguiente.

• Si estableces Path en XAML, también debes escapar (mediante entidades XML) determinados caracteres especiales para la definición del lenguaje XML:

  • Use & para escapar el carácter "&".

  • Use > para escapar de la etiqueta final ">".

• Además, si describe toda la vinculación en un atributo mediante la sintaxis de la extensión de marcado, debe escapar (mediante barras diagonales inversas \) caracteres especiales para el analizador de extensiones de marcado de WPF:

  • La barra diagonal inversa (\) es el mismo carácter de escape.

  • El signo igual (=) separa el nombre de propiedad del valor de la propiedad.

  • Coma (,) separa las propiedades.

  • La llave derecha (}) es el final de una extensión de marcado.

Dirección de los enlaces

Utilice la Binding.Mode propiedad para especificar la dirección del enlace. Los modos siguientes son las opciones disponibles para las actualizaciones de enlace:

Para obtener más información, consulte la BindingMode enumeración .

En el ejemplo siguiente se muestra cómo establecer la Mode propiedad :

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

Para detectar cambios en la fuente (aplicables a los enlaces OneWay y TwoWay), la fuente debe implementar un mecanismo adecuado para la notificación de cambios de propiedad, como INotifyPropertyChanged. Para obtener más información, consulte Proporcionar notificaciones de cambios.

Para TwoWay o OneWayToSource los enlaces, puede controlar el momento de las actualizaciones del origen estableciendo la propiedad UpdateSourceTrigger. Para obtener más información, consulte UpdateSourceTrigger.

Comportamientos predeterminados

El comportamiento predeterminado es el siguiente si no se especifica en la declaración:

• 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 de enlace. Si no se puede realizar una conversión, el convertidor predeterminado devuelve null.

• Si no establece ConverterCulture, el motor de enlace usa la Language propiedad del objeto de destino de enlace. En XAML, este valor predeterminado es en-US o hereda el valor del elemento raíz (o cualquier elemento) de la página, si se ha establecido explícitamente uno.

• Siempre que el enlace ya tenga un contexto de datos (por ejemplo, el contexto de datos heredado procedente de un elemento primario) y cualquier elemento o colección que devuelva ese contexto es adecuado para el enlace sin necesidad de modificar la ruta de acceso adicional, una declaración de enlace no puede tener ninguna cláusula en absoluto: {Binding}. Esta suele ser la forma en que se especifica un enlace para el estilo de datos, donde el enlace actúa sobre una colección. Para obtener más información, vea Usar objetos completos como origen de enlace.

• El valor predeterminado Mode varía entre unidireccional y bidireccional en función de la propiedad de dependencia que se enlaza. Siempre puede declarar explícitamente el modo de enlace para asegurarse de que el enlace tiene el comportamiento deseado. En general, las propiedades de control editables por el usuario, como TextBox.Text y RangeBase.Value, se usan de forma predeterminada en enlaces bidireccionales, pero la mayoría de las demás propiedades se convierten de forma predeterminada en enlaces unidireccionales.

• El valor predeterminado UpdateSourceTrigger varía entre PropertyChanged y LostFocus según la propiedad de dependencia enlazada. El valor predeterminado para la mayoría de las propiedades de dependencia es PropertyChanged, mientras que la TextBox.Text propiedad tiene un valor predeterminado de LostFocus.

Consulte también

• Descripción general de la vinculación de datos
• Información general sobre orígenes de enlaces
• Creación de un enlace de datos
• Sintaxis XAML PropertyPath (.NET Framework)