Immagine

L'interfaccia utente dell'app multipiattaforma .NET (.NET MAUI) Image visualizza un'immagine che può essere caricata da un file locale, un URI o un flusso. Sono supportati anche i formati di immagine standard della piattaforma, incluse le GIF animate e i file SVG (Scalable Vector Graphics) locali. Per altre informazioni sull'aggiunta di immagini a un progetto di app MAUI .NET, vedere Aggiungere immagini a un progetto di app MAUI .NET.

Image definisce le proprietà seguenti:

• Aspect, di tipo Aspect, definisce la modalità di ridimensionamento dell'immagine.
• IsAnimationPlaying, di tipo bool, determina se una GIF animata viene riprodotta o arrestata. Il valore predefinito di questa proprietà è false.
• IsLoading, di tipo bool, indica lo stato di caricamento dell'immagine. Il valore predefinito di questa proprietà è false.
• IsOpaque, di tipo bool, indica se il motore di rendering può considerare l'immagine come opaca durante il rendering. Il valore predefinito di questa proprietà è false.
• Source, di tipo ImageSource, specifica l'origine dell'immagine.

Queste proprietà sono supportate da BindableProperty oggetti, il che significa che possono essere stilizzati e essere la destinazione dei data binding.

Nota

Le icone dei tipi di carattere possono essere visualizzate da un oggetto Image specificando i dati dell'icona del carattere come FontImageSource oggetto . Per altre informazioni, vedere Visualizzare le icone dei tipi di carattere.

La ImageSource classe definisce i metodi seguenti che possono essere usati per caricare un'immagine da origini diverse:

• FromFile restituisce un oggetto FileImageSource che legge un'immagine da un file locale.
• FromUri restituisce un oggetto UriImageSource che scarica e legge un'immagine da un URI specificato.
• FromStream restituisce un oggetto StreamImageSource che legge un'immagine da un flusso che fornisce dati di immagine.

In XAML le immagini possono essere caricate da file e URI specificando il nome file o l'URI come valore stringa per la Source proprietà. Le immagini possono anche essere caricate da flussi in XAML tramite estensioni di markup personalizzate.

Importante

Le immagini verranno visualizzate con la risoluzione completa, a meno che le dimensioni dell'oggetto Image non siano vincolate dal relativo layout o che la HeightRequest proprietà o WidthRequest di Image sia specificata.

Per informazioni sull'aggiunta di icone dell'app e una schermata iniziale all'app, vedi Icone dell'app e schermata iniziale.

Caricare un'immagine locale

Le immagini possono essere aggiunte al progetto dell'app trascinandole nella cartella Resources\Images del progetto, in cui l'azione di compilazione verrà impostata automaticamente su MauiImage. In fase di compilazione, le immagini vettoriali vengono ridimensionate in base alle risoluzioni corrette per la piattaforma e il dispositivo di destinazione e aggiunte al pacchetto dell'app. Questa operazione è necessaria perché diverse piattaforme supportano risoluzioni delle immagini diverse e il sistema operativo sceglie la risoluzione dell'immagine appropriata in fase di esecuzione in base alle funzionalità del dispositivo.

Per rispettare le regole di denominazione delle risorse Android, tutti i nomi di file di immagine locali devono essere minuscoli, iniziali e finali con un carattere lettera e contengono solo caratteri alfanumerici o caratteri di sottolineatura. Per altre informazioni, vedere Panoramica delle risorse dell'app su developer.android.com.

Importante

.NET MAUI converte i file SVG in file PNG. Pertanto, quando si aggiunge un file SVG al progetto di app MAUI .NET, deve essere fatto riferimento da XAML o C# con estensione png.

L'adesione a queste regole per la denominazione e il posizionamento dei file consente al codice XAML seguente di caricare e visualizzare un'immagine:

<Image Source="dotnet_bot.png" />

Il codice C# equivalente è il seguente:

Image image = new Image
{
    Source = ImageSource.FromFile("dotnet_bot.png")
};

Il ImageSource.FromFile metodo richiede un string argomento e restituisce un nuovo FileImageSource oggetto che legge l'immagine dal file. Esiste anche un operatore di conversione implicito che consente di specificare il nome file come string argomento per la Image.Source proprietà :

Image image = new Image { Source = "dotnet_bot.png" };

Caricare un'immagine remota

Le immagini remote possono essere scaricate e visualizzate specificando un URI come valore della Source proprietà :

<Image Source="https://aka.ms/campus.jpg" />

Il codice C# equivalente è il seguente:

Image image = new Image
{
    Source = ImageSource.FromUri(new Uri("https://aka.ms/campus.jpg"))
};

Il ImageSource.FromUri metodo richiede un Uri argomento e restituisce un nuovo UriImageSource oggetto che legge l'immagine da Uri. È anche disponibile una conversione implicita per gli URI basati su stringhe:

Image image = new Image { Source = "https://aka.ms/campus.jpg" };

Memorizzazione nella cache delle immagini

La memorizzazione nella cache delle immagini scaricate è abilitata per impostazione predefinita, con le immagini memorizzate nella cache per 1 giorno. Questo comportamento può essere modificato impostando le proprietà della UriImageSource classe .

La UriImageSource classe definisce le proprietà seguenti:

