語言

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 需求

規格需求 Description
裝置系列
Windows 10 (已於 10.0.10240.0 引進)
API contract
Windows.Foundation.UniversalApiContract (已於 v1.0 引進)

備註

資源字典是存放 XAML 資源(例如樣式)的資料庫,這些資源是你的應用程式所使用的。 你可以在 XAML 中定義資源,然後使用 {StaticResource} 標記擴充功能 和 {ThemeResource} 標記擴充功能 s 在 XAML 中取得它們。 你也可以用程式碼存取資源,但這比較少見。 你可以利用資源來強制某些數值,例如筆刷顏色或像素尺寸,在整個應用程式中保持一致使用。 欲了解更多有效使用資源字典的資訊,請參閱 ResourceDictionary 與 XAML 資源參考。

ResourceDictionary 元素的用途

ResourceDictionary 類型被用作兩個屬性的值,分別是 FrameworkElement.Resources 和 Application.Resources,這兩項屬性對 UWP 應用程式的整體結構非常重要。 你從應用程式的起始專案範本取得的 XAML 檔案, FrameworkElement.Resources 的初始值會是 app.xaml 檔案,而 app.xaml 檔案的起始值可能是 Application.Resources 的初始值。 具體定義了哪些資源,取決於你使用的專案起始範本。

這個 XAML 展示了 FrameworkElement.Resources 屬性的使用。 在此案例中, FrameworkElement 是一個 頁面。 Page.Resources 屬性元素不存在 ResourceDictionary 元素,但其存在是隱含的;更多資訊請參閱下方「XAML 語法備註」。 XAML 會在 ResourceDictionary 中放置一個 Style,屬性值為「TextBlockStyle1」。 在 XAML 的更下方,{StaticResource} 標記擴充功能會參考資源字典中的 Style,為 TextBlock 元素的 Style 屬性提供值。

如圖所示的樣式其實並不會對 TextBlock 套用任何樣式,但你可以在 Microsoft Visual Studio 中新增樣式屬性。 你可以隨時使用 樣式 資源來強化統一性。

你可以用Microsoft Visual Studio來建立資源字典。 這個範例是透過以下步驟建立的:在設計表面放置 一個文字區塊 ,右鍵點擊,選擇 編輯樣式 / 建立空欄,然後 用「此文件」 在 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 將兩個 樣式 元素放入資源字典,使其在整個應用程式中都能使用。

<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>
 ...

你可以將資源納入他們自己的 XAML 檔案,方法是使用 ResourceDictionary 作為檔案的根元素。 接著你可以將這些資源納入 FrameworkElement.Resources 或 Application.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 中,ResourceDictionaryitems 的鍵是透過在代表 XAML 資源的元素上設定 x:Key 屬性來宣告的。 通常,如果你嘗試將沒有鍵值的子元素放入 ResourceDictionary,會拋出 XAML 解析異常或 Windows 執行時例外。 XAML 設計表面也可能將例外條件視為警告。 然而,有三種值得注意的情況是 ResourceDictionarychild 元素不需要 x:Key 屬性值:

透過 ResourceDictionary 迭代

你可以用 C# 或 Microsoft Visual Basic 的 ResourceDictionary 來迭代。 在很多情況下,例如使用 foreach 語法,編譯器會幫你做這種 casting,你不需要明確地 cast 到 。IEnumerable 如果你需要明確地投放,例如你想呼叫 GetEnumerator,就用 KeyValuePair<Object,Object> 約束投射到 IEnumerable<T>。

資源字典與Microsoft Visual Studio

Microsoft Visual Studio 提供資源字典新增項目頁面選項。 每當你想定義新的鬆散 XAML 資源字典時,請使用此選項,例如作為合併字典的來源。 Microsoft Visual Studio 也會在你使用 Add New Item 建立模板控制項時,為專案新增一個鬆散的 XAML 資源字典。 此資源字典提供預設主題範本。 如果你正在編輯樣式或範本的副本,而你選擇的資源位置(應用程式、頁面或獨立)還沒有資源字典,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 使用 ResourceDictionary。 支援共享的類型範例包括 Style、任何 FrameworkTemplate 子類別、 XAML 內在資料型態、筆刷、顏色與轉換。 關於哪些類型被視為可共享,請參閱 ResourceDictionary 與 XAML 資源參考。 一般而言, UIElement 衍生的類型除非來自範本並套用於特定控制實例,否則無法共享。 排除模板情況外, UIElement 在實例化後預期只會存在於物件樹中的一個位置,若 UIElement 可共享,可能會違反此原則。

實務上,ResourceDictionary 中絕大多數定義的資源會是以下之一:

  • 控制範本,包括其視覺狀態。
  • 控制元件的支援樣式
  • 像 TextBlock 這類元素,這些元素是典型應用程式介面的一部分,但不是控制項
  • 使用資料綁定的控制面板資料範本
  • 特定的 筆刷 數值,主要是 SolidColorBrush
  • 字串或其他不需要本地化的常數(需要本地化的字串和常數不應該放在 ResourceDictionary;更多資訊請參見 快速入門:翻譯 UI 資源)

在程式碼中存取 ResourceDictionary 物件

你的程式碼用來存取 ResourceDictionary 資源的 API 取決於你使用的程式語言:

欲了解更多如何在程式碼中使用 ResourceDictionary 的資訊,請參閱 ResourceDictionary 與 XAML 資源參考中的「Using a ResourceDictionary from code」章節。

系統資源

某些佈景主題資源會參考系統資源值作為基礎子值。 系統資源是在任何 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 標記。

建構函式

名稱 Description
ResourceDictionary()

初始化 ResourceDictionary 類別的新實例。

屬性

名稱 Description
Dispatcher

取得該物件所關聯的核心 派遣器 。 CoreDispatcher 代表一個設施,即使程式碼是由非 UI 執行緒發起,也能存取 UI 執行緒上的 DependencyObject。

(繼承來源 DependencyObject)
MergedDictionaries

取得組成合併詞典中各種資源字典的 ResourceDictionary 字典集合。

Size

取得集合中包含的項目數目。

Source

取得或設定一個統一資源識別碼(URI),提供合併後資源字典的來源位置。

ThemeDictionaries

獲得一組合併資源字典,專門針對主題情境進行鍵控與組合,例如提供「HighContrast」的主題值。

方法

名稱 Description
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)

適用於

另請參閱