Image.Source Propriété

Référence

Définition

Espace de noms:: Windows.UI.Xaml.Controls

Important

Certaines informations portent sur la préversion du produit qui est susceptible d’être en grande partie modifiée avant sa publication. Microsoft exclut toute garantie, expresse ou implicite, concernant les informations fournies ici.

Modifier

Obtient ou définit la source de l’image.

public:
 property ImageSource ^ Source { ImageSource ^ get(); void set(ImageSource ^ value); };

ImageSource Source();

void Source(ImageSource value);

public ImageSource Source { get; set; }

var imageSource = image.source;
image.source = imageSource;

Public Property Source As ImageSource

<Image Source="uri"/>

Valeur de propriété

ImageSource

Objet qui représente le fichier source d’image pour l’image dessinée. En règle générale, vous définissez cette valeur avec un objet BitmapImage , construit avec l’URI (Uniform Resource Identifier) qui décrit le chemin d’accès à un fichier source d’image valide. Vous pouvez également initialiser un BitmapSource avec un flux, peut-être un flux à partir d’un fichier de stockage.

Remarques

La définition de la propriété Source est par nature une action asynchrone. Étant donné qu’il s’agit d’une propriété, il n’existe pas de syntaxe attendue, mais dans la plupart des scénarios, vous n’avez pas besoin d’interagir avec les aspects asynchrones du chargement du fichier source d’image. L’infrastructure attend que la source d’image soit retournée et réexécutera la disposition lorsque le fichier source de l’image devient disponible.

La définition d’une valeur URI (Uniform Resource Identifier) qui ne peut pas être résolue en fichier source d’image valide ne lève pas d’exception. Au lieu de cela, il déclenche un événement ImageFailed . Les échecs de décodage déclenchent également ImageFailed. Vous pouvez écrire un gestionnaire ImageFailed et l’attacher à l’objet Image pour le détecter, et éventuellement utiliser errorMessage dans les données d’événement pour déterminer la nature de l’échec. En outre, si vous souhaitez vérifier qu’un fichier source d’image a été chargé correctement, vous pouvez gérer l’événement ImageOpened sur l’élément Image .

Définition de la source en XAML

Vous pouvez définir la propriété Source en tant qu’attribut en XAML. Dans ce cas, vous définissez la valeur de l’attribut Source en tant que chaîne URI (Uniform Resource Identifier) qui décrit l’emplacement du fichier image source. Ce comportement s’appuie sur la conversion de type sous-jacente qui traite la chaîne en tant qu’URI (Uniform Resource Identifier) et appelle l’équivalent du constructeur BitmapImage(URI). La définition de la propriété Source à l’aide d’une chaîne URI (Uniform Resource Identifier) est un raccourci activé par XAML. Notez que l’URI (Uniform Resource Identifier) semble ici être un URI relatif ; la prise en charge partielle de l’URI (Uniform Resource Identifier) est un autre raccourci XAML.

<Image Width="200" Source="Images/myImage.png"/>

L’analyseur XAML interprète toutes les chaînes qui représentent un URI (Uniform Resource Identifier) relatif à l’aide de l’URI (Uniform Resource Identifier) de base de la page XAML en cours d’analyse. Par exemple, si vous spécifiez une valeur « Images/myImage.png » en XAML, cette chaîne est interprétée comme un suffixe de chemin relatif ajouté à l’emplacement URI (Uniform Resource Identifier) de base dans le package d’application où la page XAML elle-même existe. Si l’élément Image précédent est ajouté à une page qui se trouve à la racine du package d’application, l’URI (Uniform Resource Identifier) est interprété comme ms-appx:///Images/myImage.png. Si l’image est ajoutée à une page qui se trouve dans un dossier Pages de l’application, l’URI (Uniform Resource Identifier) est interprété comme ms-appx:///Pages/Images/myImage.png.

