言語、スケール、ハイ コントラスト、その他の修飾子用にリソースを調整する
このトピックでは、リソース修飾子の一般概念、使用方法、各修飾子名の目的について説明します。 使用可能な修飾子の値を網羅したリファレンス テーブルについては、「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
読み込まれるのは、設定に最も適した修飾子を含む名前のファイルです。 ファイル名についても、フォルダー名と同様の照合ロジックが使用されます。
文字列または画像リソースを名前で参照する
「XAML マークアップから文字列リソース識別子を参照する」、「コードから文字列リソース識別子を参照する」、「XAML マークアップとコードから画像やその他のアセットを参照する」をご覧ください。
修飾子の実際の一致と中立的な一致
修飾子の値のすべてにリソース ファイルを指定する必要はありません。 たとえば、ハイ コントラスト用と標準コントラスト用にビジュアル アセットを各 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>
修飾子の照合について詳しくは、「リソース管理システム」を参照してください。
複数の修飾子
修飾子は、フォルダー名とファイル名で組み合わせることができます。 たとえば、ハイ コントラスト モードがオンであり表示倍率が 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
修飾子は、ハイ コントラスト設定と最も一致するリソースを提供するために使用します。
Custom
アプリで custom
修飾子の値を設定すると、その値に最も一致するリソースが読み込まれます。 たとえば、アプリのライセンスに基づいてリソースを読み込む必要があるとします。 アプリが起動すると、そのライセンスがチェックされ、コード例に示すように SetGlobalQualifierValue を呼び出して修飾子の値custom
として使用されます。
public void SetLicenseLevel(BrandID brand)
{
if (brand == BrandID.Premium)
{
ResourceContext.SetGlobalQualifierValue("Custom", "Premium", ResourceQualifierPersistence.LocalMachine);
}
else if (brand == BrandID.Standard)
{
ResourceContext.SetGlobalQualifierValue("Custom", " Standard", ResourceQualifierPersistence.LocalMachine);
}
else
{
ResourceContext.SetGlobalQualifierValue("Custom", "Trial", ResourceQualifierPersistence.LocalMachine);
}
}
このシナリオでは、修飾子 custom-premium
、custom-standard
、および custom-trial
をそれぞれ含む名前をリソースに適用します。
DeviceFamily
devicefamily
修飾子名が必要になる可能性は高くありません。 他にもっと便利で強力な修飾子を使う手法があるため、この修飾子名の使用はできる限り避けてください。 このような手法については、「アプリが実行されているプラットフォームの検出」および「バージョン アダプティブ コード」を参照してください。
ただし他に方法がなければ、XAML ビュー (XAML ビューは、UI レイアウトとコントロールを含む XAML ファイル) を格納するフォルダーの名前として devicefamily という修飾子を使用することもできます。
\devicefamily-desktop\<MainPage.xaml, and other markup files to load when running on a desktop computer>
\devicefamily-mobile\<MainPage.xaml, and other markup files to load when running on a phone>
または、次のようにファイルに命名することもできます。
\MainPage.devicefamily-desktop.xaml
\MainPage.devicefamily-mobile.xaml
いずれの場合も、MainPage.[<qualifier>].xaml
の各コピーで、共通の MainPage.xaml.cs
が使用されます (プロジェクト内で名前、場所、コンテンツが変わりません)。
また、devicefamily 修飾子を使用してリソース ファイル (.resw
) またはフォルダーに名前を付けることもできます。 たとえば、モバイル デバイス ファミリでアプリが実行されている場合、UI 要素 <TextBlock x:Uid="DeviceFriendlyName"/>
では、Resources.devicefamily-mobile.resw
ファイルに定義されているテキストと前景リソースが使用されます。以下はその例です。
<data name="DeviceFriendlyName.Foreground">
<value>Red</value>
</data>
<data name="DeviceFriendlyName.Text">
<value>Mobile device</value>
</data>
リソース ファイルの使用について詳しくは、UI 文字列のローカライズに関するページをご覧ください。
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
関連トピック
フィードバック
https://aka.ms/ContentUserFeedback」を参照してください。
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「フィードバックの送信と表示