Modelos de controleControl templates

Você pode personalizar a estrutura e o comportamento visual de um controle criando um modelo de controle na estrutura XAML.You can customize a control's visual structure and visual behavior by creating a control template in the XAML framework. Os controles têm muitas propriedades, como Background, Foreground, e FontFamily, que você pode definir para especificar diferentes aspectos da aparência do controle.Controls have many properties, such as Background, Foreground, and FontFamily, that you can set to specify different aspects of the control's appearance. Mas as mudanças que você pode fazer ao definir essas propriedades são limitadas.But the changes that you can make by setting these properties are limited. Você pode especificar personalizações adicionais criando um modelo usando a classe ControlTemplate.You can specify additional customizations by creating a template using the ControlTemplate class. Aqui, mostramos a você como criar um ControlTemplate para personalizar a aparência de um controle CheckBox.Here, we show you how to create a ControlTemplate to customize the appearance of a CheckBox control.

APIs importantes : classe ControlTemplate, propriedade Control.TemplateImportant APIs : ControlTemplate class, Control.Template property

Amostra de modelo de controle personalizadoCustom control template example

Por padrão, um controle CheckBox coloca seu conteúdo (a cadeia de caracteres ou o objeto ao lado de CheckBox ) à direita da caixa de seleção, e uma marca de seleção indica que um usuário marcou a CheckBox.By default, a CheckBox control puts its content (the string or object next to the CheckBox ) to the right of the selection box, and a check mark indicates that a user selected the CheckBox. Essas características representam a estrutura e o comportamento visual da CheckBox.These characteristics represent the visual structure and visual behavior of the CheckBox.

Consulte um CheckBox usando o ControlTemplate padrão mostrado nos estados Unchecked, Checked e Indeterminate.Here's a CheckBox using the default ControlTemplate shown in the Unchecked, Checked, and Indeterminate states.

modelo de caixa de seleção padrão

Você pode mudar estas características criando um ControlTemplate para CheckBox.You can change these characteristics by creating a ControlTemplate for the CheckBox. Por exemplo, se você quiser que o conteúdo da caixa de seleção fique abaixo da caixa de seleção e quiser usar um X para indicar que um usuário marcou a caixa de seleção.For example, if you want the content of the check box to be below the selection box, and you want to use an X to indicate that a user selected the check box. Você especifica estas características no ControlTemplate de CheckBox.You specify these characteristics in the ControlTemplate of the CheckBox.

Para usar um modelo personalizado com um controle, você atribui o ControlTemplate à propriedade Template do controle.To use a custom template with a control, assign the ControlTemplate to the Template property of the control. Aqui está uma CheckBox usando um ControlTemplate chamado CheckBoxTemplate1.Here's a CheckBox using a ControlTemplate called CheckBoxTemplate1. Mostramos a linguagem XAML para o ControlTemplate na próxima seção.We show the Extensible Application Markup Language (XAML) for the ControlTemplate in the next section.

<CheckBox Content="CheckBox" Template="{StaticResource CheckBoxTemplate1}" IsThreeState="True" Margin="20"/>

Consulte como este CheckBox fica nos estados Unchecked, Checked, e Indeterminate após aplicarmos o nosso modelo.Here's how this CheckBox looks in the Unchecked, Checked, and Indeterminate states after we apply our template.

modelo personalizado de caixa de seleção

Especificar a estrutura visual de um controleSpecify the visual structure of a control

Ao criar um ControlTemplate, você combina os objetos FrameworkElement para construir um único controle.When you create a ControlTemplate, you combine FrameworkElement objects to build a single control. Um ControlTemplate deve ter apenas um FrameworkElement como seu elemento raiz.A ControlTemplate must have only one FrameworkElement as its root element. O elemento raiz normalmente contém outros objetos FrameworkElement.The root element usually contains other FrameworkElement objects. A combinação dos objetos compõe a estrutura visual do controle.The combination of objects makes up the control's visual structure.