Si l’image source ne fait pas partie du package d’application, vous devez utiliser un URI (Uniform Resource Identifier) absolu pour définir la propriété Source en XAML. Pour plus d’informations, consultez Comment charger des ressources de fichiers et des exemples plus loin dans ce document.

Une syntaxe d’élément de propriété en XAML est également possible, en spécifiant un élément objet BitmapImage avec une source valide comme valeur de propriété.

Définition de la source dans le code

Pour définir la propriété Image.Source dans le code, vous devez également construire une instance de BitmapImage (ou BitmapSource). Si votre source d’image est un flux, utilisez la méthode async SetSourceAsync de BitmapImage pour définir les informations d’image à partir du flux.

Si votre source d’image est un fichier référencé par URI (Uniform Resource Identifier), définissez la propriété BitmapImage.UriSource ou utilisez le constructeur BitmapImage qui prend un paramètre URI (Uniform Resource Identifier). Le Windows Runtime applique qu’un URI (Uniform Resource Identifier) doit être absolu ; vous ne pouvez pas utiliser l’URI (Uniform Resource Identifier) relatif dans Windows Runtime code. Si vous utilisez une valeur System.Uri .NET Framework et que vous utilisez une signature qui nécessite une valeur UriKind , veillez à spécifier Absolute.

Lorsque vous référencez du contenu local, vous devez inclure le schéma ms-appx: dans l’URI (Uniform Resource Identifier) absolu que vous utilisez comme BitmapImage.UriSource. Dans le code, vous n’obtenez pas les raccourcis de traitement permettant de combiner des parties URI (Uniform Resource Identifier) relatives et le schéma ms-appx: qui se produit automatiquement si vous spécifiez Source comme attribut XAML. Au lieu de cela, vous devez construire explicitement un URI (Uniform Resource Identifier) absolu avec le schéma approprié.

Voici comment définir la source sur une image à partir du package d’application.

Image img = new Image();
BitmapImage bitmapImage = new BitmapImage();
Uri uri = new Uri("ms-appx:///Assets/Logo.png");
bitmapImage.UriSource = uri;
img.Source = bitmapImage;

// OR

Image img = new Image();
img.Source = new BitmapImage(new Uri("ms-appx:///Assets/Logo.png"));

Windows::UI::Xaml::Controls::Image img;
Windows::UI::Xaml::Media::Imaging::BitmapImage bitmapImage;
Windows::Foundation::Uri uri{ L"ms-appx:///Assets/LockScreenLogo.png" };
bitmapImage.UriSource(uri);
img.Source(bitmapImage);

// OR

Windows::UI::Xaml::Controls::Image img;
img.Source(Windows::UI::Xaml::Media::Imaging::BitmapImage{ Windows::Foundation::Uri{ L"ms-appx:///Assets/LockScreenLogo.png" } });

auto img = ref new Image();
auto bitmapImage = ref new Windows::UI::Xaml::Media::Imaging::BitmapImage();
auto uri = ref new Windows::Foundation::Uri("ms-appx:///Assets/Logo.png");
bitmapImage->UriSource = uri;
img->Source = bitmapImage;

// OR

auto img = ref new Image();
img->Source = ref new BitmapImage(ref new Windows::Foundation::Uri("ms-appx:///Assets/Logo.png"));

Si vous devez vous assurer que le contrôle Image est prêt avant d’essayer de l’utiliser dans le code, gérez l’événement Loaded et définissez la propriété Source dans le gestionnaire d’événements.

Notes

L’événement FrameworkElement.Loaded se produit lorsque le contrôle Image est chargé dans la page XAML. L’événement ImageOpened se produit lorsque le fichier image est ouvert dans le contrôle Image.

Voici un exemple de définition de Image.Source dans le gestionnaire de l’événement Loaded . Dans cet exemple, l’objet Image a été créé en XAML, mais n’a pas de source ou d’autres valeurs de propriété ; au lieu de cela, ces valeurs sont fournies au moment de l’exécution lorsque l’image est chargée à partir de XAML.

