言語、スケール、ハイ コントラスト、その他の修飾子用にリソースを調整する

  • [アーティクル]

このトピックでは、リソース修飾子の一般概念、使用方法、各修飾子名の目的について説明します。 使用可能な修飾子の値を網羅したリファレンス テーブルについては、「ResourceContext.QualifierValues」を参照してください。

アプリでは、表示言語、ハイ コントラスト設定、表示倍率などのランタイム コンテキストに合わせて調整されたアセットやリソースを読み込むことができます。 これを行うには、リソースのフォルダーまたはファイルの名前を、これらのコンテキストに対応した修飾子の名前と値に一致させます。 たとえば、ハイ コントラスト モードでは別のセットのイメージ アセットをアプリに読み込む、ということもできます。

アプリのローカライズの価値提案の詳細については、「グローバリゼーションとローカライズ」をご覧ください。

修飾子名、修飾子の値、修飾子

修飾子名は、一連の修飾子の値にマップされるキーです。 修飾子の名前と修飾子の値を次に示します。

Context 修飾子名 修飾子の値
ハイ コントラスト設定 contrast standard、high、black、white

修飾子は、修飾子名と修飾子の値を組み合わせて作成します。 <qualifier name>-<qualifier value> は修飾子の形式です。 contrast-standard は修飾子の例です。

ハイ コントラストの場合、修飾子のセットは contrast-standard、contrast-high、contrast-black、contrast-white になります。 修飾子名と修飾子の値では、大文字と小文字が区別されません。 たとえば、contrast-standard と Contrast-Standard は同じ修飾子であると見なされます。

修飾子をフォルダー名に使用する

アセット ファイルが含まれるフォルダーに、修飾子を使用して名前を付ける例を次に示します。 修飾子ごとに複数のアセット ファイルがある場合は、フォルダー名に修飾子を使用します。 これにより、フォルダー レベルで一度だけ修飾子を設定すると、この修飾子がフォルダー内のすべての項目に適用されます。

\Assets\Images\contrast-standard\<logo.png, and other image files>
\Assets\Images\contrast-high\<logo.png, and other image files>
\Assets\Images\contrast-black\<logo.png, and other image files>
\Assets\Images\contrast-white\<logo.png, and other image files>

上の例のようにフォルダーの名前を付けた場合、アプリはハイ コントラスト設定を使用して、適切な修飾子名が適用されたフォルダーからリソース ファイルを読み込みます。 このため、設定が [ハイ コントラスト 黒] であれば、\Assets\Images\contrast-black フォルダー内のリソース ファイルが読み込まれます。 設定が [なし] (コンピューターがハイ コントラスト モードではない) の場合は、\Assets\Images\contrast-standard フォルダー内のリソース ファイルが読み込まれます。

修飾子をファイル名に使用する

フォルダーを作成して名前を付ける代わりに、修飾子を使用してリソース ファイル自体の名前を付けることもできます。 1 つの修飾子につきリソース ファイルが 1 つのみの場合は、この方法が適しています。 次に例を示します。

\Assets\Images\logo.contrast-standard.png
\Assets\Images\logo.contrast-high.png
\Assets\Images\logo.contrast-black.png
\Assets\Images\logo.contrast-white.png

読み込まれるのは、設定に最も適した修飾子を含む名前のファイルです。 ファイル名についても、フォルダー名と同様の照合ロジックが使用されます。

文字列または画像リソースを名前で参照する

文字列またはイメージ リソースを名前で参照する方法の詳細については、次のトピックを参照してください。

修飾子の実際の一致と中立的な一致

修飾子の値のすべてにリソース ファイルを指定する必要はありません。 たとえば、ハイ コントラスト用と標準コントラスト用にビジュアル アセットを各 1 つのみ必要とする場合は、これらのアセット名を次のように付けることができます。

\Assets\Images\logo.contrast-high.png
\Assets\Images\logo.png

最初のファイル名には、contrast-high 修飾子が含まれています。 ハイ コントラストが [オン] になっている場合、この修飾子は、あらゆるハイ コントラスト設定に対する実際の一致です。 言い換えると、これは近似一致であり、優先されます。 この場合のように、実際の一致は、修飾子に実際の値が含まれている場合にのみ発生します。 この場合、 high は の 実際 の値です contrast。

logo.png というファイル名には、contrast 修飾子がまったく含まれていません。 修飾子がない値は、中立的です。 優先される一致が見つからない場合、中立値はフォールバックの一致として使用されます。 この例では、ハイ コントラストがオフになっている場合、実際の一致はありません。 見つかるベスト マッチが中立的な一致であるため、logo.png というアセットが読み込まれます。