Este XAML cria um ControlTemplate para um CheckBox que especifica que o conteúdo do controle está abaixo da caixa de seleção.This XAML creates a ControlTemplate for a CheckBox that specifies that the content of the control is below the selection box. O elemento da raiz é um Border.The root element is a Border. O exemplo especifica um Path para criar um X que indica que um usuário selecionou o CheckBox e um Ellipse que indica um estado indeterminado.The example specifies a Path to create an X that indicates that a user selected the CheckBox , and an Ellipse that indicates an indeterminate state. Note que o Opacity está definido como 0 no Path e Ellipse de forma que por padrão, nenhum aparece.Note that the Opacity is set to 0 on the Path and the Ellipse so that by default, neither appear.

Um TemplateBinding é uma associação especial que vincula o valor de uma propriedade em um modelo de controle ao valor de outra propriedade exposta no controle de modelo.A TemplateBinding is a special binding that links the value of a property in a control template to the value of some other exposed property on the templated control. TemplateBinding só pode ser usado dentro de uma definição ControlTemplate em XAML.TemplateBinding can only be used within a ControlTemplate definition in XAML. Confira Extensão de marcação TemplateBinding para obter mais informações.See TemplateBinding markup extension for more info.

Observação

Começando com o Windows 10, versão 1809 ( SDK 17763), você pode usar extensões da marcação x:Bind em lugares em que usa TemplateBinding.Starting with Windows 10, version 1809 ( SDK 17763), you can use x:Bind markup extensions in places you use TemplateBinding. Confira Extensão de marcação TemplateBinding para obter mais informações.See TemplateBinding markup extension for more info.

<ControlTemplate x:Key="CheckBoxTemplate1" TargetType="CheckBox">
    <Border BorderBrush="{TemplateBinding BorderBrush}"
            BorderThickness="{TemplateBinding BorderThickness}"
            Background="{TemplateBinding Background}">
        <Grid>
            <Grid.RowDefinitions>
                <RowDefinition Height="*"/>
                <RowDefinition Height="25"/>
            </Grid.RowDefinitions>
            <Rectangle x:Name="NormalRectangle" Fill="Transparent" Height="20" Width="20"
                       Stroke="{ThemeResource SystemControlForegroundBaseMediumHighBrush}"
                       StrokeThickness="{ThemeResource CheckBoxBorderThemeThickness}"
                       UseLayoutRounding="False"/>
            <!-- Create an X to indicate that the CheckBox is selected. -->
            <Path x:Name="CheckGlyph"
                  Data="M103,240 L111,240 119,248 127,240 135,240 123,252 135,264 127,264 119,257 111,264 103,264 114,252 z"
                  Fill="{ThemeResource CheckBoxForegroundThemeBrush}"
                  FlowDirection="LeftToRight"
                  Height="14" Width="16" Opacity="0" Stretch="Fill"/>
            <Ellipse x:Name="IndeterminateGlyph"
                     Fill="{ThemeResource CheckBoxForegroundThemeBrush}"
                     Height="8" Width="8" Opacity="0" UseLayoutRounding="False" />
            <ContentPresenter x:Name="ContentPresenter"
                              ContentTemplate="{TemplateBinding ContentTemplate}"
                              Content="{TemplateBinding Content}"
                              Margin="{TemplateBinding Padding}" Grid.Row="1"
                              HorizontalAlignment="Center"
                              VerticalAlignment="{TemplateBinding VerticalContentAlignment}"/>
        </Grid>
    </Border>
</ControlTemplate>

Especificar o comportamento visual do controleSpecify the visual behavior of a control

Um comportamento visual especifica a aparência de um controle quando ele está em um certo estado.A visual behavior specifies the appearance of a control when it is in a certain state. O controle CheckBox tem três estados de verificação: Checked, Unchecked e Indeterminate.The CheckBox control has 3 check states: Checked, Unchecked, and Indeterminate. O valor da propriedade IsChecked determina o estado de CheckBox e o seu estado determina o que aparece na caixa.The value of the IsChecked property determines the state of the CheckBox , and its state determines what appears in the box.

Esta tabela lista os possíveis valores do IsChecked, os estados correspondentes do CheckBox e a aparência de CheckBox.This table lists the possible values of IsChecked, the corresponding states of the CheckBox, and the appearance of the CheckBox.

Valor IsCheckedIsChecked value Estado da CheckBoxCheckBox state Aparência da CheckBoxCheckBox appearance
truetrue Checked Contém um "X".Contains an "X".
falsefalse Unchecked Vazio.Empty.
nullnull Indeterminate Contém um círculo.Contains a circle.

