{ThemeResource} マークアップ拡張

[アーティクル]
07/05/2024

現在アクティブなテーマに応じて異なるリソースを取得する追加のシステムロジックを使用して、リソースへの参照を評価することで、任意の 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 は、要求されたリソースのキーを指定する 1 つの引数を受け取ります。リソースキーは常に XAML の文字列Windows ランタイム。リソースキーの最初の指定方法の詳細については、「 x:Key 属性」を参照してください。

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

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

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

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

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} の使用例

既定の generic.xaml ファイルと themeresources.xaml ファイルから取得した XAML の例を次に示します。 ThemeResource の使用方法を説明します。 1 つのテンプレート (既定の Button) と、テーマの変更に対応するために 2 つのプロパティ (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 値を受け取り、 SolidColorBrush ButtonBackgroundThemeBrush および ButtonForegroundThemeBrush という名前のリソースへの参照は、 ThemeResource を使用して作成されます。

これらの同じプロパティは、 Button の一部の表示状態によっても調整されます。特に、ボタンをクリックすると背景色が変わります。ここでも、ビジュアル状態ストーリーボードの Background および Foreground アニメーションでは、キーフレーム値として 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 を使用して参照する必要があります。

Windows 8 の動作

Windows 8 では、 ThemeResource マークアップ拡張機能はサポートされていません。Windows 8.1 以降で使用できます。また、Windows 8 では、Windows ランタイムアプリのテーマ関連リソースを動的に切り替えることはサポートされていませんでした。 XAML テンプレートとスタイルのテーマの変更を取得するには、アプリを再起動する必要がありました。これは優れたユーザーエクスペリエンスではないので、アプリは Windows 8.1 を再コンパイルしてターゲットにすることを強くお勧めします。これにより、 ThemeResource 使用法でスタイルを使用でき、ユーザーが行うときにテーマを動的に切り替えることができます。 Windows 8 用にコンパイルされたが、Windows 8.1 で実行されているアプリでは、引き続き Windows 8 の動作が使用されます。