ResourceDictionary Класс

Ссылка

Определение

Пространство имен:: Windows.UI.Xaml

Важно!

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

Изменить

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

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 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(Windows.Foundation.UniversalApiContract), 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

Производный: Windows.UI.Xaml.ColorPaletteResources

Атрибуты: 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>>

Требования к Windows

Семейство устройств	Windows 10 (появилось в 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (появилось в v1.0)

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

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

Тип ResourceDictionary используется в качестве значения двух свойств, FrameworkElement.Resources и Application.Resources, которые важны для общей структуры приложения UWP. Файлы XAML, полученные из начального шаблона проекта для приложения, будут начинаться с начальных значений frameworkElement.Resources, а файл app.xaml может начинаться с начальных значений application.Resources. Точное определение ресурсов зависит от того, какой начальный шаблон проекта вы используете.

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

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

Для создания словарей ресурсов можно использовать Microsoft Visual Studio. Этот пример был создан с помощью следующих действий: поместите TextBlock в область конструктора, щелкните правой кнопкой мыши, выберите Изменить стиль / Создать пустой, а затем — "Этот документ" , чтобы определить новый ресурс в Page.Resources.

<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 определяет ресурсы стиля , используя 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 ключи для ResourceDictionaryitems объявляются путем задания атрибута x:Keyдля элементов, представляющих ресурсы XAML. Как правило, при попытке поместить дочерний элемент, который не имеет ключевого значения, в ResourceDictionary возникает исключение синтаксического анализа XAML или исключение среды выполнения Windows. Условия исключения также могут быть отмечены в качестве предупреждения в областях конструктора XAML. Однако существует три важных случая, когда элементу ResourceDictionarychild не требуется значение атрибута x:Key:

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

Итерации по ResourceDictionary

Вы можете выполнять итерацию с помощью ResourceDictionary в C# или Microsoft Visual Basic. Во многих случаях, например с помощью синтаксиса foreach , компилятор выполняет это приведение за вас, и вам не нужно выполнять приведение IEnumerable явно. Если вам нужно выполнить приведение явным образом, например, если вы хотите вызвать GetEnumerator, приведите к IEnumerable<T> с ограничением 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# или Microsoft Visual Basic используется API, реализующий IDictionary<TKey, TValue> и IEnumerable<T>. Например, TryGetValue или индексатор Item .
Для расширений компонентов Visual C++ (C++/CX) используется API, реализующий IMap<K, V> и IIterable. Например, Подстановка.
API, которые не являются частью поддержки коллекций, например Source, одинаковы на всех языках.

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

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

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

Примечания для предыдущих версий

Оптимизация загрузки ресурсов в Windows 8.1

Начиная с Windows 8.1, существует оптимизация загрузки ресурсов, которая включена моделью приложения и синтаксический анализатор среда выполнения Windows XAML. Для Windows 8 средство синтаксического анализа XAML загружало ресурсы из app.xaml и создавало каждый из них как объекты в процессе запуска. Это было не очень эффективно, если бы там были большие словари. Кроме того, эти ресурсы включали элементы, необходимые для всех трех тем, и две из трех тем даже не были активными. Начиная с Windows 8.1, средство синтаксического анализа XAML создает ресурсы только при их специальном запросе. Запрос может поступать из других ресурсов или из XAML приложения или страницы при загрузке каждого из них. Такое поведение средства синтаксического анализа сводит к минимуму время, необходимое для чтения словаря уровня приложения во время запуска, и в большинстве случаев позволяет быстрее загружать первую страницу приложения. Ресурсы, необходимые для других неактивных в настоящее время тем, загружаются только в том случае, если эта тема выбрана пользователем в качестве активной темы. В то время любой ресурс, в котором для запроса использовалось расширение разметки {ThemeResource} , пересчитывается на основе новой активной темы.

Работа в Windows 8

Windows 8 не имели описанных выше оптимизаций. ResourceDictionary для Application.Resources должен был завершить синтаксический анализ, прежде чем любая страница, кроме экрана-заставки, могла загрузиться в окно приложения. Из-за этого при перенацелии приложения на Windows 8.1 вы можете столкнуться с некоторыми различиями во времени. Приложение должно загружаться быстрее, однако невозможно изолировать это улучшение по сравнению с другими изменениями, которые вы внесли в код приложения в рамках перенацеливание. Некоторые из мест, где можно увидеть изменения времени из-за оптимизированной загрузки ресурсов, включают, когда конструкторы вызываются синтаксический анализатор, для таких объектов, как объекты приложения , преобразователи или другие пользовательские классы. Приложения, которые скомпилированы для Windows 8, но выполняются в Windows 8.1, продолжают использовать правила, действующие в Windows 8.

Дополнительные сведения о производительности и факторинге ресурсов XAML см. в статье Оптимизация разметки XAML.

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

ResourceDictionary()

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

Свойства

Dispatcher	Возвращает CoreDispatcher , с которым связан этот объект. CoreDispatcher представляет средство, которое может получить доступ к 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)

Применяется к