次の方法で共有

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

  • [アーティクル]

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

アプリは、表示言語、ハイ コントラスト、 表示スケール ファクターなどのランタイム コンテキストに合わせて調整された資産とリソースを読み込むことができます。 これを行う方法は、リソースのフォルダーまたはファイルに、それらのコンテキストに対応する修飾子名と修飾子の値に一致するように名前を付ける方法です。 たとえば、アプリでハイ コントラスト モードで別の画像アセットのセットを読み込む場合があります。

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

修飾子名、修飾子値、および修飾子

修飾子名は、修飾子値のセットにマップされるキーです。 コントラストの修飾子名と修飾子の値を次に示します。

Context 修飾子名 修飾子の値
ハイ コントラストの設定 コントラスト 標準、高、黒、白

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

したがって、ハイ コントラストでは、修飾子のセットは contrast-standard、 contrast-high、 contrast-black、および contrast-whiteです。 修飾子名と修飾子の値では、大文字と小文字は区別されません。 たとえば、 contrast-standard と Contrast-Standard は同じ修飾子です。

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

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

\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 フォルダー内のリソース ファイルが読み込まれます。 設定が None (つまり、コンピューターがハイ コントラスト モードではない) の場合は、 \Assets\Images\contrast-standard フォルダー内のリソース ファイルが読み込まれます。

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

フォルダーを作成して名前付けする代わりに、修飾子を使用してリソース ファイル自体に名前を付けることができます。 修飾子ごとにリソース ファイルが 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

設定に最も適した修飾子が名前に含まれているファイルは、読み込まれるファイルです。 この一致するロジックは、フォルダー名の場合と同じ方法でファイル名に対して機能します。

名前で文字列またはイメージ リソースを参照する

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

実際の修飾子とニュートラル修飾子の一致

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

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

最初のファイル名には、 contrast-high 修飾子が含まれています。 この修飾子は、ハイ コントラストがオンの場合ハイ コントラスト設定と一致です。 言い換えると、それは近い一致なので、それが好ましいです。 actual一致は、修飾子にactual値が含まれている場合にのみ発生します。 この場合、highは contrast の actual 値です。

logo.pngという名前のファイルには、コントラスト修飾子はありません。 修飾子がない場合は、 neutral 値です。 優先一致が見つからない場合、ニュートラル値はフォールバック マッチとして機能します。 この例では、ハイ コントラストが off の場合、実際の一致はありません。 neutral一致が見つかるのに最適な一致であるため、資産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およびその他のファイルを読み込むには、設定が both 修飾子と一致している必要があります。

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

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

フォルダー名には、アンダースコアで区切られた複数の修飾子を組み合わせます。 <qualifier1>[_<qualifier2>...] という形式を使用します。

同じ形式のファイル名に複数の修飾子を組み合わせることができます。

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

資産の作成に使用するツールとワークフロー、または最も読みやすく管理しやすいものに応じて、すべての修飾子に 1 つの名前付け戦略を選択するか、異なる修飾子に対してそれらを組み合わせることができます。

AlternateForm

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

ターゲット システムまたはアプリで、 alternateform 修飾子が照合される値を指定する必要があります。 独自のカスタム alternateform修飾子値には、msft- プレフィックスを使用しないでください。

構成

configuration修飾子名が必要になる可能性はほとんどありません。 これを使用して、特定のオーサリング時環境にのみ適用できるリソース (テスト専用リソースなど) を指定できます。

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

コントラスト

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

DXFeatureLevel

dxfeaturelevel修飾子名が必要になる可能性はほとんどありません。 Direct3D ゲーム アセットと共に使用するように設計されており、ダウンレベル リソースが読み込まれ、特定のダウンレベル ハードウェア構成に一致するように設計されています。 ただし、そのハードウェア構成の普及率が非常に低いので、この修飾子を使用しないことをお勧めします。

HomeRegion

homeregion修飾子は、国または地域に対するユーザーの設定に対応します。 これは、ユーザーの自宅の場所を表します。 値には、有効な BCP-47 リージョン タグが含まれます。 つまり、 ISO 3166-1 alpha-2 2 文字の領域コードに加えて、構成されたリージョンの ISO 3166-1 数値 3 桁の地理コードのセット (「 United Nations Statistic Division M49 composition of region codes」を参照してください)。 "選択された経済および他のグループ" のコードが無効です。

Language

language修飾子は、表示言語の設定に対応します。 値には、有効な BCP-47 言語タグが含まれます。 言語の一覧については、 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修飾子は、主に、エクスプローラーに表示ファイルの種類の関連付けアイコンまたはプロトコル アイコンを指定するために使用されます。 修飾子の値は、正方形の画像の側面の長さを生 (物理) ピクセルで表します。 エクスプローラーのビュー設定と一致する値を持つリソースが読み込まれます。または、完全に一致しない場合は、次に大きい値を持つリソース。

アプリ パッケージ マニフェスト デザイナーの [ビジュアル アセット] タブで、アプリ アイコン (/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