<Image Loaded="Image_Loaded"/>

void Image_Loaded(object sender, RoutedEventArgs e)
{
    Image img = sender as Image;
    if (img != null)
    {
        BitmapImage bitmapImage = new BitmapImage();
        img.Width = bitmapImage.DecodePixelWidth = 280;
        bitmapImage.UriSource = new Uri("ms-appx:///Assets/Logo.png");
        img.Source = bitmapImage;
    }
}

void MainPage::Image_Loaded(winrt::Windows::Foundation::IInspectable const& sender, winrt::Windows::UI::Xaml::RoutedEventArgs const& /* e */)
{
    auto img{ sender.as<Windows::UI::Xaml::Controls::Image>() }; // throws if QI fails, so no need for null-check afterwards.
    Windows::UI::Xaml::Media::Imaging::BitmapImage bitmapImage;
    img.Width(280);
    bitmapImage.DecodePixelWidth(280);
    bitmapImage.UriSource(Windows::Foundation::Uri{ L"ms-appx:///Assets/LockScreenLogo.png" });
    img.Source(bitmapImage);
}

void App1::MainPage::Image_Loaded(Platform::Object^ sender, Windows::UI::Xaml::RoutedEventArgs^ e)
{
 auto img = dynamic_cast<Image^>(sender);
 if (img != nullptr)
 {
  auto bitmapImage = ref new BitmapImage();
  img->Width = 280; bitmapImage->DecodePixelWidth = 280;
  bitmapImage->UriSource = ref new Uri("ms-appx:///Assets/Logo.png");
  img->Source = bitmapImage;
 }
}

Vous pouvez gérer l’événement ImageOpened en cas de problèmes de minutage lors de la récupération ou du décodage de la source d’image, où vous devrez peut-être afficher un autre contenu jusqu’à ce que la source d’image soit disponible. Consultez l’exemple d’images XAML pour obtenir un exemple de code.

Utilisation d’un URI relatif dans le code

Nous avons vu précédemment que l’analyseur XAML interprète un URI (Uniform Resource Identifier) relatif à l’aide de l’URI (Uniform Resource Identifier) de base de la page XAML en cours d’analyse. Pour obtenir le même résultat dans le code, vous pouvez construire un URI à l’aide de l’un des constructeurs qui crée un URI (Uniform Resource Identifier) en combinant une base absolue, puis un chemin relatif à cet emplacement. Pour le premier paramètre, appelez BaseUri sur la page où l’image est chargée. (Vous pouvez également appeler BaseUri sur l’instance Image où vous définissez la source ou un autre élément de la page. Voir la mise en garde ci-dessous.) Cela crée un URI (Uniform Resource Identifier) avec le schéma ms-appx: et ajoute le chemin qui fait partie de l’emplacement de la page XAML. Pour le deuxième paramètre, transmettez la chaîne URI (Uniform Resource Identifier) relative qui décrit l’emplacement de l’image source.

En C# ou Microsoft Visual Basic, le type URI est projeté comme System.Uri. Par conséquent, utilisez le constructeur System.Uri(Uri, String) qui prend une chaîne comme deuxième paramètre. Dans les extensions de composant Visual C++ (C++/CX), utilisez Uri(String,String).

<Image x:Name="capturedPhoto"/>

BitmapImage bitmapImage = new BitmapImage();
// Call BaseUri on the root Page element and combine it with a relative path
// to consruct an absolute URI.
bitmapImage.UriSource = new Uri(this.BaseUri, "Assets/placeholder.png");
capturedPhoto.Source = bitmapImage;

auto bitmapImage = winrt::Windows::UI::Xaml::Media::Imaging::BitmapImage();
// Call BaseUri on the root Page element and combine it with a relative path
// to consruct an absolute URI.
bitmapImage.UriSource(winrt::Windows::Foundation::Uri(BaseUri().AbsoluteUri(), L"Assets/placeholder.png"));
capturedPhoto.Source(bitmapImage);

