Comment capturer la saisie des utilisateurs à l’aide de formulaires Blazor

Gagnez du temps et des frappes avec les composants de la forme complète de Blazor.

Si vous créez des applications Web, vous devrez probablement capturer des informations auprès de vos utilisateurs. Une façon courante (toujours) courante est d’utiliser un formulaire. Mais comment utilisez-vous des formulaires dans Blazor, et que change lorsque vous basculez entre les différents modes de rendu de Blazor?

Voici un guide de démarrage rapide pour former la manipulation dans Blazor (plus, restez jusqu’à la fin pour une façon intéressante de mettre votre formulaire opérationnel plus rapidement, avec moins de chauffeur).

Une forme simple

Tout d’abord, commençons par les fondamentaux. Voici un formulaire HTML de base, où quelqu’un peut saisir son adresse e-mail.

@page "/Newsletter"

<h3>Newsletter Signup</h3>

<form method="post">
    <label for="email" class="form-label">Email:</label>
    <input type="text" name="email" id="email"/>
    <button type="submit">Submit</button>
</form>

@code {
    
}

À l’heure actuelle, il s’agit d’un formulaire HTML standard, bien que déclaré dans un composant de rasoir.

Si vous utilisez le mode de rendu statique du serveur statique de Blazor, vous pouvez déclarer un formulaire comme celui-ci et capturer les données lorsque le formulaire est soumis.

Mais si vous soumettez le formulaire, vous obtiendrez une erreur.

Un jeton antiforviille valide n’a pas reçu la demande. Ajoutez un jeton antiforviille ou désactivez la validation antiformide pour ce point final.

Alors qu’est-ce qui donne?

Voici ce qui se passe lorsque ce formulaire est soumis:

• Une demande de poste est faite par le navigateur.
• Cette demande est faite à l’URL actuelle pour la page (sauf si nous spécifions autrement). Dans ce cas, c’est <your-app>/Newsletter.
• Le serveur ramasse la demande de poste et le transmet à Blazor (ASP.NET).
• Blazor / ASP.NET lance l’erreur ci-dessus sur les jetons anti-chirurgicale.

Les jetons anti-chirurgicale aident à vous protéger des mauvais acteurs

ASP.NET utilise des jetons anti-chère pour aider à protéger votre application. Sans eux, un acteur malveillant pourrait facilement envoyer des données douteuses à cette page / newsletter, via des demandes de poste.

Pour contrer cela, lorsque vous déclarez un formulaire dans votre composant de rasoir, vous pouvez inclure un jeton anti-chère. Ce jeton est généré sur le serveur lorsque votre composant rend, puis est inclus dans le balisage résultant.

Lorsque le formulaire est par la suite soumis, ASP.NET (exécuté sur le serveur) vérifie le jeton fourni est légitime et permet la demande dans le cas.

Nous pouvons câbler ce jeton à l’aide de Blazor <AntiforgeryToken /> composant:

<form method="post">
    <label for="email" class="form-label">Email:</label>
    <input type="text" name="email" id="email"/>
    <button type="submit">Submit</button>
        
    <AntiforgeryToken />
</form>

Si vous exécutez cela dans le navigateur et inspectez le code source, vous verrez le jeton généré inclus comme un champ caché.

<form method="post" action="/newsletter">
    <label for="email" class="form-label">Email:</label>
    <input type="text" name="email" id="email">
    <button type="submit">Submit</button>
    
    <input type="hidden" name="__RequestVerificationToken" value="CfDJ8GblH5ZtkwJHinTfwL5hSdkZOv0g0xvTgr7JwOxofF2PQRVB1ORm8rhTM-MhtjNn_Ob9WZ6U01VU0a734QCLT5L-klOpNbm1ON6A2t2BuZ8R1WYHDgCfzoY0k7TKlYOBkxcUNLechsHYNC0UEvv1QVU"></form>

Ce jeton sera inclus dans les données publiées sur votre serveur lorsqu’un utilisateur soumet ce formulaire.

Token anti-forgé

La demande de poste ne précise pas quel formulaire est soumis. Pour résoudre ce problème, assurez-vous <form> Les éléments ont un attribut @formname avec n’importe quelle valeur unique, ou passez un paramètre FormName si vous utilisez <EditForm>.

Votre formulaire a besoin d’un nom

