Стили XAML

2025-04-30

Вы можете настроить внешний вид приложений различными способами с помощью платформы XAML. Стили позволяют задавать свойства элемента управления и повторно использовать эти параметры для согласованного внешнего вида в нескольких элементах управления.

WinUI и стили

Начиная с WinUI 2.2, мы использовали WinUI для доставки новых обновлений визуального стиля в компонентах пользовательского интерфейса. Если пользовательский интерфейс не обновляется до последних стилей, обязательно обновите его до последнего пакета NuGet WinUI.

Начиная с WinUI 2.6, мы предоставляем новые стили для большинства элементов управления и новую систему управления версиями, которая позволяет вернуться к предыдущим стилям элементов управления при необходимости. Мы рекомендуем использовать новые стили, так как они лучше соответствуют направлению дизайна Windows. Однако если сценарий не может поддерживать новые стили, предыдущие версии по-прежнему доступны.

Вы можете изменить версию стиля, изменив свойство ControlsResourcesVersion в XamlControlsResources, которое вы добавляете в Application.Resources, когда вы используете WinUI версии 2. ControlsResourcesVersion по умолчанию использует перечислимое значение Version2.

Если установить значение Version1, это приведет к тому, что XamlControlsResources будет загружать предыдущие версии стилей вместо новых, используемых в последней версии WinUI. Изменение этого свойства во время выполнения не поддерживается, и функция горячей перезагрузки VisualStudio не будет работать; Однако после перестроения приложения вы увидите изменения стилей элементов управления.

<Application.Resources>
    <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" 
                           ControlsResourcesVersion="Version1"/>
</Application.Resources>

Основы стиля

Используйте стили для извлечения параметров визуальных свойств в повторно используемые ресурсы. Пример ниже демонстрирует 3 кнопки со стилем, который задает свойства BorderBrush, BorderThickness и Foreground. Применяя стиль, можно сделать элементы управления одинаковыми, не устанавливая эти свойства для каждого элемента управления отдельно.

Снимок экрана трех стилизованных кнопок, расположенных бок о бок.

Вы можете определить встроенный стиль в XAML для элемента управления или как повторно используемый ресурс. Определите ресурсы в XAML-файле отдельной страницы в файле App.xaml или в отдельном файле XAML словаря ресурсов. Файл XAML словаря ресурсов можно совместно использовать для приложений, а несколько словарей ресурсов можно объединить в одном приложении. Где определяется ресурс, определяет область, в которой ее можно использовать. Ресурсы уровня страницы доступны только на странице, в которой они определены. Если ресурсы с одинаковым ключом определены как в App.xaml, так и на странице, ресурс на странице переопределяет ресурс в App.xaml. Если ресурс определен в отдельном файле словаря ресурсов, его область определяется тем, где ссылается словарь ресурсов.

В определении стиля требуется атрибут TargetType вместе с коллекцией одного или нескольких элементов Setter. Атрибут TargetType — это строка, указывающая тип FrameworkElement для применения стиля. Значение TargetType должно указывать производный от FrameworkElement тип, который определяется средой выполнения Windows или пользовательским типом, доступным в указанной сборке. Если вы пытаетесь применить стиль к элементу управления, а тип элемента управления не соответствует атрибуту TargetType стиля, которое вы пытаетесь применить, возникает исключение.

Для каждого элемента setter требуется Свойство и Значение. Эти параметры свойств указывают, к какому свойству элемента управления применяется установка, и какое значение нужно задать для этого свойства. Можно задать Setter.Value с синтаксисом атрибута или элемента свойства. В XAML здесь показан стиль, применяемый к кнопкам, показанным ранее. В этом XAML первые два элемента Setter используют синтаксис атрибутов, но последний метод Setter для свойства BorderBrush использует синтаксис элемента свойства. В примере не используется атрибут x:Key атрибут, поэтому стиль неявно применяется к кнопкам. Применение стилей неявно или явно описано в следующем разделе.

<Page.Resources>
    <Style TargetType="Button">
        <Setter Property="BorderThickness" Value="5" />
        <Setter Property="Foreground" Value="Black" />
        <Setter Property="BorderBrush" >
            <Setter.Value>
                <LinearGradientBrush StartPoint="0.5,0" EndPoint="0.5,1">
                    <GradientStop Color="Yellow" Offset="0.0" />
                    <GradientStop Color="Red" Offset="0.25" />
                    <GradientStop Color="Blue" Offset="0.75" />
                    <GradientStop Color="LimeGreen" Offset="1.0" />
                </LinearGradientBrush>
            </Setter.Value>
        </Setter>
    </Style>