logo.png の名前を logo.contrast-standard.png に変更すると、ファイル名に実際の修飾子の値が含まれます。 ハイ コントラストがオフになっている場合、logo.contrast-standard.png との実際の一致があり、このアセット ファイルが読み込まれます。 このため、別々の一致が原因ですが、同じ条件下で同じファイルが読み込まれます。

必要なアセット セットが、ハイ コントラスト用に 1 つと標準コントラスト用に 1 つのみである場合は、ファイル名の代わりにフォルダー名を使用できます。 この場合、フォルダー名を省略すると、完全に中立的な一致になります。

\Assets\Images\contrast-high\<logo.png, and other images to load when high contrast theme is not None>
\Assets\Images\<logo.png, and other images to load when high contrast theme is None>

修飾子の照合のしくみの詳細については、「 MRT Core を使用してリソースを管理する」を参照してください。

複数の修飾子

修飾子は、フォルダー名とファイル名で組み合わせることができます。 たとえば、ハイ コントラスト モードがオンであり表示倍率が 400 のときに、イメージ アセットをアプリに読み込むとします。 これを行う方法の 1 つは、入れ子になったフォルダーの使用です。

\Assets\Images\contrast-high\scale-400\<logo.png, and other image files>

logo.pngと他のファイルを読み込むには、設定が両方の修飾子と一致している必要があります。

もう 1 つのオプションは、複数の修飾子を結合して 1 つのフォルダー名にすることです。

\Assets\Images\contrast-high_scale-400\<logo.png, and other image files>

フォルダー名として、複数の修飾子をアンダー スコアで結合します。 <qualifier1>[_<qualifier2>...] という形式を使用します。

同じ形式で、複数の修飾子を結合して 1 つのファイル名にすることもできます。

\Assets\Images\logo.contrast-high_scale-400.png

アセット作成に使用するツールとワークフローや、読みやすさや管理のしやすさによって、すべての修飾子に単一の命名方法を選択することも、修飾子によって異なる方法を組み合わせることもできます。

AlternateForm

特別な目的でリソースの代替フォームを提供するには、alternateform 修飾子を使います。 これは通常、日本のアプリ開発者のみが、値 msft-phonetic が予約されているふりがな文字列を提供するために使用されます (「 ローカライズの準備方法」の「並べ替えることができる日本語文字列のふりがなをサポートする」を参照してください)。

ターゲット システムとアプリのうちいずれかが、alternateform 修飾子と一致する値を提供する必要があります。 カスタムの alternateform 修飾子の値に msft- プレフィックスを使用しないでください。

構成

configuration 修飾子名が必要になる可能性は高くありません。 テストのみのリソースなど、オーサリング時環境にのみ使用されるリソースを指定するために使用できます。

configuration 修飾子は、MS_CONFIGURATION_ATTRIBUTE_VALUE 環境変数の値と最も一致するリソースを読み込むために使用します。 このため、この変数は、関連するリソースに割り当てられた文字列値 (designer や test など) に設定することができます。

この例を、

contrast 修飾子は、ハイ コントラスト設定と最も一致するリソースを提供するために使用します。

DXFeatureLevel

dxfeaturelevel 修飾子名が必要になる可能性は高くありません。 これは Direct3D ゲーム アセットで使用し、以前の特定な下位レベル ハードウェア構成に一致するように、下位レベルのリソースを読み込むために用意されたものです。 ただ、このハードウェア構成はあまり普及していないため、この修飾子は使用しないことをお勧めします。

HomeRegion

homeregion 修飾子は、国または地域のユーザー設定に対応します。 ユーザーが住んでいる地域の場所を表します。 値には、有効な BCP-47 region タグが含まれます。 つまり、ISO 3166-1 alpha-2 の 2 文字の地域番号に、構成地域用の ISO 3166-1 numeric の 3 桁の地域番号のセットを加えた値となります (国連統計部 M49 地域番号構成に関するページをご覧ください)。 "Selected economic and other groupings" の番号は有効ではありません。

言語

language 修飾子は、表示言語設定に対応します。 値には、有効な BCP 47 language タグが含まれます。 言語の一覧については、IANA 言語サブタグ レジストリに関するページをご覧ください。

アプリで複数の表示言語をサポートする必要があり、コードまたは XAML マークアップ内に文字列リテラルが含まれている場合は、その文字列をコードまたはマークアップからリソース ファイル (.resw) に移動します。 アプリでサポートする各言語用に、このリソース ファイルを翻訳したコピーを作成することができます。

language 修飾子は通常、リソース ファイル (.resw) が含まれているフォルダーの命名に使用します。

\Strings\language-en\Resources.resw
\Strings\language-ja\Resources.resw

language 修飾子の language- の部分 (修飾子名) は省略することができます。 これは他の種類の修飾子には適用されません。また、適用できるのはフォルダー名の場合のみです。

\Strings\en\Resources.resw
\Strings\ja\Resources.resw

