表示倍率、テーマ、ハイ コントラスト、その他の設定に合わせた画像とアセットの読み込みLoad images and assets tailored for scale, theme, high contrast, and others

アプリで、表示倍率、テーマ、ハイ コントラスト、その他の実行時のコンテキストに合わせた画像リソース ファイル (またはその他のアセット ファイル) を読み込むことができます。Your app can load image resource files (or other asset files) tailored for display scale factor, theme, high contrast, and other runtime contexts. これらの画像は、命令型コードや XAML マークアップ (ImageSource プロパティなど) から参照できます。These images can be referenced from imperative code or from XAML markup, for example as the Source property of an Image. アプリ パッケージのマニフェストのソース ファイルにも表示できます (、Package.appxmanifestファイル)—など、Visual Studio のマニフェスト デザイナーの [ビジュアル資産] タブでアプリのアイコンの値として—またはタイルとトーストにします。They can also appear in your app package manifest source file (the Package.appxmanifest file)—for example, as the value for App Icon on the Visual Assets tab of the Visual Studio Manifest Designer—or on your tiles and toasts. 画像のファイル名に修飾子を使用し、必要に応じて ResourceContext を使って動的に読み込むことによって、ユーザーの実行時の表示倍率、テーマ、ハイ コントラスト、言語、その他のコンテキストの設定に最も一致する最適な画像ファイルを読み込むことができます。By using qualifiers in your images' file names, and optionally dynamically loading them with the help of a ResourceContext, you can cause the most appropriate image file to be loaded that best matches the user's runtime settings for display scale, theme, high contrast, language, and other contexts.

画像リソースは、画像リソース ファイルに含まれています。An image resource is contained in an image resource file. 画像はアセット、画像を含むファイルはアセット ファイルと考えることができ、これらの種類のリソース ファイルはプロジェクトの \Assets フォルダーにあります。You can also think of the image as an asset, and the file that contains it as an asset file; and you can find these kinds of resource files in your project's \Assets folder. 画像リソース ファイルの名前に修飾子を使用する方法の詳細については、「言語、スケール、その他の修飾子用にリソースを調整する」をご覧ください。For background on how to use qualifiers in the names of your image resource files, see Tailor your resources for language, scale, and other qualifiers.

画像の一般的な修飾子には、scalethemecontrasttargetsize があります。Some common qualifiers for images are scale, theme, contrast, and targetsize.

スケール、テーマ、コントラストに合わせて画像リソースを修飾するQualify an image resource for scale, theme, and contrast

scale 修飾子の既定値は scale-100 です。The default value for the scale qualifier is scale-100. そのため、次の 2 つのバリエーションは同等です (いずれもスケール 100、つまり倍率 1 の画像を提供します)。So, these two variants are equivalent (they both provide an image at scale 100, or scale factor 1).

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

修飾子は、ファイル名の代わりにフォルダー名に使用できます。You can use qualifiers in folder names instead of file names. 修飾子ごとにいくつかのアセット ファイルがある場合、この方法が適しています。That would be a better strategy if you have several asset files per qualifier. わかりやすい例として、次の 2 つのバリエーションは上記の 2 つと同等です。For purposes of illustration, these two variants are equivalent to the two above.

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

画像リソースのバリエーションを指定する方法の例を次に、—という/Assets/Images/logo.png—表示スケール、テーマ、およびハイ コントラストのさまざまな設定をします。Next is an example of how you can provide variants of an image resource—named /Assets/Images/logo.png—for different settings of display scale, theme, and high contrast. この例では、フォルダー名を使用しています。This example uses folder naming.

\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 マークアップとコードから画像やその他のアセットを参照するReference an image or other asset from XAML markup and code

名前—または識別子—イメージのリソースには、パスとファイルの名前をすべての修飾子を削除します。The name—or identifier—of an image resource is its path and file name with any and all qualifiers removed. 前のセクションの例のようにフォルダーやファイルに名前を付けている場合、画像リソースは 1 つであり、その (絶対パスとしての) 名前は /Assets/Images/logo.png です。If you name folders and/or files as in any of the examples in the previous section, then you have a single image resource and its name (as an absolute path) is /Assets/Images/logo.png. この名前を XAML マークアップで使用する方法は次のとおりです。Here’s how you use that name in XAML markup.

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

アプリのパッケージに付属しているファイルを参照するため、ms-appx URI スキームを使用していることに注意してください。Notice that you use the ms-appx URI scheme because you're referring to a file that comes from your app's package. URI スキーム」をご覧ください。See URI schemes. 同じ画像リソースを命令型コード内で参照する方法は次のとおりです。And here’s how you refer to the same image resource in imperative code.

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

