Images et pinceaux image

  • Article

Pour afficher une image, vous pouvez utiliser l’objet Image ou l’objet ImageBrush. Un objet Image affiche une image, tandis qu’un objet ImageBrush peint un autre objet avec une image.

S’agit-il des éléments appropriés ?

Utilisez un élément Image pour afficher une image autonome dans votre application.

Utilisez un élément ImageBrush pour appliquer une image à un autre objet. L’utilisation d’un objet ImageBrush comprend des effets d’ornement pour le texte ou des arrière-plans pour les contrôles ou les conteneurs de disposition.

UWP et WinUI 2

Important

Les informations et les exemples de cet article sont optimisés pour les applications qui utilisent le SDK d'application Windows et WinUI 3, mais qui s’appliquent généralement aux applications UWP qui utilisent WinUI 2. Consultez la référence API de la plateforme Windows universelle pour obtenir des informations et des exemples spécifiques à la plateforme.

Cette section contient les informations dont vous avez besoin pour utiliser le contrôle dans une application de la plateforme Windows universelle ou de WinUI 2.

Les API de ce contrôle existent dans les espaces de noms Windows.UI.Xaml.Controls et Windows.UI.Xaml.Media .

Nous vous recommandons d’utiliser la dernière version de WinUI 2 pour obtenir les styles et modèles les plus récents pour tous les contrôles.

À compter de Windows 10, version 1607, l’élément Image prend en charge les images GIF animées. Quand vous utilisez un BitmapImage en tant qu’image Source, vous pouvez accéder aux APIs BitmapImage pour contrôler la lecture de l’image GIF animée. Pour plus d’informations, voir les remarques dans la page de la classe BitmapImage.

Notes

La prise en charge des GIF animés est disponible lorsque votre application est compilée pour Windows 10, version 1607 et s’exécutant sur la version 1607 (ou ultérieure). Quand votre application est compilée pour des versions antérieures ou qu’elle s’exécute sur ces versions, la première image de l’image GIF s’affiche, mais elle n’est pas animée.

Créer une image

Ouvrez l’application Galerie WinUI 3 et consultez ImageBrushes en action.

L’application WinUI 3 Gallery comprend des exemples interactifs de la plupart des contrôles et des fonctionnalités WinUI 3. Procurez-vous l’application sur le Microsoft Store ou le code source sur GitHub.

SE conteneur

Cet exemple montre comment créer une image à l’aide de l’objet Image.

<Image Width="200" Source="sunset.jpg" />

Voici l’objet Image affiché.

Exemple d’un élément d’image

