Share via

Aggiungere un'icona dell'app a un progetto di app MAUI .NET

  • Articolo

Ogni app ha un'icona del logo che lo rappresenta e tale icona viene in genere visualizzata in più posizioni. Ad esempio, in iOS l'icona dell'app viene visualizzata nella schermata Home e in tutto il sistema, ad esempio in Impostazioni, notifiche e risultati della ricerca e nell'App Store. In Android l'icona dell'app viene visualizzata come icona di avvio e in tutto il sistema, ad esempio nella barra delle azioni, nelle notifiche e in Google Play Store. In Windows l'icona dell'app viene visualizzata nell'elenco delle app nel menu Start, nella barra delle applicazioni, nel riquadro dell'app e in Microsoft Store.

In un progetto di app .NET Multipiattaforma (.NET MAUI) un'icona dell'app può essere specificata in un'unica posizione nel progetto dell'app. In fase di compilazione, questa icona può essere ridimensionata automaticamente in base alla risoluzione corretta per la piattaforma e il dispositivo di destinazione e aggiunta al pacchetto dell'app. In questo modo si evita di dover duplicare manualmente e denominare l'icona dell'app in base alla piattaforma. Per impostazione predefinita, i formati di immagine bitmap (non vettoriali) non vengono ridimensionati automaticamente da .NET MAUI.

Un'icona dell'app .NET MAUI può usare uno qualsiasi dei formati standard di immagine della piattaforma, inclusi i file SVG (Scalable Vector Graphics).

Importante

.NET MAUI converte i file SVG in file PNG (Portable Network Graphic). 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'unico riferimento al file SVG deve essere nel file di progetto.

Modificare l'icona

Nel progetto MAUI .NET l'immagine con l'azione di compilazione definisce l'icona da usare per l'app MauiIcon . Questa operazione è rappresentata nel file di progetto come <MauiIcon> elemento. Potresti avere una sola icona definita per la tua app. Tutti gli elementi successivi <MauiIcon> vengono ignorati.

L'icona definita dall'app può essere costituita da una singola immagine, specificando il file come Include attributo:

<ItemGroup>
    <MauiIcon Include="Resources\AppIcon\appicon.svg" />
</ItemGroup>

Solo il primo <MauiIcon> elemento definito nel file di progetto viene elaborato da .NET MAUI. Se si vuole usare un file diverso come icona, eliminare prima l'icona esistente dal progetto e quindi aggiungere la nuova icona trascinandola nella cartella Resources\AppIcon del progetto. Visual Studio imposta automaticamente l'azione di compilazione su MauiIcon e creerà un elemento corrispondente <MauiIcon> nel file di progetto.

Nota

Un'icona dell'app può anche essere aggiunta ad altre cartelle del progetto dell'app. In questo scenario, tuttavia, l'azione di compilazione deve essere impostata manualmente su MauiIcon nella finestra Proprietà .

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

Dopo aver modificato il file icona, potrebbe essere necessario pulire il progetto in Visual Studio. Per pulire il progetto, fare clic con il pulsante destro del mouse sul file di progetto nel riquadro Esplora soluzioni e scegliere Pulisci. Potrebbe anche essere necessario disinstallare l'app dalla piattaforma di destinazione con cui si sta testando.

Attenzione

Se non pulisci il progetto e disinstalla l'app dalla piattaforma di destinazione, potresti non visualizzare la nuova icona.

Dopo aver modificato l'icona, esaminare le informazioni di configurazione specifiche della piattaforma .

Icona composta

In alternativa, l'icona dell'app può essere composta da due immagini, un'immagine che rappresenta lo sfondo e un'altra che rappresenta il primo piano. Poiché le icone vengono trasformate in file PNG, l'icona dell'app composta verrà prima a livelli con l'immagine di sfondo, in genere un'immagine di un motivo o un colore a tinta unita, seguita dall'immagine in primo piano. In questo caso, l'attributo Include rappresenta l'immagine di sfondo dell'icona e l'attributo Foreground rappresenta l'immagine in primo piano:

<ItemGroup>
    <MauiIcon Include="Resources\AppIcon\appicon.svg" ForegroundFile="Resources\AppIcon\appiconfg.svg" />
</ItemGroup>

Importante

L'immagine di sfondo (Include attributo ) deve essere specificata per l'elemento <MauiIcon> . L'immagine in primo piano (ForegroundFile attributo) è facoltativa.

Impostare le dimensioni di base

