Blazor ASP.NET Core validation de formulaire côté client dans le SSR statique

Cet article explique comment Blazor ajouter une validation côté client dynamique aux formulaires qui utilisent le rendu côté serveur statique (SSR statique). Le navigateur valide les champs individuels lorsque l’utilisateur les modifie et valide le formulaire complet avant son envoi. Si la vérification côté client passe, le formulaire est envoyé et validé à nouveau sur le serveur.

Les formulaires qui utilisent un mode de rendu interactif n’utilisent pas la fonctionnalité de validation côté client SSR statique décrite dans cet article. Leur validation par champ et leur validation lors de l’envoi du formulaire complet s’exécutent dans .NET via le EditContext du formulaire.

Fonctionnement de la validation côté client

Lorsqu’un formulaire SSR statique contient un DataAnnotationsValidator composant, Blazor affiche les règles de validation du formulaire dans la page et les applique à l’aide de JavaScript avant l’envoi du formulaire. L’utilisateur voit les erreurs de validation sans aller-retour sur le serveur.

La validation côté client s’active automatiquement lorsque les conditions suivantes sont remplies :

• Le composant d’hébergement du formulaire utilise le SSR statique (aucune @rendermode directive appliquée au composant).
• Le formulaire contient un DataAnnotationsValidator composant.
• Le modèle du formulaire utilise System.ComponentModel.DataAnnotations des attributs de validation.

Pour l’ensemble intégré d’attributs de validation, aucune configuration JavaScript, package supplémentaire ou inscription de service n’est requise. La section Règles de validation côté client personnalisées décrit comment ajouter la prise en charge des attributs de validation personnalisés.

Attributs de validation pris en charge

Les attributs suivants System.ComponentModel.DataAnnotations sont appliqués côté client, correspondant au comportement des annotations de données côté serveur :

• RequiredAttribute
• StringLengthAttribute
• MinLengthAttribute
• MaxLengthAttribute
• RangeAttribute (uniquement lorsque le type d’opérande est numérique)
• RegularExpressionAttribute
• EmailAddressAttribute
• UrlAttribute
• PhoneAttribute
• CreditCardAttribute
• CompareAttribute
• FileExtensionsAttribute

Les attributs de validation qui n’apparaissent pas dans cette liste, y compris les attributs dérivés personnalisés ValidationAttribute, ne sont pas appliqués côté client par défaut. Ils continuent d’exécuter côté serveur une fois le formulaire envoyé. Pour fournir une règle côté client pour un attribut personnalisé, consultez la section Règles de validation côté client personnalisées .

Moment de la validation

Un champ est validé lorsque sa valeur est enregistrée. Pour les entrées de texte (<input> éléments), cela se produit lorsque le champ perd le focus. Les cases à cocher et les listes déroulantes sont validées immédiatement après la sélection.

Une fois qu’un champ a affiché une erreur de validation ou une fois que le formulaire a été envoyé au moins une fois, le champ est à nouveau validé sur chaque séquence de touches afin que les corrections soient immédiatement reflétées.

L’envoi du formulaire valide chaque champ suivi. Si un champ n’est pas valide, la soumission est bloquée et le focus passe au premier champ non valide.

Messages de validation, localisation et accessibilité

La validation côté client utilise ValidationMessage<TValue> pour afficher des messages pour chaque champ et ValidationSummary pour afficher des messages pour l’ensemble du formulaire, de la même manière que la validation interactive présente les messages aux utilisateurs.

Lorsque la localisation de la validation est configurée, les messages d’erreur sont localisés sur le serveur lorsque la page est affichée. La validation côté client affiche donc les mêmes chaînes localisées que l’expérience côté serveur. La localisation nécessite Microsoft.Extensions.Validation. Pour plus d’informations, consultez Validation dans ASP.NET Core.

Les attributs ARIA sur les éléments d’entrée et les conteneurs de messages de validation sont gérés automatiquement Blazor , de sorte que les technologies d’assistance annoncent des erreurs de validation sans configuration supplémentaire.

Classes CSS d’état de validation

Le moteur de validation côté client applique les mêmes classes CSS que Blazorla validation interactive, qui sont indiquées dans le tableau suivant.

La validation côté client appelle également l’API Validation de contrainte du navigateur, de sorte que les pseudo-classes :valid CSS standard et :invalid reflètent l’état de validation actuel de chaque entrée.

Refuser la validation côté client

