スケール、テーマ、ハイコントラストなどのために調整された画像とアセットを読み込む

[アーティクル]
08/17/2023

アプリは、表示スケールファクター、テーマ、ハイコントラスト、その他のランタイムコンテキスト用に調整されたイメージリソースファイル (またはその他の資産ファイル) を読み込むことができます。これらのイメージは、命令型コードまたは 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 スキームを使用していることに注意してください。 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 、Web コンパートメント内にあるファイルと ms-appx同じファイルにアクセスします。

<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") の後に "://" が続き、その後に絶対パスが続くことがわかります。絶対パスでは、先頭の "/" によって、パッケージのルートからパスが解釈されます。

注意

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

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

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

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

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

同じイメージリソースの scale 異なるバリアントで修飾子と targetsize 修飾子を使用できますが、リソースの 1 つのバリアントで両方を使用することはできません。また、修飾子を使用せずに、少なくとも 1 つのバリアントを定義する必要があります TargetSize 。そのバリアントは、値 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 のイメージリソースを修飾する

イメージのミラーリングを参照してください。

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

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

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

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

これを行うには、新しい ResourceContext を (既定のリソースではなく) 構築し、その値をオーバーライドしてから、イメージ参照でそのコンテキストオブジェクトを使用します。

var resourceContext = new Windows.ApplicationModel.Resources.Core.ResourceContext(); // not using ResourceContext.GetForCurrentView 
resourceContext.QualifierValues["Contrast"] = "high";
var namedResource = Windows.ApplicationModel.Resources.Core.ResourceManager.Current.MainResourceMap[@"Files/Assets/Logo.png"];
var resourceCandidate = namedResource.Resolve(resourceContext);
var imageFileStream = resourceCandidate.GetValueAsStreamAsync().GetResults();
var bitmapImage = new Windows.UI.Xaml.Media.Imaging.BitmapImage();
bitmapImage.SetSourceAsync(imageFileStream);
this.myXAMLImageElement.Source = bitmapImage;

グローバルレベルで同じ効果を得るには、既定の ResourceContext で修飾子の値をオーバーライドします。ただし、代わりに ResourceContext.SetGlobalQualifierValue を呼び出すようにお勧めします。 SetGlobalQualifierValue の呼び出しで値を 1 回設定すると、それらの値は、参照に使用するたびに既定の ResourceContext で有効になります。既定では、ResourceManager クラスは既定の ResourceContext を使用します。

Windows.ApplicationModel.Resources.Core.ResourceContext.SetGlobalQualifierValue("Contrast", "high");
var namedResource = Windows.ApplicationModel.Resources.Core.ResourceManager.Current.MainResourceMap[@"Files/Assets/Logo.png"];
this.myXAMLImageElement.Source = new Windows.UI.Xaml.Media.Imaging.BitmapImage(namedResource.Uri);

修飾子値変更イベントに応答してイメージを更新する

実行中のアプリは、既定のリソースコンテキストの修飾子の値に影響を与えるシステム設定の変更に応答できます。これらのシステム設定は、ResourceContext.QualifierValues で MapChanged イベントを呼び出します。

このイベントに応答して、ResourceManager が既定で使用する既定の ResourceContext を使用してイメージを再読み込みできます。

public MainPage()
{
    this.InitializeComponent();

    ...

    // Subscribe to the event that's raised when a qualifier value changes.
    var qualifierValues = Windows.ApplicationModel.Resources.Core.ResourceContext.GetForCurrentView().QualifierValues;
    qualifierValues.MapChanged += new Windows.Foundation.Collections.MapChangedEventHandler<string, string>(QualifierValues_MapChanged);
}

private async void QualifierValues_MapChanged(IObservableMap<string, string> sender, IMapChangedEventArgs<string> @event)
{
    var dispatcher = this.myImageXAMLElement.Dispatcher;
    if (dispatcher.HasThreadAccess)
    {
        this.RefreshUIImages();
    }
    else
    {
        await dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal, () => this.RefreshUIImages());
    }
}

private void RefreshUIImages()
{
    var namedResource = Windows.ApplicationModel.Resources.Core.ResourceManager.Current.MainResourceMap[@"Files/Assets/Logo.png"];
    this.myImageXAMLElement.Source = new Windows.UI.Xaml.Media.Imaging.BitmapImage(namedResource.Uri);
}

スケール、テーマ、ハイコントラストなどのために調整された画像とアセットを読み込む

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

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

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

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

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

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

修飾子値変更イベントに応答してイメージを更新する

重要な API

フィードバック

フィードバック

その他のリソース

スケール、テーマ、ハイ コントラストなどのために調整された画像とアセットを読み込む

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

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

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

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

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

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

修飾子値変更イベントに応答してイメージを更新する

重要な API

関連トピック

フィードバック

フィードバック

その他のリソース

スケール、テーマ、ハイコントラストなどのために調整された画像とアセットを読み込む

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

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

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