Vue d’ensemble des formulaires Blazor ASP.NET Core

Cet article explique comment utiliser des formulaires dans Blazor.

Formulaires et composants d’entrée

L’infrastructure Blazor prend en charge les formulaires et fournit des composants d’entrée intégrés :

• Lier à un objet ou un modèle pouvant utiliser des annotations de données
  • Formulaires HTML avec l’élément <form>
  • Composants EditForm
• Composants d’entrée intégrés

L’espace de noms Microsoft.AspNetCore.Components.Forms fournit :

• Des classes de gestion des éléments de formulaire, de l’état et de la validation.
• Accéder aux composants Input* intégrés.

Un projet, créé à partir du modèle de projet Blazor, comprend l’espace de noms par défaut dans le fichier _Imports.razor de l’application, ce qui rend l’espace de noms disponible pour les composants Razor de l’application.

Les formulaires HTML standard sont pris en charge. Créez un formulaire à l’aide de la balise HTML <form> normale et spécifiez un gestionnaire @onsubmit pour gérer la requête du formulaire envoyée.

StarshipPlainForm.razor:

@page "/starship-plain-form"
@inject ILogger<StarshipPlainForm> Logger

<form method="post" @onsubmit="Submit" @formname="starship-plain-form">
    <AntiforgeryToken />
    <div>
        <label>
            Identifier: 
            <InputText @bind-Value="Model!.Id" />
        </label>
    </div>
    <div>
        <button type="submit">Submit</button>
    </div>
</form>

@code {
    [SupplyParameterFromForm]
    public Starship? Model { get; set; }

    protected override void OnInitialized() => Model ??= new();

    private void Submit()
    {
        Logger.LogInformation("Id = {Id}", Model?.Id);
    }

    public class Starship
    {
        public string? Id { get; set; }
    }
}

Dans le composant StarshipPlainForm précédent :

• Le formulaire est affiché où l’élément <form> apparaît. Le formulaire est nommé avec l’attribut de directive @formname, qui identifie de façon unique le formulaire dans l’infrastructure Blazor.
• Le modèle est créé dans le bloc @code du composant et conservé dans une propriété publique (Model). L’attribut [SupplyParameterFromForm] indique que la valeur de la propriété associée doit être fournie à partir des données du formulaire. Les données de la requête, correspondant au nom de la propriété, sont liées à la propriété.
• InputText est un composant d’entrée permettant de modifier des valeurs de chaîne. L’attribut de directive @bind-Value lie la propriété de modèle Model.Id à la propriété Value du composant InputText.
• La méthode Submit est inscrite en tant que gestionnaire pour le rappel @onsubmit. Le gestionnaire est appelé lorsque le formulaire est envoyé par l’utilisateur.

Important

Utilisez toujours l’attribut de directive @formname avec un nom de formulaire unique.

Blazor améliore la navigation entre les pages et la gestion des formulaires en interceptant la requête, afin d’appliquer la réponse au DOM existant, en conservant autant que possible le formulaire rendu. L’amélioration évite la nécessité de charger entièrement la page et propose une expérience utilisateur beaucoup plus fluide, similaire à une application monopage (SPA), bien que le composant soit rendu sur le serveur. Pour plus d’informations, consultez Routage et navigation ASP.NET Core Blazor.

Le rendu de la diffusion en continu est pris en charge pour les formulaires HTML standard.

Remarque

