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

2024-07-05

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

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

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

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

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

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

修飾子名と修飾子値を組み合わせて修飾子を形成します。 <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 マークアップとコードからイメージまたはその他の資産を参照するを参照するを参照してください。

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

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

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

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

logo.pngという名前のファイルには、コントラスト修飾子はありません。修飾子がない場合は、中立値になります。優先一致が見つからない場合、ニュートラル値はフォールバックマッチとして機能します。この例では、ハイコントラストがオフである場合、実際の一致はありません。中立マッチは見つけられる最良のマッチであり、そのため資産 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>...] は形式です。

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

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

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

AlternateForm（代替形式）

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

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

コンフィギュレーション

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

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

対照

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

習慣

アプリで custom 修飾子の値を設定すると、その値に最も一致するリソースが読み込まれます。たとえば、アプリのライセンスに基づいてリソースを読み込むことができます。アプリを起動すると、コード例に示すように 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-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修飾子は、国または地域に対するユーザーの設定に対応します。これは、ユーザーの自宅の場所を表します。値には、有効な BCP-47 リージョンタグが含まれます。つまり、 ISO 3166-1 alpha-2 の 2 文字の地域コードに加えて、構成済みリージョンの ISO 3166-1 数値 3 桁の地理的コードのセットが追加されます ( リージョンコードの国連統計部 M49 構成を参照)。 "選択された経済および他のグループ" のコードが無効です。

言語

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修飾子は、表示言語設定のレイアウト方向に対応します。たとえば、アラビア語やヘブライ語などの右から左の言語の場合、イメージをミラーリングする必要がある場合があります。 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) の/Assets/Square44x44Logo.png修飾子の値のいくつかのサイズを表す資産を定義できます。

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

テーマ

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

シェルライトテーマと未めっきリソース

Windows 10 May 2019 Update では、Windows シェル用の新しい "ライト" テーマが導入されました。その結果、以前は暗い背景に表示されていた一部のアプリケーションアセットが、明るい背景に表示されるようになります。タスクバーやウィンドウスイッチャー (Alt+Tab、タスクビューなど) のために代替フォームのアセットを提供したアプリの場合は、明るい背景で十分なコントラストがあることを確認してください。

ライトテーマ固有の資産の提供

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

ダウンレベルに関する考慮事項

アプリは、theme-light 修飾子を altform-unplated 修飾子と一緒に使用するべきではありません。これにより、タスクバーのリソースの読み込み方法が原因で、RS5 以前のバージョンの Windows で予期しない動作が発生します。以前のバージョンのウィンドウでは、テーマライトバージョンが正しく使用されていない可能性があります。 altform-lightunplated修飾子は、この問題を回避します。

互換性の挙動

下位互換性のために、Windows には単色アイコンを検出し、意図した背景とコントラストが付いているかどうかを確認するロジックが含まれています。アイコンがコントラストの要件を満たさなければ、Windows はアセットのコントラストホワイトバージョンを探します。使用できない場合、Windows はアセットのメッキされたバージョンを使用するように切り替えます。

重要な API

ResourceContext.QualifierValues
SetGlobalQualifierValue の