Ресурсы темы XAML

Ресурсы темы в XAML — это набор ресурсов, которые применяют разные значения в зависимости от того, какая системная тема активна. Существует 3 темы, поддерживаемые платформой XAML: Light, Dark и HighContrast.

Предварительные требования. В этом разделе предполагается, что у вас есть ссылки на ресурсы ResourceDictionary и XAML.

Ресурсы темы v. статические ресурсы

Существует два расширения разметки XAML, которые могут ссылаться на ресурс XAML из существующего словаря ресурсов XAML: расширение разметки {StaticResource} и расширение разметки {ThemeResource}.

Оценка расширения разметки {ThemeResource} возникает при загрузке приложения и последующем каждом изменении темы во время выполнения. Обычно это результат изменения параметров устройства или программного изменения в приложении, которое изменяет текущую тему.

Напротив, расширение разметки {StaticResource} вычисляется только при первой загрузке XAML приложением. Он не обновляется. Он аналогичен поиску и замене в XAML фактическим значением среды выполнения при запуске приложения.

Ресурсы темы в структуре словаря ресурсов

Каждый ресурс темы является частью файла XAML fileresources.xaml. В целях разработки themeresources.xaml доступен в папке \(Program Files)\Windows Kits\10\DesignTime\CommonConfiguration\Neutral\UAP\<SDK version>\Generic из установки пакета SDK для Windows. Словари ресурсов в themeresources.xaml также воспроизводится в generic.xaml в том же каталоге.

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

Рекомендации по пользовательским ресурсам темы

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

• Укажите словари тем для "Light" и "Dark" в дополнение к словарю HighContrast. Хотя вы можете создать ResourceDictionary с параметром Default в качестве ключа, предпочтительнее быть явным и вместо этого использовать "Light", "Dark" и "HighContrast".

• Используйте расширение разметки {ThemeResource} в: стили, наборы элементов управления, шаблоны элементов управления, методы задания свойств и анимации.

• Не используйте расширение разметки {ThemeResource} в определениях ресурсов внутри themeDictionaries. Вместо этого используйте расширение разметки {StaticResource} .

  ИСКЛЮЧЕНИЕ. Расширение разметки {ThemeResource} можно использовать для ссылки на ресурсы, которые не зависят от темы приложения в ThemeDictionaries. Примерами этих ресурсов являются ресурсы цвета акцента, такие как SystemAccentColorили системные цветовые ресурсы, которые обычно префиксируются с помощью SystemColor SystemColorButtonFaceColor.

Цветовая рампа XAML и кисти, зависящие от темы

Объединенный набор цветов для тем "Свет", "Темный" и "HighContrast" составляют цветовую рампу Windows в XAML. Следует ли изменить системные темы или применить тему к собственным элементам XAML, важно понять, как структурированы цветовые ресурсы.

Дополнительные сведения о применении цвета в приложении Windows см. в разделе "Цвет" в приложениях Windows.

Цвета светлой и темной темы

Платформа XAML предоставляет набор именованных ресурсов Color с значениями, адаптированными для тем "Свет" и "Темная". Для WinUI 2 ресурсы темы определяются в файле Xaml общих ресурсов темы. Имена цветов очень описательные для их предполагаемого использования, и для каждого ресурса Color есть соответствующий ресурс SolidColorBrush.

Приложение коллекции WinUI 3 включает интерактивные примеры большинства элементов управления, функций и функций WinUI 3. Получение приложения из Microsoft Store или получение исходного кода на GitHub

Цвета темы контрастности системы Windows

Помимо набора ресурсов, предоставляемых платформой XAML, существует набор значений цвета, производных от системной палитры Windows. Эти цвета не относятся к приложениям среды выполнения Windows или Windows. Однако многие из ресурсов кисти XAML используют эти цвета, если система работает (и приложение работает) с помощью темы HighContrast. Платформа XAML предоставляет эти системные цвета в качестве ключевых ресурсов. Ключи соответствуют формату именования: SystemColor[name]Color

Дополнительные сведения о поддержке тем контрастности см. в разделе "Темы контрастности".

