Classi di impostazioni modelloTemplate settings classes

PrerequisitiPrerequisites

Partiamo dal presupposto che tu sappia aggiungere controlli all'interfaccia utente, impostarne le proprietà e associare gestori eventi.We assume that you can add controls to your UI, set their properties, and attach event handlers. Per istruzioni sull'aggiunta di controlli all'app, vedi Aggiungere controlli e gestire eventi.For instructions for adding controls to your app, see Add controls and handle events. Presumiamo inoltre che tu conosca le tecniche di base per definire un modello personalizzato per un controllo per creare una copia del modello predefinito e 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. Per altre info in merito, vedi Guida introduttiva: Modelli di controllo.For more info on this, see Quickstart: Control templates.

Scenario per le classi TemplateSettingsThe scenario for TemplateSettings classes

Le classi TemplateSettings offrono un set di proprietà usate per definire un nuovo modello di controllo per un controllo.TemplateSettings classes provide a set of properties that are used when you define a new control template for a control. Le proprietà hanno valori come le misure in pixel per le dimensioni di determinate parti dell'elemento dell'interfaccia utente.The properties have values such as pixel measurements for the size of certain UI element parts. I valori sono a volte valori calcolati derivati dalla logica del controllo e in questo caso non è facile eseguirne l'override o persino accedervi.The values are sometimes calculated values that come from control logic that isn't typically easy to override or even access. Alcune delle proprietà sono progettate come valori From e To che controllano le transizioni e le animazioni delle parti, pertanto le proprietà TemplateSettings pertinenti sono in coppia.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.

Esistono varie classi TemplateSettings,There are several TemplateSettings classes. tutte incluse nello spazio dei nomi Windows.UI.Xaml.Controls.Primitives.All of them are in the Windows.UI.Xaml.Controls.Primitives namespace. Ecco un elenco delle classi e un collegamento alla proprietà TemplateSettings del controllo rilevante.Here's a list of the classes, and a link to the TemplateSettings property of the relevant control. Con questa proprietà TemplateSettings puoi accedere ai valori TemplateSettings per il controllo e stabilire i binding del modello alle relative proprietà:This TemplateSettings property is how you access the TemplateSettings values for the control, and can establish template bindings to its properties:

Le proprietà TemplateSettings sono sempre destinate all'uso in XAML, non nel codice.TemplateSettings properties are always intended to be used in XAML, not code. Sono proprietà secondarie di sola lettura di una proprietà TemplateSettings di sola lettura di un controllo padre.They are read-only sub-properties of a read-only TemplateSettings property of a parent control. Per scenari avanzati di uso dei controlli personalizzati, ad esempio quando crei una nuova classe basata su Control e quindi puoi influire sulla logica del controllo, valuta la possibilità di definire una proprietà TemplateSettings personalizzata nel controllo per comunicare info che potrebbero risultare utili per chiunque riutilizzi il modello.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. Come valore di sola lettura per questa proprietà, definisci una nuova classe TemplateSettings correlata al controllo che dispone di proprietà di sola lettura per ogni elemento di informazioni rilevante per le misurazioni del modello, il posizionamento di animazione e così via, quindi fornisci ai chiamanti l'istanza di runtime di tale classe che viene inizializzata con l'uso della logica del tuo controllo.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. Le classi TemplateSettings derivano da DependencyObject, in modo che le proprietà possano usare il sistema di proprietà di dipendenza per i callback di modifica delle proprietà.TemplateSettings classes are derived from DependencyObject, so that the properties can use the dependency property system for property-changed callbacks. Gli identificatori di proprietà di dipendenza per le proprietà non sono però esposti come API pubblica, perché le proprietà TemplateSettings sono pensate per essere di sola lettura per i chiamanti.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.

Come usare TemplateSettings in un modello di controlloHow to use TemplateSettings in a control template

Ecco un esempio tratto dai modelli di controllo XAML predefiniti iniziali.Here's an example that comes from the starting default XAML control templates. Questo particolare è il modello predefinito di 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}"/>

Il codice XAML completo per il modello ProgressRingè composto da centinaia di righe, quindi questo è solo un piccolo estratto.The full XAML for the ProgressRing template is hundreds of lines, so this is just a tiny excerpt. Questo codice XAML definisce una parte di controllo che è uno dei 6 elementi Ellipse che ritraggono l'animazione rotante per lo stato di avanzamento indeterminato.This XAML defines a control part that is one of 6 Ellipse elements that portray the spinning animation for indeterminate progress. Come sviluppatore, potrebbero non piacerti i cerchi e potresti voler usare una primitiva grafica diversa o una diversa forma di base per i vari stati dell'animazione.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. Ad esempio, potresti comporre un ProgressRing che usa un set di elementi Rectangle disposti in un quadrato.For example, you might compose a ProgressRing that uses a set of Rectangle elements arranged in a square instead. In questo caso, ogni singolo componente Rectangle del nuovo modello potrebbe essere simile al seguente: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}"/>

Il motivo per cui le proprietà TemplateSettings sono utili in questo caso è perché sono valori calcolati derivanti dalla logica del controllo di base di ProgressRing.The reason that the TemplateSettings properties are useful here is because they are calculated values coming from the basic control logic of ProgressRing. Il calcolo divide i valori totali di ActualWidth e ActualHeight del controllo ProgressRing e assegna una misura calcolata per ognuno degli elementi dell'animazione nei relativi modelli, in modo che le dimensioni delle parti del modello possano adattarsi al contenuto.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.

Ecco un altro esempio di utilizzo dai modelli di controllo XAML predefiniti. In questo caso illustra uno dei set di proprietà che rappresentano l'origine From e la destinazione To di un'animazione.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. Si tratta del modello predefinito 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>

Anche in questo caso il modello contiene moltissimo codice XAML e ne mostriamo solo un estratto.Again there is lots of XAML in the template so we only show an excerpt. Questo è solo uno dei diversi Stati e animazioni di tema che usano ogni proprietà ComboBoxTemplateSettings .And this is only one of several states and theme animations that each use the same ComboBoxTemplateSettings properties. Per il controllo ComboBox, l'uso dei valori ComboBoxTemplateSettings tramite binding impone che le animazioni correlate nel modello si interrompano e inizino in corrispondenza di posizioni basate su valori condivisi, pertanto le transizioni sono fluide.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    Quando si usano i valori TemplateSettings come parte del modello di controllo, assicurarsi di impostare le proprietà che corrispondono al tipo del valore.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. In caso contrario, potresti dover creare un convertitore di valori per il binding, in modo che il tipo di destinazione del binding possa essere convertito da un tipo di origine diverso dl valore 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. Per altre info, vedi IValueConverter.For more info, see IValueConverter.