Dans cet exemple, la propriété Source indique l’emplacement de l’image à afficher. Vous pouvez définir la source en spécifiant une URL absolue (par exemple, http://contoso.com/myPicture.jpg) ou en spécifiant une URL relative à la structure d’empaquetage de votre application. Pour notre exemple, nous avons placé le fichier image « sunset.jpg » dans le dossier racine de notre projet et nous déclarons les paramètres de projet qui incluent le fichier image en tant que contenu.

ImageBrush

Avec l’objet ImageBrush, vous pouvez utiliser une image pour peindre une zone qui accepte un objet Brush. Par exemple, vous pouvez utiliser un objet ImageBrush pour la valeur de la propriété Fill d’un objet Ellipse ou la propriété Background d’un objet Canvas.

L’exemple suivant montre comment utiliser un objet ImageBrush pour peindre un objet Ellipse.

<Ellipse Height="200" Width="300">
   <Ellipse.Fill>
     <ImageBrush ImageSource="sunset.jpg" />
   </Ellipse.Fill>
</Ellipse>

Voici l’objet Ellipse peint par l’objet ImageBrush.

Objet Ellipse peint par un objet ImageBrush.

Étirer une image

Si vous ne définissez pas les valeurs Width ou Height d’un objet Image, ce dernier est affiché avec les dimensions de l’image spécifiée par la propriété Source. Le fait de définir les valeurs Width et Height crée une zone rectangulaire dans laquelle l’image est affichée. Vous pouvez spécifier la façon dont l’image remplit cette zone à l’aide de la propriété Stretch. La propriété Stretch accepte ces valeurs qui sont définies par l’énumération Stretch :

  • Aucune : L’image n’est pas étirée pour remplir les dimensions de sortie. Faites preuve de prudence avec le paramètre Stretch : si l’image source est plus grande que la zone qui doit la contenir, votre image sera découpée. Cela n’est pas généralement souhaitable car, contrairement à une propriété Clip délibérée, vous n’avez aucun contrôle sur la fenêtre d’affichage.
  • Uniform : L’image est mise à l’échelle afin de correspondre aux dimensions de sortie. Mais les proportions du contenu sont conservées. Il s'agit de la valeur par défaut.
  • UniformToFill : L’image est mise à l’échelle de sorte qu’elle remplisse complètement la zone de sortie tout en conservant ses proportions d’origine.
  • Fill : L’image est mise à l’échelle afin de correspondre aux dimensions de sortie. Étant donné que la hauteur et la largeur du contenu sont mises à l’échelle indépendamment, les dimensions d’origine de l’image risquent de ne pas être conservées. C’est-à-dire que l’image risque d’être déformée afin de remplir complètement la zone de sortie.

Exemple de paramètres d’étirement.

Rogner une image

Vous pouvez utiliser la propriété Clip pour découper une zone de la sortie image. Vous affectez à la propriété Clip la valeur Geometry. Le découpage non rectangulaire n’est actuellement pas pris en charge.

L’exemple suivant montre comment utiliser un objet RectangleGeometry en tant que région de découpage pour une image. Dans cet exemple, nous définissons un objet Image et affectons à la propriété Height la valeur 200. Un objet RectangleGeometry définit un rectangle pour la zone de l’image à afficher. La propriété Rect a la valeur 25,25,100,150, ce qui définit un rectangle avec pour position de départ 25,25, une largeur de 100 et une hauteur de 150. Seule la partie de l’image qui se trouve dans la zone du rectangle est affichée.

<Image Source="sunset.jpg" Height="200">
    <Image.Clip>
        <RectangleGeometry Rect="25,25,100,150" />
    </Image.Clip>
</Image>

Voici l’image découpée sur un arrière-plan noir.

Objet Image rogné par un objet RectangleGeometry.

Appliquer une opacité

Vous pouvez appliquer une propriété Opacity à une image de façon à ce qu’elle soit affichée de manière semi-translucide. Les valeurs d’opacité vont de 0,0 à 1,0, où 1,0 correspond à une opacité totale et 0,0 correspond à une transparence totale. Cet exemple montre comment appliquer une opacité de 0,5 à un objet Image.

<Image Height="200" Source="sunset.jpg" Opacity="0.5" />

Voici l’objet Image affiché avec une opacité de 0,5 et un arrière-plan noir laissant passer l’opacité partielle.

Objet Image avec une opacité de 0,5.

Formats de fichier d’image

Les objets Image et ImageBrush permettent d’afficher les formats de fichier d’image suivants :

  • Joint Photographic Experts Group (JPEG)
  • format PNG (Portable Network Graphics)
  • image bitmap (BMP)
  • format GIF (Graphics Interchange Format)
  • format TIFF (Tagged Image File Format)
  • JPEG XR
  • icônes (ICO)

L’API pour Image, BitmapImage et BitmapSource n’inclut aucune méthode dédiée d’encodage ou de décodage des formats de média. Toutes les opérations d’encodage et de décodage sont intégrées et, au plus, feront émerger les aspects de l’encodage ou du décodage dans le cadre des données d’événement pour les événements de chargement. Si vous voulez effectuer des tâches spéciales avec encodage ou décodage d’image, que vous pouvez utiliser si votre application effectue des conversions ou des manipulations d’image, vous devez utiliser les API disponibles dans l’espace de noms Windows.Graphics.Imaging. Ces API sont également prises en charge par le composant Imagerie Windows (WIC) de Windows.

Pour plus d’informations sur les ressources d’application et sur la façon d’empaqueter des sources d’images dans une application, consultez Charger des images et des ressources adaptées à la mise à l’échelle, au thème, au contraste élevé, etc.

WriteableBitmap

Un élément WriteableBitmap fournit un élément BitmapSource qui peut être modifié et qui n’utilise pas le décodage standard basé sur les fichiers à partir du composant WIC. Vous pouvez modifier des images dynamiquement et réafficher l’image mise à jour. Pour définir le contenu du tampon d’un élément WriteableBitmap, utilisez la propriété PixelBuffer pour accéder au tampon et utilisez un flux ou un type de tampon propre à un langage pour le remplir. Pour obtenir un exemple de code, voir WriteableBitmap.

RenderTargetBitmap

La classe RenderTargetBitmap peut capturer l’arborescence de l’interface utilisateur XAML d’une application en cours d’exécution, puis représenter une source d’image bitmap. Après la capture, cette source d’image peut être appliquée à d’autres parties de l’application, enregistrée en tant que ressource ou données d’application par l’utilisateur, ou utilisée à d’autres fins. Un scénario particulièrement utile consiste à créer une miniature d’exécution d’une page XAML pour un schéma de navigation. RenderTargetBitmap limite toutefois le contenu pouvant apparaître dans l’image capturée. Pour plus d’informations, voir la rubrique de référence de l’API pour RenderTargetBitmap.

Sources d’images et mise à l’échelle

Vous devez créer vos sources d’images selon plusieurs tailles recommandées afin de vous assurer que votre application garde son aspect esthétique lorsque Windows la redimensionne. Lorsque vous spécifiez une propriété Source pour un objet Image, vous pouvez utiliser une convention d’affectation de noms qui référencera automatiquement la ressource appropriée pour la mise à l’échelle actuelle. Pour connaître les spécificités de la convention d’affectation de noms et obtenir plus d’informations, voir Démarrage rapide : Utilisation de ressources de fichiers ou d’images.

Pour plus d’informations sur la conception prenant en charge la mise à l’échelle, voir Recommandations en matière d’expérience utilisateur pour la disposition et la mise à l’échelle.

Image et ImageBrush dans le code

Il est courant de spécifier les éléments Image et ImageBrush en XAML plutôt que sous forme de code. Cela est dû au fait que ces éléments sont souvent la sortie d’outils de conception dans le cadre d’une définition d’interface utilisateur XAML.

Si vous définissez un élément Image ou ImageBrush à l’aide de code, utilisez les constructeurs par défaut, puis définissez la propriété Source appropriée (Image.Source ou ImageBrush.ImageSource). Celle-ci nécessite un élément BitmapImage (et non un URI) quand vous la définissez à l’aide de code. Si votre source est un flux, utilisez la méthode SetSourceAsync pour initialiser la valeur. Si votre source est un URI incluant du contenu de votre application qui utilise les modèles ms-appx ou ms-resource, utilisez le constructeur BitmapImage qui prend un URI. Vous pouvez également envisager de gérer l’événement ImageOpened s’il existe des problèmes de délai liés à la récupération ou au décodage de la source de l’image, auquel cas un contenu alternatif peut s’avérer nécessaire à afficher tant que la source de l’image n’est pas disponible. Pour obtenir un exemple de code, consultez l’exemple WinUI Gallery.

Notes

Si vous établissez des images à l’aide de code, vous pouvez utiliser la gestion automatique pour accéder à des ressources non qualifiées avec les qualificateurs d’échelle et de culture actuels, ou vous pouvez utiliser ResourceManager et ResourceMap avec des qualificateurs pour la culture et l’échelle afin d’obtenir les ressources directement. Pour plus d’informations, voir Système de gestion des ressources.

Obtenir l’exemple de code