Image.Source Proprietà

Riferimento

Definizione

Spazio dei nomi:: Windows.UI.Xaml.Controls

Importante

Alcune informazioni sono relative alla release non definitiva del prodotto, che potrebbe subire modifiche significative prima della release definitiva. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.

Modifica

Ottiene o imposta l'origine per l'immagine.

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"/>

Valore della proprietà

ImageSource

Oggetto che rappresenta il file di origine dell'immagine per l'immagine disegnata. In genere si imposta questo oggetto con un oggetto BitmapImage , costruito con l'URI (Uniform Resource Identifier) che descrive il percorso di un file di origine dell'immagine valido. In alternativa, è possibile inizializzare bitmapSource con un flusso, ad esempio un flusso da un file di archiviazione.

Commenti

L'impostazione della proprietà Source è intrinsecamente un'azione asincrona. Poiché è una proprietà, non esiste una sintassi attesa, ma per la maggior parte degli scenari non è necessario interagire con gli aspetti asincroni del caricamento dei file di origine dell'immagine. Il framework attende la restituzione dell'origine immagine e verrà eseguito nuovamente il layout quando il file di origine immagine diventa disponibile.

L'impostazione dell'origine su un valore URI (Uniform Resource Identifier) che non può essere risolto in un file di origine immagine valido non genera un'eccezione. Genera invece un evento ImageFailed . Gli errori di decodifica attivano anche ImageFailed. È possibile scrivere un gestore ImageFailed e collegarlo all'oggetto Image per rilevare il problema e eventualmente usare i dati errorMessage in eventi per determinare la natura dell'errore. Inoltre, se si vuole verificare che sia stato caricato correttamente un file di origine immagine, è possibile gestire l'evento ImageOpened nell'elemento Image .

Impostazione dell'origine in XAML

È possibile impostare la proprietà Source come attributo in XAML. In questo caso, si imposta il valore dell'attributo Source come stringa URI (Uniform Resource Identifier) che descrive il percorso del file di immagine di origine. Questo comportamento si basa sulla conversione dei tipi sottostanti che elabora la stringa come URI (Uniform Resource Identifier) e chiama l'equivalente del costruttore BitmapImage(Uri). L'impostazione della proprietà Source tramite una stringa URI (Uniform Resource Identifier) è un collegamento abilitato da XAML. Si noti che l'URI (Uniform Resource Identifier) viene visualizzato come un URI (Uniform Resource Identifier) relativo; il supporto di URI (Uniform Resource Identifier) parziale è un altro collegamento XAML.

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

Il parser XAML interpreta tutte le stringhe che rappresentano un URI (Uniform Resource Identifier) relativo usando l'URI (Uniform Resource Identifier) di base della pagina XAML analizzata. Ad esempio, se si specifica un valore "Images/myImage.png" in XAML, tale stringa viene interpretata come suffisso percorso relativo aggiunto alla posizione URI (Uniform Resource Identifier) di base all'interno del pacchetto dell'app in cui esiste la pagina XAML stessa. Se l'elemento Image precedente viene aggiunto a una pagina nella radice del pacchetto dell'app, l'URI (Uniform Resource Identifier) viene interpretato come ms-appx:///Images/myImage.png. Se l'immagine viene aggiunta a una pagina in una cartella Pages nell'app, l'URI (Uniform Resource Identifier) viene interpretato come ms-appx:///Pages/Images/myImage.png.

Se l'immagine di origine non fa parte del pacchetto dell'app, è necessario usare un URI (Uniform Resource Identifier) assoluto per impostare la proprietà Source in XAML. Per altre informazioni, vedere Come caricare le risorse dei file ed esempi più avanti in questo documento.

È anche possibile specificare un elemento BitmapImage con un'origine valida come valore della proprietà.

Impostazione dell'origine nel codice

Per impostare la proprietà Image.Source nel codice è necessaria un'istanza di BitmapImage (o BitmapSource), che è necessario costruire anche. Se l'origine immagine è un flusso, usare il metodo SetSourceAsync asincrono di BitmapImage per definire le informazioni sull'immagine dal flusso.

