ResourceDictionary 类
定义
重要
一些信息与预发行产品相关,相应产品在发行之前可能会进行重大修改。 对于此处提供的信息,Microsoft 不作任何明示或暗示的担保。
为应用使用的 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>
- 继承
- 派生
- 属性
- 实现
-
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.Resources 属性元素的 ResourceDictionary 元素,但其存在是隐含的;有关详细信息,请参阅下面的“XAML 语法说明”部分。 XAML 将 样式 置于 ResourceDictionary 中,其 x:Key 属性值 为“TextBlockStyle1”。 在 XAML 中,{StaticResource} 标记扩展引用资源字典中的 Style,以提供 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>
此来自文件 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 定义 Style 资源作为根元素:
<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 属性值:
- 样式资源可以使用其 TargetType 值作为隐式资源键。 有关样式和控件模板的隐式键的工作原理的详细信息,请参阅 “设置控件样式”。
- ResourceDictionary 元素,其 源 值表示 ResourceDictionary.MergedDictionaries 值不能在 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<对象、对象>约束强制转换为 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 取决于所使用的编程语言:
- 对于 C# 或Microsoft Visual Basic使用实现 IDictionary<TKey、TValue> 和 IEnumerable<T> 的 API。 例如, TryGetValue 或 Item 索引器。
- 对于 Visual C++ 组件扩展(C++/CX),请使用实现 IMap<K、V> 和 IIterable<T> 的 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时,你可能会看到一些时间差异。 应用加载速度应该更快,但是,在重定目标过程中,可能无法隔离此改进与其他对应用代码所做的更改。 某些位置可能会看到由于优化资源加载而导致的计时更改的证据,包括分析器调用构造函数时,对于 应用程序 对象、转换器或其他自定义类等对象。 已针对Windows 8编译但Windows 8.1上运行的应用继续使用Windows 8行为。
有关性能和 XAML 资源分解的详细信息,请参阅 “优化 XAML 标记”。
构造函数
| 名称 | 说明 |
|---|---|
| ResourceDictionary() |
初始化 ResourceDictionary 类的新实例。 |
属性
| 名称 | 说明 |
|---|---|
| Dispatcher |
获取与此对象关联的 CoreDispatcher 。 CoreDispatcher 表示可以访问 UI 线程上的 DependencyObject 的设施,即使代码是由非 UI 线程启动的。 (继承自 DependencyObject) |
| MergedDictionaries |
获取构成合并字典中各种资源字典的 ResourceDictionary 字典的集合。 |
| Size |
获取集合中包含的元素数。 |
| Source |
获取或设置提供合并资源字典的源位置的统一资源标识符(URI)。 |
| ThemeDictionaries |
获取合并的资源字典的集合,这些字典专门进行键键和组合以处理主题方案,例如为“HighContrast”提供主题值。 |