Joindre du code C# à des événements DOM avec des gestionnaires d’événements Blazor

La plupart des éléments HTML exposent des événements déclenchés lorsque quelque chose d’important se produit. Par exemple, lorsqu’une page termine le chargement, l’utilisateur clique sur un bouton ou le contenu d’un élément HTML est modifié. Une application peut gérer un événement de plusieurs façons :

• L’application peut ignorer l’événement.
• L’application peut exécuter un gestionnaire d’événements écrit en JavaScript pour traiter l’événement.
• L’application peut exécuter un gestionnaire d’événements Blazor écrit en C# pour traiter l’événement.

Dans cette unité, vous obtenez un aperçu détaillé de la troisième option ; comment créer un gestionnaire d’événements Blazor en C# pour traiter un événement.

Gérer un événement avec Blazor et C#

Chaque élément du balisage HTML d’une application Blazor prend en charge de nombreux événements. La plupart de ces événements correspondent aux événements DOM disponibles dans les applications web standard, mais vous pouvez également créer des événements définis par l’utilisateur qui sont déclenchés par l’écriture de code. Pour capturer un événement avec Blazor, vous écrivez une méthode C# qui gère l’événement, puis vous liez l’événement à la méthode avec une directive Blazor. Pour un événement DOM, la directive Blazor partage le même nom que l’événement HTML équivalent, comme @onkeydown ou @onfocus. Par exemple, l’exemple d’application généré à l’aide de l’application Blazor Server contient le code suivant dans la page Counter.razor . Cette page affiche un bouton. Lorsque l’utilisateur sélectionne le bouton, l’événement @onclick déclenche la IncrementCount méthode qui incrémente un compteur indiquant combien de fois le bouton a été cliqué. L’élément <p> de la page affiche la valeur de la variable de compteur :

@page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

De nombreuses méthodes de gestionnaire d’événements utilisent un paramètre qui fournit des informations contextuelles supplémentaires. Ce paramètre est connu sous le nom de paramètre EventArgs. Par exemple, l’événement @onclick transmet des informations sur le bouton sur lequel l’utilisateur a cliqué, ou s’il a appuyé sur un bouton tel que Ctrl ou Alt en même temps que cliquer sur le bouton, dans un MouseEventArgs paramètre. Vous n’avez pas besoin de fournir ce paramètre quand vous appelez la méthode, le runtime Blazor l’ajoute automatiquement. Vous pouvez interroger ce paramètre dans le gestionnaire d’événements. Le code suivant incrémente le compteur indiqué dans l’exemple précédent par cinq si l’utilisateur appuie sur la touche Ctrl en même temps que sur le bouton :

@page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>


@code {
    private int currentCount = 0;

    private void IncrementCount(MouseEventArgs e)
    {
        if (e.CtrlKey) // Ctrl key pressed as well
        {
            currentCount += 5;
        }
        else
        {
            currentCount++;
        }
    }
}

D’autres événements fournissent des paramètres EventArgs différents. Par exemple, l’événement @onkeypress passe un paramètre KeyboardEventArgs qui indique la touche sur laquelle l’utilisateur a appuyé. Pour les événements DOM, si vous n’avez pas besoin de ces informations, vous pouvez omettre le paramètre EventArgs de la méthode de gestion des événements.

Comparaison de la gestion des événements dans JavaScript par rapport à la gestion des événements avec Blazor

Une application web traditionnelle utilise JavaScript pour capturer et traiter des événements. Vous créez une fonction dans le cadre d’un élément <script> HTML, puis vous vous organisez pour appeler cette fonction quand l’événement se produit. Pour comparer l’exemple Blazor précédent, le code suivant montre un fragment à partir d’une page HTML qui incrémente une valeur et affiche le résultat chaque fois que l’utilisateur sélectionne le bouton Cliquer sur moi . Le code utilise la bibliothèque jQuery pour accéder au modèle DOM.

<p id="currentCount">Current count: 0</p>

<button class="btn btn-primary" onclick="incrementCount()">Click me</button>

<!-- Omitted for brevity -->

<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<script>
    var currentCount = 0;

    function incrementCount() {
        currentCount++;
        $('#currentCount').html('Current count:' + currentCount);
    }
</script>

Outre les différences syntaxiques entre les deux versions du gestionnaire d’événements, vous devez noter les différences fonctionnelles suivantes :

