Clases de configuración de plantillasTemplate settings classes

Requisitos previosPrerequisites

Damos por hecho que sabes agregar controles a la interfaz de usuario, establecer sus propiedades y adjuntar controladores de eventos.We assume that you can add controls to your UI, set their properties, and attach event handlers. Para obtener instrucciones para agregar controles a la aplicación, consulta Agregar controles y administrar eventos.For instructions for adding controls to your app, see Add controls and handle events. También damos por hecho que conoces los conceptos básicos de cómo definir una plantilla personalizada para un control al realizar una copia de la plantilla predeterminada y modificarla.We also assume that you know the basics of how to define a custom template for a control by making a copy of the default template and editing it. Para obtener más información al respecto, consulta Inicio rápido: plantillas de control.For more info on this, see Quickstart: Control templates.

Escenario para las clases TemplateSettingsThe scenario for TemplateSettings classes

Las clases TemplateSettings proporcionan un conjunto de propiedades que se usan al definir una nueva plantilla de control para un control.TemplateSettings classes provide a set of properties that are used when you define a new control template for a control. Las propiedades tienen valores como medidas de píxel para el tamaño de determinadas partes de los elementos de la interfaz de usuario.The properties have values such as pixel measurements for the size of certain UI element parts. A veces, los valores son valores calculados que provienen de la lógica de control que normalmente no es de fácil reemplazo ni acceso.The values are sometimes calculated values that come from control logic that isn't typically easy to override or even access. Algunas de las propiedades están pensadas como valores De origen y De destino que controlan las transiciones y animaciones de los elementos y, por ende, las propiedades TemplateSettings correspondientes vienen en pares.Some of the properties are intended as From and To values that control transitions and animations of parts, and thus the relevant TemplateSettings properties come in pairs.

Existen varias clases TemplateSettings.There are several TemplateSettings classes. Todas ellas están en el espacio de nombres Windows.UI.Xaml.Controls.Primitives.All of them are in the Windows.UI.Xaml.Controls.Primitives namespace. A continuación, se ofrece una lista de las clases y un vínculo a la propiedad TemplateSettings del control correspondiente.Here's a list of the classes, and a link to the TemplateSettings property of the relevant control. Esta propiedad TemplateSettings define el modo de acceso a los valores TemplateSettings para el control y puede establecer enlaces de plantilla a sus propiedades:This TemplateSettings property is how you access the TemplateSettings values for the control, and can establish template bindings to its properties:

Las propiedades TemplateSettings están pensadas para usarlas siempre en XAML, no para el código.TemplateSettings properties are always intended to be used in XAML, not code. Se trata de subpropiedades de solo lectura de una propiedad TemplateSettings de solo lectura de un control principal.They are read-only sub-properties of a read-only TemplateSettings property of a parent control. Para un escenario avanzado de control personalizado, en el que creas una nueva clase basada en Control que, por consiguiente, puede influir en la lógica de control, considera la posibilidad de definir una propiedad TemplateSettings personalizada en el control para comunicar información que podría resultar útil a cualquier persona que esté volviendo a generar plantillas del control.For an advanced custom control scenario, where you're creating a new Control-based class and thus can influence the control logic, consider defining a custom TemplateSettings property on the control in order to communicate info that might be useful for anyone that is re-templating the control. Dado que esa propiedad es un valor de solo lectura, define una nueva clase TemplateSettings relacionada con tu control que tiene propiedades de solo lectura para cada uno de los elementos de información que son relevantes para las medidas de plantilla, posicionamiento de animación, etc. y asigna a los llamadores la instancia en tiempo de ejecución de la clase que se inicializa con la lógica de control.As that property's read-only value, define a new TemplateSettings class related to your control that has read-only properties for each of the info items that are relevant for template measurements, animation positioning, and so on, and give callers the runtime instance of that class that's initialized using your control logic. Las clases TemplateSettings se derivan de DependencyObject, de modo que las propiedades pueden usar el sistema de propiedades de dependencia de devoluciones de llamada de cambio de propiedad.TemplateSettings classes are derived from DependencyObject, so that the properties can use the dependency property system for property-changed callbacks. Pero los identificadores de propiedades de dependencia para las propiedades no se exponen como API pública, porque las propiedades TemplateSettings deben ser de solo lectura para los llamadores.But the dependency property identifiers for the properties aren't exposed as public API, because the TemplateSettings properties are meant to be read-only to callers.

Cómo usar TemplateSettings en una plantilla de controlHow to use TemplateSettings in a control template

Este es un ejemplo proveniente de las plantillas predeterminadas iniciales de control XAML.Here's an example that comes from the starting default XAML control templates. Este ejemplo en particular proviene de la plantilla predeterminada de ProgressRing:This particular one is from the default template of ProgressRing:

<Ellipse
    x:Name="E1"
    Style="{StaticResource ProgressRingEllipseStyle}"
    Width="{Binding RelativeSource={RelativeSource TemplatedParent}, 
        Path=TemplateSettings.EllipseDiameter}"
    Height="{Binding RelativeSource={RelativeSource TemplatedParent}, 
        Path=TemplateSettings.EllipseDiameter}"
    Margin="{Binding RelativeSource={RelativeSource TemplatedParent}, 
        Path=TemplateSettings.EllipseOffset}"
    Fill="{TemplateBinding Foreground}"/>