.NET MAUI usa l'icona su più piattaforme e dispositivi e tenta di ridimensionare l'icona in base a ogni piattaforma e dispositivo. L'icona dell'app viene usata anche per scopi diversi, ad esempio una voce dello Store per l'app o l'icona usata per rappresentare l'app dopo l'installazione in un dispositivo.

Le dimensioni di base dell'icona rappresentano la densità di base dell'immagine ed è effettivamente il fattore di scala 1,0 da cui derivano tutte le altre dimensioni. Se non specifichi le dimensioni di base per un'icona dell'app basata su bitmap, ad esempio un file PNG, l'immagine non viene ridimensionata. Se non specifichi le dimensioni di base per un'icona dell'app basata su vettore, ad esempio un file SVG, le dimensioni specificate nell'immagine vengono usate come dimensioni di base. Per impedire il ridimensionamento di un'immagine vettoriale, impostare l'attributo Resize su false.

La figura seguente illustra come le dimensioni di base influiscono su un'immagine:

How base size affects an app icon for .NET MAUI.

Il processo illustrato nella figura precedente segue questa procedura:

  • A: l'immagine viene aggiunta come icona MAUI .NET e ha dimensioni pari a 210x260 e la dimensione di base è impostata su 424x520.
  • B: .NET MAUI ridimensiona automaticamente l'immagine in modo che corrisponda alle dimensioni di base di 424x520.
  • C: poiché diverse piattaforme di destinazione richiedono dimensioni diverse dell'immagine, .NET MAUI ridimensiona automaticamente l'immagine dalle dimensioni della base a dimensioni diverse.

Suggerimento

Usare un'immagine SVG come icona. Le immagini SVG possono essere di alto livello fino a dimensioni maggiori e sembrano ancora nitide e pulite. Le immagini basate su bitmap, ad esempio un'immagine PNG o JPG, sembrano sfocate quando sono di alto livello.

La dimensione di base viene specificata con l'attributo BaseSize="W,H" , dove W è la larghezza dell'icona ed H è l'altezza dell'icona. Nell'esempio seguente vengono impostate le dimensioni di base:

<ItemGroup>
    <MauiIcon Include="Resources\AppIcon\appicon.png" BaseSize="128,128" />
</ItemGroup>

L'esempio seguente arresta il ridimensionamento automatico di un'immagine basata su vettore:

<ItemGroup>
    <MauiIcon Include="Resources\AppIcon\appicon.svg" Resize="false" />
</ItemGroup>

Ricolorare lo sfondo

Se l'immagine di sfondo usata per comporre l'icona dell'app usa la trasparenza, può essere ricolorata specificando l'attributo Color in <MauiIcon>. L'esempio seguente imposta il colore di sfondo dell'icona dell'app su rosso:

<ItemGroup>
    <MauiIcon Include="Resources\AppIcon\appicon.svg" Color="#FF0000" />
</ItemGroup>

I valori di colore possono essere specificati in formato esadecimale, usando il formato o #RRGGBB#AARRGGBB. Il valore di RR rappresenta il canale rosso, GG il canale verde, BB il canale blu e AA il canale alfa. Anziché un valore esadecimale, è possibile usare un colore MAUI denominato .NET, ad esempio Red o PaleVioletRed.

Attenzione

Se non definisci un colore di sfondo per l'icona dell'app, lo sfondo viene considerato tranparent in iOS e Mac Catalyst. Questo causerà un errore durante la verifica Connessione dell'App Store e non sarà possibile caricare l'app.

Ricolorare il primo piano

Se l'icona dell'app è composta da un'immagine di sfondo (Include) e da un'immagine in primo piano (ForegroundFile), l'immagine di primo piano può essere tinta. Per tintare l'immagine di primo piano, specificare un colore con l'attributo TintColor . Nell'esempio seguente viene tintato il giallo dell'immagine in primo piano:

<ItemGroup>
    <MauiIcon Include="Resources\AppIcon\appicon.png" ForegroundFile="Resources\AppIcon\appiconfg.svg" TintColor="Yellow" />
</ItemGroup>

I valori di colore possono essere specificati in formato esadecimale, usando il formato o #RRGGBB#AARRGGBB. Il valore di RR rappresenta il canale rosso, GG il canale verde, BB il canale blu e AA il canale alfa. Anziché un valore esadecimale, è possibile usare un colore MAUI denominato .NET, ad esempio Red o PaleVioletRed.

Usare un'icona diversa per ogni piattaforma

