Propriétés pouvant être liées et modèles de contrôle dans .NET MAUI

Découvrez comment combiner des vues de contenu avec des propriétés pouvant être liées, afin de pouvoir contrôler à la fois l’apparence et le comportement d’un contrôle personnalisé.

Dans le monde du développement mobile et du développement en général, il est toujours nécessaire de combiner deux ou plusieurs contrôles pour créer des composants plus complexes que nous pouvons réutiliser dans différents projets. Heureusement, .NET MAUI possède des fonctionnalités qui nous permettent d’y parvenir.

Dans cet article, vous apprendrez comment créer un composant réutilisable qui montre la progression d’une tâche. Nous y parviendrons en combinant des vues de contenu avec des propriétés pouvant être liées, ce qui nous permettra de contrôler à la fois l’apparence et le comportement du contrôle personnalisé. Commençons !

Création d’une vue de contenu

UN Vue de contenu est un contrôle qui permet la création de contrôles réutilisables et personnalisés. Vous pouvez considérer ce champ comme une toile vierge sur laquelle vous pouvez placer différents champs, images, textes, etc., dans le but de le réutiliser dans une ou plusieurs applications.

Quelques exemples d’utilisation d’un contrôle ContentView pourraient consister à définir l’apparence visuelle des lignes dans un CollectionView ou une vue personnalisée pour un TitleView. Bien qu’il existe plusieurs manières de créer un ContentView, la plus simple est de cliquer sur le menu contextuel de l’explorateur de solutions, puis Clic droit | Ajouter | Nouvel article | Page de contenu .NET MAUI (XAML) comme indiqué ci-dessous :

Certaines choses à noter dans l’image précédente sont qu’il est également possible de créer un fichier ContentView avec uniquement du code C#. Dans mon cas, j’utiliserai le modèle XAML avec le nom Téléchargeur.

Ajout de contenu à ContentView

Une fois le fichier ContentView créé, il sera ouvert automatiquement. Ce fichier a une structure similaire à une ContentPage à la différence que le type de conteneur est un ContentView:

<ContentView xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="CustomControlDemo.Views.Downloader">
    ...
</ContentView>

Tout comme une ContentPage, une ContentView a un Content propriété, que nous pouvons utiliser pour ajouter n’importe quel contenu souhaité. Dans cet exemple, nous utiliserons les contrôles suivants pour créer le contrôle personnalisé :

• UN Border pour regrouper le contenu du champ et ajouter une ombre
• UN Label pour afficher un message personnalisé sur le téléchargement en général
• UN Label pour indiquer le pourcentage réalisé
• UN RadLinearProgressBar contrôle pour indiquer visuellement la progression

Le code XAML ressemblerait à ceci :

<Grid Margin="10" MaximumHeightRequest="150">
    <Border
        Background="White"
        Stroke="White"
        StrokeShape="RoundRectangle 10">
        <Grid Margin="15" RowDefinitions="*,*,Auto">
            <Label
                x:Name="SubTitleControl"
                FontAttributes="Bold"
                FontSize="12"
                Text="Your progress"
                TextColor="#BFC9D2" />
            <Label
                x:Name="TitleControl"
                Grid.Row="1"
                FontAttributes="Bold"
                FontSize="15"
                Text="30% To Complete"
                TextColor="#0F49F7" />
            <telerik:RadLinearProgressBar
                x:Name="ProgressControl"
                Grid.Row="2"
                Margin="0,10,0,0"
                AutomationId="progressBar"
                Value="60" />
        </Grid>
        <Border.Shadow>
            <Shadow
                Brush="Gray"
                Opacity="0.8"
                Radius="40"
                Offset="20,20" />
        </Border.Shadow>
    </Border>
</Grid>

Avec cela, nous avons créé le contenu du contrôle personnalisé. L’étape suivante consiste à l’utiliser quelque part dans le projet .NET MAUI, ce que nous ferons ensuite.

Utilisation du contrôle personnalisé dans le projet

Une fois que nous aurons créé le contrôle personnalisé, nous l’utiliserons dans notre projet. Pour ce faire, vous devez d’abord ajouter la référence à l’emplacement de l’espace de noms de votre contrôle. J’ai créé un dossier appelé Contrôles au sein du projet, l’espace de noms à utiliser sera donc le suivant :