Você especifica a aparência de um controle quando ele está em um determinado estado usando os objetos VisualState.You specify the appearance of a control when it is in a certain state by using VisualState objects. Um VisualState contém um Setter ou Storyboard que muda a aparência dos elementos no ControlTemplate.A VisualState contains a Setter or Storyboard that changes the appearance of the elements in the ControlTemplate. Quando o controle entra no estado que a propriedade VisualState.Name especifica, as alterações de propriedade no Setter ou Storyboard são aplicadas.When the control enters the state that the VisualState.Name property specifies, the property changes in the Setter or Storyboard are applied. Quando o controle sai do estado, as alterações são removidas.When the control exits the state, the changes are removed. Adicione objetos VisualState aos objetos VisualStateGroup.You add VisualState objects to VisualStateGroup objects. Adicione objetos VisualStateGroup à propriedade VisualStateManager.VisualStateGroups anexada, a qual você definiu na raiz do FrameworkElement do ControlTemplate.You add VisualStateGroup objects to the VisualStateManager.VisualStateGroups attached property, which you set on the root FrameworkElement of the ControlTemplate.

Este XAML mostra os objetos VisualState para os estados Checked, Unchecked e Indeterminate.This XAML shows the VisualState objects for the Checked, Unchecked, and Indeterminate states. O exemplo define a propriedade VisualStateManager.VisualStateGroups anexada no Border, que é o elemento raiz do ControlTemplate.The example sets the VisualStateManager.VisualStateGroups attached property on the Border, which is the root element of the ControlTemplate. O Checked VisualState especifica que a Opacity do Path chamado CheckGlyph (que mostramos no exemplo anterior) é 1.The Checked VisualState specifies that the Opacity of the Path named CheckGlyph (which we show in the previous example) is 1. O Indeterminate VisualState especifica que a Opacity da Ellipse chamada IndeterminateGlyph é 1.The Indeterminate VisualState specifies that the Opacity of the Ellipse named IndeterminateGlyph is 1. O Unchecked VisualState não tem nenhum Setter ou Storyboard e, portanto, a CheckBox volta à aparência padrão.The Unchecked VisualState has no Setter or Storyboard, so the CheckBox returns to its default appearance.

<ControlTemplate x:Key="CheckBoxTemplate1" TargetType="CheckBox">
    <Border BorderBrush="{TemplateBinding BorderBrush}"
            BorderThickness="{TemplateBinding BorderThickness}"
            Background="{TemplateBinding Background}">

        <VisualStateManager.VisualStateGroups>
            <VisualStateGroup x:Name="CheckStates">
                <VisualState x:Name="Checked">
                    <VisualState.Setters>
                        <Setter Target="CheckGlyph.Opacity" Value="1"/>
                    </VisualState.Setters>
                    <!-- This Storyboard is equivalent to the Setter. -->
                    <!--<Storyboard>
                        <DoubleAnimation Duration="0" To="1"
                         Storyboard.TargetName="CheckGlyph" Storyboard.TargetProperty="Opacity"/>
                    </Storyboard>-->
                </VisualState>
                <VisualState x:Name="Unchecked"/>
                <VisualState x:Name="Indeterminate">
                    <VisualState.Setters>
                        <Setter Target="IndeterminateGlyph.Opacity" Value="1"/>
                    </VisualState.Setters>
                    <!-- This Storyboard is equivalent to the Setter. -->
                    <!--<Storyboard>
                        <DoubleAnimation Duration="0" To="1"
                         Storyboard.TargetName="IndeterminateGlyph" Storyboard.TargetProperty="Opacity"/>
                    </Storyboard>-->
                </VisualState>
            </VisualStateGroup>
        </VisualStateManager.VisualStateGroups>

        <Grid>
            <Grid.RowDefinitions>
                <RowDefinition Height="*"/>
                <RowDefinition Height="25"/>
            </Grid.RowDefinitions>
            <Rectangle x:Name="NormalRectangle" Fill="Transparent" Height="20" Width="20"
                       Stroke="{ThemeResource SystemControlForegroundBaseMediumHighBrush}"
                       StrokeThickness="{ThemeResource CheckBoxBorderThemeThickness}"
                       UseLayoutRounding="False"/>
            <!-- Create an X to indicate that the CheckBox is selected. -->
            <Path x:Name="CheckGlyph"
                  Data="M103,240 L111,240 119,248 127,240 135,240 123,252 135,264 127,264 119,257 111,264 103,264 114,252 z"
                  Fill="{ThemeResource CheckBoxForegroundThemeBrush}"
                  FlowDirection="LeftToRight"
                  Height="14" Width="16" Opacity="0" Stretch="Fill"/>
            <Ellipse x:Name="IndeterminateGlyph"
                     Fill="{ThemeResource CheckBoxForegroundThemeBrush}"
                     Height="8" Width="8" Opacity="0" UseLayoutRounding="False" />
            <ContentPresenter x:Name="ContentPresenter"
                              ContentTemplate="{TemplateBinding ContentTemplate}"
                              Content="{TemplateBinding Content}"
                              Margin="{TemplateBinding Padding}" Grid.Row="1"
                              HorizontalAlignment="Center"
                              VerticalAlignment="{TemplateBinding VerticalContentAlignment}"/>
        </Grid>
    </Border>