Цвет системного акцента

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

Кисти, зависящие от темы

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

Давайте рассмотрим, как значение цвета для этой кисти определяется во время выполнения. В словарях ресурсов Light и Dark эта кисть определяется следующим образом:

<SolidColorBrush x:Key="TextFillColorPrimaryBrush" Color="{StaticResource TextFillColorPrimary}"/>

В словаре ресурсов HighContrast эта кисть определяется следующим образом:

<SolidColorBrush x:Key="TextFillColorPrimaryBrush" Color="{ThemeResource SystemColorWindowTextColor}"/>

Если эта кисть применяется к элементу XAML, его цвет определяется во время выполнения текущей темой, как показано в этой таблице.

Пандус типа XAML

Файл themeresources.xaml определяет несколько ресурсов, определяющих стиль , который можно применить к текстовым контейнерам в пользовательском интерфейсе, в частности для TextBlock или RichTextBlock. Это неявные стили по умолчанию. Они предоставляются для упрощения создания определений пользовательского интерфейса XAML, которые соответствуют пандусу типа Windows , документированному в рекомендациях по шрифтам.

Эти стили предназначены для текстовых атрибутов, которые необходимо применить ко всему текстовому контейнеру. Если вы хотите применить стили только к разделам текста, задайте атрибуты для текстовых элементов в контейнере, например в файле Run in TextBlock.Inlines или абзаце в RichTextBlock.Blocks.

Стили выглядят следующим образом при применении к TextBlock:

<TextBlock Text="Caption" Style="{StaticResource CaptionTextBlockStyle}"/>
<TextBlock Text="Body" Style="{StaticResource BodyTextBlockStyle}"/>
<TextBlock Text="Body Strong" Style="{StaticResource BodyStrongTextBlockStyle}"/>
<TextBlock Text="Body Large" Style="{StaticResource BodyLargeTextBlockStyle}"/>
<TextBlock Text="Subtitle" Style="{StaticResource SubtitleTextBlockStyle}"/>
<TextBlock Text="Title" Style="{StaticResource TitleTextBlockStyle}"/>
<TextBlock Text="Title Large" Style="{StaticResource TitleLargeTextBlockStyle}"/>
<TextBlock Text="Display" Style="{StaticResource DisplayTextBlockStyle}"/>

Инструкции по использованию пандуса типов Windows в приложении см. в разделе "Типография" в приложениях Windows.

Дополнительные сведения о стилях XAML см. в статье WinUI на сайте GitHub:

• Заголовок TextBlockStyle
• Body TextBlockStyle
• Body Strong TextBlockStyle

• Подзаголовок TextBlockStyle
• Title TextBlockStyle
• Заголовок Large TextBlockStyle
• Отображение TextBlockStyle

BaseRichTextBlockStyle

TargetType: RichTextBlock

Предоставляет общие свойства для всех других стилей контейнеров RichTextBlock .

<!-- Usage -->
<RichTextBlock Style="{StaticResource BaseRichTextBlockStyle}">
    <Paragraph>Rich text.</Paragraph>
</RichTextBlock>

<!-- Style definition -->
<Style x:Key="BaseRichTextBlockStyle" TargetType="RichTextBlock">
    <Setter Property="FontFamily" Value="Segoe UI"/>
    <Setter Property="FontWeight" Value="SemiBold"/>
    <Setter Property="FontSize" Value="14"/>
    <Setter Property="TextTrimming" Value="None"/>
    <Setter Property="TextWrapping" Value="Wrap"/>
    <Setter Property="LineStackingStrategy" Value="MaxHeight"/>
    <Setter Property="TextLineBounds" Value="Full"/>
    <Setter Property="OpticalMarginAlignment" Value="TrimSideBearings"/>
</Style>

BodyRichTextBlockStyle

<!-- Usage -->
<RichTextBlock Style="{StaticResource BodyRichTextBlockStyle}">
    <Paragraph>Rich text.</Paragraph>
</RichTextBlock>

<!-- Style definition -->
<Style x:Key="BodyRichTextBlockStyle" TargetType="RichTextBlock" BasedOn="{StaticResource BaseRichTextBlockStyle}">
    <Setter Property="FontWeight" Value="Normal"/>
