ResourceDictionary Класс

Определение

/// [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 является страницей. Элемент свойства не ResourceDictionary подчинен Page.Resources , но его присутствие подразумевается. Дополнительные сведения см. в разделе "Заметки о синтаксисе XAML" ниже. XAML помещает стиль в 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 помещает два элемента стиля в словарь ресурсов, что делает их доступными во всем приложении.

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

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

Итерации с помощью ResourceDictionary

Вы можете выполнять итерацию с помощью ResourceDictionary C#. Во многих случаях, например использование 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

Обратите внимание, что синтаксис ResourceDictionary неявной коллекции XAML не включает элемент объекта для 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 потенциально нарушает этот принцип.

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

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

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

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

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

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

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

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

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

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