Compartir por

Visión general de las propiedades adjuntas

Una propiedad adjunta es un concepto XAML. Las propiedades adjuntas permiten establecer pares adicionales de propiedad/valor en un objeto, pero las propiedades no forman parte de la definición de objeto original. Las propiedades adjuntas normalmente se definen como una forma especializada de propiedad de dependencia que no tiene un envoltorio de propiedad convencional en el modelo de objetos del tipo propietario.

Prerrequisitos

Se supone que comprende el concepto básico de las propiedades de dependencia y que ha leído Información general sobre las propiedades de dependencia.

Propiedades adjuntas en XAML

En XAML, estableces propiedades adjuntas mediante la sintaxis AttachedPropertyProvider.PropertyName. Este es un ejemplo de cómo puedes establecer Canvas.Left en XAML.

<Canvas>
  <Button Canvas.Left="50">Hello</Button>
</Canvas>

Nota:

Solo usamos Canvas.Left como una propiedad adjunta de ejemplo sin explicar completamente por qué lo usaría. Si quieres saber más sobre lo que Canvas.Left es para y cómo Canvas controla sus elementos secundarios de diseño, consulta el tema de referencia canvas o Definir diseños con XAML.

¿Por qué usar propiedades adjuntas?

Las propiedades adjuntas son una manera de escapar las convenciones de codificación que podrían impedir que diferentes objetos de una relación se comuniquen entre sí en tiempo de ejecución. Sin duda, es posible colocar propiedades en una clase base común para que cada objeto pueda obtener y establecer esa propiedad. Sin embargo, eventualmente, la gran cantidad de escenarios en los que podría querer hacer esto sobrecargará sus clases base con propiedades compartibles. Podría incluso introducir casos en los que solo dos de cientos de descendientes intenten usar una propiedad. No es un buen diseño de clase. Para solucionar esto, el concepto de propiedad adjunta permite a un objeto asignar un valor para una propiedad que su propia estructura de clases no define. La clase de definición puede leer el valor de los objetos secundarios en tiempo de ejecución después de crear los distintos objetos en un árbol de objetos.

Por ejemplo, los elementos secundarios pueden usar propiedades adjuntas para informar a su elemento primario de cómo se van a presentar en la interfaz de usuario. Este es el caso de la propiedad adjunta Canvas.Left . Canvas.Left se crea como una propiedad adjunta porque se establece en elementos contenidos en un elemento Canvas , en lugar de en el propio Canvas . Después, cualquier elemento secundario posible usa Canvas.Left y Canvas.Top para especificar su offset de diseño dentro del contenedor de diseño Canvas del elemento primario. Las propiedades adjuntas permiten que esto funcione sin desordenar el modelo de objetos del elemento base con una gran cantidad de propiedades que se aplican a solo uno de los muchos contenedores de diseño posibles. En su lugar, muchos de los contenedores de diseño implementan su propio conjunto de propiedades adjuntas.

Para implementar la propiedad adjunta, la clase Canvas define un campo DependencyProperty estático denominado Canvas.LeftProperty. A continuación, Canvas proporciona los métodos SetLeft y GetLeft como descriptores de acceso públicos para la propiedad adjunta, para habilitar tanto la configuración XAML como el acceso a valores en tiempo de ejecución. Para XAML y para el sistema de propiedades de dependencia, este conjunto de API satisface un patrón que habilita una sintaxis XAML específica para las propiedades adjuntas y almacena el valor en el almacén de propiedades de dependencia.

Cómo usa el tipo propietario las propiedades adjuntas

Aunque las propiedades adjuntas se pueden establecer en cualquier elemento XAML (o en cualquier dependencyObject subyacente), eso no significa automáticamente que establecer la propiedad produce un resultado tangible o que se accede al valor. El tipo que define la propiedad adjunta suele seguir uno de estos escenarios:

  • El tipo que define la propiedad adjunta es el elemento primario en una relación de otros objetos. Los objetos secundarios establecerán valores para la propiedad asociada. El tipo de propietario de propiedad adjunta tiene un comportamiento innato que recorre en iteración sus elementos secundarios, obtiene los valores y actúa en esos valores en algún momento de la duración del objeto (una acción de diseño, SizeChanged, etc.)
  • El tipo que define la propiedad adjunta se usa como elemento secundario para una variedad de posibles elementos primarios y modelos de contenido, pero la información no es necesariamente información de diseño.
  • La propiedad adjunta notifica información a un servicio, no a otro elemento de interfaz de usuario.

Para obtener más información sobre estos escenarios y tipos propietarios, vea la sección "Más información sobre Canvas.Left" de propiedades adjuntas personalizadas.

Propiedades adjuntas en el código

Las propiedades adjuntas no tienen los contenedores de propiedades típicos para facilitar la obtención y establecer el acceso como lo hacen otras propiedades de dependencia. Esto se debe a que la propiedad adjunta no forma parte necesariamente del modelo de objetos centrado en código para instancias en las que se establece la propiedad. (Es permisible, aunque poco frecuente, definir una propiedad que sea tanto una propiedad adjunta que otros tipos puedan establecer por sí mismos, como una propiedad con un uso convencional en el tipo propietario).