</Style>

Примечание. Стили RichTextBlock не имеют всех стилей настроек текста, которые выполняет TextBlock , в основном потому, что объектная модель документа на основе блоков для RichTextBlock упрощает настройку атрибутов для отдельных текстовых элементов. Кроме того, при настройке TextBlock.Text с помощью свойства содержимого XAML возникает ситуация, в которой отсутствует текстовый элемент для стиля, поэтому вам придется стиль контейнера. Это не проблема для RichTextBlock , так как его текстовое содержимое всегда должно находиться в определенных текстовых элементах, таких как Абзац, где можно применять стили XAML для заголовка страницы, подзаголовки страницы и аналогичных определений текстового пандуса.

Другие стили именованных именованных элементов

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

NavigationBackButtonNormalStyle

TargetType: Button

Этот стиль предоставляет полный шаблон для кнопки , которая может быть кнопкой назад навигации для приложения навигации. Размеры по умолчанию — 40 x 40 пикселей. Чтобы настроить стили, вы можете явно задать высоту, ширину, шрифтSize и другие свойства на кнопке или создать производный стиль с помощью BasedOn.

Вот кнопка с ресурсом NavigationBackButtonNormalStyle , примененным к нему.

<Button Style="{StaticResource NavigationBackButtonNormalStyle}" />

Он будет выглядеть примерно так:

NavigationBackButtonSmallStyle

TargetType: Button

Этот стиль предоставляет полный шаблон для кнопки , которая может быть кнопкой назад навигации для приложения навигации. Он похож на NavigationBackButtonNormalStyle, но его размеры составляют 30 x 30 пикселей.

Вот кнопка с ресурсом NavigationBackButtonSmallStyle , примененным к нему.

<Button Style="{StaticResource NavigationBackButtonSmallStyle}" />

Устранение неполадок с ресурсами темы

Если вы не следуйте рекомендациям по использованию ресурсов темы, в приложении может появиться непредвиденное поведение, связанное с темами.

Например, при открытии всплывающего меню с светлой темой части вашего темного приложения также изменяются, как если бы они были в светлой теме. Или если перейти к светло-тематическим страницам, а затем вернуться, исходная темная тематические страницы (или части) теперь выглядит, как будто она находится в светлой теме.

Как правило, эти типы проблем возникают при предоставлении темы по умолчанию и темы HighContrast для поддержки сценариев высокой контрастности, а затем используются темы Light и Dark в разных частях приложения.

Например, рассмотрим это определение словаря тем:

<!-- DO NOT USE. THIS XAML DEMONSTRATES AN ERROR. -->
<ResourceDictionary>
  <ResourceDictionary.ThemeDictionaries>
    <ResourceDictionary x:Key="Default">
      <SolidColorBrush x:Key="myBrush" Color="{ThemeResource ControlFillColorDefault}"/>
    </ResourceDictionary>
    <ResourceDictionary x:Key="HighContrast">
      <SolidColorBrush x:Key="myBrush" Color="{ThemeResource SystemColorButtonFaceColor}"/>
    </ResourceDictionary>
  </ResourceDictionary.ThemeDictionaries>
</ResourceDictionary>

Интуитивно это выглядит правильно. Вы хотите изменить цвет, указывающий на myBrush то, когда в высокой контрастности, но если не в высокой контрастности, вы полагаетесь на расширение разметки {ThemeResource} , чтобы убедиться, что myBrush указывает на правильный цвет для вашей темы. Если приложение никогда не имеет FrameworkElement.RequestedTheme для элементов в визуальном дереве, это обычно будет работать должным образом. Однако в приложении возникают проблемы, как только вы начнете повторно тему различных частей визуального дерева.

Проблема возникает, так как кисти являются общими ресурсами, в отличие от большинства других типов XAML. Если у вас есть 2 элемента в вложенных деревах XAML с различными темами, ссылающимися на один ресурс кисти, то при использовании платформы выполняется пошаговое обновление всех вложенных деревьев для обновления выражений расширения разметки {ThemeResource} , изменения в общем ресурсе кисти отражаются в другом дочернем дереве, который не является вашим предполагаемым результатом.

