スケール、テーマ、ハイ コントラストなどのために調整された画像とアセットを読み込む
アプリは、 表示スケール ファクター、テーマ、ハイ コントラスト、その他のランタイム コンテキストに合わせて調整されたイメージ リソース ファイル (またはその他の資産ファイル) を読み込むことができます。 これらのイメージは、命令型コードまたは XAML マークアップから参照できます。たとえば、Image の Source プロパティとして参照できます。 また、アプリ パッケージ マニフェスト ソース ファイル (Package.appxmanifest ファイル) に (たとえば、Visual Studio マニフェスト デザイナーの [ビジュアル資産] タブでアプリ アイコンの値として) 表示することや、タイルやトースト通知に表示することもできます。 イメージのファイル名に修飾子を使用し、必要に応じて ResourceContext を使用して動的に読み込むことで、表示スケール、テーマ、ハイ コントラスト、言語、およびその他のコンテキストに対するユーザーのランタイム設定に最も適したイメージ ファイルを読み込むことができます。
イメージ リソースは、イメージ リソース ファイルに含まれています。 また、イメージをアセットと考え、それを含むファイルをアセット ファイルと見なすこともできます。これらの種類のリソース ファイルは、プロジェクトの \Assets フォルダーにあります。 イメージ リソース ファイルの名前で修飾子を使用する方法の背景については、「 言語、スケール、およびその他の修飾子についてリソースを調整する」を参照してください。
イメージの一般的な修飾子には、 scale、 theme、 contrast、 targetsizeがあります。
スケール、テーマ、コントラストの画像リソースを修飾する
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スキームは、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"/>
言語、スケール、ハイ コントラストのトーストサポートも参照してください。
ターゲット サイズのイメージ リソースを修飾する
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.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);
}
重要な API
関連トピック
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示