Definire e usare le risorse

5 minuti

Una risorsa è simile a una costante simbolica di un linguaggio di programmazione. La si definisce in una posizione e vi si fa riferimento ovunque sia necessario. Il codice è più facile da leggere perché si usa un nome descrittivo invece di un valore "magic". Se è necessario modificare il valore, è sufficiente aggiornare la definizione.

In questo modulo, si apprenderà come usare le risorse per eliminare i valori hardcoded dall'istanza Extensible Application Markup Language (XAML) in uso in .NET Multi-platform App UI (MAUI).

Che cos'è una risorsa?

Una risorsa è un oggetto che può essere condiviso nell'interfaccia utente. Gli esempi più comuni sono i tipi di carattere, i colori e le dimensioni. È tuttavia possibile archiviare come risorse anche oggetti complessi, ad esempio le istanze Stile e OnPlatform.

Si definisce una risorsa in XAML o nel codice, quindi la si applica in XAML o nel codice. In genere si lavora esclusivamente in XAML, anche se più avanti vengono illustrati alcuni casi in cui il codice è utile.

Si prenda in considerazione un esempio. Si supponga di voler usare gli stessi valori di TextColor nei controlli di una pagina. Se si usassero valori hardcoded, il codice XAML sarebbe simile al seguente. Si noti che il valore per il colore del testo viene ripetuto nei due controlli.

<Label TextColor="Blue" FontSize="14">
<Button TextColor="Blue" FontSize="14">

Invece di ripetere il colore del testo, è possibile definirlo come risorsa. La definizione è simile a questo XAML:

<Color x:Key="PageControlTextColor">Blue</Color>

Si noti come l'elemento definito abbia una proprietà x:Key che assegna un nome alla risorsa. Usare questa chiave per cercare la risorsa nel codice XAML.

Prima di poter usare una risorsa, è necessario archiviarla in un dizionario risorse.

Che cos'è ResourceDictionary?

ResourceDictionary è una classe di librerie .NET MAUI personalizzata per l'uso con le risorse dell'interfaccia utente. Essendo un dizionario, archivia le coppie chiave-valore. Il tipo della chiave è limitato a Stringa, mentre il valore può essere qualsiasi oggetto.

Ogni pagina XAML .NET MAUI ha una proprietà denominata Resources che può contenere un oggetto ResourceDictionary . Poiché la proprietà è Null per impostazione predefinita, è necessario creare un'istanza del dizionario prima di poterla usare. Il codice seguente mostra come creare un oggetto ResourceDictionary e assegnarlo alla proprietà Resources di una ContentPage:

<ContentPage.Resources>
    <ResourceDictionary>
        ...
    </ResourceDictionary>
</ContentPage.Resources>

Per impostazione predefinita, .NET MAUI XAML integra una pratica sintassi che crea l'istanza del dizionario automaticamente ogni volta che si inizia a usare la proprietà Resources. L'esempio precedente può essere semplificato con il codice seguente:

<ContentPage.Resources>
    ...
</ContentPage.Resources>

Ogni pagina dell'app può avere un proprio dizionario. Questi dizionari specifici delle pagine consentono di archiviare le risorse che vengono utilizzate esclusivamente in una determinata pagina.

Nota

Ogni controllo in una pagina può avere anche un proprio dizionario risorse. Ad esempio, è possibile aggiungere un dizionario risorse a un controllo Label in questo modo:

<Label Text="Hello, World!"
        ...
        <Label.Resources>
           ...
        </Label.Resources>
</Label>

Oltre ai layout e alle viste, che possono contenere elementi figlio, non è comune aggiungere un dizionario risorse a livello di controllo.

Creare una risorsa

Per creare una risorsa, è necessario dichiararla all'interno della proprietà Resources per una pagina. L'esempio seguente crea la risorsa colore testo descritta in precedenza

<ContentPage.Resources>
    <Color x:Key="PageControlTextColor">Blue</Color>
</ContentPage.Resources>

Quando si seleziona una chiave per la risorsa, scegliere un nome che rifletta l'uso anziché il valore della risorsa. Ad esempio, per impostare lo sfondo di un'etichetta su rosso, non usare RedColor come chiave, usare invece BackgroundColor.

Applicare una risorsa usando StaticResource

StaticResource è un’estensione di markup per cercare risorse in un dizionario risorse. Se si specifica la chiave della risorsa, l'estensione di markup restituisce il valore corrispondente. Il markup XAML seguente mostra un esempio che crea e usa una risorsa Color denominata PageControlTextColor. Il markup XAML per il controllo etichetta nell'esempio usa l'estensione di markup StaticResource per recuperare il valore.

<ContentPage.Resources>
    <Color x:Key="PageControlTextColor">Blue</Color>
</ContentPage.Resources>

...

<Label TextColor="{StaticResource PageControlTextColor}" ... />

L'estensione è denominata StaticResource perché viene valutata una sola volta. La ricerca nel dizionario viene eseguita quando viene creato l'oggetto di destinazione. Se il valore della risorsa nel dizionario viene modificato, la proprietà di destinazione non viene aggiornata.

Avviso

StaticResource genera un’eccezione di runtime se la chiave non viene trovata.

Tipi intrinseci di XAML

L'esempio originale presentato all'inizio di questa unità imposta la proprietà TextColor e la proprietà FontSize:

<Label TextColor="Blue" FontSize="14">
<Button TextColor="Blue" FontSize="14">

La proprietà FontSize ha il tipo Double. Per creare una risorsa per questo valore, è possibile usare uno dei tipi intrinseci XAML definiti nella specifica XAML. La specifica XAML definisce i nomi per molti dei tipi semplici C#. Il codice seguente illustra risorse di esempio per ognuno dei tipi intrinseci.

<ContentPage.Resources>
    <x:String x:Key="...">Hello</x:String>
    <x:Char x:Key="...">X</x:Char>
    <x:Single x:Key="...">31.4</x:Single>
    <x:Double x:Key="...">27.1</x:Double>
    <x:Byte x:Key="...">8</x:Byte>
    <x:Int16 x:Key="...">16</x:Int16>
    <x:Int32 x:Key="...">32</x:Int32>
    <x:Int64 x:Key="...">64</x:Int64>
    <x:Decimal x:Key="...">12345</x:Decimal>
    <x:TimeSpan x:Key="...">1.23:5959</x:TimeSpan>
    <x:Boolean x:Key="...">True</x:Boolean>
</ContentPage.Resources>

Impostare valori specifici della piattaforma per una risorsa

Accade spesso di dover modificare leggermente l'interfaccia utente dell'app a seconda della piattaforma. Il modo standard per definire i valori specifici della piattaforma consiste nell'usare un oggetto OnPlatform quando si definisce una risorsa. Ad esempio, il codice seguente mostra come creare una risorsa che fa riferimento a colori di testo diversi in iOS, Android, macOS (Mac Catalyst) e Windows (WinUI).

<ContentPage.Resources>
    <OnPlatform x:Key="textColor" x:TypeArguments="Color">
        <On Platform="iOS" Value="Silver" />
        <On Platform="Android" Value="Green" />
        <On Platform="WinUI" Value="Yellow" />
        <On Platform="MacCatalyst" Value="Pink" />
    </OnPlatform> 
</ContentPage.Resources>
...

<Label TextColor="{StaticResource textColor}" ... />