{ThemeResource} マークアップ拡張

2025-09-11

現在アクティブなテーマに応じて異なるリソースを取得する追加のシステムロジックを使用して、リソースへの参照を評価することで、任意の XAML 属性の値を提供します。 {StaticResource} マークアップ拡張機能と同様に、リソースは ResourceDictionary で定義され、ThemeResource の使用状況は ResourceDictionary でそのリソースのキーを参照します。

XAML 属性の使用方法

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

XAML 値

任期	Description
キー	要求されたリソースのキー。このキーは、 ResourceDictionary によって最初に割り当てられます。リソースキーには、XamlName Grammar で定義されている任意の文字列を指定できます。

注釈

ThemeResource は、XAML リソースディクショナリ内の他の場所で定義されている XAML 属性の値を取得するための手法です。マークアップ拡張機能は、 {StaticResource} マークアップ拡張機能と同じ基本的な目的を果たします。動作と {StaticResource} マークアップ拡張の違いは、 ThemeResource 参照で、システムで現在使用されているテーマに応じて、異なるディクショナリをプライマリ参照の場所として動的に使用できることです。

アプリが最初に起動すると、 ThemeResource 参照によって行われたリソース参照は、起動時に使用されているテーマに基づいて評価されます。ただし、ユーザーが実行時にアクティブなテーマを変更すると、システムはすべての ThemeResource 参照を再評価し、異なる可能性があるテーマ固有のリソースを取得し、ビジュアルツリー内のすべての適切な場所で新しいリソース値を使用してアプリを再表示します。 StaticResource は、XAML の読み込み時/アプリの起動時に決定され、実行時に再評価されません。 (XAML を動的に再読み込みする表示状態などの他の手法もありますが、これらの手法は、{StaticResource} マークアップ拡張によって基本的なリソース評価が有効になるより高いレベルで動作します)。

ThemeResource は、要求されたリソースのキーを指定する 1 つの引数を受け取ります。リソースキーは、Windows ランタイム XAML では常に文字列です。リソースキーの最初の指定方法の詳細については、「 x:Key 属性」を参照してください。

リソースを定義し、サンプルコードを含む ResourceDictionary を適切に使用する方法の詳細については、「 ResourceDictionary および XAML リソース参照」を参照してください。

大事なStaticResource と同様に、ThemeResource は、XAML ファイル内で構文的に定義されたリソースへの前方参照を試みてはなりません。この操作はサポートされていません。前方参照が失敗しない場合でも、前方参照をしようとするとパフォーマンスに影響します。最適な結果を得るには、前方参照が回避されるようにリソースディクショナリの構成を調整します。

解決できないキーに ThemeResource を指定しようとすると、実行時に XAML 解析例外がスローされます。デザインツールでは、警告やエラーが表示される場合もあります。

Windows ランタイム XAML プロセッサの実装では、 ThemeResource のバッキングクラス表現はありません。コードで最も近いのは、Contains や *TryGetValue の呼び出しなど、ResourceDictionary のコレクション API を使用することです。

ThemeResource はマークアップ拡張機能です。マークアップ拡張は通常、リテラル値またはハンドラー名以外の属性値をエスケープする必要があり、特定の型またはプロパティに型コンバーターを配置するよりもグローバルな要件である場合に実装されます。 XAML のすべてのマークアップ拡張では、属性構文で "{" 文字と "}" 文字が使用されます。これは、マークアップ拡張機能が属性を処理する必要があることを XAML プロセッサが認識する規則です。

{StaticResource} ではなく {ThemeResource} を使用するタイミングと方法

ThemeResource がリソースディクショナリ内の項目に解決する規則は、通常、StaticResource と同じです。 ThemeResource 参照は、ThemeDictionaries コレクションで参照される ResourceDictionary ファイルに拡張できますが、StaticResource でもこれを行うことができます。違いは、 ThemeResource は実行時に再評価でき 、StaticResource では再評価できないということです。

各テーマディクショナリのキーのセットは、アクティブなテーマに関係なく、キー付きリソースの同じセットを提供する必要があります。 HighContrast テーマディクショナリに特定のキー付きリソースが存在する場合は、その名前の別のリソースも Light と Default に存在する必要があります。これが正しくない場合、ユーザーがテーマを切り替えると、アプリが正しく表示されないと、リソース検索が失敗する可能性があります。ただし、テーマディクショナリには、サブ値を提供するために同じスコープ内からのみ参照されるキー付きリソースを含めることができます。これらは、すべてのテーマで同等である必要はありません。

