スケール、テーマ、ハイコントラストなどに合わせた画像と資産の読み込み

[アーティクル]
11/02/2024

アプリは、表示スケールファクター、テーマ、ハイコントラスト、その他のランタイムコンテキストに合わせて調整されたイメージリソースファイル (またはその他の資産ファイル) を読み込むことができます。これらのイメージは、命令型コードまたは XAML マークアップから参照できます。たとえば、Image の Source プロパティとして参照できます。また、アプリパッケージマニフェストソースファイル (Package.appxmanifest ファイル) に (たとえば、Visual Studio マニフェストデザイナーの [ビジュアル資産] タブでアプリアイコンの値として) 表示することや、タイルやトースト通知に表示することもできます。イメージのファイル名に修飾子を使用し、必要に応じて ResourceContext を使用して動的に読み込むことで、表示スケール、テーマ、ハイコントラスト、言語、およびその他のコンテキストに対するユーザーのランタイム設定に最も適したイメージファイルを読み込むことができます。

イメージリソースは、イメージリソースファイルに含まれています。また、イメージをアセットと考え、それを含むファイルをアセットファイルと見なすこともできます。これらの種類のリソースファイルは、プロジェクトの \Assets フォルダーにあります。イメージリソースファイルの名前で修飾子を使用する方法の背景については、「言語、スケール、およびその他の修飾子についてリソースを調整する」を参照してください。

イメージの一般的な修飾子は次のとおりです。

スケール、テーマ、コントラストの画像リソースを修飾する

scale修飾子の既定値はscale-100。したがって、これら 2 つのバリアントは同等です (どちらもスケール 100 またはスケールファクター 1 の画像を提供します)。

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

ファイル名の代わりにフォルダー名に修飾子を使用できます。これは、修飾子ごとに複数の資産ファイルがある場合に適した戦略です。図の目的上、これら 2 つのバリアントは上記の 2 つのバリアントと同じです。

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

次の例では、表示スケール、テーマ、ハイコントラストのさまざまな設定に対して、 /Assets/Images/logo.pngという名前の画像リソースのバリエーションを提供する方法を示します。この例では、フォルダーの名前付けを使用します。

\Assets\Images\contrast-standard\theme-dark
    \scale-100\logo.png
    \scale-200\logo.png
\Assets\Images\contrast-standard\theme-light
    \scale-100\logo.png
    \scale-200\logo.png
\Assets\Images\contrast-high
    \scale-100\logo.png
    \scale-200\logo.png

XAML マークアップとコードからイメージまたはその他の資産を参照する

画像リソースの名前 (つまり識別子) は、そのパスとファイル名からすべての修飾子を削除したものです。前のセクションの例のようにフォルダーやファイルに名前を付ければ、イメージリソースが 1 つあり、その名前 (絶対パスとして) が /Assets/Images/logo.png。 XAML マークアップでその名前を使用する方法を次に示します。

<Image x:Name="myXAMLImageElement" Source="ms-appx:///Assets/Images/logo.png"/>

アプリのパッケージから取得したファイルを参照しているため、 ms-appx URI スキームを使用していることに注意してください。 UWP ドキュメントの「 URI スキームを参照してください。これは、命令型コードで同じイメージリソースを参照する方法です。

this.myXAMLImageElement.Source = new BitmapImage(new Uri("ms-appx:///Assets/Images/logo.png"));

ms-appxを使用して、アプリパッケージから任意のファイルを読み込むことができます。

var uri = new System.Uri("ms-appx:///Assets/anyAsset.ext");
var storagefile = await Windows.Storage.StorageFile.GetFileFromApplicationUriAsync(uri);

ms-appx-webスキームは、ms-appxと同じファイルにアクセスしますが、Web コンパートメント内にあります。

<WebView x:Name="myXAMLWebViewElement" Source="ms-appx-web:///Pages/default.html"/>

this.myXAMLWebViewElement.Source = new Uri("ms-appx-web:///Pages/default.html");

これらの例に示すシナリオでは、UriKind を推論する Uri コンストラクターオーバーロードを使用します。スキームと機関を含む有効な絶対 URI を指定するか、上記の例のように、機関がアプリのパッケージに既定で設定されるようにします。

これらの例の URI では、スキーム ("ms-appx" または "ms-appx-web") の後に "://" が続き、その後に絶対パスが続くことがわかります。絶対パスでは、先頭の "/" によって、パッケージのルートからパスが解釈されます。

Note

ms-resource (文字列リソースの場合) および ms-appx(-web) (画像やその他のアセットの場合) URI スキームは、自動で修飾子の照合を実行して、現在のコンテキストに最も適切なリソースを見つけます。 ms-appdata URI スキーム (アプリデータの読み込みに使用) では、このような自動照合は実行されませんが、ResourceContext.QualifierValues の内容に応答し URI の完全な物理ファイル名を使用してアプリデータから適切な資産を明示的に読み込むことができます。アプリデータの詳細については、「 Store」を参照し、設定とその他のアプリデータを取得します。 Web URI スキーム ( http、 https、 ftpなど) では、自動照合も実行されません。その場合の処理については、「クラウドでのイメージのホストと読み込み」を参照してください。

絶対パスは、イメージファイルがプロジェクト構造内の場所に残っている場合に適しています。イメージファイルを移動できるようにしたいが、参照元の XAML マークアップファイルと同じ場所に残ることを注意する必要がある場合は、絶対パスの代わりに、含まれるマークアップファイルに対する相対パスを使用する必要があります。これを行う場合は、URI スキームを使用する必要はありません。この場合も、自動修飾子の一致のメリットは得られますが、XAML マークアップで相対パスを使用しているためです。