• Uri, di tipo Uri, rappresenta l'URI dell'immagine da scaricare per la visualizzazione.
• CacheValidity, di tipo TimeSpan, specifica per quanto tempo l'immagine verrà archiviata in locale. Il valore predefinito di questa proprietà è 1 giorno.
• CachingEnabled, di tipo bool, definisce se la memorizzazione nella cache delle immagini è abilitata. Il valore predefinito di questa proprietà è true.

Queste proprietà sono supportate da BindableProperty oggetti, il che significa che possono essere stilizzati e essere la destinazione dei data binding.

Per impostare un periodo di cache specifico, impostare la Source proprietà su un UriImageSource oggetto che imposta la relativa CacheValidity proprietà:

<Image>
    <Image.Source>
        <UriImageSource Uri="https://aka.ms/campus.jpg"
                        CacheValidity="10:00:00:00" />
    </Image.Source>
</Image>

Il codice C# equivalente è il seguente:

Image image = new Image();
image.Source = new UriImageSource
{
    Uri = new Uri("https://aka.ms/campus.jpg"),
    CacheValidity = new TimeSpan(10,0,0,0)
};

In questo esempio il periodo di memorizzazione nella cache è impostato su 10 giorni.

Caricare un'immagine da un flusso

Le immagini possono essere caricate da flussi con il ImageSource.FromStream metodo :

Image image = new Image
{
    Source = ImageSource.FromStream(() => stream)
};

Importante

La memorizzazione nella cache delle immagini è disabilitata in Android durante il caricamento di un'immagine da un flusso con il ImageSource.FromStream metodo . Ciò è dovuto alla mancanza di dati da cui creare una chiave di cache ragionevole.

Caricare un'icona del tipo di carattere

L'estensione FontImage di markup consente di visualizzare un'icona del carattere in qualsiasi visualizzazione in grado di visualizzare un oggetto ImageSource. Fornisce la stessa funzionalità della FontImageSource classe , ma con una rappresentazione più concisa.

L'estensione FontImage di markup è supportata dalla FontImageExtension classe , che definisce le proprietà seguenti:

• FontFamily di tipo string, la famiglia di caratteri a cui appartiene l'icona del carattere.
• Glyph di tipo string, il valore del carattere Unicode dell'icona del tipo di carattere.
• Color di tipo Color, il colore da utilizzare durante la visualizzazione dell'icona del carattere.
• Size di tipo double, la dimensione, in unità indipendenti dal dispositivo, dell'icona del tipo di carattere di cui è stato eseguito il rendering. Il valore predefinito è 30. Inoltre, questa proprietà può essere impostata su una dimensione del carattere denominata.

Nota

Il parser XAML consente di abbreviatare la FontImageExtension classe come FontImage.

La Glyph proprietà è la proprietà content di FontImageExtension. Pertanto, per le espressioni di markup XAML espresse con parentesi graffe, puoi eliminare la Glyph= parte dell'espressione purché sia il primo argomento.

L'esempio XAML seguente illustra come usare l'estensione di FontImage markup:

<Image BackgroundColor="#D1D1D1"
       Source="{FontImage &#xf30c;, FontFamily=Ionicons, Size=44}" />

In questo esempio viene usata la versione abbreviata del nome della FontImageExtension classe per visualizzare un'icona XBox, dalla famiglia di tipi dicaratterei, in un Imageoggetto :

Mentre il carattere Unicode per l'icona è \uf30c, deve essere preceduto da un carattere di escape in XAML e quindi diventa .

Per informazioni sulla visualizzazione delle icone dei tipi di carattere specificando i dati dell'icona del carattere in un FontImageSource oggetto, vedere Visualizzare le icone dei tipi di carattere.

Caricare GIF animate

.NET MAUI include il supporto per la visualizzazione di GIF animate di piccole dimensioni. Questa operazione viene eseguita impostando la Source proprietà su un file GIF animato:

<Image Source="demo.gif" />

Importante

Anche se il supporto GIF animato in .NET MAUI include la possibilità di scaricare i file, non supporta la memorizzazione nella cache o lo streaming di GIF animate.

Per impostazione predefinita, quando viene caricata una GIF animata, non verrà riprodotta. Ciò è dovuto al fatto che la IsAnimationPlaying proprietà , che controlla se una GIF animata è in riproduzione o arrestata, ha un valore predefinito di false. Pertanto, quando viene caricata una GIF animata, non verrà riprodotta finché la IsAnimationPlaying proprietà non viene impostata su true. La riproduzione può essere arrestata reimpostando la IsAnimationPlaying proprietà su false. Si noti che questa proprietà non ha alcun effetto quando viene visualizzata un'origine immagine non GIF.

Controllare il ridimensionamento delle immagini

La Aspect proprietà determina la modalità di ridimensionamento dell'immagine in base all'area di visualizzazione e deve essere impostata su uno dei membri dell'enumerazione Aspect :

• AspectFit - casella di lettere l'immagine (se necessario) in modo che l'intera immagine si inserisca nell'area di visualizzazione, con spazio vuoto aggiunto all'angolo superiore/inferiore o ai lati a seconda che l'immagine sia larga o alta.
• AspectFill: ritaglia l'immagine in modo da riempire l'area di visualizzazione mantenendo le proporzioni.
• Fill: estende l'immagine in modo da riempire completamente l'area di visualizzazione. Ciò può comportare la distorsione dell'immagine.
• Center - centra l'immagine nell'area di visualizzazione mantenendo le proporzioni.