ResourceDictionary 类

定义

命名空间:

Windows.UI.Xaml

定义应用使用的 XAML 资源（例如样式）的存储库。 在 XAML 中定义资源，然后可以使用 {StaticResource} 标记扩展和 {ThemeResource} 标记扩展在 XAML 中检索它们。 还可以使用代码访问资源，但这并不常见。

/// [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 中定义资源，然后可以使用 {StaticResource} 标记扩展和 {ThemeResource} 标记扩展在 XAML 中检索它们。 还可以使用代码访问资源，但这并不常见。 你可以使用资源来强制在整个应用中一致地使用某些值，例如画笔颜色或像素度量。 有关有效使用资源字典的详细信息，请参阅 ResourceDictionary 和 XAML 资源引用。

ResourceDictionary 元素的使用

ResourceDictionary 类型用作两个属性（ FrameworkElement.Resources 和 Application.Resources）的值，它们对 UWP 应用的整体结构非常重要。 从应用的起始项目模板获取的 XAML 文件将以 FrameworkElement.Resources 的初始值开头，app.xaml 文件可能以 Application.Resources 的初始值开头。 具体定义哪些资源取决于所使用的项目启动模板。

此 XAML 演示如何使用 FrameworkElement.Resources 属性。 在本例中， FrameworkElement 为 Page。 没有从属于 Page.Resources 属性元素的 ResourceDictionary 元素，但它的存在是默示的;有关详细信息，请参阅下面的“XAML 语法说明”部分。 XAML 将具有 x：Key 属性值“TextBlockStyle1”的 Style 放入 ResourceDictionary。 在 XAML 中，{StaticResource} 标记扩展引用资源字典中的 Style，为 TextBlock 元素的 Style 属性提供值。

所示的 样式 实际上不会对 TextBlock 应用任何样式，但你可以在 Microsoft Visual Studio 中添加 Style 属性。 然后，可以根据需要在页面上使用 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>

来自 AtomPub 示例的 AppPage.xaml 文件中的此 XAML 显示 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> 

来自文件 MainPage.xaml 的此 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>
 ...

可以使用 ResourceDictionary 作为文件的根元素，将资源分解为自己的 XAML 文件。 然后，可以将这些资源包含在 FrameworkElement.Resources 或 Application.Resources 资源字典中。 为此，请使用 ResourceDictionary.MergedDictionaries 属性或 ResourceDictionary 元素的 ResourceDictionary.ThemeDictionaries 属性。

此文件 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，它同样定义了 Style 资源。 此 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 中，通过对表示 XAML 资源的元素设置 x：Key 属性来声明 ResourceDictionary 项的键。 通常，如果尝试将没有键值的子元素放入 ResourceDictionary 中，则会引发 XAML 分析异常或 Windows 运行时异常。 XAML 设计图面也可能将异常条件标记为警告。 但是，有三种值得注意的情况，即 ResourceDictionarychild 元素不需要 x：Key 属性值：

• Style 资源可以使用其 TargetType 值作为隐式资源键。 有关样式和控件模板的隐式键工作原理的详细信息，请参阅 设置控件样式。
• 具有 表示ResourceDictionary.MergedDictionaries 值的 Source 值的 ResourceDictionary 元素不能在 ResourceDictionary 上具有 x：Key 属性 。 在每个合并的字典文件中， (URI 引用的文件作为其 源) 需要每个资源的密钥。
• 出于传统原因，可以使用 x：Name 属性 而不是 x：Key 属性。 但是， x：Name 属性 本身不会启用该项目的 XAML 资源查找。 x：Name 属性标识约定用于某些方案，例如定义情节提要动画。 有关详细信息，请参阅 x：Name 属性。

循环访问 ResourceDictionary

可以使用 C# 或 Microsoft Visual Basic 循环访问 ResourceDictionary。 在许多情况下，例如使用 foreach 语法，编译器会为你执行此强制转换，你无需显式转换为 IEnumerable 。 如果需要显式强制转换（例如，如果要调用 GetEnumerator），请使用 KeyValuePair<Object，Object> 约束强制转换为 IEnumerable<T>。

ResourceDictionary 和 Microsoft Visual Studio

