{ThemeResource} 標記延伸

  • 發行項

藉由評估資源的參考來提供任何 XAML 屬性的值，以及根據目前使用中主題擷取不同資源的其他系統邏輯。 類似於 {StaticResource} 標記延伸，資源是在 ResourceDictionary 中定義，而 ThemeResource 使用方式會參考 ResourceDictionary 中該資源的索引鍵。

XAML 屬性用法

<object property="{ThemeResource key}" .../>

XAML 值

詞彙 描述
索引鍵 要求資源的金鑰。 此索引鍵一開始是由 ResourceDictionary 指派。 資源索引鍵可以是 XamlName 文法中定義的任何字串。

備註

ThemeResource 是一種技術，可用來取得 XAML 屬性的值，該屬性是在 XAML 資源字典中其他地方定義的。 標記延伸與 {StaticResource} 標記延伸具有相同的基本用途。 行為與 {StaticResource} 標記延伸的差異在於 ，ThemeResource 參考可以動態使用不同的字典做為主要查閱位置，視系統目前使用的主題而定。

當應用程式第一次啟動時，ThemeResource 參考所做的任何資源參考都會根據啟動時使用的主題進行評估。 但是，如果使用者後續在執行階段變更使用中主題，系統會重新評估每個 ThemeResource 參考、擷取可能不同的主題特定資源，並在視覺化樹狀結構的所有適當位置以新的資源值重新顯示應用程式。 StaticResource 是在 XAML 載入時間/應用程式啟動時決定，而且不會在執行階段重新評估。 (還有其他技術，例如動態重新載入 XAML 的視覺狀態，但這些技術在比 {StaticResource} 標記延伸啟用的基本資源評估更高的層級上運作)。

ThemeResource 會採用一個引數，指定所要求資源的索引鍵。 資源索引鍵一律是 Windows 執行階段 XAML 中的字串。 如需最初如何指定資源索引鍵的詳細資訊，請參閱 x:Key attribute。

有關如何定義資源和正確使用 ResourceDictionary 的詳細資訊 (包括範例程式碼)，請參閱 ResourceDictionary 和 XAML 資源參考。

重要：與 StaticResource 一樣，ThemeResource 不得嘗試對 XAML 檔案中進一步按詞法定義的資源進行向前參考。 不支援嘗試這樣做。 即使前向參考沒有失敗，嘗試進行向前參考也會帶來效能損失。 為了獲得最佳結果，請調整資源字典的組成，以避免向前參考。

嘗試將 ThemeResource 指定給無法解析在執行階段擲回 XAML 剖析例外狀況的索引鍵。 設計工具也可能提供警告或錯誤。

在 Windows 執行階段 XAML 處理器實作中，ThemeResource 沒有支援類別表示法。 程式碼中最接近的等效項是使用 ResourceDictionary 的集合 API，例如呼叫 Contains 或 *TryGetValue。

ThemeResource是標記延伸。 如果必須將屬性 (Attribute) 值加上逸出符號，以免成為常值或處理常式名稱，而且這個動作必須更全面地實施 (而不是只對特定類型或屬性 (Property) 設定類型轉換子 (Type Converter))，則通常會實作標記延伸。 XAML 中的所有標記延伸在其屬性語法中都使用「{" and "}」字元，這是 XAML 處理器識別標記延伸必須處理屬性的慣例。

使用 {ThemeResource} 而不是 {StaticResource} 的時機和方式

ThemeResource 解析為資源字典中的項目的規則通常與 StaticResource 相同。 ThemeResource 查閱可以延伸至 ThemeDictionaries 集合中所參考的 ResourceDictionary 檔案，但 StaticResource 也可以這麼做。 差別在於 ThemeResource 可以在執行階段重新評估，而 StaticResource 則無法重新評估。

每個主題字典中的索引鍵集合都應該提供相同的索引鍵資源集，無論哪個主題為使用中。 如果特定的索引鍵資源存在於 HighContrast 主題字典中，則具有該名稱的另一個資源也應該存在於 Light 和 Default 中。 如果不正確，當使用者切換主題，且您的應用程式看起來不正確時，資源查閱可能會失敗。 不過，主題字典可以包含僅從相同範圍內參考的索引鍵資源，以提供子值；這些不需要在所有主題中都相等。