auto bitmapImage = ref new Windows::UI::Xaml::Media::Imaging::BitmapImage();
// Call BaseUri on the root Page element and combine it with a relative path
// to consruct an absolute URI.
bitmapImage->UriSource = ref new Windows::Foundation::Uri(BaseUri->AbsoluteUri, "Assets/placeholder.png");
capturedPhoto->Source = bitmapImage;

Notes

Si vous instanciez une nouvelle image dans le code, la propriété BaseUri est null jusqu’à ce que l’image soit ajoutée à l’arborescence visuelle de la page. Par exemple, le code suivant lève une exception ArgumentNull . Pour éviter l’exception, ajoutez l’image à l’arborescence visuelle avant de définir la propriété Source.

Cet exemple lève une exception, car il appelle BaseUri sur l’image avant l’ajout de l’image à la page. Il est supposé que « stackPanel1 » est un élément StackPanel déclaré en XAML.

Image img = new Image();
BitmapImage bitmapImage = new BitmapImage();

// AN EXCEPTION IS THROWN BECAUSE img.BaseUri IS NULL AT THIS POINT.
Uri uri = new Uri(img.BaseUri, "Assets/Logo.png");

bitmapImage.UriSource = uri;
img.Source = bitmapImage;
stackPanel1.Children.Add(img);

Image img;
BitmapImage bitmapImage;

// AN EXCEPTION IS THROWN BECAUSE img.BaseUri IS NULL AT THIS POINT.
Uri uri(img.BaseUri(), L"Assets/Logo.png");

bitmapImage.UriSource(uri);
img.Source(bitmapImage);
stackPanel1.Children().Add(img);

auto img = ref new Image();
auto bitmapImage = ref new Windows::UI::Xaml::Media::Imaging::BitmapImage();

// AN EXCEPTION IS THROWN BECAUSE img->BaseUri IS NULL AT THIS POINT.
auto uri = ref new Windows::Foundation::Uri(img->BaseUri->AbsoluteUri, "Assets/Logo.png");

bitmapImage->UriSource = uri;
img->Source = bitmapImage;
stackPanel1->Children->Append(img);

Pour éviter cette erreur, vous pouvez appeler BaseUri sur la page elle-même, comme indiqué précédemment, ou ajouter l’image à la page avant d’appeler BaseUri, comme illustré ici.

Dans cet exemple, l’image étant ajoutée à la page avant l’appel à BaseUri, BaseUri n’a pas la valeur Null. Il est supposé que « stackPanel1 » est un élément StackPanel déclaré en XAML.

Image img = new Image();
// Add the image to the page.
stackPanel1.Children.Add(img);

BitmapImage bitmapImage = new BitmapImage();
// img.BaseUri in not null because img has been added to the page.
Uri uri = new Uri(img.BaseUri, "Assets/Logo.png");
bitmapImage.UriSource = uri;
img.Source = bitmapImage;

Image img;
// Add the image to the page.
stackPanel1.Children().Add(img);

BitmapImage bitmapImage;
// img.BaseUri in not null because img has been added to the page.
Uri uri(img.BaseUri(), L"Assets/Logo.png");
bitmapImage.UriSource(uri);
img.Source(bitmapImage);

auto img = ref new Image();
// Add the image to the page.
stackPanel1->Children->Append(img);

auto bitmapImage = ref new Windows::UI::Xaml::Media::Imaging::BitmapImage();
// img->BaseUri in not null because img has been added to the page.
auto uri = ref new Windows::Foundation::Uri(img->BaseUri->AbsoluteUri, "Assets/Logo.png");
bitmapImage->UriSource = uri;
img->Source = bitmapImage;

Utilisation de fichiers à partir d’un réseau

Pour utiliser un fichier d’un emplacement réseau comme source d’image, utilisez les schémas http: ou https: , comme illustré ici. Spécifiez l’URI (Uniform Resource Identifier) absolu. Pour plus d’informations, consultez Comment charger des ressources de fichiers.