Se l'origine immagine è un file a cui fa riferimento l'URI (Uniform Resource Identifier), impostare la proprietà BitmapImage.UriSource oppure usare il costruttore BitmapImage che accetta un parametro URI (Uniform Resource Identifier). La Windows Runtime impone che un URI (Uniform Resource Identifier) sia assoluto. Non è possibile usare l'URI (Uniform Resource Identifier) relativo nel codice Windows Runtime. Se si usa un valore .NET Framework System.Uri e si usa una firma che richiede un valore UriKind , assicurarsi di specificare Absolute.

Quando si fa riferimento al contenuto locale, è necessario includere lo schema ms-appx: nello schema URI (Uniform Resource Identifier) assoluto usato come BitmapImage.UriSource. Nel codice non si ottengono i collegamenti di elaborazione per combinare parti URI (Uniform Resource Identifier) relative e lo schema ms-appx: si verifica automaticamente se si specifica Source come attributo XAML. È invece necessario costruire in modo esplicito un URI (Uniform Resource Identifier) assoluto con lo schema appropriato.

Ecco come impostare l'origine su un'immagine dal pacchetto dell'app.

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

Se è necessario assicurarsi che il controllo Image sia pronto prima di provare a usarlo nel codice, gestire l'evento Caricato e impostare la proprietà Source nel gestore eventi.

Nota

L'evento FrameworkElement.Loaded si verifica quando il controllo Image viene caricato nella pagina XAML. L'evento ImageOpened si verifica quando il file di immagine viene aperto nel controllo Image .

Ecco un esempio di impostazione di Image.Source nel gestore per l'evento Caricato . In questo esempio l'oggetto Image è stato creato in XAML, ma non ha un'origine o altri valori di proprietà; Questi valori vengono invece forniti in fase di esecuzione quando l'immagine viene caricata da 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;
 }
}

È possibile gestire l'evento ImageOpened se si verificano problemi di intervallo con il recupero o la decodifica dell'origine immagine, in cui potrebbe essere necessario visualizzare contenuto alternativo fino a quando non è disponibile l'origine dell'immagine. Per esempio, vedere l'esempio di immagini XAML .

Uso di un URI relativo nel codice

In precedenza, il parser XAML interpreta un URI (Uniform Resource Identifier) relativo usando l'URI (Uniform Resource Identifier) di base della pagina XAML analizzata. Per ottenere lo stesso risultato nel codice, è possibile costruire un URI usando uno dei costruttori che crea un URI (Uniform Resource Identifier) combinando una base assoluta e quindi un percorso relativo all'interno di tale posizione. Per il primo parametro, chiamare BaseUri nella pagina in cui viene caricata l'immagine . È anche possibile chiamare BaseUri nell'istanza di Image in cui si imposta l'origine o un altro elemento nella pagina. Vedere la prudenza riportata di seguito. In questo modo viene creato un URI (Uniform Resource Identifier) con lo schema ms-appx: lo schema e aggiunge il percorso che fa parte della posizione della pagina XAML. Per il secondo parametro, passare la stringa URI (Uniform Resource Identifier) relativa che descrive il percorso dell'immagine di origine.

In C# o Microsoft Visual Basic il tipo Uri viene proiettato come System.Uri, quindi usare il costruttore System.Uri(Uri, String) che accetta una stringa come secondo parametro. Nelle estensioni dei componenti di Visual C++ (C++/CX) usare 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;

Nota

Se si crea un'istanza di una nuova immagine nel codice, la proprietà BaseUri non è null finché l'immagine non viene aggiunta all'albero visivo di una pagina. Ad esempio, il codice seguente genera un'eccezione ArgumentNull . Per evitare l'eccezione, aggiungere l'immagine all'albero visivo prima di impostare la proprietà Source.

In questo esempio viene generata un'eccezione perché chiama BaseUri nell'immagine prima dell'aggiunta dell'immagine alla pagina. Si presuppone che " stackPanel1 " sia un elemento StackPanel dichiarato in 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);

Per evitare questo errore, è possibile chiamare BaseUri nella pagina stessa, come illustrato in precedenza o aggiungere l'immagine alla pagina prima di chiamare BaseUri, come illustrato qui.

