Charger des images et des ressources adaptées à la mise à l’échelle, au thème, au contraste élevé et bien plus encore

  • Article

Votre application peut charger des fichiers de ressources d’image (ou d’autres fichiers de ressources) adaptés pour le facteur d’échelle d’affichage, le thème, le contraste élevé et d’autres contextes d’exécution. Ces images peuvent être référencées à partir du code impératif ou du balisage XAML, par exemple en tant que propriété Source d’une image. Ils peuvent également apparaître dans le fichier source du manifeste du package d’application (le Package.appxmanifest fichier), par exemple, comme valeur de l’icône d’application sous l’onglet Éléments visuels du Concepteur de manifeste Visual Studio, ou sur vos vignettes et toasts. En utilisant des qualificateurs dans les noms de fichiers de vos images et éventuellement en les chargeant dynamiquement avec l’aide d’un ResourceContext, vous pouvez charger le fichier image le plus approprié qui correspond le mieux aux paramètres d’exécution de l’utilisateur pour l’échelle d’affichage, le thème, le contraste élevé, la langue et d’autres contextes.

Une ressource image est contenue dans un fichier de ressources d’image. Vous pouvez également considérer l’image comme une ressource et le fichier qui le contient en tant que fichier de ressources ; et vous pouvez trouver ces types de fichiers de ressources dans le dossier \Assets de votre projet. Pour plus d’informations sur l’utilisation de qualificateurs dans les noms de vos fichiers de ressources image, consultez Personnaliser vos ressources pour la langue, la mise à l’échelle et d’autres qualificateurs.

Certains qualificateurs courants pour les images sont mis à l’échelle, le thème, le contraste et la cible.

Qualifier une ressource d’image pour la mise à l’échelle, le thème et le contraste

La valeur par défaut du scale qualificateur est scale-100. Par conséquent, ces deux variantes sont équivalentes (elles fournissent toutes deux une image à l’échelle 100, ou facteur d’échelle 1).

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

Vous pouvez utiliser des qualificateurs dans des noms de dossiers au lieu de noms de fichiers. Cela serait une meilleure stratégie si vous avez plusieurs fichiers de ressources par qualificateur. À des fins d’illustration, ces deux variantes sont équivalentes aux deux ci-dessus.

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

Voici un exemple de la façon dont vous pouvez fournir des variantes d’une ressource d’image nommée /Assets/Images/logo.pngpour différents paramètres d’échelle d’affichage, de thème et de contraste élevé. Cet exemple utilise le nommage de dossiers.

\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

Référencer une image ou un autre élément multimédia à partir du balisage XAML et du code

Le nom ou l’identificateur d’une ressource d’image est son chemin d’accès et son nom de fichier avec tous les qualificateurs supprimés. Si vous nommez des dossiers et/ou des fichiers comme dans l’un des exemples de la section précédente, vous avez une seule ressource d’image et son nom (comme chemin absolu) est /Assets/Images/logo.png. Voici comment utiliser ce nom dans le balisage XAML.

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

Notez que vous utilisez le ms-appx schéma d’URI, car vous faites référence à un fichier provenant du package de votre application. Consultez les schémas d’URI. Et voici comment faire référence à la même ressource d’image dans le code impératif.

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

Vous pouvez utiliser ms-appx pour charger n’importe quel fichier arbitraire à partir de votre package d’application.

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

Le ms-appx-web schéma accède aux mêmes fichiers que ms-appx, mais dans le compartiment web.

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

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

Pour l’un des scénarios présentés dans ces exemples, utilisez la surcharge du constructeur Uri qui déduit l’UriKind. Spécifiez un URI absolu valide, y compris le schéma et l’autorité, ou laissez simplement l’autorité par défaut au package de l’application comme dans l’exemple ci-dessus.

Notez comment, dans ces exemples d’URI, le schéma («ms-appx » ou «ms-appx-web ») est suivi de «:// » suivi d’un chemin absolu. Dans un chemin absolu, le «/ » de début entraîne l’interprétation du chemin à partir de la racine du package.

Note

Les ms-resource schémas d’URI (pour les ressources de chaîne) et ms-appx(-web) (pour les images et d’autres ressources) effectuent une correspondance de qualificateur automatique pour rechercher la ressource la plus appropriée pour le contexte actuel. Le ms-appdata schéma d’URI (utilisé pour charger des données d’application) n’effectue aucune correspondance automatique, mais vous pouvez répondre au contenu de ResourceContext.QualifierValues et charger explicitement les ressources appropriées à partir de données d’application à l’aide de leur nom de fichier physique complet dans l’URI. Pour plus d’informations sur les données d’application, consultez Store et récupérer des paramètres et d’autres données d’application. Les schémas d’URI web (par exemple, http, httpset ftp) n’effectuent pas de correspondance automatique, non plus. Pour plus d’informations sur ce qu’il faut faire dans ce cas, consultez Hébergement et chargement d’images dans le cloud.