Hay dos maneras de establecer una propiedad adjunta en el código: usar las API del sistema de propiedades o usar los descriptores de acceso de patrones XAML. Estas técnicas son prácticamente equivalentes en términos de su resultado final, por lo que uno para usar es principalmente una cuestión de estilo de codificación.

Uso del sistema de propiedades

Las propiedades adjuntas para Windows Runtime se implementan como propiedades de dependencia, de modo que los valores se puedan almacenar en el almacén de propiedades de dependencia compartida por el sistema de propiedades. Por lo tanto, las propiedades adjuntas exponen un identificador de propiedad dependiente en la clase propietaria.

Para establecer una propiedad adjunta en el código, llame al método SetValue y pase el campo DependencyProperty que actúa como identificador de esa propiedad adjunta. (También se asigna el valor a establecer).

Para obtener el valor de una propiedad adjunta en el código, llame al método GetValue y vuelva a pasar el campo DependencyProperty que actúa como identificador.

Uso del patrón de descriptor de acceso XAML

Un procesador XAML debe poder establecer valores de propiedad adjuntos cuando se analiza XAML en un árbol de objetos. El tipo de propietario de la propiedad adjunta debe implementar métodos de acceso dedicados con los nombres de GetPropertyName y SetPropertyName. Estos métodos de acceso dedicados también son una manera de obtener o establecer la propiedad adjunta en el código. Desde una perspectiva de código, una propiedad adjunta es similar a un campo de respaldo que tiene descriptores de acceso de método en lugar de descriptores de acceso de propiedad, y ese campo de respaldo puede existir en cualquier objeto en lugar de tener que definirse específicamente.

En el ejemplo siguiente se muestra cómo establecer una propiedad adjunta en el código a través de la API de descriptor de acceso XAML. En este ejemplo, myCheckBox es una instancia de la clase CheckBox . La última línea es el código que realmente establece el valor; las líneas antes de eso simplemente establecen las instancias y su relación de padre-hijo. La última línea sin comentario es la sintaxis si utilizas el sistema de propiedades. La última línea comentada es la sintaxis si usas el patrón de accesor XAML.

    Canvas myC = new Canvas();
    CheckBox myCheckBox = new CheckBox();
    myCheckBox.Content = "Hello";
    myC.Children.Add(myCheckBox);
    myCheckBox.SetValue(Canvas.TopProperty,75);
    //Canvas.SetTop(myCheckBox, 75);

    Dim myC As Canvas = New Canvas()
    Dim myCheckBox As CheckBox= New CheckBox()
    myCheckBox.Content = "Hello"
    myC.Children.Add(myCheckBox)
    myCheckBox.SetValue(Canvas.TopProperty,75)
    ' Canvas.SetTop(myCheckBox, 75)

Canvas myC;
CheckBox myCheckBox;
myCheckBox.Content(winrt::box_value(L"Hello"));
myC.Children().Append(myCheckBox);
myCheckBox.SetValue(Canvas::TopProperty(), winrt::box_value(75));
// Canvas::SetTop(myCheckBox, 75);

    Canvas^ myC = ref new Canvas();
    CheckBox^ myCheckBox = ref new CheckBox();
    myCheckBox->Content="Hello";
    myC->Children->Append(myCheckBox);
    myCheckBox->SetValue(Canvas::TopProperty,75);
    // Canvas::SetTop(myCheckBox, 75);

Propiedades adjuntas personalizadas

Para obtener ejemplos de código sobre cómo definir propiedades adjuntas personalizadas y más información sobre los escenarios para usar una propiedad adjunta, consulte Propiedades adjuntas personalizadas.

Sintaxis especial para las referencias de propiedades adjuntas

El punto en el nombre de una propiedad adjunta es una parte clave del patrón de identificación. A veces hay ambigüedades cuando una sintaxis o situación trata el punto como si tuviera algún otro significado. Por ejemplo, un punto se trata como un recorrido de modelo de objetos para una ruta de acceso de enlace. En la mayoría de los casos que implican esta ambigüedad, hay una sintaxis especial para una propiedad adjunta que permite que el punto interno aún se interprete como el separador propietario.propiedad de una propiedad adjunta.

  • Para especificar una propiedad adjunta como parte de una ruta de acceso de destino para una animación, incluya el nombre de propiedad adjunta entre paréntesis ()( por ejemplo, (Canvas.Left). Para obtener más información, consulta Sintaxis de ruta de propiedades.

Advertencia

Una limitación existente de la implementación de WinUI es que no se puede animar una propiedad adjunta personalizada.

  • Para especificar una propiedad adjunta como la propiedad de destino para una referencia de recursos de un archivo de recursos a x:Uid, debe usar una sintaxis especial que inserte una declaración using: calificada por completo al estilo de código entre corchetes ("[]"), para delimitar deliberadamente el ámbito. Por ejemplo, suponiendo que exista un elemento <TextBlock x:Uid="Title" />, la clave de recurso en el archivo de recursos que tiene como destino el valor de Canvas.Top en esa instancia es Title.\[using:Microsoft.UI.Xaml.Controls\]Canvas.Top. Para obtener más información sobre los archivos de recursos y XAML, consulta Localizar cadenas en la interfaz de usuario.
  • Last updated on