Introducción a 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 contenedor de propiedades convencional en el modelo de objetos del tipo de propietario.

Requisitos previos

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>

¿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. Pero, finalmente, el número máximo de escenarios en los que es posible que quiera hacerlo aumentará las clases base con propiedades que se pueden compartir. Incluso puede presentar 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 desplazamiento de diseño dentro del elemento primario del contenedor de diseño de Canvas . 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 adjunta. 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 sobre esos valores en algún momento de la duración del objeto (una acción de diseño, SizeChanged, etcetera).
• El tipo que define la propiedad adjunta se usa como elemento secundario para una variedad de posibles elementos primarios y con modo carpa ls, 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 es una propiedad adjunta que otros tipos pueden establecerse en sí mismos, y que también tiene un uso de propiedad 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 de dependencia 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 pasa 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 descriptor de acceso dedicados denominados en el formulario GetPropertyName y SetPropertyName. Estos métodos de descriptor 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 establece realmente el valor; las líneas antes de que simplemente establezcan las instancias y su relación de elementos primarios y secundarios. La última línea sin marca de comentario es la sintaxis si se usa el sistema de propiedades. La última línea comentada es la sintaxis si usas el patrón de descriptor de acceso 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 de un nombre de 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 tener 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 todavía se analice como propietario.separador de 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 más información, consulta Sintaxis de property-path.

• Para especificar una propiedad adjunta como la propiedad de destino para una referencia de recursos de un archivo de recursos a x:Uid, use una sintaxis especial que inserte un estilo de código completo mediante: declaración entre corchetes ("[]"), para crear un salto de ámbito deliberado. Por ejemplo, suponiendo que existe 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:Windows.UI.Xaml.Controls]Canvas.Top". Para obtener más información sobre los archivos de recursos y XAML, consulta Inicio rápido: Traducción de recursos de interfaz de usuario.

Temas relacionados

• Propiedades adjuntas personalizadas
• Introducción a las propiedades de dependencia
• Definición de diseños con XAML
• Inicio rápido: Traducción de recursos de interfaz de usuario
• SetValue
• GetValue