ResourceDictionary Класс

Определение

Пространство имен:

Microsoft.UI.Xaml

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

/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.WinUIContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class ResourceDictionary : DependencyObject, IIterable<IKeyValuePair<IInspectable, IInspectable const&>>, IMap<IInspectable, IInspectable const&>

[Windows.Foundation.Metadata.ContractVersion(typeof(Microsoft.UI.Xaml.WinUIContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public class ResourceDictionary : DependencyObject, IDictionary<object,object>, IEnumerable<KeyValuePair<object,object>>

Public Class ResourceDictionary
Inherits DependencyObject
Implements IDictionary(Of Object, Object), IEnumerable(Of KeyValuePair(Of Object, Object))

<ResourceDictionary>
  oneOrMoreResources
</ResourceDictionary>
- or -
<frameworkElement>
  <frameworkElement.Resources>
    oneOrMoreResources
  </frameworkElement.Resources>
</frameworkElement>

Наследование

Object IInspectable DependencyObject ResourceDictionary

Производный

Microsoft.UI.Xaml.ColorPaletteResources

Microsoft.UI.Xaml.Controls.XamlControlsResources

Атрибуты

ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Реализации

IDictionary<Object,Object> IMap<IInspectable,IInspectable> IIterable<IKeyValuePair<K,V>> IEnumerable<KeyValuePair<K,V>> IEnumerable<KeyValuePair<Object,Object>> IIterable<IKeyValuePair<IInspectable,IInspectable>>

Комментарии

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

Использование элементов ResourceDictionary

Тип ResourceDictionary используется в качестве значения двух свойств, FrameworkElement.Resources и Application.Resources, которые важны для общей структуры приложения Windows App SDK. Xaml-файлы, полученные из шаблона начального проекта для приложения, будут начинаться с начальных значений для FrameworkElement.Resources, а файл app.xaml может начинаться с начальных значений для Application.Resources. Точное определение ресурсов зависит от того, какой начальный шаблон проекта вы используете.

В этом XAML показано использование свойства FrameworkElement.Resources . В этом случае FrameworkElement является элементом Page. Элемент, подчиненный элементу Page.Resources свойства, отсутствуетResourceDictionary, но его наличие подразумевается. Дополнительные сведения см. в разделе "Примечания по синтаксису XAML" ниже. XAML помещает style в ResourceDictionary с атрибутом x:Key , равным TextBlockStyle1. Далее в XAML расширение разметки {StaticResource} ссылается на Style в словаре ресурсов, чтобы предоставить значение для свойства Style элемента TextBlock .

Стиль, как показано ниже, фактически не применяет никакой стиль к TextBlock, но вы можете добавить Style свойства в Microsoft Visual Studio. Затем ресурс можно использовать Style так часто, как вам нравится, на странице для обеспечения единообразия.

<Page
    x:Class="ResourceDictionary_example.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:ResourceDictionary_example"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d">
    <Page.Resources>
        <Style x:Key="TextBlockStyle1" TargetType="TextBlock"/>
    </Page.Resources>

    <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
        <TextBlock Style="{StaticResource TextBlockStyle1}" Text="TextBlock"/>
    </Grid>
</Page>

В этом коде XAML из файла AppPage.xaml примера AtomPub показано использование свойства Application.Resources . XAML помещает два элемента Style в словарь ресурсов, делая их доступными во всем приложении.

<Application xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 
    x:Class="AtomPub.App"
    RequestedTheme="Light" >
    <Application.Resources>
        <ResourceDictionary>
            <Style x:Key="TitleStyle" TargetType="TextBlock">
                <Setter Property="Foreground" Value="#707070"/>
                <Setter Property="FontFamily" Value="Segoe UI Light"/>
                <Setter Property="FontSize" Value="16"/>
            </Style>
            <Style x:Key="H1Style" TargetType="TextBlock">
                <Setter Property="Foreground" Value="#212121"/>
                <Setter Property="FontFamily" Value="Segoe UI Semilight"/>
                <Setter Property="FontSize" Value="26.667"/>
                <Setter Property="Margin" Value="0,0,0,25"/>
            </Style>
            ...
        </ResourceDictionary>
    </Application.Resources>
</Application> 

Этот XAML из файла MainPage.xaml использует расширение разметки {StaticResource} для доступа к стилям TitleStyle и H1Style :

...
<!-- Header -->
<StackPanel x:Name="Header" Grid.Row="0">
    <StackPanel Orientation="Horizontal">
        ...
        <TextBlock Text="Windows SDK Samples" VerticalAlignment="Bottom" Style="{StaticResource TitleStyle}" TextWrapping="Wrap"/>
    </StackPanel>
    <TextBlock x:Name="FeatureName" Text="Add Feature Name" Style="{StaticResource H1Style}" TextWrapping="Wrap"/>
</StackPanel>
 ...

Ресурсы можно учитывать в собственном XAML-файле, используя ResourceDictionary в качестве корневого элемента файла. Затем эти ресурсы можно включить в словарь ресурсов FrameworkElement.Resources или Application.Resources . Для этого используйте свойство ResourceDictionary.MergedDictionaries или свойство ResourceDictionary.ThemeDictionaries элемента ResourceDictionary.

Этот файл Common/Styles1.xaml определяет ресурсы Style , используя ResourceDictionary в качестве корневого элемента:

<ResourceDictionary
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

    <Style x:Key="TitleTextStyle" TargetType="TextBlock">
        <Setter Property="FontFamily" Value="Segoe UI Light"/>
        <Setter Property="FontSize" Value="16"/>
    </Style>
    <Style x:Key="HeaderTextStyle" TargetType="TextBlock">
        <Setter Property="FontFamily" Value="Segoe UI Semilight"/>
        <Setter Property="FontSize" Value="26.667"/>
        <Setter Property="Margin" Value="0,0,0,25"/>
    </Style>
    ...
</ResourceDictionary>

Теперь предположим, что имеется другой файл Common/Styles2.xaml, который аналогичным образом определяет ресурсы стиля . В этом XAML показано, как объединить ресурсы в этих двух файлах с помощью свойства ResourceDictionary.MergedDictionaries для создания словаря ресурсов Application.Resources . XAML также определяет два дополнительных ресурса Style и объединяет их с ресурсами из двух файлов.

<Application
    .... >
    <Application.Resources>
        <ResourceDictionary>
            <Style x:Key="ErrorStyle" TargetType="TextBlock">
                <Setter Property="Foreground" Value="DarkRed"/>
                <Setter Property="FontFamily" Value="Segoe UI Semilight"/>
                <Setter Property="FontSize" Value="15"/>
            </Style>
            <Style x:Key="StatusStyle" TargetType="TextBlock">
                <Setter Property="Foreground" Value="Black"/>
                <Setter Property="FontFamily" Value="Segoe UI Semilight"/>
                <Setter Property="FontSize" Value="15"/>
            </Style>
            <ResourceDictionary.MergedDictionaries>
                <!-- 
                    Styles that define common aspects of the platform look and feel
                 -->
                <ResourceDictionary Source="Common/Styles1.xaml"/>
                <ResourceDictionary Source="Common/Styles2.xaml"/>
            </ResourceDictionary.MergedDictionaries>
        </ResourceDictionary>
    </Application.Resources>
</Application>

Сведения о том, как разрешаются объединенные ресурсы словаря, см. в разделе "Объединенные словари ресурсов" статьи Ссылки на ресурсы ResourceDictionary и XAML.

Свойство x:Key

В XAML ключи для ResourceDictionary элементов объявляются путем задания атрибута x:Keyдля элементов, представляющих ресурсы XAML. Как правило, при попытке поместить дочерний элемент, который не имеет значения ключа, в ResourceDictionaryобъект возникает исключение синтаксического анализа XAML или исключение среда выполнения Windows. Условие исключения также может быть отмечено в качестве предупреждения для поверхностей конструктора XAML. Однако есть три важных случая, когда дочернему ResourceDictionary элементу не требуется значение атрибута x:Key :

• Ресурс Style может использовать значение TargetType в качестве ключа неявного ресурса. Дополнительные сведения о том, как работают неявные ключи для стилей и шаблонов элементов управления, см. в разделе Стилизация элементов управления.
• Элементы ResourceDictionary со значениями Source , представляющие значения ResourceDictionary.MergedDictionaries , не могут иметь атрибут x:Key в ResourceDictionary. В каждом объединенном файле словаря (на который ссылается URI в качестве источника) требуются ключи для каждого ресурса.
• Атрибут x:Name можно использовать вместо атрибута x:Key по причинам прежних версий. Однако атрибут x:Name сам по себе не включает поиск этого элемента в ресурсе XAML. Соглашение об определении атрибута x:Name используется для определенных сценариев, таких как определение раскадровки анимаций. Дополнительные сведения см. в разделе Атрибут x:Name.

Итерации по ResourceDictionary

В C# можно выполнить итерацию по объекту ResourceDictionary . Во многих случаях, например с помощью foreach синтаксиса, компилятор выполняет это приведение за вас, и вам не нужно явно приводить к IEnumerable . Если необходимо выполнить приведение явным образом, например, если вы хотите вызвать GetEnumerator, приведите к IEnumerable с ограничениемKeyValuePair<Object,Object>.

ResourceDictionary и Microsoft Visual Studio

Microsoft Visual Studio предоставляет выбор страницы "Добавление нового элемента" для словаря ресурсов. Используйте этот параметр всякий раз, когда вы хотите определить новый свободный словарь ресурсов XAML, например для использования в качестве источника для объединенного словаря. Microsoft Visual Studio также добавляет свободный словарь ресурсов XAML в проект всякий раз, когда вы используете команду Добавить новый элемент для создания шаблонного элемента управления. Этот словарь ресурсов предоставляет шаблоны тем по умолчанию. Microsoft Visual Studio может создать новый ResourceDictionary объект в XAML, если вы редактируете копии стилей или шаблонов, а ResourceDictionary для выбранного расположения ресурса (приложения, страницы или автономного) еще не существует.

Примечания по синтаксису XAML

Обратите внимание, что синтаксис неявной коллекции XAML для ResourceDictionary не включает объектный элемент для ResourceDictionary. Это пример синтаксиса неявной коллекции XAML; Тег, представляющий элемент коллекции, можно опустить. Элементы, добавляемые в коллекцию в качестве элементов, указываются как дочерние элементы элемента свойства свойства, базовый тип которого поддерживает метод Add dictionary/map.

Для объединенного словаря ресурсов необходимо явно объявить объектный ResourceDictionary элемент, чтобы можно было также объявить элемент свойств ResourceDictionary.MergedDictionaries и Source. Таким образом, используются как минимум два ResourceDictionary объектных элемента, и вы используете этот синтаксис.

<ResourceDictionary>
  <ResourceDictionary.MergedDictionaries>
    <ResourceDictionary Source="uri"/>
    ...
  </ResourceDictionary.MergedDictionaries>
...
</ResourceDictionary>

В этом синтаксисе внешний ResourceDictionary объект является основным ResourceDictionary. Внутреннее ResourceDictionary — это слияние ResourceDictionary .

Для неявного использования коллекции отображается заполнитель, соответствующий свойству FrameworkElement.Resources . Вы также можете использовать это неявное использование коллекции для свойства Application.Resources или, возможно, для пользовательского свойства, которое использует ResourceDictionary в качестве типа свойства.

Общие типы и типы UIElement

Словарь ресурсов — это метод определения общих типов и значений этих типов в XAML. Не все типы или значения подходят для использования из ResourceDictionary. Примеры типов, для которых поддерживается общий доступ, включают Style, любой подкласс FrameworkTemplate , встроенные типы данных XAML, кисти, цвета и преобразования. Дополнительные сведения о том, какие типы считаются общими, см. в статье Ссылки на ресурсы ResourceDictionary и XAML. Как правило, типы, производные от UIElement, не являются общими, если они не получены из шаблонов и применения шаблона в определенном экземпляре элемента управления. За исключением варианта шаблона, uiElement должен существовать только в одном месте в дереве объектов после создания его экземпляра, а наличие элемента UIElement , доступного для общего доступа, потенциально нарушает этот принцип.

На практике подавляющее большинство ресурсов, определенных в , ResourceDictionary будет одним из следующих:

• Шаблоны элементов управления для элемента управления, включая его визуальные состояния.
• Поддержка стилей для частей элементов управления
• Стили для элементов, которые являются частью типичного пользовательского интерфейса приложения, но не являются элементами управления, например TextBlock
• Шаблоны данных для элементов управления и панелей, использующих привязку данных
• Конкретные значения кисти , в основном SolidColorBrush
• Строки или другие константы, которые никогда не нужно локализовать (строки и константы, которые необходимо локализовать, не должны находиться в ResourceDictionary; дополнительные сведения см. в статье Краткое руководство. Перевод ресурсов пользовательского интерфейса).

Доступ к объекту ResourceDictionary в коде

API, используемый кодом для доступа к ресурсам в ResourceDictionary, зависит от того, какой язык программирования вы используете:

• Для C# используется API, реализующий IDictionary<TKey, TValue> и IEnumerable. Например, TryGetValue или индексатор Item .
• API, которые не являются частью поддержки коллекций, например Source, одинаковы на всех языках.

Дополнительные сведения об использовании ResourceDictionary в коде см. в разделе "Использование ResourceDictionary из кода" статьи Ссылки на ресурсы ResourceDictionary и XAML.

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

Некоторые ресурсы темы ссылаются на значения системных ресурсов в качестве базового значения. Системный ресурс имеет особое значение, которое не входит ни в один словарь ресурсов XAML. Такие значения зависят от поддержки XAML в среде выполнения Windows, которая получает значения из системы и представляет их в формате, на который может ссылаться ресурс XAML.

Конструкторы

ResourceDictionary()

Инициализирует новый экземпляр класса ResourceDictionary .

Свойства

Dispatcher	Всегда возвращает в null приложении Windows App SDK. Вместо этого используйте DispatcherQueue . (Унаследовано от DependencyObject)
DispatcherQueue	Возвращает объект , DispatcherQueue с которым связан этот объект. представляет DispatcherQueue средство, которое может получить доступ к в потоке DependencyObject пользовательского интерфейса, даже если код инициируется потоком, не относящегося к пользовательскому интерфейсу. (Унаследовано от DependencyObject)
MergedDictionaries	Возвращает коллекцию словарей ResourceDictionary , составляющих различные словари ресурсов в объединенных словарях.
Size	Возвращает количество элементов, содержащихся в коллекции.
Source	Возвращает или задает универсальный код ресурса (URI), предоставляющий исходное расположение объединенного словаря ресурсов.
ThemeDictionaries	Возвращает коллекцию объединенных словарей ресурсов, которые специально связаны с ключами и составлены для сценариев темы, например при предоставлении значений темы для HighContrast.

Методы

Clear()	Удаляет все элементы из этого ResourceDictionary.
ClearValue(DependencyProperty)	Очищает локальное значение свойства зависимостей. (Унаследовано от DependencyObject)
First()	Возвращает итератор для элементов в коллекции.
GetAnimationBaseValue(DependencyProperty)	Возвращает любое базовое значение, установленное для свойства зависимостей, которое применяется в случаях, когда анимация не активна. (Унаследовано от DependencyObject)
GetValue(DependencyProperty)	Возвращает текущее действующее значение свойства зависимостей из DependencyObject. (Унаследовано от DependencyObject)
GetView()	Извлекает представление для ResourceDictionary.
HasKey(Object)	Возвращает значение, указывающее, содержит ли ResourceDictionary запись с запрошенным ключом.
Insert(Object, Object)	Добавляет новую запись в ResourceDictionary.
Lookup(Object)	Возвращает значение из запрошенного ключа, если существует запись с этим ключом.
ReadLocalValue(DependencyProperty)	Возвращает локальное значение свойства зависимостей, если задано локальное значение. (Унаследовано от DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)	Регистрирует функцию уведомления для прослушивания изменений определенного DependencyProperty в этом экземпляре DependencyObject . (Унаследовано от DependencyObject)
Remove(Object)	Удаляет определенный элемент из ResourceDictionary.
SetValue(DependencyProperty, Object)	Задает локальное значение свойства зависимостей для Объекта DependencyObject. (Унаследовано от DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	Отменяет уведомление об изменениях, которое было ранее зарегистрировано путем вызова Метода RegisterPropertyChangedCallback. (Унаследовано от DependencyObject)

См. также раздел

• Ссылки на ресурсы ResourceDictionary и XAML
• Пример ресурсов и локализации приложения
• Расширение разметки {ThemeResource}
• Расширение разметки {StaticResource}
• Атрибут x:Key