Partager via

Charger des images et des ressources adaptées pour la mise à l’échelle, le thème, le contraste élevé et autres

  • 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.

Voici quelques qualificateurs courants pour les images :

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. Il s’agit d’une meilleure stratégie lorsque 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

L’exemple suivant montre comment 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 dans la documentation UWP. Il s’agit de la façon dont vous faites 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.

Remarque

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é.

Référencer une image ou une autre ressource à partir d’une bibliothèque de classes

Vous pouvez charger des images et d’autres ressources à partir d’un projet de bibliothèque de classes référencée (WinUI 3 in Desktop) en référençant la ressource dans un URI qui utilise le ms-appx schéma. L’URI doit inclure le nom du projet de bibliothèque de classes et le chemin d’accès à la ressource dans le projet de bibliothèque de classes. Par exemple, si vous avez un projet de bibliothèque de classes nommé MyClassLibrary qui contient une image nommée dans un dossier nommé logo.png Assets, vous pouvez référencer l’image dans votre projet d’application comme suit :

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

Vous utiliserez ce même format d’URI pour référencer des ressources dans une bibliothèque de classes à partir du balisage XAML ou du code. Par exemple, vous pouvez utiliser le code suivant pour charger l’image à partir de votre bibliothèque de classes et la placer dans un objet 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;
}

Notez que vous pouvez référencer des images à partir de la bibliothèque de classes à partir du projet d’application et du projet de bibliothèque de classes lui-même.

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.

ajouter une ressource, anglais

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 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 remplaçant ses valeurs, puis en utilisant cet objet de contexte dans vos recherches d’images ResourceMap avec GetValue ou 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;
}

Par défaut, la classe ResourceManager utilise resourceContext par défaut.

API importantes

Les API suivantes sont imporantes à comprendre lors de l’utilisation des ressources d’image :

Contenu connexe