Se si vogliono usare diverse risorse icona o impostazioni per ogni piattaforma, aggiungere l'attributo Condition all'elemento <MauiIcon> ed eseguire una query per la piattaforma specifica. Se la condizione viene soddisfatta, l'elemento <MauiIcon> viene elaborato. Solo il primo elemento valido <MauiIcon> viene usato da .NET MAUI, quindi tutti gli elementi condizionali devono essere dichiarati per primi, seguiti da un elemento predefinito <MauiIcon> senza una condizione. Il codice XML seguente illustra la dichiarazione di un'icona specifica per Windows e un'icona di fallback per tutte le altre piattaforme:

<ItemGroup>
    <!-- App icon for Windows -->
    <MauiIcon Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'windows'"
              Include="Resources\AppIcon\backicon.png" ForegroundFile="Resources\AppIcon\appiconfg.svg" TintColor="#40FF00FF" />

    <!-- App icon for all other platforms -->
    <MauiIcon Include="Resources\AppIcon\appicon.png" ForegroundFile="Resources\AppIcon\appiconfg.svg" TintColor="Yellow" />
</ItemGroup>

È possibile impostare la piattaforma di destinazione modificando il valore confrontato nella condizione con uno dei valori seguenti:

  • 'ios'
  • 'maccatalyst'
  • 'android'
  • 'windows'

Ad esempio, una condizione destinata ad Android sarebbe Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'android'".

Configurazione specifica della piattaforma

Mentre il file di progetto dichiara le risorse da cui è composta l'icona dell'app, è comunque necessario aggiornare le singole configurazioni della piattaforma con riferimento a tali icone dell'app. Le informazioni seguenti descrivono queste impostazioni specifiche della piattaforma.

L'icona usata da Android è specificata nel manifesto Android, che si trova in Platforms\Android\AndroidManifest.xml. Il manifest/application nodo contiene due attributi per definire l'icona: android:icon e android:roundIcon. I valori di questi due attributi seguono questo formato: @mipmap/{name} e @mipmap/{name}_round, rispettivamente. Il valore per {name} è derivato dall'elemento del file di <MauiIcon> progetto .NET MAUI, in particolare il nome file definito dall'attributo, senza il percorso o l'estensione Include .

Si consideri l'esempio seguente, che definisce la risorsa Resources\AppIcon\healthapp.png come icona:

<ItemGroup>
    <MauiIcon Include="Resources\AppIcon\healthapp.png" ForegroundFile="Resources\AppIcon\appiconfg.svg" TintColor="Yellow" />
</ItemGroup>

Il nome trasformato, la risorsa senza il percorso o l'estensione, è healthapp. I valori per android:icon e android:roundIcon sono @mipmap/healthapp rispettivamente e @mipmap/healthapp_round. Il manifesto android deve essere aggiornato in modo che corrisponda healthapp all'icona:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application android:allowBackup="true" android:icon="@mipmap/healthapp" android:roundIcon="@mipmap/healthapp_round" android:supportsRtl="true"></application>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.INTERNET" />
</manifest>

Suggerimento

Anziché creare nuovi file di immagine per l'icona, sostituire semplicemente i due file di immagine forniti dal modello MAUI .NET: Resources\AppIcon\appicon.svg per lo sfondo e Resources\AppIcon\appiconfg.svg in primo piano.

Utilità di avvio adattivo

.NET MAUI supporta la creazione di un'icona di avvio adattiva in Android 8.0 e versioni successive, dall'icona dell'app. Le icone dell'utilità di avvio adattivo possono essere visualizzate come varie forme in diversi modelli di dispositivo, tra cui circolare e quadrata. Per altre informazioni sulle icone adattive, vedere la Guida per sviluppatori Android: Icone adattive.

Le icone dell'utilità di avvio adattivo sono icone composte, usando un livello di sfondo e un livello di primo piano e un valore di ridimensionamento facoltativo. Per altre informazioni, vedere la sezione Icona composta. Se l'icona composta è definita, specificando l'attributo ForegroundFile , verrà generata un'icona di avvio adattivo. Il codice XML seguente illustra la definizione di un'icona usata come icona di avvio adattivo:

<ItemGroup>
    <MauiIcon Include="Resources\AppIcon\appicon.svg" ForegroundFile="Resources\AppIcon\appiconfg.svg" ForegroundScale="0.65" Color="#512BD4" />
</ItemGroup>

L'attributo ForegroundScale può essere facoltativamente specificato per modificare il ridimensionamento del livello in primo piano di cui viene eseguito il rendering sul livello di sfondo.