• JavaScript ne préfixe pas le nom de l’événement avec un @ signe ; il ne s’agit pas d’une directive Blazor.
• Dans le code Blazor, vous spécifiez le nom de la méthode de gestion des événements quand vous la joignez à un événement. En JavaScript, vous écrivez une instruction qui appelle la méthode de gestion des événements. Vous spécifiez des parenthèses et des paramètres obligatoires.
• Plus important encore, le gestionnaire d’événements JavaScript s’exécute dans le navigateur, sur le client. Si vous créez une application Blazor Server, le gestionnaire d’événements Blazor s’exécute sur le serveur et met à jour le navigateur uniquement avec les modifications apportées à l’interface utilisateur quand le gestionnaire d’événements a été effectué. En outre, le mécanisme Blazor permet à un gestionnaire d’événements d’accéder aux données statiques partagées entre les sessions ; le modèle JavaScript ne le fait pas. Toutefois, la gestion de certains événements fréquents comme @onmousemove peut provoquer un ralentissement de l’interface utilisateur, car elle nécessite un aller-retour réseau vers le serveur. Vous préférez peut-être gérer des événements comme ceux dans le navigateur, à l’aide de JavaScript.

Gérer les événements de manière asynchrone

Par défaut, les gestionnaires d’événements Blazor sont synchrones. Si un gestionnaire d’événements effectue une opération potentiellement longue, telle que l’appel d’un service web, le thread sur lequel le gestionnaire d’événements s’exécute est bloqué jusqu’à la fin de l’opération. Cette situation peut entraîner une mauvaise réponse dans l’interface utilisateur. Pour résoudre ce problème, vous pouvez désigner une méthode de gestionnaire d’événements comme asynchrone. Utilisez le mot clé C# async. La méthode doit retourner un objet Task. Vous pouvez ensuite utiliser l’opérateur await à l’intérieur de la méthode de gestionnaire d’événements pour lancer des tâches durables sur un thread distinct et libérer le thread actuel pour un autre travail. Quand une tâche durable se termine, le gestionnaire d’événements reprend. L’exemple suivant montre un gestionnaire d’événements qui exécute une méthode nécessitant beaucoup de temps de façon asynchrone :

<button @onclick="DoWork">Run time-consuming operation</button>

@code {
    private async Task DoWork()
    {
        // Call a method that takes a long time to run and free the current thread
        var data = await timeConsumingOperation();

        // Omitted for brevity
    }
}

Utiliser un événement pour définir le focus sur un élément DOM

Sur une page HTML, l’utilisateur peut passer d’un élément à un autre via la touche de tabulation. Le focus se déplace naturellement dans l’ordre d’apparition des éléments HTML sur la page. Dans certains cas, vous devez peut-être substituer cette séquence et forcer l’utilisateur à consulter un élément spécifique.

La façon la plus simple d’effectuer cette tâche consiste à utiliser la méthode FocusAsync. Cette méthode est une méthode d’instance d’un ElementReference objet. ElementReference doit référencer l’élément sur lequel vous souhaitez définir le focus. Vous désignez une référence d’élément avec l’attribut @ref et créez un objet C# portant le même nom dans votre code.

Dans l’exemple suivant, le gestionnaire d’événements @onclick pour l’élément <bouton> définit le focus sur l’élément <entrée>. Le gestionnaire d’événements @onfocus de l’élément <input> affiche le message « Received focus » lorsque l’élément obtient l’assistant de concentration. L’élément <input> est référencé par le biais de la variable InputField dans le code :

<button class="btn btn-primary" @onclick="ChangeFocus">Click me to change focus</button>
<input @ref=InputField @onfocus="HandleFocus" value="@data"/>

