Image.Source Proprietà
Definizione
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.
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à
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é si tratta di una proprietà, non esiste una sintassi awaitable, ma per la maggior parte degli scenari non è necessario interagire con gli aspetti asincroni del caricamento dei file di origine delle immagini. Il framework attenderà la restituzione dell'origine dell'immagine e eseguirà nuovamente il layout quando il file di origine dell'immagine diventa disponibile.
L'impostazione dell'origine su un valore URI (Uniform Resource Identifier) che non può essere risolto in un file di origine dell'immagine valido non genera un'eccezione. Genera invece un evento ImageFailed . Gli errori di decodifica generano anche ImageFailed. È possibile scrivere un gestore ImageFailed e collegarlo all'oggetto Image per rilevarlo e, eventualmente, usare ErrorMessage nei dati dell'evento per determinare la natura dell'errore. Inoltre, se si desidera verificare che un file di origine dell'immagine sia stato caricato correttamente, è possibile gestire l'evento ImageOpened nell'elemento Image .
Impostazione dell'origine in XAML
Puoi 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 del tipo sottostante 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) sembra essere un URI (Uniform Resource Identifier) relativo; il supporto di un 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 specifichi un valore "Images/myImage.png" in XAML, tale stringa viene interpretata come suffisso di 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 che si trova 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 che si trova 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, devi usare un URI (Uniform Resource Identifier) assoluto per impostare la proprietà Source in XAML. Per altre informazioni, vedere Come caricare le risorse di 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. Se l'origine dell'immagine è un flusso, usare il metodo setSourceAsync asincrono di BitmapImage per definire le informazioni sull'immagine dal flusso.
Se l'origine dell'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). Il 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 System.Uri di .NET Framework 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: nell'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: che avviene 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 Loaded 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 Loaded . 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 tempo durante il recupero o la decodifica dell'origine dell'immagine, in cui potrebbe essere necessario visualizzare contenuto alternativo fino a quando l'origine dell'immagine non è disponibile. Vedi l'esempio di immagini XAML per codice di esempio.
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 image in cui si imposta l'origine o un altro elemento nella pagina. Vedere attenzione di seguito. In questo modo viene creato un URI (Uniform Resource Identifier) con lo schema ms-appx: e viene aggiunto 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 del componente 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 = 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 un nuovo oggetto Image nel codice, la proprietà BaseUri è Null finché l'immagine non viene aggiunta all'albero visuale di una pagina. Ad esempio, il codice seguente genera un'eccezione ArgumentNull . Per evitare l'eccezione, aggiungere Image all'albero visuale prima di impostare la proprietà Source.
In questo esempio viene generata un'eccezione perché chiama BaseUrinell'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);
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, oppure aggiungere l'immagine alla pagina prima di chiamare BaseUri, come illustrato di seguito.
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;
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 dell'immagine, usare gli schemi http: o https: come illustrato di seguito. Specificare l'URI (Uniform Resource Identifier) assoluto. Per altre info, vedi Come caricare le risorse 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"));
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 nella risorsa di archiviazione locale dell'app come origine dell'immagine, usare lo schema ms-appdata: come illustrato di seguito. Specificare l'URI (Uniform Resource Identifier) assoluto. Per altre info, vedi Come caricare le risorse 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 raccolta Immagini
Un uso tipico degli elementi Image in un'app consiste nel mostrare immagini dalla raccolta immagini dell'utente. È possibile accedere a queste immagini a livello di codice o tramite un oggetto 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 Image per l'uso del flusso. Questa operazione non può essere eseguita solo in XAML.
Per visualizzare una singola immagine, usare gli oggetti StorageFile dall'enumerazione della libreria e chiamare OpenAsync per ottenere un flusso. Usare questo flusso per impostare l'origine dell'immagine creando una nuova bitmapImage, quindi chiamando SetSourceAsync e passando il flusso da usare come parametro streamSource .
In questo esempio viene illustrato come usare un oggetto FileOpenPicker per accedere a un file di immagine dalla raccolta Immagini e impostarlo come Origine di un controllo Immagine . Il codice è già awaitable 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 delle selezioni file, vedi 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 raccolta Immagini e impostarlo come Origine di un controllo Immagine . Per accedere al contenuto della raccolta Immagini a livello di codice, chiamare StorageFolder.GetFilesAsync. Tenere presente che è necessario specificare una funzionalità per accedere alla raccolta 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 fai riferimento a immagini incluse nel pacchetto nella tua app, devi creare le origini delle immagini con diverse dimensioni consigliate, per assicurarti che l'app abbia un aspetto ottimale quando il 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à automaticamente riferimento alla risorsa immagine corretta per la scalabilità corrente rilevata 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 info su come progettare per il ridimensionamento, vedi Design reattivo 101 per o Osservazioni in Immagine.
Origini di immagini e qualificatori di risorse
È possibile usare la gestione automatica per accedere a risorse non qualificate con qualificatori di scala 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 info, vedi Sistema di gestione delle risorse o Osservazioni in Immagine. Per altre info sulle risorse dell'app e su come creare un pacchetto di origini immagini in un'app, vedi Definizione delle risorse dell'app.