Cette fois, la demande a passé les chèques de .NET (il a un jeton anti-chirurgical valide), donc ASP.NET tentera de comprendre où envoyer la demande entrante.

Pour que cela fonctionne, vous devez donner un nom à votre formulaire.

<form method="post" @formname="newsletter-signup">
    <label for="email" class="form-label">Email:</label>
    <input type="text" name="email" id="email"/>
    <button type="submit">Submit</button>
    
    <AntiforgeryToken />
</form>

Notez que nous avons utilisé le @formname Directive pour donner à notre forme un nom unique. Ce nom est ensuite rendu dans le HTML résultant comme une valeur pour le _handler champ caché.

<form method="post" action="/newsletter">
    <input type="hidden" name="_handler" value="newsletter-signup">
    
    
</form>

ASP.NET, lorsqu’il gère la demande, utilisera ce nom pour localiser votre composant (vérifier un composant avec un formulaire avec ce nom).

Succès! Maintenant, lorsque vous soumettez ce formulaire, .NET enverra les données à votre composant mais…

Rien ne se passe.

Parce que nous avons raté une dernière étape. Nous devons écrire le code pour gérer les données de formulaire soumises.

Nous pouvons utiliser le @onsubmit Directive pour indiquer quelle méthode doit gérer les données de formulaire publiées.

<form method="post" @formname="newsletter-signup" @onsubmit="EmailSubmitted">
    
</form>

Implémentez ensuite le gestionnaire lui-même.

@code {

    [SupplyParameterFromForm] 
    public string Email { get; set; }

    public void EmailSubmitted()
    {
        Console.WriteLine(Email);
    }

}

Ici, nous avons déclaré une propriété pour capturer l’adresse e-mail à partir des données de formulaire soumises et le EmailSubmittedMéthode qui sera invoquée lorsqu’une soumission arrivera.

Le [SupplyParameterFromForm] assure le Email La propriété sera remplie de la valeur que l’utilisateur est entrée dans le formulaire.

Avec cela, notre forme est vivante!

Entrez une adresse e-mail, soumettez le formulaire et vous verrez l’adresse e-mail connectée au Sortir Fenêtre de votre IDE (ou terminal, selon la façon dont vous avez lancé votre application localement).

À l’heure actuelle, lorsque le formulaire est soumis, l’adresse e-mail (entrée par l’utilisateur) sera effacée du formulaire du formulaire du texte.

Nous pouvons préserver cette valeur en liant la valeur de l’entrée de texte dans le Email propriété que nous avons déclaré dans cette dernière étape.

<form method="post" @formname="newsletter-signup" @onsubmit="EmailSubmitted">
    <label for="email" class="form-label">Email:</label>
    
    
    <input type="text" name="email" id="email" value="@Email"/>
    
    
</form>

Ici, nous avons lié value pour notre entrée de texte au Email propriété dans notre composant.

Maintenant, lorsque le formulaire est soumis, l’entrée du texte continuera d’afficher l’adresse e-mail saisie.

Réduisez la binesse avec EditForm

Des formes HTML simples comme celle-ci fonctionnent très bien avec Blazor Static SSR, mais que se passe-t-il si vous voulez réduire une partie de la passerelle et obtenir une meilleure sécurité de temps de compilation pour votre formulaire?

Pour cela, Blazor a un composant de formulaire dédié appelé EditForm.

Voici comment nous pouvons déclarer le même formulaire en utilisant EditForm.

@page "/Newsletter/EditForm"
@using BlazorDemoApp.Data

<h3>Newsletter Signup</h3>

<EditForm method="post" Model="NewsletterForm" FormName="newsletter-signup" OnValidSubmit="EmailSubmitted" >
    <label for="email" class="form-label">Email:</label>
    <InputText id="email" @bind-Value="NewsletterForm.Email"/>
    <button type="submit">Submit</button>
</EditForm>

Une grande partie de ceci est la même (ou très similaire) à notre forme HTML ordinaire.

Mais remarquez que nous n’avons pas eu besoin d’ajouter le <AntiforgeryToken /> composant, comme EditForm comprend cela automatiquement.

Nous pouvons utiliser le Model propriété pour indiquer le modèle de données sous-jacent pour notre formulaire.

Voici comment nous avons mis cela en place pour ce composant.

