Définir et utiliser des ressources

5 minutes

Une ressource s’apparente à une constante symbolique dans un langage de programmation. Vous la définissez à un seul endroit et la référencez là où vous en avez besoin. Vous lui attribuez un nom descriptif au lieu d’une valeur « magique », ce qui rend votre code plus facile à lire. Si vous devez changer la valeur d’une ressource, il vous suffit de mettre à jour la définition.

Dans ce module, vous découvrez comment utiliser des ressources pour éliminer les valeurs codées en dur dans votre XAML.

Qu’est-ce qu’une ressource ?

Une ressource est n’importe quel objet qui peut être partagé dans une interface utilisateur. Les polices, les couleurs et les tailles sont des exemples de ressources les plus courantes. Toutefois, vous pouvez aussi stocker des objets complexes comme des instances Style et OnPlatform en tant que ressources.

Vous définissez une ressource dans XAML ou dans le code. Vous l’appliquez ensuite dans XAML ou le code. En règle générale, vous travaillez toujours dans XAML, mais nous verrons plus tard quelques cas où le code est utile.

Prenons un exemple. Supposons que vous souhaitez utiliser les mêmes valeurs TextColor dans tous les contrôles figurant dans une page. Avec des valeurs codées en dur, votre XAML se présenterait comme suit. Notez que la valeur de la couleur du texte est répétée dans les deux contrôles.

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

Au lieu de répéter la couleur du texte, vous pouvez la définir comme une ressource. La définition ressemble alors à cet exemple XAML :

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

Notez que l’élément défini a une propriété x:Key qui donne un nom à la ressource. Vous utilisez cette clé pour rechercher la ressource dans votre XAML.

Avant de pouvoir utiliser une ressource, vous devez la stocker dans un dictionnaire de ressources.

Qu’est-ce que ResourceDictionary ?

ResourceDictionary est une classe de bibliothèque .NET MAUI personnalisée pour être utilisée avec des ressources d’interface utilisateur. C’est un dictionnaire où sont stockées des paires clé-valeur. La clé est obligatoirement du type String, tandis que la valeur peut être n’importe quel objet.

Chaque page XAML .NET MAUI a une propriété nommée Resources qui peut contenir un objet ResourceDictionary. La propriété étant null par défaut, vous devez créer une instance de dictionnaire pour pouvoir l’utiliser. Le code suivant montre comment créer un objet ResourceDictionary et l’affecter à la propriété Resources d’un ContentPage :

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

Le langage XAML .NET MAUI intègre une fonction qui crée l’instance de dictionnaire automatiquement dès que vous utilisez la propriété Resources. L’exemple de code précédent peut être simplifié de la façon suivante :

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

Chaque page de votre application peut avoir son propre dictionnaire. Dans ces dictionnaires au niveau de la page, vous stockez les ressources qui sont exclusivement utilisées dans cette page.

Remarque

Chaque contrôle d’une page peut également avoir son propre dictionnaire de ressources. Par exemple, vous pouvez ajouter un répertoire de ressources à un contrôle Label comme suit :

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

À part les dispositions et les vues, qui peuvent contenir des éléments enfants, il n’est pas courant de le faire au niveau du contrôle.

Créer une ressource

Pour créer une ressource, vous la déclarez à l’intérieur de la propriété Resources d’une page. L’exemple suivant crée la ressource de couleur de texte décrite précédemment

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

Lorsque vous sélectionnez une clé pour votre ressource, choisissez un nom qui reflète l’utilisation plutôt que la valeur de la ressource. Pour définir l’arrière-plan d’une étiquette sur Red par exemple, n’utilisez pas RedColor comme clé, utilisez plutôt BackgroundColor.

Appliquer une ressource avec StaticResource

StaticResource est une extension de balisage permettant de rechercher des ressources dans un dictionnaire de ressources. Vous fournissez la clé de la ressource et l’extension de balisage retourne la valeur correspondante. Le balisage XAML suivant montre un exemple qui crée et utilise une ressource Color appelée PageControlTextColor. Le balisage XAML du contrôle d’étiquette dans l’exemple utilise l’extension de balisage StaticResource pour récupérer la valeur.

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

...

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

L’extension est appelée StaticResource parce qu’elle n’est évaluée qu’une seule fois. La recherche dans le dictionnaire commence quand l’objet cible est créé. La propriété cible n’est pas mise à jour si la valeur de la ressource dans le dictionnaire change.

Avertissement

StaticResource lève une exception de runtime si la clé n’est pas trouvée.

Types intrinsèques XAML

L’exemple d’origine présenté au début de cette unité définit la propriété TextColor et la propriété FontSize :

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

FontSize a le type Double. Pour créer une ressource pour cette valeur, vous utilisez l’un des types intrinsèques XAML définis dans la spécification XAML. La spécification XAML définit les noms d’un grand nombre de types C# simples. Le code suivant montre un exemple de ressources pour chacun des types intrinsèques.

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

Définir des valeurs spécifiques à la plateforme pour une ressource

Il est fréquent d’avoir à adapter un peu l’interface utilisateur d’une application en fonction de la plateforme. La méthode standard pour définir les valeurs spécifiques à la plateforme consiste à utiliser un objet OnPlatform lorsque vous définissez une ressource. Par exemple, le code suivant montre comment créer une ressource qui référence différentes couleurs de texte sur iOS, Android, macOS (Mac Catalyst) et 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}" ... />