Расширение разметки {ThemeResource}

2025-09-11

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

Использование атрибута XAML

<object property="{ThemeResource key}" .../>

Значения XAML

Срок	Description
key	Ключ запрошенного ресурса. Этот ключ изначально назначается ResourceDictionary. Ключ ресурса может быть любой строкой, определенной в грамматике XamlName.

Замечания

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

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

ThemeResource принимает один аргумент, указывающий ключ для запрошенного ресурса. Ключ ресурса всегда является строкой в XAML среды выполнения Windows. Дополнительные сведения о первоначальном указании ключа ресурса см. в атрибуте x:Key.

Дополнительные сведения о том, как определить ресурсы и правильно использовать ResourceDictionary, включая пример кода, см. в справочниках по ресурсам ResourceDictionary и XAML.

Важный Как и в случае с StaticResource, объект ThemeResource не должен пытаться выполнить переадресацию ссылки на ресурс, определенный лексически в XAML-файле. Попытка сделать это не поддерживается. Даже если прямая ссылка не завершается неудачей, попытка ее создания приводит к снижению производительности. Для получения наилучших результатов настройте состав словарей ресурсов, чтобы избежать перенаправления ссылок.

Попытка указать ThemeResource на ключ, который не может быть разрешён, приводит к возникновению исключения синтаксического анализа XAML во время выполнения. Средства разработки также могут предлагать предупреждения или ошибки.

В реализации обработчика XAML среды выполнения Windows не существует резервного представления класса для ThemeResource. Ближайшим эквивалентом в коде является использование API коллекции ResourceDictionary, например вызов Contains или *TryGetValue.

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

Когда и как использовать {ThemeResource}, а не {StaticResource}

Правила, по которым ThemeResource сопоставляется с элементом в словаре ресурсов, в основном такие же, как и у StaticResource. Поиск ThemeResource может расшириться в файлы ResourceDictionary, на которые ссылается коллекция ThemeDictionaries, но StaticResource также может это делать. Разница заключается в том, что ThemeResource может повторно оцениваться во время выполнения, и StaticResource не может.

Набор ключей в каждом словаре тем должен предоставлять одинаковый набор ключевых ресурсов независимо от активной темы. Если указанный ресурс с ключом существует в словаре тем HighContrast , другой ресурс с таким именем также должен существовать в Light и Default. Если это не так, может произойти сбой при поиске ресурсов, когда пользователь переключает темы, и ваше приложение может отображаться неправильно. Возможно, что словарь тем может содержать ресурсы с ключами, на которые ссылаются только в пределах того же диапазона для предоставления подзначений; они не должны быть эквивалентны во всех темах.

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

Кисти, в частности цвета для SolidColorBrush. Они составляют около 80% использования ThemeResource в шаблонах элементов управления XAML по умолчанию (generic.xaml).
Значения пикселей для границ, смещения, поля и заполнения и т. д.
Свойства шрифта, такие как FontFamily или FontSize.
Полные шаблоны для ограниченного количества элементов управления, которые обычно являются системными и используются для динамической презентации, например GridViewItem и ListViewItem.
Стили отображения текста (обычно для изменения цвета шрифта, фона и возможного размера).

Среда выполнения Windows предоставляет набор ресурсов, которые специально предназначены для ссылки на ThemeResource. Все они перечислены в составе файла XAML themeresources.xaml, который доступен в папке include/winrt/xaml/design в составе пакета SDK для Windows Software Development Kit( SDK). Документацию по кистям темы и дополнительным стилям, определенным в themeresources.xaml, смотрите в ресурсах темы XAML. Кисти документируются в таблице, которая указывает, какое значение цвета каждая кисть имеет для каждой из трех возможных активных тем.

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

Использование ThemeResource можно увидеть в ряде зависимых значений. Например, значение Color, используемое SolidColorBrush, которое также является ключевым ресурсом, может использовать ссылку на ThemeResource. Все свойства пользовательского интерфейса, использующие ресурс SolidColorBrush через ключ, также будут ссылаться на ThemeResource, чтобы каждое свойство типа SolidColorBrush обеспечивало динамическое изменение значения при смене темы.

Примечание{ThemeResource} и оценка ресурсов в режиме выполнения при переключении тем поддерживается в XAML Windows 8.1, но не поддерживается в XAML для приложений, предназначенных для Windows 8.

Системные ресурсы

Некоторые ресурсы темы ссылаются на значения системных ресурсов как на базовые подзначения. Системный ресурс — это специальное значение ресурса, которое не найдено в словаре ресурсов XAML. Эти значения зависят от поведения в XAML среды выполнения Windows для передачи значений из самой системы и представляют их в виде, на который может ссылаться XAML-ресурс. Например, существует системный ресурс с именем SystemColorButtonFaceColor, представляющий цвет RGB. Цвет этого параметра исходит из аспектов системных цветов и тем, которые относятся не только к среде выполнения Windows и приложениям на её основе.

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