xmlns:controls="clr-namespace:CustomControlDemo.Controls"

Une fois la référence créée, il suffit d’utiliser le contrôle, comme dans l’exemple suivant :

<VerticalStackLayout Spacing="50" VerticalOptions="Center">
    <controls:Downloader />
    <Button Margin="25" Text="Start Download" />
</VerticalStackLayout>

Cela affichera le contrôle lorsque l’application est exécutée, comme dans l’image suivante :

Le contrôle a sans aucun doute fière allure, mais il n’est pas utilisable pour le moment car il n’y a aucun moyen de manipuler les valeurs du contrôle personnalisé. C’est là que Bindable Properties peut nous aider à créer un point d’accès pour un contrôle personnalisé. Voyons comment les utiliser !

Création de votre première propriété pouvant être liée

UN propriété pouvant être liée permet d’étendre une propriété Common Language Runtime (CLR) en utilisant un BindableProperty tapez au lieu d’un champ. En bref, cela signifie que nous pourrons utiliser ces propriétés via la liaison de données et, si nécessaire, nous pourrons attribuer des valeurs par défaut, valider les valeurs des propriétés et ajouter des rappels pour exécuter des actions lorsque les valeurs des propriétés changent.

Pour créer une propriété pouvant être liée, nous irons dans la classe où nous voulons l’ajouter. Dans notre exemple, nous irons au Downloader.xaml.cs déposer. Dans ce fichier, nous allons créer le BindableProperty suivant :

public static readonly BindableProperty TitleProperty =
    BindableProperty.Create
    (
        "Title",
        typeof(string),
        typeof(Downloader),
        "0% To Complete",
        propertyChanged: (bindable, oldValue, newValue) =>
        {
            if (bindable is Downloader instance)
            {
                instance.TitleControl.Text = (string)newValue;
            }
        });

Voici ce que fait chaque ligne du code précédent :

1. Spécifie l’identifiant de la propriété pouvant être liée (TitleProperty), avec la signature public static readonly BindableProperty. Cette signature doit toujours être utilisée lors de la création d’une propriété pouvant être liée et, par convention, elle doit contenir le mot « Propriété » à la fin.
2. Invoque le Create méthode, qui initialise l’instance en fonction des paramètres fournis.
3. Spécifie le nom de la propriété pouvant être liée, qui, par convention, doit être identique à l’identifiant mais sans le mot « Propriété ».
4. Spécifie le type de la propriété pouvant être liée. Dans notre cas, puisque nous souhaitons modifier le texte qui affiche le pourcentage complété, nous indiquerons qu’il est de type chaîne.
5. Spécifie le type de l’objet qui contient la propriété pouvant être liée ; dans notre exemple, la classe conteneur est Downloader.
6. Spécifie une valeur par défaut, ce qui signifie que si l’utilisateur de la propriété pouvant être liée n’attribue pas de valeur, une valeur par défaut est renvoyée pour éviter les erreurs.
7. Spécifie un délégué de modification de propriété qui sera appelé lorsque la valeur de la propriété change. Concrètement, on obtient la référence du contrôle personnalisé pour accéder à ses contrôles internes et modifier le Text propriété du TitleControl contrôle, qui est l’une des étiquettes affichant les informations d’achèvement.

Le Create La méthode accepte plus de paramètres que ceux affichés ici. Pour plus d’informations, vous pouvez vous référer à ce qui suit page de documentation.

La deuxième partie de la création d’une propriété pouvant être liée implique la création d’un propriété soutenu par le BindableProperty nous avons créé précédemment. Nous y parvenons de la manière suivante :

public string Title
{
    get { return (string)GetValue(TitleProperty); }
    set { SetValue(TitleProperty, value); }
}

Dans le code précédent, vous pouvez voir que la propriété utilise le GetValue méthode pour renvoyer la valeur de TitleProperty dans le getter, et le SetValue méthode pour attribuer la valeur à TitleProperty dans le passeur.

Puisque nous voulons que le contrôle personnalisé ait plusieurs propriétés disponibles (vous pouvez en ajouter autant que vous le souhaitez à l’exemple), j’en ai créé quelques autres que je montre ci-dessous :