</Page.Resources>

<StackPanel Orientation="Horizontal">
    <Button Content="Button"/>
    <Button Content="Button"/>
    <Button Content="Button"/>
</StackPanel>

Применение неявного или явного стиля

Если вы определяете стиль как ресурс, к элементам управления можно применить два способа:

Неявно, указав только TargetType для стиля.
Явно укажите атрибут TargetType и атрибут x:Key для Style, а затем установите свойство Style целевого элемента управления с расширением разметки {StaticResource}, использующую явный ключ.

Если стиль содержит атрибут x:Key, его можно применить только к элементу управления, задав свойство Style элемента управления на стиль с ключом. В отличие от этого, стиль без атрибута x:Key автоматически применяется к каждому элементу управления его целевого типа, который в противном случае не имеет явного параметра стиля.

Ниже приведены две кнопки, демонстрирующие неявные и явные стили.

стилизованные кнопки с неявным и явным стилями.

В этом примере первый стиль имеет атрибут x:Key, а его целевой тип — Button. Для свойства стиля первой кнопки задано значение этого ключа, поэтому этот стиль применяется явным образом. Второй стиль применяется неявно ко второй кнопке, так как его целевой тип — Button , а стиль не имеет атрибута x:Key.

<Page.Resources>
    <Style x:Key="PurpleStyle" TargetType="Button">
        <Setter Property="FontFamily" Value="Segoe UI"/>
        <Setter Property="FontSize" Value="14"/>
        <Setter Property="Foreground" Value="Purple"/>
    </Style>

    <Style TargetType="Button">
        <Setter Property="FontFamily" Value="Segoe UI"/>
        <Setter Property="FontSize" Value="14"/>
        <Setter Property="RenderTransform">
            <Setter.Value>
                <RotateTransform Angle="25"/>
            </Setter.Value>
        </Setter>
        <Setter Property="BorderBrush" Value="Green"/>
        <Setter Property="BorderThickness" Value="2"/>
        <Setter Property="Foreground" Value="Green"/>
    </Style>
</Page.Resources>

<Grid x:Name="LayoutRoot">
    <Button Content="Button" Style="{StaticResource PurpleStyle}"/>
    <Button Content="Button"/>
</Grid>

Использование стилей на основе других

Чтобы упростить обслуживание стилей и оптимизировать повторное использование стилей, можно создавать стили, наследуемые от других стилей. Свойство BasedOn используется для создания унаследованных стилей. Стили, наследуемые от других стилей, должны нацелены на тот же тип элемента управления или элемент управления, производный от типа, предназначенного для базового стиля. Например, если базовый стиль предназначен для ContentControl, стили, основанные на этом стиле, могут использовать ContentControl или типы, производные от ContentControl, такие как кнопка и ScrollViewer. Если значение не задано в стиле на основе, оно наследуется от базового стиля. Чтобы изменить значение основного стиля, стиль, основанный на нём, переопределяет это значение. В следующем примере показана кнопка и флажок со стилями, наследующими от одного базового стиля.

кнопки, стилизованные на основе стилей.

Базовый стиль нацелен на ContentControlи задает свойства высотыи ширины. Стили, основанные на этом стиле, нацелены на CheckBox и Button, которые происходят от ContentControl. На основе стилей задаются различные цвета для свойств BorderBrush и переднего плана. (Обычно границу вокруг checkBox не помещают. Мы делаем это здесь, чтобы показать эффекты стиля.)

<Page.Resources>
    <Style x:Key="BasicStyle" TargetType="ContentControl">
        <Setter Property="Width" Value="130" />
        <Setter Property="Height" Value="30" />
    </Style>

    <Style x:Key="ButtonStyle" TargetType="Button"
           BasedOn="{StaticResource BasicStyle}">
        <Setter Property="BorderBrush" Value="Orange" />
        <Setter Property="BorderThickness" Value="2" />
        <Setter Property="Foreground" Value="Red" />
    </Style>

    <Style x:Key="CheckBoxStyle" TargetType="CheckBox"
           BasedOn="{StaticResource BasicStyle}">
        <Setter Property="BorderBrush" Value="Blue" />
        <Setter Property="BorderThickness" Value="2" />
        <Setter Property="Foreground" Value="Green" />
    </Style>
</Page.Resources>