</ControlTemplate>

Para entender melhor como os objetos VisualState funcionam, considere o que ocorre quando CheckBox vai do estado Unchecked ao estado Checked e, em seguida, ao estado Indeterminate e, em seguida, de volta ao estado Unchecked.To better understand how VisualState objects work, consider what happens when the CheckBox goes from the Unchecked state to the Checked state, then to the Indeterminate state, and then back to the Unchecked state. Estes são as transições:Here are the transitions.

Transição de estadoState transition O que ocorreWhat happens Aparência da caixa de seleção quando a transição completaCheckBox appearance when the transition completes
De Unchecked a Checked.From Unchecked to Checked. O valor Setter do Checked VisualState é aplicado e, portanto, a Opacity de CheckGlyph é 1.The Setter value of the Checked VisualState is applied, so the Opacity of CheckGlyph is 1. Um X é exibido.An X is displayed.
De Checked a Indeterminate.From Checked to Indeterminate. O valor Setter do Indeterminate VisualState é aplicado e, portanto, a Opacity de IndeterminateGlyph é 1.The Setter value of the Indeterminate VisualState is applied, so the Opacity of IndeterminateGlyph is 1. O valor Setter do Checked VisualState é removido e, portanto, a Opacity de CheckGlyph é 0.The Setter value of the Checked VisualState is removed, so the Opacity of CheckGlyph is 0. Um círculo é exibido.A circle is displayed.
De Indeterminate a Unchecked.From Indeterminate to Unchecked. O valor Setter do Indeterminate VisualState é removido e, portanto, a Opacity de IndeterminateGlyph é 0.The Setter value of the Indeterminate VisualState is removed, so the Opacity of IndeterminateGlyph is 0. Nada é exibido.Nothing is displayed.

Para saber mais sobre como criar estados visuais para controles e, em especial, como usar a classe Storyboard e os tipos de animação, consulte Animações de storyboard para estados visuais.For more info about how to create visual states for controls, and in particular how to use the Storyboard class and the animation types, see Storyboarded animations for visual states.

Use as ferramentas para trabalhar com os temas facilmenteUse tools to work with themes easily

Uma forma rápida de aplicar temas aos seus controles é clicar com o botão direito em um controle no Estrutura de Tópicos do Documento do Microsoft Visual Studio e selecionar Editar Tema ou Editar Estilo (dependendo do controle no qual você está clicando com o botão direito).A fast way to apply themes to your controls is to right-click on a control on the Microsoft Visual Studio Document Outline and select Edit Theme or Edit Style (depending on the control you are right-clicking on). Em seguida, você pode aplicar um tema existente selecionando Aplicar Recurso ou excluir um novo selecionando Criar Vazio.You can then apply an existing theme by selecting Apply Resource or define a new one by selecting Create Empty.

Controles e acessibilidadeControls and accessibility