Les liens de documentation vers la source de référence .NET chargent généralement la branche par défaut du référentiel, qui représente le développement actuel pour la prochaine version de .NET. Pour sélectionner une balise pour une version spécifique, utilisez la liste déroulante Échanger les branches ou les balises. Pour plus d’informations, consultez Comment sélectionner une balise de version du code source ASP.NET Core (dotnet/AspNetCore.Docs #26205).

L’exemple précédent inclut la prise en charge antiforgery en incluant un composant AntiforgeryToken dans le formulaire. La prise en charge antiforgery est expliquée plus loin dans la section Prise en charge antiforgery de cet article.

Pour envoyer un formulaire basé sur les événements DOM d’un autre élément, par exemple oninput ou onblur, utilisez JavaScript pour envoyer le formulaire (submit (documentation MDN)).

Au lieu d’utiliser des formulaires standard dans les applications Blazor, un formulaire est généralement défini avec la prise en charge intégrée du formulaire de Blazor à l’aide du composant EditForm du framework. Le composant Razor suivant illustre les éléments, les composants et le code Razor classiques pour afficher un formulaire web à l’aide d’un composant EditForm.

Starship1.razor :

@page "/starship-1"
@inject ILogger<Starship1> Logger

<EditForm Model="Model" OnSubmit="Submit" FormName="Starship1">
    <div>
        <label>
            Identifier:
            <InputText @bind-Value="Model!.Id" />
        </label>
    </div>
    <div>
        <button type="submit">Submit</button>
    </div>
</EditForm>

@code {
    [SupplyParameterFromForm]
    public Starship? Model { get; set; }

    protected override void OnInitialized() => Model ??= new();

    private void Submit()
    {
        Logger.LogInformation("Id = {Id}", Model?.Id);
    }

    public class Starship
    {
        public string? Id { get; set; }
    }
}

Dans le composant Starship1 précédent :

• Le composant EditForm est affiché à l’endroit où l’élément <EditForm> s’affiche. Le formulaire est nommé avec l’attribut de directive @formname, qui identifie de façon unique le formulaire dans l’infrastructure Blazor.
• Le modèle est créé dans le bloc @code du composant et conservé dans une propriété publique (Model). La propriété est affectée au paramètre EditForm.Model. L’attribut [SupplyParameterFromForm] indique que la valeur de la propriété associée doit être fournie à partir des données du formulaire. Les données de la requête, correspondant au nom de la propriété, sont liées à la propriété.
• InputText est un composant d’entrée permettant de modifier des valeurs de chaîne. L’attribut de directive @bind-Value lie la propriété de modèle Model.Id à la propriété Value du composant InputText.
• La méthode Submit est inscrite en tant que gestionnaire pour le rappel OnSubmit. Le gestionnaire est appelé lorsque le formulaire est envoyé par l’utilisateur.

Important

Utilisez toujours l’attribut de directive @formname avec un nom de formulaire unique.

Blazor améliore la navigation de page et la gestion des formulaires pour les composants EditForm. Pour plus d’informations, consultez Routage et navigation ASP.NET Core Blazor.

Le rendu de la diffusion en continu est pris en charge pour EditForm.

Remarque

Les liens de documentation vers la source de référence .NET chargent généralement la branche par défaut du référentiel, qui représente le développement actuel pour la prochaine version de .NET. Pour sélectionner une balise pour une version spécifique, utilisez la liste déroulante Échanger les branches ou les balises. Pour plus d’informations, consultez Comment sélectionner une balise de version du code source ASP.NET Core (dotnet/AspNetCore.Docs #26205).

†Pour plus d’informations sur la liaison de propriétés, consultez Liaison de données Blazor ASP.NET Core.

Dans l’exemple suivant, le composant précédent est modifié pour créer le formulaire dans le composant Starship2 :

• OnSubmit est remplacé par OnValidSubmit, qui traite le gestionnaire d’événements affecté si le formulaire est valide lors de l’envoi par l’utilisateur.
• Un composant ValidationSummary est ajouté pour afficher les messages de validation lorsque le formulaire n’est pas valide lors de l’envoi du formulaire.
• Le validateur d’annotations de données (composant† DataAnnotationsValidator) assure la prise en charge de la validation à l’aide d’annotations de données :
  • Si le champ de formulaire <input> est vide lorsque le bouton Submit est sélectionné, une erreur s’affiche dans le résumé de validation (composant‡ ValidationSummary) (« The Id field is required. ») et Submit n’est pas appelé.
  • Si le champ de formulaire <input> contient plus de dix caractères, lorsque le bouton Submit est sélectionné, une erreur s’affiche dans le résumé de validation (« Id is too long. »). Submit n’est pas appelé.
  • Si le champ de formulaire <input> contient une valeur valide lorsque le bouton Submit est sélectionné, Submit est appelé.

†Le composant DataAnnotationsValidator est abordé dans la section Composant validateur. ‡Le composant ValidationSummary est abordé dans la section Composants du résumé de validation et du message de validation.

Starship2.razor:

@page "/starship-2"
@using System.ComponentModel.DataAnnotations
@inject ILogger<Starship2> Logger

<EditForm Model="Model" OnValidSubmit="Submit" FormName="Starship2">
    <DataAnnotationsValidator />
    <ValidationSummary />
    <label>
        Identifier: 
        <InputText @bind-Value="Model!.Id" />
    </label>
    <button type="submit">Submit</button>
</EditForm>

@code {
    [SupplyParameterFromForm]
    public Starship? Model { get; set; }

    protected override void OnInitialized() => Model ??= new();

    private void Submit()
    {
        Logger.LogInformation("Id = {Id}", Model?.Id);
    }

    public class Starship
    {
        [Required]
        [StringLength(10, ErrorMessage = "Id is too long.")]
        public string? Id { get; set; }
    }
}

Gérer l’envoi du formulaire

Le EditForm fournit les rappels suivants pour la gestion de la soumission du formulaire :

• Utilisez OnValidSubmit pour affecter un gestionnaire d’événements à exécuter lorsqu’un formulaire avec des champs valides est envoyé.
• Utilisez OnInvalidSubmit pour affecter un gestionnaire d’événements à exécuter lorsqu’un formulaire avec des champs non valides est envoyé.
• Utilisez OnSubmit pour affecter un gestionnaire d’événements à exécuter, quel que soit l’état de validation des champs du formulaire. Le formulaire est validé en appelant EditContext.Validate dans la méthode du gestionnaire d’événements. Si Validate renvoie true, le formulaire est valide.

Effacer un formulaire ou un champ

Réinitialisez un formulaire en désactivant son modèle à son état par défaut, qui peut être effectué à l’intérieur ou à l’extérieur d’un balisage de EditForm :

<button @onclick="ClearForm">Clear form</button>

...

private void ClearForm() => Model = new();

Vous pouvez également utiliser une expression Razor explicite :

<button @onclick="@(() => Model = new())">Clear form</button>

Réinitialiser un champ en ramenant la valeur de son modèle à son état par défaut :

<button @onclick="ResetId">Reset Identifier</button>

...

private void ResetId() => Model!.Id = string.Empty;

Vous pouvez également utiliser une expression Razor explicite :

<button @onclick="@(() => Model!.Id = string.Empty)">Reset Identifier</button>

Il n’est pas nécessaire d’appeler StateHasChanged dans les exemples précédents, car StateHasChanged est automatiquement appelé par l’infrastructure de Blazor pour renvoyer le composant après l’appel d’un(e) gestionnaire d’événements. Si un(e) gestionnaire d’événements n’est pas utilisé pour appeler les méthodes qui effacent un formulaire ou un champ, le code du développeur doit appeler StateHasChanged pour renvoyer le composant.

Prise en charge d’Antiforgery

Les services anti-falsification sont automatiquement ajoutés aux applications Blazor lorsqu’ils AddRazorComponents sont appelés dans le fichier Program.

L’application utilise l’intergiciel Antiforgery en appelant UseAntiforgery dans son pipeline de traitement des requêtes dans le fichier Program. UseAntiforgery est appelé après l’appel à UseRouting. S’il y a des appels vers UseRouting et UseEndpoints, l’appel vers UseAntiforgery doit passer entre eux. Un appel à UseAntiforgery doit être placer après les appels à UseAuthentication et UseAuthorization.

Le composant AntiforgeryToken restitue un jeton antiforgery en tant que champ masqué et l’attribut [RequireAntiforgeryToken] active la protection antiforgery. Si une vérification antiforgery échoue, une réponse 400 - Bad Request est levée et le formulaire n’est pas traité.

Pour les formulaires basés sur EditForm, le composant AntiforgeryToken et l’attribut [RequireAntiforgeryToken] sont automatiquement ajoutés afin de fournir une protection antiforgery par défaut.

Pour les formulaires basés sur l’élément <form> HTML, ajoutez manuellement le composant AntiforgeryToken au formulaire :

<form method="post" @onsubmit="Submit" @formname="starshipForm">
    <AntiforgeryToken />
    <input id="send" type="submit" value="Send" />
</form>

@if (submitted)
{
    <p>Form submitted!</p>
}

@code{
    private bool submitted = false;

    private void Submit() => submitted = true;
}

Warning

Pour les formulaires basés sur EditForm ou sur l’élément HTML <form>, la protection antiforgery peut être désactivée en transmettant required: false à l’attribut [RequireAntiforgeryToken]. L’exemple suivant désactive antiforgery et n’est pas recommandé pour les applications publiques :

@using Microsoft.AspNetCore.Antiforgery
@attribute [RequireAntiforgeryToken(required: false)]

Pour plus d’informations, consultez ASP.NET Core Blazor Authentification et autorisation.

Gestion améliorée des formulaires

La navigation améliorée pour les requêtes POST de formulaire avec le paramètre Enhance pour les formulaires EditForm ou l’attribut data-enhance pour les formulaires HTML (<form>) :

<EditForm ... Enhance ...>
    ...
</EditForm>

<form ... data-enhance ...>
    ...
</form>

❌Non pris en charge : vous ne pouvez pas définir la navigation améliorée sur l’élément ancêtre d’un formulaire pour activer la gestion améliorée des formulaires.

<div ... data-enhance ...>
    <form ...>
        <!-- NOT enhanced -->
    </form>
</div>

Les publications de formulaire améliorées fonctionnent uniquement avec les points de terminaison Blazor. La publication d’un formulaire amélioré sur un point de terminaison non-Blazor entraîne une erreur.

Pour désactiver la gestion améliorée des formulaires :

• Pour un EditForm, supprimez le paramètre Enhance de l’élément de formulaire (ou définissez-le sur false : Enhance="false").
• Pour un code HTML <form>, supprimez l’attribut data-enhance de l’élément de formulaire (ou définissez-le sur false : data-enhance="false").

La navigation améliorée et la gestion des formulaires de Blazor peuvent annuler les modifications dynamiques apportées au DOM si le contenu mis à jour ne fait pas partie du rendu du serveur. Pour conserver le contenu d’un élément, utilisez l’attribut data-permanent.

Dans l’exemple suivant, le contenu de l’élément <div> est mis à jour dynamiquement par un script lorsque la page se charge :

<div data-permanent>
    ...
</div>

Pour désactiver globalement la navigation améliorée et la gestion des formulaires, consultez Démarrage de ASP.NET Core Blazor.

Pour obtenir des conseils sur l’utilisation de l’événement enhancedload pour écouter les mises à jour de page améliorées, consultez Routage et navigation ASP.NET Core Blazor.

Exemples

Les exemples n’adoptent pas la gestion améliorée des formulaires pour les requêtes POST de formulaire, mais tous les exemples peuvent être mis à jour pour adopter les fonctionnalités améliorées en suivant les instructions de la section Gestion améliorée des formulaires.

Pour montrer comment les formulaires fonctionnent avec la validation des annotations de données, les exemples de composants s’appuient sur l’API System.ComponentModel.DataAnnotations. Si vous souhaitez éviter une ligne de code supplémentaire dans les composants qui utilisent des annotations de données, rendez l’espace de noms disponible dans les composants de l’application avec le fichier d’importation (_Imports.razor) :

@using System.ComponentModel.DataAnnotations

Des exemples de formulaires référencent des aspects de l’univers Star Trek. Star Trek est une œuvre sous droits d’auteur ©1966-2023 de CBS Studios et Paramount.

Ressources supplémentaires

• Chargements de fichiers Blazor ASP.NET Core
• Blazor exemples de référentiel GitHub (dotnet/blazor-samples) (comment télécharger)
• Ressources de formulaires de test du référentiel GitHub ASP.NET Core (dotnet/aspnetcore)