ResourceDictionary 类

定义

定义应用使用的 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 要求

设备系列
Windows 10 (在 10.0.10240.0 中引入)
API contract
Windows.Foundation.UniversalApiContract (在 v1.0 中引入)

注解

资源字典是应用使用的 XAML 资源的存储库,例如样式。 在 XAML 中定义资源,然后使用 {StaticResource} 标记扩展{ThemeResource} 标记扩展 在 XAML 中检索它们。 还可以使用代码访问资源,但这不太常见。 可以使用资源强制实施某些值,例如画笔颜色或像素度量在整个应用中一致地使用。 有关有效使用资源字典的详细信息,请参阅 ResourceDictionary 和 XAML 资源引用

ResourceDictionary 元素的使用

ResourceDictionary 类型用作两个属性 (FrameworkElement.ResourcesApplication.Resources)的值,这些属性对于 UWP 应用的整体结构非常重要。 从应用的起始项目模板获取的 XAML 文件将从 FrameworkElement.Resources 的初始值开始,app.xaml 文件可能以 Application.Resources 的初始值开头。 确切地说,定义哪些资源取决于所使用的项目启动模板。

此 XAML 显示 FrameworkElement.Resources 属性的使用。 在本例中, FrameworkElementPage。 没有从属于 Page.Resources 属性元素的 ResourceDictionary 元素,但其存在是隐含的;有关详细信息,请参阅下面的“XAML 语法说明”部分。 XAML 将 样式 置于 ResourceDictionary 中,其 x:Key 属性值 为“TextBlockStyle1”。 在 XAML 中,{StaticResource} 标记扩展引用资源字典中的样式,以提供 TextBlock 元素的 Style 属性的值。

如所示的 样式 实际上不会对 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>

来自 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> 

此 XAML 来自文件 MainPage.xaml 使用 {StaticResource} 标记扩展 来访问 TitleStyleH1Style 样式:

...
<!-- 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.ResourcesApplication.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,它同样定义了 样式 资源。 此 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 中,通过对表示 XAML 资源的元素设置 x:Key 属性来声明 ResourceDictionaryitems 的键。 通常,如果尝试将没有键值的子元素放入 ResourceDictionary 中,则会引发 XAML 分析异常或 Windows Runtimeexception。 XAML 设计图面可能还会将异常条件描述为警告。 但是,有三个值得注意的情况:ResourceDictionarychild 元素不需要 x:Key 属性值

循环访问 ResourceDictionary

可以在 C# 或 Microsoft Visual Basic 中循环访问 ResourceDictionary。 在许多情况下,例如使用 foreach 语法,编译器会为你执行此强制转换,无需显式强制转换 IEnumerable 。 如果需要显式强制转换,例如,如果要调用 GetEnumerator,请使用 KeyValuePair<对象、对象>约束强制转换为 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)的元素的样式
  • 使用数据绑定的控件和面板的数据模板
  • 特定 画笔 值,主要是 SolidColorBrush
  • 字符串或其他不需要本地化的常量 (字符串和需要本地化的常量不应位于 ResourceDictionary 中;有关详细信息,请参阅 快速入门:翻译 UI 资源)

在代码中访问 ResourceDictionary 对象

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

有关如何在代码中使用 ResourceDictionary 的详细信息,请参阅 ResourceDictionary 和 XAML 资源引用的“使用 Code 中的 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没有上述优化。 在初始屏幕以外的任何页面加载到应用窗口之前,必须完成分析的 ResourceDictionaryApplication.Resources。 因此,在将应用重定向到Windows 8.1时,可能会看到时间差异。 应用加载速度应更快,但是,在重定向过程中,可能无法隔离此改进与其他对应用代码所做的更改。 由于优化的资源加载,你可能会看到时间更改的一些位置,包括分析器调用构造函数时,例如 应用程序 对象、转换器或其他自定义类的对象。 对于针对 Windows 8 编译的应用,如果它在 Windows 8.1 上运行,将继续使用 Windows 8 行为。

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

构造函数

ResourceDictionary()

初始化 ResourceDictionary 类的新实例。

属性

Dispatcher

获取与此对象关联的 CoreDispatcherCoreDispatcher 表示可以访问 UI 线程上的 DependencyObject 的设施,即使代码是由非 UI 线程启动的。

(继承自 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)

注册一个通知函数,用于侦听此 DependencyObject 实例上对特定 DependencyProperty 所做的更改。

(继承自 DependencyObject)
Remove(Object)

ResourceDictionary 中删除特定项。

SetValue(DependencyProperty, Object)

设置 DependencyObject 上的依赖属性的本地值。

(继承自 DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty, Int64)

取消以前通过调用 RegisterPropertyChangedCallback 注册的更改通知。

(继承自 DependencyObject)

适用于

另请参阅