Пример использования {ThemeResource}

Ниже приведен пример XAML, взятый из файлов generic.xaml и themeresources.xaml по умолчанию, иллюстрирующих использование ThemeResource. Мы рассмотрим только один шаблон ( кнопка по умолчанию) и как объявляются два свойства (фон и передний план), чтобы реагировать на изменения темы.

    <!-- Default style for Windows.UI.Xaml.Controls.Button -->
    <Style TargetType="Button">
        <Setter Property="Background" Value="{ThemeResource ButtonBackgroundThemeBrush}" />
        <Setter Property="Foreground" Value="{ThemeResource ButtonForegroundThemeBrush}"/>
...

Здесь свойства принимают значение Кисти, а ресурсы SolidColorBrush с именами ButtonBackgroundThemeBrush и ButtonForegroundThemeBrush упоминаются с помощью ThemeResource.

Эти же свойства также корректируются некоторыми визуальными состояниями для кнопки. В частности, цвет фона изменяется при нажатии кнопки. Здесь также анимации фона и переднего плана в раскадровке визуального состояния используют объекты DiscreteObjectKeyFrame и ссылки на кисти с ThemeResource в качестве значения ключевого кадра.

<VisualState x:Name="Pressed">
  <Storyboard>
    <ObjectAnimationUsingKeyFrames Storyboard.TargetName="Border"
        Storyboard.TargetProperty="Background">
      <DiscreteObjectKeyFrame KeyTime="0" Value="{ThemeResource ButtonPressedBackgroundThemeBrush}" />
    </ObjectAnimationUsingKeyFrames>
    <ObjectAnimationUsingKeyFrames Storyboard.TargetName="ContentPresenter"
         Storyboard.TargetProperty="Foreground">
       <DiscreteObjectKeyFrame KeyTime="0" Value="{ThemeResource ButtonPressedForegroundThemeBrush}" />
    </ObjectAnimationUsingKeyFrames>
  </Storyboard>
</VisualState>

Каждая из этих кистей определена ранее в generic.xaml: они должны быть определены до любых шаблонов, использующих их, чтобы избежать предварительных ссылок XAML. Ниже приведены эти определения для словаря тем по умолчанию.

    <ResourceDictionary.ThemeDictionaries>
        <ResourceDictionary x:Key="Default">
...
            <SolidColorBrush x:Key="ButtonBackgroundThemeBrush" Color="Transparent" />
            <SolidColorBrush x:Key="ButtonForegroundThemeBrush" Color="#FFFFFFFF" />
...
            <SolidColorBrush x:Key="ButtonPressedBackgroundThemeBrush" Color="#FFFFFFFF" />
            <SolidColorBrush x:Key="ButtonPressedForegroundThemeBrush" Color="#FF000000" />
...

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

        <ResourceDictionary x:Key="HighContrast">
            <!-- High Contrast theme resources -->
...
            <SolidColorBrush x:Key="ButtonBackgroundThemeBrush" Color="{ThemeResource SystemColorButtonFaceColor}" />
            <SolidColorBrush x:Key="ButtonForegroundThemeBrush" Color="{ThemeResource SystemColorButtonTextColor}" />

...
            <SolidColorBrush x:Key="ButtonPressedBackgroundThemeBrush" Color="{ThemeResource SystemColorButtonTextColor}" />
            <SolidColorBrush x:Key="ButtonPressedForegroundThemeBrush" Color="{ThemeResource SystemColorButtonFaceColor}" />

Здесь значение color является еще одной ссылкой ThemeResource на системный ресурс. Если вы ссылаетесь на системный ресурс и хотите изменить его в ответ на изменение темы, следует использовать ThemeResource , чтобы сделать ссылку.

Поддержка инструментов разработки во время проектирования для расширения разметки {ThemeResource}

Microsoft Visual Studio может включать возможные ключевые значения в раскрывающиеся списки Microsoft IntelliSense при использовании расширения разметки {ThemeResource} на странице XAML. Например, как только вы введите "{ThemeResource", отображаются все ключи ресурсов из ресурсов темы XAML .

Как только ключ ресурса становится частью любого применения {ThemeResource}, функция Go To Definition (F12) может определить этот ресурс и показать файл generic.xaml во время проектирования, где определяется ресурс темы. Так как ресурсы темы определяются несколько раз (для каждой темы) Перейти к определению , вы перейдете к первому определению, найденном в файле, который является определением по умолчанию. Если вы хотите получить другие определения, вы можете поискать имя ключа в файле, чтобы найти определения других тем.

Поделиться через