ResourceDictionary 类

参考

定义

命名空间:: Microsoft.UI.Xaml

重要

一些信息与预发行产品相关，相应产品在发行之前可能会进行重大修改。对于此处提供的信息，Microsoft 不作任何明示或暗示的担保。

编辑

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

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

ResourceDictionary 元素的使用

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

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

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

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

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

循环访问 ResourceDictionary

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

ResourceDictionary 和 Microsoft Visual Studio

Microsoft Visual Studio 为资源字典提供了 “添加新项 ”页选项。每当要定义新的松散 XAML 资源字典（例如，用作合并字典的源）时，请使用此选项。每当使用 “添加新项” 创建模板化控件时，Microsoft Visual Studio 还会向项目添加宽松的 XAML 资源字典。此资源字典提供默认主题模板。如果你正在编辑样式或模板的副本，Microsoft Visual Studio 可能会在 XAML 中为你新建 ResourceDictionary 一个 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#，使用实现 IDictionary<TKey、TValue> 和 IEnumerable 的 API。例如， TryGetValue 或项索引器。
不属于集合支持的 API（如 Source）在所有语言中都是相同的。

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

系统资源

某些主题资源引用系统资源值作为基础子值。系统资源是不存在于任何 XAML 资源字典中的特殊资源值。这些值依赖于 Windows 运行时 XAML 支持中的行为转发来自系统本身的值，并以 XAML 资源可以引用的形式表示它们。

构造函数

ResourceDictionary()

初始化 ResourceDictionary 类的新实例。

属性

Dispatcher	始终在Windows 应用 SDK应用中返回 `null` 。请改用 DispatcherQueue 。 (继承自 DependencyObject)
DispatcherQueue	`DispatcherQueue`获取与此对象关联的。表示 `DispatcherQueue` 一个可以在 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)

适用于

通过