El código XAML completo para la plantilla ProgressRing contiene cientos de líneas, por lo que aquí se muestra un pequeño fragmento.The full XAML for the ProgressRing template is hundreds of lines, so this is just a tiny excerpt. Este código XAML define un elemento de control que es uno de los seis elementos Elipse que revelan la animación de giro de progreso indeterminado.This XAML defines a control part that is one of 6 Ellipse elements that portray the spinning animation for indeterminate progress. Como desarrollador, quizá no quieras los círculos y podrías usar otra primitiva gráfica u otra una forma básica para el modo de avance de la animación.As a developer, you might not like the circles and might use a different graphics primitive or a different basic shape for how the animation progresses. Por ejemplo, puedes componer un ProgressRing que use un conjunto de elementos Rectángulo organizados en un cuadrado.For example, you might compose a ProgressRing that uses a set of Rectangle elements arranged in a square instead. Si así fuera, cada componente de Rectángulo de la nueva plantilla podrían tener el aspecto siguiente:If so, each individual Rectangle component of your new template might look like this:

<Rectangle
    x:Name="R1"
    Width="{Binding RelativeSource={RelativeSource TemplatedParent}, 
        Path=TemplateSettings.EllipseDiameter}"
    Height="{Binding RelativeSource={RelativeSource TemplatedParent}, 
        Path=TemplateSettings.EllipseDiameter}"
    Margin="{Binding RelativeSource={RelativeSource TemplatedParent}, 
        Path=TemplateSettings.EllipseOffset}"
    Fill="{TemplateBinding Foreground}"/>

El motivo por el cual las propiedades TemplateSettings son útiles aquí es porque son valores calculados procedentes de la lógica de control básico de ProgressRing.The reason that the TemplateSettings properties are useful here is because they are calculated values coming from the basic control logic of ProgressRing. El cálculo se realiza al dividir los valores ActualWidth y ActualHeight generales de ProgressRing y al asignar una medida calculada a cada uno de los elementos de movimiento en sus plantillas para que los elementos de plantilla puedan cambiar el tamaño según el contenido.The calculation is dividing up the overall ActualWidth and ActualHeight of the ProgressRing, and allotting a calculated measurement for each of the motion elements in its templates so that the template parts can size to content.

Este es otro ejemplo de uso de plantillas predeterminadas de control XAML. Esta vez el ejemplo muestra uno de los conjuntos de propiedades que corresponden a los valores De origen y De destino de una animación.Here's another example usage from the default XAML control templates, this time showing one of the property sets that are the From and To of an animation. Se trata de la plantilla predeterminada ComboBox:This is from the ComboBox default template:

<VisualStateGroup x:Name="DropDownStates">
    <VisualState x:Name="Opened">
        <Storyboard>
            <SplitOpenThemeAnimation
               OpenedTargetName="PopupBorder"
               ContentTargetName="ScrollViewer"
               ClosedTargetName="ContentPresenter"
               ContentTranslationOffset="0"
               OffsetFromCenter="{Binding RelativeSource={RelativeSource TemplatedParent}, 
                 Path=TemplateSettings.DropDownOffset}"
               OpenedLength="{Binding RelativeSource={RelativeSource TemplatedParent}, 
                 Path=TemplateSettings.DropDownOpenedHeight}"
               ClosedLength="{Binding RelativeSource={RelativeSource TemplatedParent},
                 Path=TemplateSettings.DropDownClosedHeight}" />
        </Storyboard>
   </VisualState>
...
</VisualStateGroup>

Una vez más, hay gran cantidad de XAML en la plantilla, por lo que solo mostramos un fragmento.Again there is lots of XAML in the template so we only show an excerpt. Además, este es solo uno de los diversos estados y animaciones de tema que usan las mismas propiedades ComboBoxTemplateSettings.And this is only one of several states and theme animations that each use the same ComboBoxTemplateSettings properties. En el caso de ComboBox, el uso de los valores ComboBoxTemplateSettings mediante enlaces exige que las animaciones relacionadas de la plantilla se detengan y se inicien en posiciones basadas en valores compartidos y, por consiguiente, la transición se realiza sin problemas.For ComboBox, use of the ComboBoxTemplateSettings values through bindings enforces that related animations in the template will stop and start at positions that are based on shared values, and thus transition smoothly.

Nota:    Cuando use valores TemplateSettings como parte de la plantilla de control, asegúrese de que está estableciendo las propiedades que coinciden con el tipo de valor.Note   When you do use TemplateSettings values as part of your control template, make sure you're setting properties that match the type of the value. De lo contrario, tendrías que crear un convertidor de valores para el enlace para poder convertir el tipo de destino del enlace a partir de un tipo de origen diferente del valor TemplateSettings.If not, you might need to create a value converter for the binding so that the target type of the binding can be converted from a different source type of the TemplateSettings value. Para obtener más información, consulta IValueConverter.For more info, see IValueConverter.