<StackPanel>
    <Button Content="Button" Style="{StaticResource ButtonStyle}" Margin="0,10"/>
    <CheckBox Content="CheckBox" Style="{StaticResource CheckBoxStyle}"/>
</StackPanel>

Используйте средства для легкой работы со стилями.

Быстрый способ применить стили к элементам управления — щелкнуть правой кнопкой мыши элемент управления в области конструктора XAML Microsoft Visual Studio и выбрать пункт "Изменить стиль " или " Изменить шаблон " (в зависимости от элемента управления, который вы щелкаете правой кнопкой мыши). Затем можно применить существующий стиль, выбрав Применить стиль или определить новый стиль, выбрав Создать пустой. Если вы создаете пустой стиль, вы можете определить его на странице, в файле App.xaml или в отдельном словаре ресурсов.

Облегченная стилизация

Переопределение системных кистей обычно выполняется на уровне приложения или страницы, и в любом случае переопределение цвета повлияет на все элементы управления, ссылающиеся на кисть, и в XAML многие элементы управления могут ссылаться на одну и ту же системную кисть.

<Page.Resources>
    <ResourceDictionary>
        <ResourceDictionary.ThemeDictionaries>
            <ResourceDictionary x:Key="Light">
                 <SolidColorBrush x:Key="ButtonBackground" Color="Transparent"/>
                 <SolidColorBrush x:Key="ButtonForeground" Color="MediumSlateBlue"/>
                 <SolidColorBrush x:Key="ButtonBorderBrush" Color="MediumSlateBlue"/>
            </ResourceDictionary>
        </ResourceDictionary.ThemeDictionaries>
    </ResourceDictionary>
</Page.Resources>

Для таких состояний, как PointerOver (наведите указатель мыши на кнопку), PointerPressed (кнопка вызвана) или отключена (кнопка не взаимодействует). Эти окончания добавляются в исходные имена упрощенной стилизации: ButtonBackgroundPointerOver, ButtonForegroundPressed, ButtonBorderBrushDisabledи т. д. Изменение этих кистей также обеспечит согласованность цвета элементов управления в теме вашего приложения.

Переопределение этих кистей на уровне App.Resources изменит внешний вид всех кнопок во всем приложении, а не только на одной странице.

Стилизация каждого элемента управления

В других случаях изменение одного элемента управления на одной странице только для определенного вида без изменения других версий этого элемента управления требуется:

снимок экрана трёх стилизованных кнопок, расположенных одна над другой.

<CheckBox Content="Normal CheckBox" Margin="5"/>
<CheckBox Content="Special CheckBox" Margin="5">
    <CheckBox.Resources>
        <ResourceDictionary>
            <ResourceDictionary.ThemeDictionaries>
                <ResourceDictionary x:Key="Light">
                    <SolidColorBrush x:Key="CheckBoxForegroundUnchecked"
                        Color="Purple"/>
                    <SolidColorBrush x:Key="CheckBoxForegroundChecked"
                        Color="Purple"/>
                    <SolidColorBrush x:Key="CheckBoxCheckGlyphForegroundChecked"
                        Color="White"/>
                    <SolidColorBrush x:Key="CheckBoxCheckBackgroundStrokeChecked"  
                        Color="Purple"/>
                    <SolidColorBrush x:Key="CheckBoxCheckBackgroundFillChecked"
                        Color="Purple"/>
                </ResourceDictionary>
            </ResourceDictionary.ThemeDictionaries>
        </ResourceDictionary>
    </CheckBox.Resources>
</CheckBox>
<CheckBox Content="Normal CheckBox" Margin="5"/>

Это будет влиять только на один элемент управления "Специальный флажок" на странице, где существует этот элемент управления.

Пользовательские элементы управления

При создании собственных пользовательских элементов управления, которые могут быть визуально и (или) функционально согласованы со встроенными элементами управления, рекомендуется использовать неявные ресурсы стилей и упрощенных стилей для определения пользовательского содержимого. Вы можете использовать ресурсы напрямую или создать новый псевдоним для ресурса.

Использование ресурсов управления напрямую

Например, если вы пишете элемент управления, который выглядит как Кнопка, вы можете ссылаться на ресурсы кнопки напрямую, как показано ниже.

<Style TargetType="local:MyCustomControl">
  <Setter Property="Background" Value="{ThemeResource ButtonBackground}" />
  <Setter Property="BorderBrush" Value="{ThemeResource ButtonBorderBrush}" />
