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

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

このトピックでは、リソース修飾子の一般概念、使用方法、各修飾子名の目的について説明します。使用可能なすべての修飾子値の参照テーブルについては、 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

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

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

「 XAML マークアップから文字列リソース識別子を参照する、コードから文字列リソース識別子に参照する、および XAML マークアップとコードから画像やその他の資産を参照するを参照してください。

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

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>

修飾子の照合のしくみの詳細については、「リソース管理システムを参照してください。

複数の修飾子

フォルダー名とファイル名に修飾子を組み合わせることができます。たとえば、ハイコントラストモードがで表示倍率が 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修飾子は、ハイコントラスト設定に最も一致するリソースを提供するために使用されます。

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修飾子名が必要になる可能性はほとんどありません。より便利で堅牢な代わりに使用できる手法があるため、可能な限り使用することはできず、避ける必要があります。これらの手法については、「アプリが実行されているプラットフォームの検出および Version アダプティブコードで説明されています。

ただし、最後の手段として、devicefamily 修飾子を使用して、XAML ビューを含むフォルダーに名前を付けることができます (XAML ビューは、UI レイアウトとコントロールを含む XAML ファイルです)。

\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) またはフォルダーに名前を付けることもできます。たとえば、アプリがモバイルデバイスファミリで実行されている場合、 <TextBlock x:Uid="DeviceFriendlyName"/> UI 要素は、 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 リージョンタグが含まれます。つまり、 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 はアセットのプレートありバージョンを使用するようにフォールバックします。

次の方法で共有

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

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

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

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

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

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

複数の修飾子

AlternateForm

構成

コントラスト

Custom

DeviceFamily

DXFeatureLevel

HomeRegion

Language

LayoutDirection

スケール

TargetSize

テーマ

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

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

ダウンレベルの考慮事項

互換性の動作

重要な API

フィードバック

その他のリソース

次の方法で共有

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

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

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

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

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

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

複数の修飾子

AlternateForm

構成

コントラスト

Custom

DeviceFamily

DXFeatureLevel

HomeRegion

Language

LayoutDirection

スケール

TargetSize

テーマ

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

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

ダウンレベルの考慮事項

互換性の動作

重要な API

関連トピック

フィードバック

その他のリソース

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

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

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

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