Ao criar um novo modelo de controle, além da possibilidade de mudar o comportamento e a aparência visual do controle, você também pode alterar como o controle se representa nas estruturas de acessibilidade.When you create a new template for a control, in addition to possibly changing the control's behavior and visual appearance, you might also be changing how the control represents itself to accessibility frameworks. O aplicativo do Windows é compatível com a estrutura de Automação da Interface do Usuário da Microsoft para acessibilidade.The Windows app supports the Microsoft UI Automation framework for accessibility. Todos os controles padrão e seus modelos permitem tipos e padrões comuns de controle de Automação da Interface do Usuário adequados para a finalidade e a função do controle.All of the default controls and their templates have support for common UI Automation control types and patterns that are appropriate for the control's purpose and function. Esses tipos e padrões de controle são interpretados por clientes de Automação da Interface do Usuário, como tecnologias adaptativas, permitindo acessar um controle como parte de uma interface do usuário de aplicativo acessível maior.These control types and patterns are interpreted by UI Automation clients such as assistive technologies, and this enables a control to be accessible as a part of a larger accessible app UI.

Para separar a lógica de controle básica e também atender a alguns requisitos de arquitetura da Automação da Interface do Usuário, as classes de controle incluem o suporte para acessibilidade em uma classe separada, um par de automação.To separate the basic control logic and also to satisfy some of the architectural requirements of UI Automation, control classes include their accessibility support in a separate class, an automation peer. Os pares de automação às vezes têm interações com os modelos de controle, pois os pares esperam que existam determinadas partes nomeadas nos modelos para que funcionalidades, como a habilitação de tecnologias adaptativas, possam invocar as ações dos botões.The automation peers sometimes have interactions with the control templates because the peers expect certain named parts to exist in the templates, so that functionality such as enabling assistive technologies to invoke actions of buttons is possible.

Ao criar um controle personalizado completamente novo, convém também criar um novo par de automação para trabalhar com ele.When you create a completely new custom control, you sometimes also will want to create a new automation peer to go along with it. Para obter mais informações, consulte Pares de automação personalizados.For more info, see Custom automation peers.

Saiba mais sobre o modelo padrão de um controleLearn more about a control's default template

Os tópicos que documentam os estilos e modelos dos controles de XAML mostram trechos do mesmo XAML inicial que você veria se usasse as técnicas Editar Tema ou Editar Estilo explicadas anteriormente.The topics that document the styles and templates for XAML controls show you excerpts of the same starting XAML you'd see if you used the Edit Theme or Edit Style techniques explained previously. Cada tópico lista os nomes dos estados visuais, os recursos de temas usados e o XAML completo para o estilo que contém o modelo.Each topic lists the names of the visual states, the theme resources used, and the full XAML for the style that contains the template. Os tópicos podem ser diretrizes úteis se você já começou a modificar um modelo e quer ver qual era a aparência do modelo original ou verificar se o novo modelo tem todos os estados visuais nomeados obrigatórios.The topics can be useful guidance if you've already started modifying a template and want to see what the original template looked like, or to verify that your new template has all of the required named visual states.

Recursos de tema em modelos de controleTheme resources in control templates

Para alguns dos atributos nos exemplos de XAML, você pode ter percebido referências de recursos que usam a extensão de marcação {ThemeResource}.For some of the attributes in the XAML examples, you may have noticed resource references that use the {ThemeResource} markup extension. Essa é uma técnica que permite que um único modelo de controle use recursos que podem ser valores diferentes dependendo de qual tema está ativo no momento.This is a technique that enables a single control template to use resources that can be different values depending on which theme is currently active. Isso é particularmente importante para pincéis e cores, porque a finalidade principal dos temas é permitir que os usuários escolham se querem um tema de contraste escuro, claro ou alto aplicado ao sistema como um todo.This is particularly important for brushes and colors, because the main purpose of the themes is to enable users to choose whether they want a dark, light, or high contrast theme applied to the system overall. Os aplicativos que usam o sistema de recursos de XAML podem usar um conjunto de recursos apropriado para esse tema, de maneira que as escolhas de tema na interface do usuário de um aplicativo reflitam a escolha de tema em todo o sistema feita pelo usuário.Apps that use the XAML resource system can use a resource set that's appropriate for that theme, so that the theme choices in an app's UI are reflective of the user's systemwide theme choice.

Obter o código de exemploGet the sample code