ms-appx を使用して、アプリ パッケージから任意のファイルを読み込むことができます。You can use ms-appx to load any arbitrary file from your app package.

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

ms-appx-web スキームは、ms-appx と同じファイルにアクセスしますが、このファイルは Web コンパートメントにあります。The ms-appx-web scheme accesses the same files as ms-appx, but in the web compartment.

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

これらの例に示されているどのシナリオの場合も、UriKind を推測する Uri コンストラクターのオーバーロードを使用します。For any of the scenarios shown in these examples, use the Uri constructor overload that infers the UriKind. スキームと機関を含む有効な絶対 URI を指定するか、上記の例のように、機関の既定をアプリのパッケージに自動的に設定します。Specify a valid absolute URI including the scheme and authority, or just let the authority default to the app's package as in the example above.

これらの URI の例で、スキーム ("ms-appx" または "ms-appx-web") の後に "://" が続き、その後に絶対パスが続くことに注意してください。Notice how in these example URIs the scheme ("ms-appx" or "ms-appx-web") is followed by "://" which is followed by an absolute path. 絶対パスでは、先頭の "/" によって、パスはパッケージのルートからのパスとして解釈されます。In an absolute path, the leading "/" causes the path to be interpreted from the root of the package.

注意

ms-resource (の文字列リソース) とms-appx(-web)を現在のコンテキストの最適なリソースを見つける自動修飾子が一致するが URI スキーム (イメージやその他の資産) を実行します。The ms-resource (for string resources) and ms-appx(-web) (for images and other assets) URI schemes perform automatic qualifier matching to find the resource that's most appropriate for the current context. ms-appdata URI スキーム (アプリ データを読み込むために使用される) は、このような自動的な照合を実行しませんが、ResourceContext.QualifierValues の内容に応答し、URI の完全な物理ファイル名を使用して、アプリ データから適切なアセットを明示的に読み込むことができます。The ms-appdata URI scheme (which is used to load app data) does not perform any such automatic matching, but you can respond to the contents of ResourceContext.QualifierValues and explicitly load the appropriate assets from app data using their full physical file name in the URI. アプリ データについては、「設定と他のアプリ データを保存して取得する」をご覧ください。For info about app data, see Store and retrieve settings and other app data. Web URI スキーム (httphttpsftp など) も、自動的な照合を実行しません。Web URI schemes (for example, http, https, and ftp) do not perform automatic matching, either. その場合の対処方法については、「クラウドでの画像のホスティングと読み込み」をご覧ください。For info about what to do in that case, see Hosting and loading images in the cloud.

絶対パスは、画像ファイルがプロジェクト構造内で元の場所に残る場合に適切な選択肢です。Absolute paths are a good choice if your image files remain where they are in the project structure. 画像ファイルを移動できるようにする必要があるが、参照している XAML マークアップ ファイルから相対的に同じ場所に残るように注意している場合は、絶対パスの代わりに、ファイルを格納するマークアップ ファイルからの相対パスを使用できます。If you want to be able to move an image file, but you're careful that it remains in the same location relative to its referencing XAML markup file, then instead of an absolute path you might want to use a path that's relative to the containing markup file. その場合、URI スキームを使用する必要はありません。If you do that, then you needn't use a URI scheme. この場合も、自動的な修飾子の照合のメリットはありますが、それは XAML マークアップで相対パスを使用していることにのみ起因します。You will still benefit from automatic qualifier matching in this case, but only because you are using the relative path in XAML markup.

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

言語、スケール、ハイ コントラストに合わせたタイルとトーストのサポート」もご覧ください。Also see Tile and toast support for language, scale, and high contrast.

ターゲット サイズに合わせて画像リソースを修飾するQualify an image resource for targetsize

同じ画像リソースの異なるバリエーションでは scale 修飾子と targetsize 修飾子を別々に使用できますが、リソースの 1 つのバリエーションでその両方を使用することはできません。You can use the scale and targetsize qualifiers on different variants of the same image resource; but you can't use them both on a single variant of a resource. また、TargetSize 修飾子を持たないバリエーションを少なくとも 1 つ定義する必要があります。Also, you need to define at least one variant without a TargetSize qualifier. そのバリエーションでは、scale の値を定義するか、その既定値を scale-100 にする必要があります。That variant must either define a value for scale, or let it default to scale-100. したがって、/Assets/Square44x44Logo.png リソースのこれら 2 つのバリエーションは有効です。So, these two variants of the /Assets/Square44x44Logo.png resource are valid.

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

また、次の 2 つのバリエーションは有効です。And these two variants are valid.

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