@code {
    private ElementReference InputField;
    private string data;

    private async Task ChangeFocus()
    {
        await InputField.FocusAsync();
    }

    private async Task HandleFocus()
    {
        data = "Received focus";
    }

L’image suivante montre le résultat obtenu quand l’utilisateur sélectionne le bouton :

Écrire des gestionnaires d’événements inline

C# prend en charge les expressions lambda. Une expression lambda vous permet de créer une fonction anonyme. Une expression lambda est utile si vous disposez d’un gestionnaire d’événements simple que vous n’avez pas besoin de réutiliser ailleurs dans une page ou un composant. Dans l’exemple de nombre de clics initial indiqué au début de cette leçon, vous pouvez supprimer la méthode IncrementCount et remplacer l’appel de la méthode par une expression lambda qui effectue la même tâche :

@page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="() => currentCount++">Click me</button>

@code {
    private int currentCount = 0;
}

Cette approche est également utile si vous souhaitez fournir d’autres arguments à une méthode de gestion des événements. Dans l’exemple suivant, la méthode HandleClick prend un paramètre MouseEventArgs de la même façon qu’un gestionnaire d’événements de clic ordinaires, mais elle accepte également un paramètre de chaîne. La méthode traite l’événement click comme avant, mais affiche également le message si l’utilisateur appuie sur la touche Ctrl . L’expression lambda appelle la méthode HandleCLick, en passant le paramètre MouseEventArgs (mouseEvent) et une chaîne.

@page "/counter"
@inject IJSRuntime JS

<h1>Counter</h1>

<p id="currentCount">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick='mouseEvent => HandleClick(mouseEvent, "Hello")'>Click me</button>

@code {
    private int currentCount = 0;

    private async Task HandleClick(MouseEventArgs e, string msg)
    {
        if (e.CtrlKey) // Ctrl key pressed as well
        {
            await JS.InvokeVoidAsync("alert", msg);
            currentCount += 5;
        }
        else
        {
            currentCount++;
        }
    }
}

Substituer les actions DOM par défaut pour les événements

Plusieurs événements DOM ont des actions par défaut qui s’exécutent quand l’événement se produit, qu’un gestionnaire d’événements soit disponible ou pas pour cet événement. Par exemple, l’événement @onkeypress d’un élément d’entrée <> affiche toujours le caractère qui correspond à la touche enfoncée par l’utilisateur, puis gère la touche d’appui. Dans l’exemple suivant, l’événement @onkeypress est utilisé pour convertir l’entrée utilisateur en majuscules. En outre, si l’utilisateur tape un caractère @, le gestionnaire d’événements affiche une alerte :

<input value=@data @onkeypress="ProcessKeyPress"/>

@code {
    private string data;

    private async Task ProcessKeyPress(KeyboardEventArgs e)
    {
        if (e.Key == "@")
        {
            await JS.InvokeVoidAsync("alert", "You pressed @");
        }
        else
        {
            data += e.Key.ToUpper();
        }
    }
}

Si vous exécutez ce code et appuyez sur la @ touche, l’alerte s’affiche, mais le @ caractère est également ajouté à l’entrée. L’ajout du caractère @ est l’action par défaut de l’événement.

Si vous souhaitez empêcher l’affichage de ce caractère dans la zone d’entrée, vous pouvez substituer l’action par défaut par l’attribut preventDefault de l’événement, comme suit :

<input value=@data @onkeypress="ProcessKeyPress" @onkeypress:preventDefault />

L’événement se déclenche toujours, mais seules les actions définies par le gestionnaire d’événements sont effectuées.

Certains événements dans un élément enfant du DOM peuvent déclencher des événements dans leurs éléments parents. Dans l’exemple suivant, l’élément <div> contient un gestionnaire d’événements @onclick. Le <bouton> à l’intérieur de <div> a son propre gestionnaire d’événements @onclick. En outre, <div> contient un élément <input> :

<div @onclick="HandleDivClick">
    <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
    <input value=@data @onkeypress="ProcessKeyPress" @onkeypress:preventDefault />
</div>

@code {
    private async Task HandleDivClick()
    {
        await JS.InvokeVoidAsync("alert", "Div click");
    }

    private async Task ProcessKeyPress(KeyboardEventArgs e)
    {
        // Omitted for brevity
    }

    private int currentCount = 0;

    private void IncrementCount(MouseEventArgs e)
    {
        // Omitted for brevity
    }
}

Lorsque l’application s’exécute, si l’utilisateur clique sur un élément (ou un espace vide) dans la zone occupée par l’élément <div> , la méthode HandleDivClick s’exécute et affiche un message. Si l’utilisateur sélectionne le Click me bouton, la IncrementCount méthode s’exécute, suivie de HandleDivClick; l’événement @onclick se propage à l’arborescence DOM. Si <div> fait partie d’un autre élément qui gère également l’événement @onclick, ce gestionnaire d’événements s’exécute également, et ainsi de suite, à la racine de l’arborescence DOM. Vous pouvez réduire cette prolifération ascendante des événements avec l’attribut stopPropagation d’un événement, comme indiqué ici :

<div @onclick="HandleDivClick">
    <button class="btn btn-primary" @onclick="IncrementCount" @onclick:stopPropagation>Click me</button>
    <!-- Omitted for brevity -->
</div>

Utiliser un EventCallback suivant pour gérer les événements sur les composants

Une page Blazor peut contenir un ou plusieurs composants Blazor. Les composants peuvent également être imbriqués dans une relation parent-enfant. Un événement dans un composant enfant peut déclencher une méthode de gestionnaire d’événements dans un composant parent à l’aide d’un EventCallback. Un rappel référence une méthode dans le composant parent. Le composant enfant peut exécuter la méthode en appelant le rappel. Ce mécanisme est semblable à l’utilisation d’un delegate pour référencer une méthode dans une application C#.

Un rappel peut accepter un seul paramètre. EventCallback est un type générique. Le paramètre de type spécifie le type de l’argument transmis au rappel.

Examinez par exemple le scénario suivant. Vous souhaitez créer un composant nommé TextDisplay qui permet à l’utilisateur d’entrer une chaîne d’entrée et de transformer cette chaîne d’une certaine manière. Vous pouvez vouloir le convertir en majuscules, en minuscules, en caractères mixtes, filtrer des caractères ou effectuer un autre type de transformation. Toutefois, lorsque vous écrivez le code du TextDisplay composant, vous ne savez pas ce que le processus de transformation va être. Au lieu de cela, vous souhaitez différer cette opération vers un autre composant. Le code suivant montre le composant TextDisplay. Il fournit la chaîne d’entrée sous la forme d’un élément <input> qui permet à l’utilisateur d’entrer une valeur de texte.

@* TextDisplay component *@
@using WebApplication.Data;

<p>Enter text:</p>
<input @onkeypress="HandleKeyPress" value="@data" />

@code {
    [Parameter]
    public EventCallback<KeyTransformation> OnKeyPressCallback { get; set; }

    private string data;

    private async Task HandleKeyPress(KeyboardEventArgs e)
    {
        KeyTransformation t = new KeyTransformation() { Key = e.Key };
        await OnKeyPressCallback.InvokeAsync(t);
        data += t.TransformedKey;
    }
}

Le composant TextDisplay utilise un objet EventCallback nommé OnKeyPressCallback. Le code dans la méthode HandleKeypress appelle le rappel. Le gestionnaire d’événements @onkeypress s’exécute chaque fois qu’une touche est enfoncée et appelle la méthode HandleKeypress. La méthode HandleKeypress crée un objet KeyTransformation à l’aide de la touche sur laquelle l’utilisateur a appuyé et transmet cet objet en tant que paramètre au rappel. Le type KeyTransformation est une classe simple avec deux champs :

namespace WebApplication.Data
{
    public class KeyTransformation
    {
        public string Key { get; set; }
        public string TransformedKey { get; set; }
    }
}

Le key champ contient la valeur entrée par l’utilisateur, et le TransformedKey champ contient la valeur transformée de la clé après le traitement.

Dans cet exemple, l’objet EventCallback est un paramètre de composant et la valeur est fournie lors de la création du composant. Le composant nommé TextTransformer effectue cette action :

@page "/texttransformer"
@using WebApplication.Data;

<h1>Text Transformer - Parent</h1>

<TextDisplay OnKeypressCallback="@TransformText" />

@code {
    private void TransformText(KeyTransformation k)
    {
        k.TransformedKey = k.Key.ToUpper();
    }
}

Le composant TextTransformer est une page Blazor qui crée une instance du composant TextDisplay. Il remplit le paramètre OnKeypressCallback avec une référence à la méthode TransformText dans la section de code de la page. La méthode TransformText prend l’objet KeyTransformation fourni comme argument et remplit la propriété TransformedKey avec la valeur trouvée dans la propriété Key convertie en majuscules. Le diagramme suivant illustre le flux du contrôle quand un utilisateur entre une valeur dans le champ <input> du composant TextDisplay affiché par la page TextTransformer :

L’avantage de cette approche est que vous pouvez utiliser le composant TextDisplay avec n’importe quelle page fournissant un rappel pour le paramètre OnKeypressCallback. La séparation est totale entre l’affichage et le traitement. Vous pouvez basculer la méthode TransformText pour tout autre rappel qui correspond à la signature du paramètre EventCallback dans le composant TextDisplay.

Vous pouvez connecter directement un rappel à un gestionnaire d’événements sans utiliser de méthode intermédiaire si le rappel est typé avec le paramètre EventArgs approprié. Par exemple, un composant enfant peut référencer un rappel qui peut gérer ainsi des événements de souris comme @onclick :

<button @onclick="OnClickCallback">
    Click me!
</button>

@code {
    [Parameter]
    public EventCallback<MouseEventArgs> OnClickCallback { get; set; }
}

Dans ce cas, EventCallback prend un paramètre de type MouseEventArgs, de sorte qu’il peut être spécifié en tant que gestionnaire pour l’événement @onclick.