<Image Source="http://www.contoso.com/images/logo.png"/>

Image img = new Image();
img.Source = new BitmapImage(new Uri("http://www.contoso.com/images/logo.png"));

Image img;
img.Source(BitmapImage(Uri(L"http://www.contoso.com/images/logo.png")));

auto img = ref new Image();
img->Source = ref new BitmapImage(ref new Windows::Foundation::Uri("http://www.contoso.com/images/logo.png"));

Utilisation de fichiers à partir d’un stockage local

Pour utiliser des fichiers placés dans le stockage local de votre application comme source d’image, utilisez le schéma ms-appdata: , comme illustré ici. Spécifiez l’URI (Uniform Resource Identifier) absolu. Pour plus d’informations, consultez Comment charger des ressources de fichiers.

<!-- Access an image file stored in the local folder -->
<Image Source="ms-appdata:///local/images/logo.png"/>

<!-- Access an image file stored in the roaming folder -->
<Image Source="ms-appdata:///roaming/images/logo.png"/>

<!-- Access an image file stored in the temp folder -->
<Image Source="ms-appdata:///temp/images/logo.png"/>

var uri = new System.Uri("ms-appdata:///local/images/logo.png");
var file = await Windows.Storage.StorageFile.GetFileFromApplicationUriAsync(uri);

Image img = new Image();
img.Source = file;

Utilisation d’une source de flux pour afficher des images de la bibliothèque d’images

Une utilisation classique des éléments Image dans une application consiste à afficher des images de la bibliothèque Images de l’utilisateur. Ces images peuvent être accessibles par programmation ou via un FileOpenPicker. Dans les deux cas, l’objet StorageFile que vous obtenez peut être ouvert en tant que flux, mais ne fournit pas de référence URI (Uniform Resource Identifier) au fichier image. Pour utiliser un flux comme source d’image, vous devez écrire du code qui définit votre image instance à utiliser le flux. Cette opération ne peut pas être effectuée uniquement en XAML.

Pour afficher une image individuelle, utilisez les objets StorageFile de l’énumération de la bibliothèque et appelez OpenAsync pour obtenir un flux. Utilisez ce flux pour définir la source de l’image, en créant une image BitmapImage, puis en appelant SetSourceAsync et en transmettant le flux à utiliser comme paramètre streamSource .

Cet exemple montre comment utiliser un FileOpenPicker pour accéder à un fichier image à partir de la bibliothèque Images et le définir comme source d’un contrôle Image . Le code est déjà attendu, car il attend que l’utilisateur choisisse un fichier et ne s’exécute qu’après cela. Le flux à utiliser provient de StorageFile.OpenAsync après le retour d’un instance StorageFile à partir des actions du sélecteur asynchrone. Pour plus d’informations sur l’utilisation des sélecteurs de fichiers, consultez Ouvrir des fichiers et des dossiers avec un sélecteur.

<Button Content="Get photo" Click="GetPhotoButton_Click"/>

<Image x:Name="image1" Width="300"/>

private async void GetPhotoButton_Click(object sender, RoutedEventArgs e)
{
    // Set up the file picker.
    Windows.Storage.Pickers.FileOpenPicker openPicker = 
        new Windows.Storage.Pickers.FileOpenPicker();
    openPicker.SuggestedStartLocation = 
        Windows.Storage.Pickers.PickerLocationId.PicturesLibrary;
    openPicker.ViewMode = 
        Windows.Storage.Pickers.PickerViewMode.Thumbnail;

    // Filter to include a sample subset of file types.
    openPicker.FileTypeFilter.Clear();
    openPicker.FileTypeFilter.Add(".bmp");
    openPicker.FileTypeFilter.Add(".png");
    openPicker.FileTypeFilter.Add(".jpeg");
    openPicker.FileTypeFilter.Add(".jpg");

    // Open the file picker.
    Windows.Storage.StorageFile file = 
        await openPicker.PickSingleFileAsync();

    // 'file' is null if user cancels the file picker.
    if (file != null)
    {
        // Open a stream for the selected file.
        // The 'using' block ensures the stream is disposed
        // after the image is loaded.
        using (Windows.Storage.Streams.IRandomAccessStream fileStream =
            await file.OpenAsync(Windows.Storage.FileAccessMode.Read))
        {
            // Set the image source to the selected bitmap.
            Windows.UI.Xaml.Media.Imaging.BitmapImage bitmapImage =
                new Windows.UI.Xaml.Media.Imaging.BitmapImage();

            bitmapImage.SetSource(fileStream);
            image1.Source = bitmapImage;
        }
    }
}

