共用方式為

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
衍生
屬性
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。 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 會將 Style 置於 ResourceDictionary 中，其 x：Key 屬性值 為 「TextBlockStyle1」。 進一步在 XAML 中，{StaticResource} 標記延伸會參考資源字典中的Style，以提供TextBlock元素Style屬性的值。

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

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

逐一查看 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 隱含集合語法的範例;可以省略代表集合專案的標記。 新增為專案至集合的專案會指定為屬性之屬性元素的子專案，其基礎類型支援字典/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 取決於您所使用的程式設計語言：

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 資源可以參考的形式呈現這些值。

舊版的注意事項

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) ，以提供合併資源字典的來源位置。
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)

適用於

另請參閱