La fonctionnalité peut être désactivée à plusieurs niveaux. La validation côté serveur n’est pas affectée par l’une des options de cette section.

Se désinscrire pour un seul formulaire

Définissez le paramètre DisableClientValidation du composant DataAnnotationsValidator sur true:

<DataAnnotationsValidator DisableClientValidation="true" />

Désactiver l’ensemble de l’application

Définissez DisableClientValidation sur RazorComponentsServiceOptions lorsque les services de composants Razor sont enregistrés dans le fichier Program :

builder.Services.AddRazorComponents(options =>
{
    options.DisableClientValidation = true;
});

L’option globale est prioritaire. Lorsqu’il est défini truesur , les formulaires n’émettent pas de règles de validation côté client.

Se désinscrire pour un seul bouton d’envoi

Utilisez l’attribut HTML formnovalidate standard sur le bouton. Le formulaire est publié sans vérification côté client et la validation côté serveur s’exécute toujours après la publication :

<button type="submit" formnovalidate>Save draft</button>

Cela peut être utilisé pour implémenter un bouton « Enregistrer le brouillon » ou « Précédent » qui ne nécessite pas de formulaire entièrement valide pour que l’envoi réussisse.

Règles de validation côté client personnalisées

Les attributs de validation personnalisés continuent d’être exécutés sur le serveur, mais n’ont pas d’implémentation côté client par défaut. L’application d’une règle personnalisée dans le navigateur implique deux étapes : l’émission de la règle à partir de l’attribut .NET et l’inscription d’un validateur JavaScript correspondant. L’implémentation côté serveur reste faisant autorité.

Émettre la règle à partir de .NET

Implémentez IClientValidationRuleProvider sur l’attribut de validation et retournez une ou plusieurs ClientValidationRule instances. La règle Name identifie le validateur côté client et Parameters fournit des valeurs dont le validateur a besoin.

L’élément suivant StartsWithAttribute effectue une validation côté serveur dans IsValid et fournit une règle côté client startswith avec un paramètre prefix :

using System.ComponentModel.DataAnnotations;
using Microsoft.AspNetCore.Components.Forms;

namespace BlazorSample.Validation;

// A custom validation attribute that also contributes a client-side rule for static SSR
// forms. The rule name ('startswith') must match the validator registered on the client
// with Blazor.formValidation.addValidator.
public sealed class StartsWithAttribute : ValidationAttribute, IClientValidationRuleProvider
{
    private readonly string prefix;

    public StartsWithAttribute(string prefix)
    {
        this.prefix = prefix;
        ErrorMessage = $"The value must start with '{prefix}'.";
    }

    protected override ValidationResult? IsValid(object? value,
        ValidationContext validationContext)
    {
        // Leave empty values to RequiredAttribute, matching the client-side validator.
        if (value is not string text || text.Length == 0)
        {
            return ValidationResult.Success;
        }

        if (!text.StartsWith(prefix, StringComparison.Ordinal))
        {
            return new ValidationResult(ErrorMessage, [validationContext.MemberName!]);
        }

        return ValidationResult.Success;
    }

    public IEnumerable<ClientValidationRule> GetClientValidationRules()
    {
        yield return new ClientValidationRule(
            "startswith",
            new Dictionary<string, string> { ["prefix"] = prefix });
    }
}

Appliquez l’attribut au modèle de la façon habituelle :

using System.ComponentModel.DataAnnotations;

namespace BlazorSample.Validation;

// Model for the static SSR client-side validation sample. The StartsWith attribute
// contributes a client-side rule enforced in the browser before the form is submitted.
public class ShipModel
{
    [Required]
    [StartsWith("NCC-")]
    public string? Registry { get; set; }
}

Inscrire le validateur JavaScript

Dans JavaScript, appelez Blazor.formValidation.addValidator(name, validator) pour associer un nom de règle à une fonction validateur. Le name doit correspondre exactement à ClientValidationRule.Name, y compris la casse. Les inscriptions sont à l’échelle de l’application et l’inscription du même nom remplace à nouveau le validateur précédent.

Enregistrez les validateurs personnalisés une seule fois dans le code de démarrage de l’application. Choisissez l’emplacement d’enregistrement selon la façon dont Blazor démarre, comme décrit dans le tableau suivant.

Un initialiseur JavaScript fonctionne avec l’un ou l’autre style de démarrage. Dans un fichier nommé {ASSEMBLY NAME}.lib.module.js dans le dossier de l’application wwwroot :