@code {

    [SupplyParameterFromForm]
    public NewsletterForm NewsletterForm { get; set; } = new();

    public void EmailSubmitted()
    {
        Console.WriteLine(NewsletterForm.Email);
    }

}

Ici, nous avons un NewsletterForm propriété qui est instanciée dans un objet vide lorsque le composant monte pour la première fois.

Le NewsletterForm Le modèle lui-même ressemble à ceci:

public class NewsletterForm
{
    public string Email { get; set; }
}

De retour sous la forme, à la place du input élément, nous avons déclaré une instance de Blazor InputText composant.

<InputText id="email" @bind-Value="NewsletterForm.Email"/>

Que nous pouvons lier à une propriété spécifique sur le modèle (Email dans ce cas).

Parce que nous utilisons le rendu statique côté serveur comme mode de rendu, nous avons toujours besoin de cela [SupplyParameterFromForm] attribut que nous avons vu plus tôt si nous voulons notre NewsletterForm propriété à remplir avec les données de formulaire soumises.

Cette forme fonctionne de manière très similaire à notre forme HTML ordinaire, mais il existe certains avantages.

Si nous essayons de cartographier une entrée dans une propriété inexistante sur le modèle, nous obtiendrons une erreur de compilation (plutôt que de devoir attendre le temps d’exécution pour que le problème devienne évident).

Nous pouvons également éviter de compter sur des cordes magiques pour des choses comme le name de l’entrée de texte.

Commutation de modes de rendu

Avec EditFormnous pouvons désormais facilement changer de modes de rendu.

Le formulaire ci-dessus fonctionnera exactement de la même manière avec le mode de rendu défini sur InteractiveServer, InteractiveWebAssembly ou InteractiveAuto.

Dans ces cas, vous pouvez laisser tomber le [SupplyParameterFromForm] car ce n’est pas nécessaire.

Valider les données entrantes

Bien sûr, vous ne pouvez pas toujours compter sur les utilisateurs pour saisir des données valides pour vos formulaires. Blazor a une prise en charge intégrée pour la validation du formulaire.

L’option la plus simple de la porte est d’utiliser DataAnnotations. (Vous pouvez également utiliser d’autres bibliothèques telles que la validation courante.)

Nous pouvons indiquer quand un champ de notre modèle sous-jacent est requis (et / ou spécifier d’autres critères de validation, par exemple qu’un nombre doit se situer dans une certaine plage).

using System.ComponentModel.DataAnnotations;

namespace BlazorDemoApp.Data;

public class NewsletterForm
{
    [Required]
    public string Email { get; set; }
}

Puis apportez le DataAnnotationsValidator pour saisir tout problème lorsque le formulaire est soumis.

<EditForm method="post" Model="NewsletterForm" FormName="newsletter-signup" OnValidSubmit="EmailSubmitted">
    <DataAnnotationsValidator />
    <label for="email" class="form-label">Email:</label>
    <InputText id="email" @bind-Value="NewsletterForm.Email"/>
    <button type="submit">Submit</button>
    <ValidationSummary />
</EditForm>

Avec ça, le Email L’entrée sera mise en évidence en rouge si nous omettons une adresse e-mail lorsque nous soumettons le formulaire. Nous verrons également un message d’erreur affiché en bas du formulaire.

Si nous avions plusieurs entrées, et plusieurs d’entre elles ont échoué la validation, ValidationSummary montrera un résumé de ces erreurs de validation.

Décomposer de grandes formes en composants plus petits

Parfois, vous pouvez vous retrouver à demander les mêmes informations deux fois à un utilisateur.

Prenez un formulaire de paiement de la boutique en ligne par exemple. Si les utilisateurs ont des adresses d’expédition et de livraison différentes, vous souhaiterez peut-être capturer les mêmes informations pour les deux (rue, ville, etc.).

Vous pouvez créer un composant pour les champs de formulaire d’adresse pertinents et l’utiliser à plusieurs endroits de votre formulaire.

Tout d’abord, voici un modèle que nous pourrions utiliser pour un formulaire de paiement.

public record PlaceOrderCommand
{
    public Address BillingAddress { get; set; } = new();
    public Address ShippingAddress { get; set; } = new();
    public List<OrderItem> Items { get; set; } = new();

    public class Address
    {
        [Required]
        public string Name { get; set; }
        public string AddressLine1 { get; set; }
        public string AddressLine2 { get; set; }
        public string City { get; set; }
        