In questo esempio, l'immagine viene aggiunta alla pagina prima della chiamata a BaseUri, quindi BaseUri non è null. Si presuppone che " stackPanel1 " sia un elemento StackPanel dichiarato in 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;

Uso di file da una rete

Per usare un file da un percorso di rete come origine immagine, usare gli schemi http: o https, come illustrato di seguito. Specificare l'URI (Uniform Resource Identifier) assoluto. Per altre informazioni, vedere Come caricare le risorse dei file.

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

Uso di file dall'archiviazione locale

Per usare i file inseriti nell'archiviazione locale dell'app come origine immagine, usare lo schema ms-appdata: come illustrato di seguito. Specificare l'URI (Uniform Resource Identifier) assoluto. Per altre informazioni, vedere Come caricare le risorse dei file.

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

Uso di un'origine di flusso per visualizzare immagini dalla libreria Immagini

Un uso tipico degli elementi Image in un'app consiste nel visualizzare immagini dalla libreria Immagini dell'utente. Queste immagini possono essere accessibili a livello di codice o tramite fileOpenPicker. In entrambi i casi, l'oggetto StorageFile che si ottiene può essere aperto come flusso, ma non fornisce un riferimento URI (Uniform Resource Identifier) al file di immagine. Per usare un flusso come origine immagine, è necessario scrivere codice che imposta l'istanza di Immagine per usare il flusso. Questa operazione non può essere eseguita solo in XAML.

Per visualizzare un'immagine singola, usare gli oggetti StorageFile dall'enumerazione della libreria e chiamare OpenAsync per ottenere un flusso. Usare questo flusso per impostare l'origine immagine creando una nuova BitmapImage, quindi chiamando SetSourceAsync e passando il flusso da usare come parametro streamSource .

In questo esempio viene illustrato come usare fileOpenPicker per accedere a un file di immagine dalla libreria Immagini e impostarlo come origine di un controllo Immagine . Il codice è già in attesa perché è in attesa che l'utente scelga un file e venga eseguito solo dopo tale operazione. Il flusso da usare proviene da StorageFile.OpenAsync dopo che un'istanza di StorageFile viene restituita dalle azioni di selezione asincrone. Per altre informazioni sull'uso di selezione file, vedere Aprire file e cartelle con una selezione.

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

In questo esempio viene illustrato come accedere a livello di codice a un file di immagine dalla libreria Immagini e impostarlo come origine di un controllo Immagine . Per accedere al contenuto della libreria Immagini a livello di codice, chiamare StorageFolder.GetFilesAsync. Tenere presente che è necessario specificare una funzionalità per accedere alla libreria Immagini a livello di codice.

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

Origini delle immagini e ridimensionamento

Se si fa riferimento a immagini in pacchetto nell'app, è consigliabile creare le origini immagini in diverse dimensioni consigliate, per assicurarsi che l'app sia ottimale quando l'Windows Runtime lo ridimensiona. Quando si specifica un'origine per un'immagine come URI (Uniform Resource Identifier), è possibile usare una convenzione di denominazione che farà riferimento automaticamente alla risorsa immagine corretta per il ridimensionamento corrente rilevato dal sistema in fase di esecuzione. Per le specifiche della convenzione di denominazione e ulteriori informazioni, vedi Guida introduttiva: Utilizzare risorse di file o immagine.

Per altre informazioni su come progettare per il ridimensionamento, vedere Dimensioni dello schermo e punti di interruzione o osservazioni nell'immagine.

Origini immagini e qualificatori di risorse

È possibile usare la gestione automatica per accedere alle risorse non qualificate con qualificatori di scalabilità e impostazioni cultura correnti oppure è possibile usare ResourceManager e ResourceMap con qualificatori per le impostazioni cultura e la scalabilità per ottenere direttamente le risorse. Per altre informazioni, vedere Sistema di gestione delle risorse o Osservazioni in Immagine. Per altre informazioni sulle risorse dell'app e su come creare pacchetti di origini immagini in un'app, vedere Definizione delle risorse dell'app.

Si applica a

Condividi tramite