Microsoft Visual Studio 为资源字典提供了 “添加新项 ”页选项。 每当要定义新的松散 XAML 资源字典（例如，用作合并字典的源）时，请使用此选项。 每当使用 “添加新项” 创建模板化控件时，Microsoft Visual Studio 还会向项目添加松散的 XAML 资源字典。 此资源字典提供默认主题模板。 如果你正在编辑样式或模板的副本，并且所选资源位置的 ResourceDictionary (应用、页面或独立) 尚不存在，Microsoft Visual Studio 可能会在 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 中使用。 支持共享的类型示例包括 Style、任何 FrameworkTemplate 子类、 XAML 内部数据类型、画笔、颜色和转换。 有关哪些类型被视为可共享类型的详细信息，请参阅 ResourceDictionary 和 XAML 资源引用。 通常， UIElement 派生的类型不可共享，除非它们来自特定控件实例上的模板和模板应用。 不包括模板用例，在实例化后 ，UIElement 应仅存在于对象树中的一个位置，并且将 UIElement 设置为可共享可能会违反此原则。

实际上，ResourceDictionary 中定义的绝大多数资源将是以下资源之一：

• 控件的控件模板，包括其视觉状态。
• 控件部分的支持样式
• 属于典型应用 UI 但不是控件的元素样式，如 TextBlock
• 使用数据绑定的控件和面板的数据模板
• 特定 Brush 值，主要是 SolidColorBrush
• 永远不需要本地化的字符串或其他常量 (字符串和需要本地化的常量不应位于 ResourceDictionary 中;有关详细信息，请参阅 快速入门：翻译 UI 资源)

在代码中访问 ResourceDictionary 对象

代码用于访问 ResourceDictionary 中的资源的 API 取决于所使用的编程语言：

• 对于 C# 或 Microsoft Visual Basic，请使用实现 IDictionary<TKey、TValue> 和 IEnumerable T> 的< API。 例如， TryGetValue 或 项 索引器。
• 对于 visual C++ 组件扩展 (C++/CX) 使用实现 IMap<K、V> 和 IIterable 的 API。 例如 ，Lookup。
• 不属于集合支持的 API（如 Source）在所有语言中都是相同的。

有关如何在代码中使用 ResourceDictionary 的详细信息，请参阅 ResourceDictionary 和 XAML 资源引用的“从代码使用 ResourceDictionary”部分。

系统资源

某些主题资源引用系统资源值作为基础子值。 系统资源是不存在于任何 XAML 资源字典中的特殊资源值。 这些值依赖于 Windows 运行时 XAML 支持中的行为转发来自系统本身的值，并以 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重定向应用时，你可能会看到一些时间差异。 应用应该加载得更快，但可能无法将此改进与作为重定向的一部分对应用代码所做的其他更改隔离开来。 对于 Application 对象、转换器或其他自定义类等对象，你可能会看到由于优化的资源加载而发生计时更改的一些地方包括分析程序调用构造函数的时间。 对于针对 Windows 8 编译的应用，如果它在 Windows 8.1 上运行，将继续使用 Windows 8 行为。

有关性能和 XAML 资源分解的详细信息，请参阅 优化 XAML 标记。

构造函数

ResourceDictionary()

初始化 ResourceDictionary 类的新实例。

属性

Dispatcher	获取与此 对象关联的 CoreDispatcher 。 CoreDispatcher 表示可以访问 UI 线程上的 DependencyObject 的工具，即使代码是由非 UI 线程启动的。 (继承自 DependencyObject)
MergedDictionaries	获取构成合并字典中各种资源字典的 ResourceDictionary 字典的集合。
Size	获取集合中包含的元素数。
Source	获取或设置统一资源标识符 (URI) ，该 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)	注册一个通知函数，用于侦听此 DependencyObject 实例上特定 DependencyProperty 的更改。 (继承自 DependencyObject)
Remove(Object)	从 ResourceDictionary 中删除特定项。
SetValue(DependencyProperty, Object)	设置 DependencyObject 上依赖属性的本地值。 (继承自 DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	取消以前通过调用 RegisterPropertyChangedCallback 注册的更改通知。 (继承自 DependencyObject)

另请参阅

• ResourceDictionary 和 XAML 资源引用
• 应用程序资源和本地化示例
• {ThemeResource} 标记扩展
• {StaticResource} 标记扩展
• x:Key 特性