// A JavaScript initializer works with automatic or manual Blazor startup. The validation service
// is available when afterWebStarted runs, even if the current page contains no validated form.
export function afterWebStarted(blazor) {
  blazor.formValidation.addValidator('startswith', (context) => {
    const value = context.value;

    // An empty value is valid. Use [Required] to require a value.
    if (!value) {
      return { success: true };
    }

    return { success: value.startsWith(context.params.prefix) };
  });
}

Avec le démarrage automatique, un script de validateur spécifique à l’application peut être chargé immédiatement après blazor.web.js:

<script src="@Assets["_framework/blazor.web.js"]"></script>
<script src="@Assets["js/custom-validation.js"]"></script>

Le deuxième script peut appeler Blazor.formValidation.addValidator directement.

Avec le démarrage manuel, définissez l’inscription dans un script d’application :

function registerCustomValidators(blazor) {
  blazor.formValidation.addValidator('startswith', (context) => {
    const value = context.value;

    if (!value) {
      return { success: true };
    }

    return { success: value.startsWith(context.params.prefix) };
  });
}

// Automatic startup initializes formValidation before this script runs.
// Manual startup calls registerCustomValidators after Blazor.start completes.
if (Blazor.formValidation) {
  registerCustomValidators(Blazor);
}

Chargez les scripts avec le démarrage automatique désactivé, et enregistrez les validateurs une fois Blazor.start() terminé :

<script src="@Assets["_framework/blazor.web.js"]" autostart="false"></script>
<script src="@Assets["js/custom-validation.js"]"></script>
<script>
    Blazor.start().then(() => {
        registerCustomValidators(Blazor);
    });
</script>

Écrire des fonctions de validateur JavaScript

Le validateur reçoit un objet de contexte avec les membres suivants, comme indiqué dans le tableau suivant.

Le validateur est censé retourner { success: true } lorsque la valeur est valide. Renvoyez { success: false } pour utiliser le message fourni par le serveur pour la règle, ou vous pouvez renvoyer { success: false, message: '...' } pour remplacer le message pour cet appel.

Les valeurs vides doivent normalement être traitées comme valides par des règles autres que required, ce qui permet à un champ facultatif de rester vide tout en validant les valeurs fournies.

Implémentez les mêmes règles sémantiques dans .NET et JavaScript, y compris la sensibilité à la casse, la normalisation et la gestion des valeurs vides. Si les implémentations diffèrent, le navigateur et la validation côté serveur faisant autorité peuvent produire des résultats différents.

Valider le formulaire à la demande

L’API Blazor.formValidation expose également des méthodes JavaScript pour la validation à la demande, comme le montre le tableau suivant.

Limitations

• Les règles côté client sont émises uniquement pour les champs inclus dans la validation côté serveur. Sans Microsoft.Extensions.Validation, seules les propriétés de modèle de niveau supérieur sont validées. La validation des objets et collections imbriqués nécessite que l’application appelle AddValidation et que le modèle soit découvert. Pour plus d’informations, consultez Validation dans ASP.NET Core. Notez que cette limitation est une fonctionnalité intentionnelle qui permet d’empêcher les bogues dans lesquels la validation du serveur faisant autorité serait manquante en raison d’une configuration incorrecte.
• Les entrées ajoutées à un formulaire existant par une mise à jour de rendu de streaming ultérieure ne reçoivent pas de validation côté client. Un formulaire envoyé dans un seul lot en flux continu est normalement pris en charge.
• Seuls les attributs répertoriés dans les attributs de validation pris en charge ont des implémentations côté client intégrées. Par exemple, un RangeAttribute type d’opérande non numérique est appliqué uniquement sur le serveur. D’autres attributs nécessitent une règle de validation côté client personnalisée.
• Les validateurs JavaScript personnalisés sont synchrones. Les règles qui nécessitent un appel réseau ou un autre travail asynchrone doivent s’exécuter sur le serveur ou utiliser la validation asynchrone avec un mode de rendu interactif. Pour plus d’informations, consultez ASP.NET Core Blazor validation avancée du formulaire.

Ressources additionnelles

• Blazor validation des formulaires ASP.NET Core
• ASP.NET Core Blazor validation avancée des formulaires
• Validation dans ASP.NET Core
• Modes de rendu ASP.NET Core Blazor