<Image Source="Assets/Images/logo.png"/>

言語、スケール、ハイコントラストのトーストサポートも参照してください。

クラスライブラリからイメージまたはその他の資産を参照する

ms-appx スキームを使用する URI でリソースを参照することで、参照先の Class ライブラリ (デスクトップの WinUI 3) プロジェクトからイメージやその他のリソースを読み込むことができます。 URI には、クラスライブラリプロジェクトの名前と、クラスライブラリプロジェクト内のリソースへのパスを含める必要があります。たとえば、Assets という名前のフォルダーに logo.png という名前のイメージを含む MyClassLibrary という名前のクラスライブラリプロジェクトがある場合は、次のようにアプリプロジェクト内のイメージを参照できます。

<Image Source="ms-appx:///MyClassLibrary/Assets/logo.png"/>

この同じ URI 形式を使用して、XAML マークアップまたはコードからクラスライブラリ内のリソースを参照します。たとえば、次のコードを使用して、クラスライブラリからイメージを読み込み、 StorageFile オブジェクトに配置できます。

private async Task<DateTimeOffset> GetLogoCreatedDateAsync()
{
    Uri uri = new($"ms-appx:///MyClassLibrary/Assets/logo.png");
    Windows.Storage.StorageFile file =
        await Windows.Storage.StorageFile.GetFileFromApplicationUriAsync(uri);

    return file.DateCreated;
}

アプリプロジェクトとクラスライブラリプロジェクト自体の両方からクラスライブラリのイメージを参照できることに注意してください。

ターゲットサイズのイメージリソースを修飾する

scale修飾子とtargetsize修飾子は、同じイメージリソースのさまざまなバリエーションで使用できますが、リソースの 1 つのバリアントで両方を使用することはできません。また、 targetsize 修飾子を使用せずに、少なくとも 1 つのバリアントを定義する必要があります。そのバリアントは、 scaleの値を定義するか、既定で scale-100する必要があります。そのため、 /Assets/Square44x44Logo.png リソースのこれら 2 つのバリアントは有効です。

\Assets\Square44x44Logo.scale-200.png
\Assets\Square44x44Logo.targetsize-24.png

また、これら 2 つのバリアントは有効です。

\Assets\Square44x44Logo.png // defaults to scale-100
\Assets\Square44x44Logo.targetsize-24.png

ただし、このバリアントは無効です。

\Assets\Square44x44Logo.scale-200_targetsize-24.png

アプリパッケージマニフェストからイメージファイルを参照する

前のセクションの 2 つの有効な例のいずれかのようにフォルダーやファイルに名前を付ければ、1 つのアプリアイコンイメージリソースがあり、その名前 (相対パスとして) が Assets\Square44x44Logo.png。アプリパッケージマニフェストで、リソースを名前で参照するだけです。 URI スキームを使用する必要はありません。

これで必要な操作はこれですべてであり、OS は自動修飾子照合を実行して、現在のコンテキストに最も適したリソースを見つけます。この方法でローカライズまたは修飾できるアプリパッケージマニフェスト内のすべての項目の一覧については、「ローカライズ可能なマニフェスト項目を参照してください。

layoutdirection のイメージリソースを修飾する

Mirroring イメージを参照してください。

特定の言語またはその他のコンテキストのイメージを読み込む

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

既定の ResourceContext には、既定のランタイムコンテキスト (つまり、現在のユーザーとコンピューターの設定) を表す修飾子名ごとに修飾子値が含まれます。画像ファイルは、(その名前に含まれる修飾子に基づいて) 実行時コンテキストでの修飾子の値と比較されます。

ただし、アプリでシステム設定をオーバーライドし、読み込む一致するイメージを探すときに使用する言語、スケール、またはその他の修飾子の値について明示的に指定したい場合があります。たとえば、ハイコントラスト画像を読み込むタイミングとタイミングを正確に制御できます。

これを行うには、新しい ResourceContext (既定値を使用するのではなく) を作成し、その値をオーバーライドし、そのコンテキストオブジェクトを ResourceMap GetValue または TryGetValue で使用します。

var resourceManager = new Microsoft.Windows.ApplicationModel.Resources.ResourceManager();
var resourceContext = resourceManager.CreateResourceContext();
resourceContext.QualifierValues["Contrast"] = "high";
var resourceMap = resourceManager.MainResourceMap;
var namedResource = resourceMap.TryGetValue(@"Files/Assets/Logo.png", resourceContext);
var imageFileBytes = namedResource.ValueAsBytes;

using (var ms = new InMemoryRandomAccessStream())
{
    using (var writer = new DataWriter(ms.GetOutputStreamAt(0)))
    {
        writer.WriteBytes(imageFileBytes);
        writer.StoreAsync().GetResults();
    }
    var image = new BitmapImage();
    image.SetSource(ms);
    this.myXAMLImageElement.Source = image;
}

既定では、 ResourceManager クラスは既定の ResourceContext を使用します。

重要な API

次の API は、イメージリソースを操作する際に理解が必要です。

次の方法で共有

スケール、テーマ、ハイ コントラストなどに合わせた画像と資産の読み込み

スケール、テーマ、コントラストの画像リソースを修飾する

XAML マークアップとコードからイメージまたはその他の資産を参照する

クラス ライブラリからイメージまたはその他の資産を参照する

ターゲット サイズのイメージ リソースを修飾する

アプリ パッケージ マニフェストからイメージ ファイルを参照する

layoutdirection のイメージ リソースを修飾する