Чтобы устранить эту проблему, замените словарь по умолчанию отдельными словарями тем для тем "Light" и "Dark" в дополнение к HighContrast:

<!-- DO NOT USE. THIS XAML DEMONSTRATES AN ERROR. -->
<ResourceDictionary>
  <ResourceDictionary.ThemeDictionaries>
    <ResourceDictionary x:Key="Light">
      <SolidColorBrush x:Key="myBrush" Color="{ThemeResource ControlFillColorDefault}"/>
    </ResourceDictionary>
    <ResourceDictionary x:Key="Dark">
      <SolidColorBrush x:Key="myBrush" Color="{ThemeResource ControlFillColorDefault}"/>
    </ResourceDictionary>
    <ResourceDictionary x:Key="HighContrast">
      <SolidColorBrush x:Key="myBrush" Color="{ThemeResource SystemColorButtonFaceColor}"/>
    </ResourceDictionary>
  </ResourceDictionary.ThemeDictionaries>
</ResourceDictionary>

Однако проблемы по-прежнему возникают, если какие-либо из этих ресурсов ссылаются в унаследованных свойствах, таких как foreground. Шаблон пользовательского элемента управления может указать цвет переднего плана элемента с помощью расширения разметки {ThemeResource}, но когда платформа распространяет унаследованное значение на дочерние элементы, она предоставляет прямую ссылку на ресурс, который был разрешен выражением расширения разметки {ThemeResource}. Это приводит к проблемам, когда платформа обрабатывает изменения темы, так как она проходит визуальное дерево элемента управления. Он повторно оценивает выражение расширения разметки {ThemeResource}, чтобы получить новый ресурс кисти, но пока не распространяет эту ссылку на дочерние элементы элемента управления; это происходит позже, например во время следующей меры.

В результате после перехода визуального дерева элемента управления в ответ на изменение темы платформа выполняет обход дочерних элементов и обновляет все выражения расширения разметки {ThemeResource} , заданные на них, или объекты, заданные в их свойствах. Это место, где возникает проблема; Платформа обрабатывает ресурс кисти, так как он задает его цвет с помощью расширения разметки {ThemeResource}, он вычисляется повторно.

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

Чтобы устранить эту проблему, используйте расширение разметки {StaticResource} вместо расширения разметки {ThemeResource}. При применении рекомендаций словари тем выглядят следующим образом:

<ResourceDictionary>
  <ResourceDictionary.ThemeDictionaries>
    <ResourceDictionary x:Key="Light">
      <SolidColorBrush x:Key="myBrush" Color="{StaticResource ControlFillColorDefault}"/>
    </ResourceDictionary>
    <ResourceDictionary x:Key="Dark">
      <SolidColorBrush x:Key="myBrush" Color="{StaticResource ControlFillColorDefault}"/>
    </ResourceDictionary>
    <ResourceDictionary x:Key="HighContrast">
      <SolidColorBrush x:Key="myBrush" Color="{ThemeResource SystemColorButtonFaceColor}"/>
    </ResourceDictionary>
  </ResourceDictionary.ThemeDictionaries>
</ResourceDictionary>

Обратите внимание, что расширение разметки {ThemeResource} по-прежнему используется в словаре HighContrast вместо расширения разметки {StaticResource}. Эта ситуация относится к исключению, приведенному ранее в рекомендациях. Большинство значений кистей, используемых для темы HighContrast, используют варианты цвета, которые глобально управляются системой, но предоставляются XAML в качестве специально именованного ресурса (те, которые имеют префикс SystemColor в имени). Система позволяет пользователю задать определенные цвета, которые следует использовать для параметров темы контрастности с помощью Центра простоты доступа. Эти варианты цвета применяются к специально именованным ресурсам. Платформа XAML использует событие изменения той же темы, чтобы также обновить эти кисти при обнаружении их изменений на уровне системы. Поэтому здесь используется расширение разметки {ThemeResource}.