ResourceDictionary 類別

定義

命名空間:

Microsoft.UI.Xaml

定義應用程式所使用的 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 是 Page。 There is no ResourceDictionary element subordinate to the Page.Resources property element, but its presence is implied; for more info see the "Notes on XAML syntax" section below. XAML 會將 StyleResourceDictionary 放入 ，其 x：Key 屬性值 為 「TextBlockStyle1」。 在 XAML 中進一步，{StaticResource} 標記延伸會參考 Style 資源字典中的 ，以提供TextBlock元素Style屬性的值。

如所示的 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>

這個 XAML 來自 AtomPub 範例的 AppPage.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 同樣定義 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 中，專案的索引鍵 ResourceDictionary 是藉由在代表 XAML 資源的元素上設定 x：Key 屬性來宣告。 一般而言，如果您嘗試將沒有索引鍵值的子專案放入 ResourceDictionary 中，這會擲回 XAML 剖析例外狀況或Windows 執行階段例外狀況。 XAML 設計介面可能也會將例外狀況標記為警告。 不過，有三個值得注意的情況 ResourceDictionary 是子項目不需要 x：Key 屬性值 ：

• Style資源可以使用其TargetType值作為隱含資源索引鍵。 如需樣式和控制項範本隱含索引鍵如何運作的詳細資訊，請參閱 設定控制項的樣式。
• ResourceDictionary具有Source值的專案，代表ResourceDictionary.MergedDictionaries值在 上 ResourceDictionary 不能有x：Key 屬性。 在每個合併字典檔案中， (URI 所參考的字典檔案作為 其來源) 您需要每個資源的索引鍵。
• 基於舊版原因，可以使用 x：Name 屬性 ，而不是 x：Key 屬性。 不過， x：Name 屬性 本身不會啟用該專案的 XAML 資源查閱。 x：Name 屬性識別慣例用於某些案例，例如定義腳本動畫。 如需詳細資訊，請參閱 x：Name 屬性。

逐一查看 ResourceDictionary

您可以在 C# 中逐一查看 ResourceDictionary 。 在許多情況下，例如使用 foreach 語法，編譯器會為您執行此轉換，而且您不需要明確地轉換成 IEnumerable 。 如果您需要明確轉換，例如，如果您想要呼叫GetEnumerator，請使用 KeyValuePair<Object,Object> 條件約束轉換成IEnumerable。

ResourceDictionary 和 Microsoft Visual Studio

Microsoft Visual Studio 提供資源字典的 [新增專案 ] 頁面選擇。 每當您想要定義新的鬆散 XAML 資源字典時，請使用此選項，例如做為合併字典的來源。 每當您使用 [新增專案 ] 建立樣板化控制項時，Microsoft Visual Studio 也會將鬆散的 XAML 資源字典新增至專案。 此資源字典提供預設的主題範本。 如果您要編輯樣式或範本的複本，且 ResourceDictionary 所選資源位置 (應用程式、頁面或獨立) 尚不存在，Microsoft Visual Studio 可能會為您在 XAML 中建立新的 ResourceDictionary 。

XAML 語法的注意事項

請注意， 的 ResourceDictionary XAML 隱含集合語法不包含 的物件 ResourceDictionary 專案。 這是 XAML 隱含集合語法的範例;可以省略代表集合專案的標記。 新增為專案至集合的專案會指定為屬性之屬性元素的子專案，其基礎類型支援字典/map 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 或 Item 索引子。
• 不屬於集合支援的 API，例如 Source，在所有語言中都相同。

For more info on how to use ResourceDictionary in code, see "Using a ResourceDictionary from code" section of ResourceDictionary and XAML resource references.

系統資源

有些佈景主題資源會將系統資源值當作基礎子值來參考。 系統資源是在任何 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)

另請參閱

• ResourceDictionary 與 XAML 資源參考
• 應用程式資源和當地語系化範例
• {ThemeResource} 標記延伸
• {StaticResource} 標記延伸
• x:Key 屬性 \(部分機器翻譯\)