</Style>

Присвоение контрольным ресурсам новых псевдонимов

Кроме того, если вы предпочитаете создавать собственные ресурсы, следует псевдонимировать эти пользовательские имена для наших ресурсов упрощенного стиля по умолчанию.

Например, стиль вашего пользовательского элемента управления может иметь специальные определения ресурсов.

<Style TargetType="local:MyCustomControl">
  <Setter Property="Background" Value="{ThemeResource MyCustomControlBackground}" />
  <Setter Property="BorderBrush" Value="{ThemeResource MyCustomControlBorderBrush}"/>
</Style>

В словаре ресурсов или главном определении можно подключить ресурсы упрощенного стиля к пользовательским:

<ResourceDictionary.ThemeDictionaries>
    <ResourceDictionary x:Key="Default">
        <StaticResource x:Key="MyCustomControlBackground" ResourceKey="ButtonBackground" />
        <StaticResource x:Key="MyCustomControlBorderBrush" ResourceKey="ButtonBorderBrush" />
    </ResourceDictionary>        
    <ResourceDictionary x:Key="Light">
        <StaticResource x:Key="MyCustomControlBackground" ResourceKey="ButtonBackground" />
        <StaticResource x:Key="MyCustomControlBorderBrush" ResourceKey="ButtonBorderBrush" />
    </ResourceDictionary>
    <ResourceDictionary x:Key="HighContrast">
        <StaticResource x:Key="MyCustomControlBackground" ResourceKey="ButtonBackground" />
        <StaticResource x:Key="MyCustomControlBorderBrush" ResourceKey="ButtonBorderBrush" />
    </ResourceDictionary>
</ResourceDictionary.ThemeDictionaries>

Требуется использовать ThemeDictionary, дублируемый три раза, чтобы правильно обработать три различных изменения темы (Default, Light, HighContrast).

Осторожность

Если вы назначаете ресурс упрощенной стилизации новому псевдониму, а также переопределяете ресурс упрощенного стиля, настройка может не применяться, если поиск ресурсов не соответствует правильному порядку. Например, в случае, если переопределить ButtonBackground в месте, которое находится до того, как будет найден MyCustomControlBackground, переопределение будет пропущено.

Избегайте изменения стиля элементов управления

WinUI 2.2 или более поздней версии включает новые стили и шаблоны для элементов управления WinUI и системы.

Лучший способ оставаться в курсе наших последних визуальных стилей — использовать последний пакет WinUI 2 и избегать пользовательских стилей и шаблонов (также известных как повторное шаблонирование). Стили по-прежнему удобно применять набор значений последовательно между элементами управления в приложении. При этом обязательно следуйте нашим последним стилям.

Для системных элементов управления, использующих стили WinUI (Windows.UI.Xaml.Controls пространство имен), укажите BasedOn="{StaticResource Default<ControlName>Style}", где <ControlName> — это имя элемента управления. Рассмотрим пример.

<Style TargetType="TextBox" BasedOn="{StaticResource DefaultTextBoxStyle}">
    <Setter Property="Foreground" Value="Blue"/>
</Style>

Для элементов управления WinUI 2 (Microsoft.UI.Xaml.Controls пространство имен) стиль по умолчанию определяется в метаданных, поэтому опустите BasedOn его.

Производные элементы управления

Если вы создаёте программный элемент управления на основе существующего элемента управления XAML, по умолчанию он не будет использовать стили WinUI 2. Чтобы применить стили WinUI 2, выполните следующие действия.

Создайте новый стиль , установив для его TargetType ваш пользовательский элемент управления.
На основе стиля по умолчанию производного элемента управления.

Один из распространенных сценариев заключается в том, чтобы получить новый элемент управления из ContentDialog. В этом примере показано, как создать новый стиль, который будет применяться DefaultContentDialogStyle к вашему пользовательскому диалогу.

<ContentDialog
    x:Class="ExampleApp.SignInContentDialog"
    ... >

    <ContentDialog.Resources>
        <Style TargetType="local:SignInContentDialog" BasedOn="{StaticResource DefaultContentDialogStyle}"/>
        ...
    </ContentDialog.Resources> 
    <!-- CONTENT -->
</ContentDialog>

Свойство шаблона

Средство задания стиля можно использовать для свойства шаблона элемента управления, и на самом деле это составляет большинство типичных стилей XAML и ресурсов XAML приложения. Это подробно рассматривается в разделе шаблонов элементов управления.