一般に、テーマディクショナリにリソースを配置し、 ThemeResource を使用してそれらのリソースへの参照を行う必要があるのは、それらの値がテーマ間で変更される場合、または変更される値によってサポートされている場合のみです。これは、次の種類のリソースに適しています。

ブラシ、特に SolidColorBrush の色。これらは、既定の XAML コントロールテンプレート (generic.xaml) での ThemeResource の使用法の約 80% を構成します。
罫線、オフセット、余白、パディングなどのピクセル値。
FontFamily や FontSize などのフォント プロパティ。
GridViewItem や ListViewItem など、通常はシステムスタイルで動的なプレゼンテーションに使用される限られた数のコントロールの完全なテンプレート。
テキスト表示スタイル (通常、フォントの色、背景、場合によってはサイズを変更するため)。

Windows ランタイムは、 ThemeResource によって参照されることを具体的に意図した一連のリソースを提供します。これらはすべて XAML ファイル themeresources.xaml の一部として一覧表示されます。これは、Windows ソフトウェア開発キット (SDK) の一部として include/winrt/xaml/design フォルダーで入手できます。テーマブラシおよび themeresources.xaml で定義されているその他のスタイルのドキュメントについては、 XAML テーマリソースを参照してください。ブラシは、使用可能な 3 つのアクティブなテーマのそれぞれに対して各ブラシが持つ色の値を示す表に記載されています。

コントロールテンプレート内のビジュアル状態の XAML 定義では、テーマの変更によって変更される可能性がある基になるリソースがある場合は常に ThemeResource 参照を使用する必要があります。通常、システムテーマの変更では、表示状態の変更も発生しません。この場合、リソースは ThemeResource 参照を使用して、まだアクティブな表示状態の値を再評価できるようにする必要があります。たとえば、特定の UI パーツのブラシの色とそのプロパティの 1 つを変更する表示状態があり、そのブラシの色がテーマごとに異なる場合は、 ThemeResource 参照を使用して、既定のテンプレートでそのプロパティの値を指定し、その既定のテンプレートに対するビジュアル状態の変更を行う必要があります。

ThemeResource の使用法は、一連の依存値で見られる場合があります。たとえば、キー付きリソースでもある SolidColorBrush で使用される Color 値では、ThemeResource 参照を使用できます。ただし、キー付きの SolidColorBrush リソースを使用する UI プロパティも ThemeResource 参照を使用するため、テーマが変更されたときに動的な値の変更を有効にする各 Brush 型プロパティが具体的に使用されます。

注{ThemeResource} テーマ切り替え時のランタイムリソース評価は Windows 8.1 XAML ではサポートされていますが、Windows 8 を対象とするアプリの XAML ではサポートされていません。

システムリソース

一部のテーマリソースでは、システムリソースの値が基になるサブ値として参照されます。システムリソースは、XAML リソースディクショナリには見つからない特殊なリソース値です。これらの値は、Windows ランタイム XAML サポートの動作に依存してシステム自体から値を転送し、XAML リソースが参照できる形式で値を表します。たとえば、RGB 色を表す "SystemColorButtonFaceColor" という名前のシステムリソースがあります。この色は、Windows ランタイムアプリと Windows ランタイムアプリに固有ではないシステムの色とテーマの側面に由来します。

多くの場合、システムリソースはハイコントラストテーマの基になる値です。ユーザーはハイコントラストテーマの色の選択を制御しており、ユーザーは Windows ランタイムアプリに固有ではないシステム機能を使用してこれらの選択を行います。システムリソースを ThemeResource 参照として参照することで、Windows ランタイムアプリのハイコントラストテーマの既定の動作では、ユーザーによって制御され、システムによって公開されるテーマ固有の値を使用できます。また、ランタイムテーマの変更がシステムによって検出された場合、参照は再評価対象としてマークされるようになりました。

{ThemeResource} の使用例

ThemeResource の使用方法を説明するために、既定の generic.xaml ファイルと themeresources.xaml ファイルから取得した XAML の例を次に示します。 1 つのテンプレート (既定の ボタン) と、テーマの変更に対応するために 2 つのプロパティ (背景と前景) がどのように宣言されているかを見ていきます。

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

ここでは、プロパティは Brush 値を受け取り、およびという名前の ButtonForegroundThemeBrush リソースへの参照は ThemeResource を使用して作成されます。

これらの同じプロパティは、 Button の一部の表示状態によっても調整されます。特に、ボタンをクリックすると背景色が変わります。ここでは、ビジュアル状態のストーリーボードの背景アニメーションと前景アニメーションでも、キーフレーム値として ThemeResource を使用するブラシへの DiscreteObjectKeyFrame オブジェクトと参照が使用されます。

<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 を使用して参照する必要があります。