Les chemins absolus sont un bon choix si vos fichiers image restent là où ils se trouvent dans la structure du projet. Si vous souhaitez pouvoir déplacer un fichier image, mais veillez à ce qu’il reste dans le même emplacement par rapport à son fichier de balisage XAML de référence, au lieu d’un chemin d’accès absolu, vous pouvez utiliser un chemin d’accès relatif au fichier de balisage contenant. Si vous le faites, vous n’avez pas besoin d’utiliser un schéma d’URI. Vous bénéficiez toujours de la correspondance automatique des qualificateurs dans ce cas, mais uniquement parce que vous utilisez le chemin relatif dans le balisage XAML.

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

Consultez également la prise en charge des vignettes et des toasts pour la langue, la mise à l’échelle et le contraste élevé.

Qualifier une ressource d’image pour la cible

Vous pouvez utiliser les qualificateurs et targetsize les scale qualificateurs sur différentes variantes de la même ressource d’image, mais vous ne pouvez pas les utiliser sur une seule variante d’une ressource. En outre, vous devez définir au moins une variante sans TargetSize qualificateur. Cette variante doit définir une valeur pour scale, ou laisser la valeur par défaut scale-100. Par conséquent, ces deux variantes de la /Assets/Square44x44Logo.png ressource sont valides.

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

Et ces deux variantes sont valides.

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

Mais cette variante n’est pas valide.

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

Reportez-vous à un fichier image à partir du manifeste de votre package d’application

Si vous nommez des dossiers et/ou des fichiers comme dans l’un des deux exemples valides de la section précédente, vous avez une seule ressource d’image d’icône d’application et son nom (en tant que chemin relatif) est Assets\Square44x44Logo.png. Dans le manifeste du package d’application, reportez-vous simplement à la ressource par nom. Il n’est pas nécessaire d’utiliser un schéma d’URI.

add resource, english

C’est tout ce que vous devez faire, et le système d’exploitation effectue la correspondance automatique des qualificateurs pour trouver la ressource la plus appropriée pour le contexte actuel. Pour obtenir la liste de tous les éléments du manifeste de package d’application que vous pouvez localiser ou qualifier de cette façon, consultez les éléments de manifeste localisables.

Qualifier une ressource d’image pour layoutdirection

Consultez les images de mise en miroir.

Charger une image pour une langue spécifique ou un autre contexte

Pour plus d’informations sur la proposition de valeur de la localisation de votre application, consultez Internationalisation et localisation.

ResourceContext par défaut (obtenu à partir de ResourceContext.GetForCurrentView) contient une valeur de qualificateur pour chaque nom de qualificateur, représentant le contexte d’exécution par défaut (en d’autres termes, les paramètres de l’utilisateur et de l’ordinateur actuels). Les fichiers image sont mis en correspondance, en fonction des qualificateurs dans leurs noms, par rapport aux valeurs de qualificateur dans ce contexte d’exécution.

Toutefois, il peut arriver que votre application remplace les paramètres système et qu’elle soit explicite sur la langue, l’échelle ou une autre valeur de qualificateur à utiliser lors de la recherche d’une image correspondante à charger. Par exemple, vous pouvez contrôler exactement quand et quelles images à contraste élevé sont chargées.

Vous pouvez le faire en construisant un nouveau ResourceContext (au lieu d’utiliser la valeur par défaut), en substituant ses valeurs, puis en utilisant cet objet de contexte dans vos recherches d’image.

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;

Pour obtenir le même effet au niveau global, vous pouvez remplacer les valeurs de qualificateur dans resourceContext par défaut. Mais au lieu de cela, nous vous conseillons d’appeler ResourceContext.SetGlobalQualifierValue. Vous définissez des valeurs une fois avec un appel à SetGlobalQualifierValue, puis ces valeurs sont appliquées au ResourceContext par défaut chaque fois que vous l’utilisez pour les recherches. Par défaut, la classe ResourceManager utilise resourceContext par défaut.

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

Mise à jour d’images en réponse aux événements de modification de valeur de qualificateur

Votre application en cours d’exécution peut répondre aux modifications apportées aux paramètres système qui affectent les valeurs de qualificateur dans le contexte de ressource par défaut. L’un de ces paramètres système appelle l’événement MapChanged sur ResourceContext.QualifierValues.

En réponse à cet événement, vous pouvez recharger vos images à l’aide de ResourceContext par défaut, que ResourceManager utilise par défaut.

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 importantes