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

Стиль, как показано, на самом деле не применяет стили к TextBlock, но вы можете добавить свойства стиля в 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 помещает два элемента стиля в словарь ресурсов, что делает их доступными во всем приложении.

<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/Style1.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/Style2.xaml, который аналогично определяет ресурсы стиля . В этом XAML показано, как объединить ресурсы в этих двух файлах с помощью свойства ResourceDictionary.MergedDictionaries для создания словаря ресурсов Application.Resources . XAML также определяет два дополнительных ресурса стиля и объединяет их с ресурсами из двух файлов.

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

Ресурс Style может использовать значение TargetType в качестве неявного ключа ресурса. Дополнительные сведения о том, как работают неявные ключи для стилей и шаблонов элементов управления, см. в разделе "Стилизация элементов управления".
Элементы ResourceDictionary со значениями источника , представляющие значения 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> .

ResourceDictionary и Microsoft Visual Studio

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

Заметки о синтаксисе XAML

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

Для объединенного словаря ресурсов необходимо явно объявить элемент объекта 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. Примеры типов, в которых поддерживается общий доступ, включают стиль, подкласс 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<T>. Например, подстановка.
API, которые не являются частью поддержки коллекции, например Source, одинаковы на всех языках.

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

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

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

Заметки для предыдущих версий

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

Начиная с Windows 8.1, существует оптимизация загрузки ресурсов, включенная моделью приложения и средство синтаксического анализа XAML среда выполнения Windows. Для 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)

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

См. также

Обратная связь

Были ли сведения на этой странице полезными?