Cet exemple montre comment accéder par programmation à un fichier image à partir de la bibliothèque Images et le définir comme source d’un contrôle Image . Pour accéder au contenu de la bibliothèque d’images par programmation, appelez StorageFolder.GetFilesAsync. N’oubliez pas que vous devez spécifier une fonctionnalité permettant d’accéder à la bibliothèque d’images par programme.

protected async override void OnNavigatedTo(NavigationEventArgs e)
{
    // Get the Pictures library
    Windows.Storage.StorageFolder picturesFolder = 
        Windows.Storage.KnownFolders.PicturesLibrary;
    IReadOnlyList<StorageFolder> folders = 
        await picturesFolder.GetFoldersAsync();

    // Process file folders
    foreach (StorageFolder folder in folders)
    {
        // Get and process files in folder
        IReadOnlyList<StorageFile> fileList = await folder.GetFilesAsync();
        foreach (StorageFile file in fileList)
        {
            Windows.UI.Xaml.Media.Imaging.BitmapImage bitmapImage = 
                new Windows.UI.Xaml.Media.Imaging.BitmapImage();

            // Open a stream for the selected file.
            // The 'using' block ensures the stream is disposed
            // after the image is loaded.
            using (Windows.Storage.Streams.IRandomAccessStream fileStream = 
                await file.OpenAsync(Windows.Storage.FileAccessMode.Read))
            {
                // Set the image source to the selected bitmap.
                Windows.UI.Xaml.Media.Imaging.BitmapImage bitmapImage =
                    new Windows.UI.Xaml.Media.Imaging.BitmapImage();
                bitmapImage.SetSource(fileStream);

                // Create an Image control.  
                Image img = new Image();
                img.Height = 50;
                img.Source = bitmapImage;

                // Add the Image control to the UI. 'imageGrid' is a
                // VariableSizedWrapGrid declared in the XAML page.
                imageGrid.Children.Add(img);
            }
        }
    }
}

Sources d’images et mise à l’échelle

Si vous référencez des images qui sont empaquetées dans votre application, vous devez créer vos sources d’images à plusieurs tailles recommandées, pour vous assurer que votre application s’affiche bien lorsque le Windows Runtime la met à l’échelle. Lorsque vous spécifiez une source pour une image en tant qu’URI (Uniform Resource Identifier), vous pouvez utiliser une convention de nommage qui référencera automatiquement la ressource d’image appropriée pour la mise à l’échelle actuelle, telle que détectée par le système au moment de l’exécution. 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 de la mise à l’échelle, consultez Tailles d’écran et points d’arrêt ou Remarques dans l’image.

Sources d’images et qualificateurs de ressources

Vous pouvez utiliser la gestion automatique pour accéder aux ressources non qualifiées avec des qualificateurs d’échelle et de culture actuels, ou vous pouvez utiliser ResourceManager et ResourceMap avec des qualificateurs pour la culture et la mise à l’échelle pour obtenir directement les ressources. Pour plus d’informations, consultez Système de gestion des ressources ou Remarques dans l’image. Pour plus d’informations sur les ressources d’application et sur la façon de empaqueter des sources d’images dans une application, consultez Définition des ressources d’application.

S’applique à

Partage via