フォルダーに名前を付ける代わりに、language 修飾子を使用してリソース ファイル自体の名前を付けることもできます。

\Strings\Resources.language-en.resw
\Strings\Resources.language-ja.resw

文字列リソースを使用してアプリをローカライズ可能にする方法と、アプリ内で文字列リソースを参照する方法について詳しくは、UI 文字列のローカライズに関するページをご覧ください。

LayoutDirection

layoutdirection 修飾子は、表示言語設定のレイアウト方向に対応します。 たとえば、アラビア語やヘブライ語などの右から左に記述する言語では、イメージの反転が必要になる場合があります。 UI のレイアウト パネルとイメージは、FlowDirection プロパティを設定すると、レイアウト方向が正しく反映されます (「レイアウトやフォントの調整と RTL のサポート」をご覧ください)。 layoutdirection 修飾子は、単純な反転だけでは十分でないケースを想定し、特定の読み取り順序の辞書やテキスト配置にも、より一般的な方法で対応することができます。

スケール

Windows では、ディスプレイの DPI (1 インチあたりのドット数) と、デバイスの視聴距離に基づいて各ディスプレイの倍率が自動的に選択されます。 「有効ピクセルと倍率」をご覧ください。 Windows で最適なサイズを選択したり、最も近いサイズを使用して拡大または縮小したりできるように、いくつかの推奨されるサイズ (少なくとも、100、200、400) で画像を作成する必要があります。 Windows で表示倍率に対して正確なサイズの画像を含む物理ファイルを識別できるように、scale 修飾子を使用します。 リソースのスケールは、DisplayInformation.ResolutionScale の値、または次に大きい拡大リソースに一致します。

フォルダー レベルで修飾子を設定する例を次に示します。

\Assets\Images\scale-100\<logo.png, and other image files>
\Assets\Images\scale-200\<logo.png, and other image files>
\Assets\Images\scale-400\<logo.png, and other image files>

この例では、ファイル レベルで修飾子を設定します。

\Assets\Images\logo.scale-100.png
\Assets\Images\logo.scale-200.png
\Assets\Images\logo.scale-400.png

と の両方scaleのリソースを修飾する方法については、「targetsize のイメージ リソースを修飾する」を参照してください。targetsize

TargetSize

修飾子はtargetsize、主に、エクスプローラーに表示するファイルの種類の関連付けアイコンまたはプロトコル アイコンを指定するために使用されます。 この修飾子の値は、正方形のイメージの辺の長さを RAW (物理) ピクセル単位で表します。 エクスプローラーの表示設定に値が一致するリソースが読み込まれます。正確に一致する対象が存在しない場合は、次に大きな値のリソースが読み込まれます。

アプリ パッケージ マニフェスト デザイナーの [ビジュアル資産] タブで、複数サイズのアプリ アイコン (/Assets/Square44x44Logo.png) に対応する targetsize 修飾子の値を表すアセットを定義できます。

と の両方scaleのリソースを修飾する方法については、「targetsize のイメージ リソースを修飾する」を参照してください。targetsize

テーマ

修飾子は、既定の theme アプリ モード設定に最も一致するリソース、または Application.RequestedTheme を使用したアプリのオーバーライドを提供するために使用されます。

シェル ライト テーマとプレートなしのリソース

Windows 10 May 2019 更新プログラムでは、Windows シェル用に新しい "ライト" テーマが導入されました。 その結果、以前は暗い背景に表示されていた一部のアプリケーション アセットが、明るい背景に表示されるようになりました。 タスク バーとウィンドウ スイッチャー (Alt + Tab、タスク ビューなど) に altform-unplated アセットを提供していたアプリでは、明るい背景で使用できるコントラストがあることを確認する必要があります。

ライト テーマ固有のアセットを提供する

シェル ライト テーマ用に調整されたリソースを提供する必要があるアプリでは、新しい代替フォーム リソース修飾子 altform-lightunplated を使用できます。 この修飾子には、既存の altform-unplated 修飾子が反映されています。

ダウンレベルの考慮事項

アプリでは、theme-light 修飾子と altform-unplated 修飾子を一緒に使用しないでください。 これを行うと、リソースがタスク バーに読み込まれる方法のため、RS5 以前のバージョンの Windows で予期しない動作が発生します。 以前のバージョンの Windows では、theme-light バージョンが正しく使用されない場合があります。 altform-lightunplated 修飾子では、この問題が回避されます。

互換性の動作

下位互換性のため、Windows には、モノクロ アイコンを検出し、意図した背景とのコントラストが適切かどうかをチェックするロジックが含まれています。 アイコンがコントラストの要件を満たしていない場合、Windows はアセットの contrast-white バージョンを検索します。 それが使用できない場合は、Windows はアセットのプレートありバージョンを使用するようにフォールバックします。

重要な API