        [Required]
        public string PostCode { get; set; }
    }

    public class OrderItem
    {
        public string SKU { get; set; }
        public int Quantity { get; set; }
    }
}

Remarquez les deux champs d’adresse, BillingAddress et ShippingAddress.

Nous pouvons définir un composant distinct pour capturer les détails de l’adresse.

@using BlazorDemoApp.Shared.Checkout
@inherits Editor<PlaceOrderCommand.Address>

<div>
    <label>Name</label>
    <InputText @bind-Value="Value.Name"/>
</div>
<div>
    <label>Address 1</label>
    <InputText @bind-Value="Value.AddressLine1"/>
</div>
<div>
    <label>Address 2</label>
    <InputText @bind-Value="Value.AddressLine2"/>
</div>
<div>
    <label>City</label>
    <InputText @bind-Value="Value.City"/>
</div>
<div>
    <label>Post Code</label>
    <InputText @bind-Value="Value.PostCode"/>
</div>

Notez comment ce composant hérite Editor<PlaceOrderCommand.Address>.

Nous pouvons référencer ce composant dans notre formulaire de paiement principal (plusieurs fois, pour plusieurs champs d’adresse).

<EditForm Model="Command" method="post" OnValidSubmit="SubmitOrder" FormName="checkout">
    <DataAnnotationsValidator/>

    <h4>Bill To:</h4>
    <AddressEntry @bind-Value="Command.BillingAddress"/>

    <h4>Ship To:</h4>
    <AddressEntry @bind-Value="Command.ShippingAddress"/>

    <button type="submit">Place Order</button>
    <ValidationSummary/>
</EditForm>

C’est un moyen pratique d’éviter la duplication dans votre forme, en particulier lorsque vous capturez les mêmes informations exactes.

Boostez vos formulaires avec des composants de forme tiers

Enfin, tandis que le EditForm est un composant clé de Blazor et gérera la plupart des scénarios, vous pourriez vous retrouver à faire des formulaires sans avoir à écrire autant de code de passe-partout.

Dans les exemples précédents, nous avons dû déclarer les étiquettes pour nos entrées, ainsi que les entrées elles-mêmes.

Pour contrôler l’apparence du formulaire, nous devons écrire CSS ou utiliser des classes intégrées dans des cadres CSS comme Blazor pour faire apparaître chaque champ comme nous le voulons.

Les composants de la forme tiers ont coupé une grande partie de ce temps / effort.

Par exemple, voici une version du formulaire d’inscription à la newsletter (avec quelques champs supplémentaires) construits en utilisant le Forme de blazor Composant de Progress Telerik.

Remarquez que nous avons abandonné le label Éléments, préférant Telerik FormItem Composant à la place (qui rendra automatiquement une étiquette pour chaque entrée).

Voici comment ce formulaire rend dans le navigateur.

Avec cette approche, les types corrects de champs d’entrée sont rendus automatiquement, sur la base du modèle sous-jacent.

Par exemple, le modèle dans ce cas a un int propriété pour Agenous obtenons donc une entrée de nombre pour ce champ.

Nous pouvons organiser la forme en plusieurs colonnes (comme ici) et changer facilement l’orientation du formulaire (vertical ou horizontal).

Combiner la forme avec Telerik Blazor MediaQueryet le formulaire devient réactif (sans avoir à configurer manuellement CSS pour le faire paraître correctement sur mobile).

Si vous construisez une application avec beaucoup de formulaires, c’est un moyen solide de faire fonctionner un formulaire de combat contre la bataille rapidement.

En résumé

Les formulaires sont essentiels pour de nombreuses applications Web.

Si vous devez ajouter des formulaires à votre application Web, vous pouvez commencer par des formulaires HTML simples (pour les applications SSR statiques Blazor), mais pour une meilleure prise en charge des modes de rendu de Blazor et pour réduire le code Boiilerplate, vous pouvez vous tourner vers les composants de formulaire intégrés de Blazor, tels que EditForm.

Enfin, si vous construisez beaucoup de formulaires, des composants de forme tiers tels que celui inclus en cours Telerik UI pour Blazor Peut vous faire gagner du temps (et des frappes) en réduisant la bine-plaque, et vous éviter d’écrire beaucoup de CSS pour que vos formulaires aient l’air bien dans le navigateur. Essayez-le gratuitement pendant 30 jours.