一般而言，您應該將資源放在主題字典中，並且只有在這些值可以在主題之間變更，或由變更的值支援時，才使用 ThemeResource 來參考這些資源。 這適用於下列類型的資源：

  • 筆刷，特別是 SolidColorBrush 的色彩。 這些內容約佔預設 XAML 控制項範本中 ThemeResource 使用量的 80% (generic.xaml)。
  • 框線、位移、邊界及邊框間距等的像素值。
  • 字型屬性，例如 FontFamily 或 FontSize。
  • 有限數量的控制項的完整範本，這些控制項通常是系統樣式的並用於動態呈現，例如 GridViewItem 和 ListViewItem。
  • 文字顯示樣式 (通常是變更字型色彩、背景和可能的大小)。

Windows 執行階段提供一組特別要由 ThemeResource 參考的資源。 這些全都列為 XAML 檔案 themeresources.xaml 的一部分，可在 include/winrt/xaml/design 資料夾中做為 Windows 軟體開發套件 (SDK) 的一部分使用。 如需主題筆刷和 themeresources.xaml 中所定義之其他樣式的檔案，請參閱 XAML 主題資源。 筆刷會記錄在資料表中，告訴您每個筆刷針對三個可能使用中主題中每個筆刷的色彩值。

每當有基礎資源因為主題變更而變更時，控制項範本中視覺狀態的 XAML 定義應該使用 ThemeResource 參考。 系統主題變更通常也不會造成視覺狀態變更。 在此案例中，資源需要使用 ThemeResource 參考，以便重新評估仍使用中視覺狀態的值。 例如，如果您的視覺狀態會變更特定 UI 部分及其其中一個屬性的筆刷色彩，且該筆刷色彩與每個主題不同，則應該使用 ThemeResource 參考，在預設範本中提供該屬性的值，以及該預設範本的任何視覺狀態修改。

ThemeResource 使用方式可能會在一系列相依值中看到。 例如，SolidColorBrush 所使用的 Color 值，也是索引鍵資源，可能會使用 ThemeResource 參考。 但是，任何使用索引鍵 SolidColorBrush 資源的 UI 屬性也會使用 ThemeResource 參考，因此它會在主題變更時，特別啟用動態值變更的每個 Brush 類型屬性。

注意{ThemeResource}：Windows 8.1 XAML 支援主題切換的執行階段資源評估，但針對以 Windows 8 為目標的應用程式不支援 XAML。

系統資源

某些主題資源會參考系統資源值做為基礎子值。 系統資源是任何 XAML 資源字典中找不到的特殊資源值。 這些值依賴 XAML 支援 Windows 執行階段行為，從系統本身轉送值，並以 XAML 資源可以參考的形式來表示這些值。 例如，有一個名為「SystemColorButtonFaceColor」的系統資源代表 RGB 色彩。 這種色彩來自系統色彩和主題的各個層面，這些色彩不只是 Windows 執行階段和 Windows 執行階段應用程式專屬。

系統資源通常是高對比度主題的基礎值。 使用者可控制其高對比度主題的色彩選擇，而使用者會使用非 Windows 執行階段應用程式專屬的系統功能來進行這些選擇。 透過將系統資源做為 ThemeResource 參考進行參考，Windows 執行階段應用程式的高對比度主題的預設行為，可以使用這些由使用者控制並由系統公開的特定主題的值。 此外，如果系統偵測到執行階段主題變更，則參考現在會標示為重新評估。

範例 {ThemeResource} 使用量

以下是從預設 generic.xaml 和 themeresources.xaml 檔案取得的一些範例 XAML，說明如何使用 ThemeResource。 我們只會查看一個範本 (預設的 Button)，以及如何宣告兩個屬性 (Background 和 Foreground) 以回應主題變更。

    <!-- Default style for Windows.UI.Xaml.Controls.Button -->
    <Style TargetType="Button">
        <Setter Property="Background" Value="{ThemeResource ButtonBackgroundThemeBrush}" />
        <Setter Property="Foreground" Value="{ThemeResource ButtonForegroundThemeBrush}"/>
...

此處，屬性採用 Brush 值，並使用 ThemeResource 參考名為 ButtonBackgroundThemeBrush 和 ButtonForegroundThemeBrush 的 SolidColorBrush 資源。