ただし、次のバリエーションは有効ではありません。But this variant is not valid.

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

アプリ パッケージ マニフェストから画像ファイルを参照するRefer to an image file from your app package manifest

前のセクションの 2 つの有効な例のいずれかのように、フォルダーやファイルに名前を付けている場合、アプリ アイコンの画像リソースは 1 つであり、その (相対パスとしての) 名前は Assets\Square44x44Logo.png です。If you name folders and/or files as in either of the two valid examples in the previous section, then you have a single app icon image resource and its name (as a relative path) is Assets\Square44x44Logo.png. アプリ パッケージ マニフェストでは、単に名前でリソースを参照します。In your app package manifest, simply refer to the resource by name. URI スキームを使用する必要はありません。There's no need to use any URI scheme.

リソースの追加 (英語)

必要な処理はこれだけです。OS が自動で修飾子の照合を実行して、現在のコンテキストに最も適切なリソースを見つけます。That's all you need to do, and the OS will perform automatic qualifier matching to find the resource that's most appropriate for the current context. アプリ パッケージ マニフェスト内で、このようにローカライズまたはその他の方法で修飾できるすべての項目の一覧については、「マニフェストのローカライズ可能な項目」をご覧ください。For a list of all items in the app package manifest that you can localize or otherwise qualify in this way, see Localizable manifest items.

レイアウト方向に合わせて画像リソースを修飾するQualify an image resource for layoutdirection

画像の左右反転」をご覧ください。See Mirroring images.

特定の言語または他のコンテキスト用の画像を読み込むLoad an image for a specific language or other context

アプリのローカライズの価値提案の詳細については、「グローバリゼーションとローカライズ」をご覧ください。For more info about the value proposition of localizing your app, see Globalization and localization.

既定の ResourceContext (ResourceContext.GetForCurrentView から取得された) には、既定の実行時コンテキスト (つまり、現在のユーザーとコンピューターの設定) を表す、各修飾子名の修飾子の値が含まれています。The default ResourceContext (obtained from ResourceContext.GetForCurrentView) contains a qualifier value for each qualifier name, representing the default runtime context (in other words, the settings for the current user and machine). イメージ ファイルが一致する—、名前に修飾子に基づいて—ランタイム コンテキストでの修飾子の値と比較します。Image files are matched—based on the qualifiers in their names—against the qualifier values in that runtime context.

ただし、アプリでシステム設定を上書きし、読み込む画像を検索するときに使用する言語、スケール、その他の修飾子の値を明示的に指定することが必要になる場合があります。But there might be times when you want your app to override the system settings and be explicit about the language, scale, or other qualifier value to use when looking for a matching image to load. たとえば、いつ、どのハイ コントラスト画像を読み込むかを正確に制御することが必要になる場合があります。For example, you might want to control exactly when and which high contrast images are loaded.

そのためには、(既定のものを使用する代わりに) 新しい ResourceContext を作成し、その値をオーバーライドして、画像検索でそのコンテキスト オブジェクトを使用します。You can do that by constructing a new ResourceContext (instead of using the default one), overriding its values, and then using that context object in your image lookups.

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 で修飾子の値を上書きすることができますFor the same effect at a global level, you can override the qualifier values in the default ResourceContext. ただし、その代わりに、ResourceContext.SetGlobalQualifierValue を呼び出すことをお勧めします。But instead we advise you to call ResourceContext.SetGlobalQualifierValue. SetGlobalQualifierValue の呼び出しで一度値を設定すると、ResourceContext を検索に使用するたびに、これらの値が既定の ResourceContext で有効になります。You set values one time with a call to SetGlobalQualifierValue and then those values are in effect on the default ResourceContext each time you use it for lookups. 既定では、ResourceManager クラスは、既定の ResourceContext を使用します。By default, the ResourceManager class uses the default 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);

修飾子の値の変更イベントへの応答で画像を更新するUpdating images in response to qualifier value change events

実行中のアプリは、既定のリソースのコンテキストで修飾子の値に影響を与えるシステム設定の変更に応答できます。Your running app can respond to changes in system settings that affect the qualifier values in the default resource context. これらのシステム設定のいずれかが、ResourceContext.QualifierValuesMapChanged イベントを呼び出します。Any of these system settings invokes the MapChanged event on ResourceContext.QualifierValues.

このイベントへの応答で、既定の ResourceContext を使用して画像を再読み込みすることができます。これは、ResourceManager が既定で使用するものです。In response to this event, you can reload your images with the help of the default ResourceContext, which ResourceManager uses by default.

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);
}

重要な APIImportant APIs