public partial class Downloader : ContentView
{
    public static readonly BindableProperty TitleProperty =
        BindableProperty.Create("Title", typeof(string), typeof(Downloader), "0% To Complete",
            propertyChanged: (bindable, oldValue, newValue) =>
            {
                if (bindable is Downloader instance)
                {
                    instance.TitleControl.Text = (string)newValue;
                }
            });

    public static readonly BindableProperty SubTitleProperty =
        BindableProperty.Create("SubTitle", typeof(string), typeof(Downloader), "Your progress",
             propertyChanged: (bindable, oldValue, newValue) =>
             {
                 if (bindable is Downloader instance)
                 {
                     instance.SubTitleControl.Text = (string)newValue;
                 }
             });
    public static readonly BindableProperty ProgressProperty =
        BindableProperty.Create("Progress", typeof(double), typeof(Downloader), 0.0,
            propertyChanged: (bindable, oldValue, newValue) =>
            {
                if (bindable is Downloader instance)
                {
                    instance.ProgressControl.Value = (double)newValue;
                }
            });
    public string Title
    {
        get { return (string)GetValue(TitleProperty); }
        set { SetValue(TitleProperty, value); }
    }

    public string SubTitle
    {
        get { return (string)GetValue(SubTitleProperty); }
        set { SetValue(SubTitleProperty, value); }
    }

    public string Progress
    {
        get { return (string)GetValue(ProgressProperty); }
        set { SetValue(ProgressProperty, value); }
    }


    public Downloader()
    {
        InitializeComponent();
        TitleControl.Text = (string)TitleProperty.DefaultValue;
        SubTitleControl.Text = (string)SubTitleProperty.DefaultValue;
        ProgressControl.Value = (double)ProgressProperty.DefaultValue;
    }
}

Manipulation des propriétés de contrôle personnalisé

Nous disposons désormais des parties graphiques et logiques du contrôle personnalisé. Nous pouvons maintenant revenir à l’endroit où nous avons utilisé le contrôle et utiliser les propriétés pouvant être liées nouvellement créées :

<controls:Downloader
    Title="Current download: 0%"
    Progress="25"
    SubTitle="Saving a copy of the file" />

Vous pouvez voir comment cela nous permet de personnaliser le contrôle personnalisé autant que nous le souhaitons. Le véritable pouvoir des propriétés pouvant être liées est que nous pouvons les lier à un ViewModel à travers des liaisons. Dans mon exemple, j’ai créé le ViewModel suivant :

public partial class MainViewModel : ObservableObject
{
    [ObservableProperty]
    string title = "Current download: 0%";

    [ObservableProperty]
    double progress;

    [ObservableProperty]
    string subTitle = "Saving a copy of the file";
    partial void OnProgressChanged(double value)
    {            
        Title = $"Current download: {value.ToString("F2")}%";
    }
    [RelayCommand]
    public async Task Download()
    {
        Progress = 0.0;
        for (int i = 0; i <= 100; i++)
        {
            await Task.Delay(100);
            Progress = i;
        }
    }
}

Dans le code précédent, j’ai créé des propriétés pouvant être liées pour manipuler les propriétés du contrôle, y compris une simulation de téléchargement d’un fichier dans le Download méthode. Avec cela, nous pouvons lier les propriétés du ViewModel avec le code XAML comme suit :

<VerticalStackLayout Spacing="50" VerticalOptions="Center">
    <controls:Downloader
        Title="{Binding Title}"
        Progress="{Binding Progress}"
        SubTitle="{Binding SubTitle}" />
    <Button
        Margin="25"
        Command="{Binding DownloadCommand}"
        Text="Start Download" />
</VerticalStackLayout>

Le résultat est de voir comment les valeurs du contrôle personnalisé changent lorsque vous appuyez sur le bouton :

Conclusion

Dans cet article, vous avez appris à créer des ContentViews pour créer la partie graphique d’un contrôle personnalisé. De même, vous avez appris ce que sont les propriétés pouvant être liées et comment les utiliser pour activer des propriétés extérieures au contrôle, permettant ainsi l’utilisation de la liaison de données.

Ces connaissances vous donneront un grand pouvoir pour créer des composants réutilisables non seulement dans un projet mais dans tous vos projets avec .NET MAUI.