這些相同的屬性也可以透過 Button 的某些視覺狀態進行調整。 值得注意的是，按下按鈕時，背景色彩會變更。 在此處，視覺狀態分鏡腳本中的 Background 和 Foreground 動畫也會使用 DiscreteObjectKeyFrame 物件和以 ThemeResource 做為主要畫面值的筆刷參考。

<VisualState x:Name="Pressed">
  <Storyboard>
    <ObjectAnimationUsingKeyFrames Storyboard.TargetName="Border"
        Storyboard.TargetProperty="Background">
      <DiscreteObjectKeyFrame KeyTime="0" Value="{ThemeResource ButtonPressedBackgroundThemeBrush}" />
    </ObjectAnimationUsingKeyFrames>
    <ObjectAnimationUsingKeyFrames Storyboard.TargetName="ContentPresenter"
         Storyboard.TargetProperty="Foreground">
       <DiscreteObjectKeyFrame KeyTime="0" Value="{ThemeResource ButtonPressedForegroundThemeBrush}" />
    </ObjectAnimationUsingKeyFrames>
  </Storyboard>
</VisualState>

這些筆刷都是在 generic.xaml 中稍早定義：這些筆刷必須在使用它們的任何範本之前定義，以避免 XAML 向前參考。 以下是「預設」主題字典的這些定義。

    <ResourceDictionary.ThemeDictionaries>
        <ResourceDictionary x:Key="Default">
...
            <SolidColorBrush x:Key="ButtonBackgroundThemeBrush" Color="Transparent" />
            <SolidColorBrush x:Key="ButtonForegroundThemeBrush" Color="#FFFFFFFF" />
...
            <SolidColorBrush x:Key="ButtonPressedBackgroundThemeBrush" Color="#FFFFFFFF" />
            <SolidColorBrush x:Key="ButtonPressedForegroundThemeBrush" Color="#FF000000" />
...

然後，其他每個主題字典也會定義這些筆刷，例如：

        <ResourceDictionary x:Key="HighContrast">
            <!-- High Contrast theme resources -->
...
            <SolidColorBrush x:Key="ButtonBackgroundThemeBrush" Color="{ThemeResource SystemColorButtonFaceColor}" />
            <SolidColorBrush x:Key="ButtonForegroundThemeBrush" Color="{ThemeResource SystemColorButtonTextColor}" />

...
            <SolidColorBrush x:Key="ButtonPressedBackgroundThemeBrush" Color="{ThemeResource SystemColorButtonTextColor}" />
            <SolidColorBrush x:Key="ButtonPressedForegroundThemeBrush" Color="{ThemeResource SystemColorButtonFaceColor}" />

在此處，Color 值是對系統資源的另一個 ThemeResource 參考。 如果您參考系統資源，而且想要變更以回應主題變更，您應該使用 ThemeResource 進行參考。

Windows 8 行為

Windows 8 不支援 ThemeResource 標記延伸，從 Windows 8.1 開始即可使用。 此外，Windows 8 不支援動態切換 Windows 執行階段應用程式的主題相關資源。 應用程式必須重新啟動，才能挑選 XAML 範本和樣式的主題變更。 這並非良好的使用者體驗，因此強烈建議應用程式重新編譯並以 Windows 8.1 為目標，以便它們可以使用具有 ThemeResource 用法的樣式，並可以在使用者切換主題時動態切換主題。 針對 Windows 8 編譯但在 Windows 8.1 上執行的應用程式會繼續使用 Windows 8 行為。

設計階段工具支援 {ThemeResource} 標記延伸

當您在 XAML 頁面中使用 {ThemeResource} 標記延伸時，Microsoft Visual Studio 2013 可以在 Microsoft IntelliSense 下拉式清單中包含可能的索引鍵值。 例如，只要輸入「{ThemeResource」，就會顯示 XAML 主題資源中的任何資源索引鍵。

一旦資源索引鍵做為任何 {ThemeResource} 用法的一部分存在，「前往定義」(F12) 功能就可以解析該資源並顯示設計階段的 generic.xaml，其中定義了主題資源。 因為主題資源定義多次 (每個主題)，前往定義會帶您前往檔案中找到的第一個定義，也就是 Default 的定義。 如果您想要其他定義，您可以在檔案內搜尋索引鍵名稱，並尋找其他主題的定義。