Blazor ASP.NET Core convalida dei moduli lato client in SSR statico

Questo articolo illustra come Blazor aggiunge la convalida lato client in tempo reale ai moduli che usano il rendering statico lato server (SSR statico). Il browser convalida i singoli campi man mano che l'utente li modifica e convalida il modulo completo prima dell'invio. Se il controllo sul lato client viene superato, il modulo viene inviato e convalidato nuovamente nel server.

I moduli che usano una modalità di rendering interattiva non usano la funzionalità di convalida lato client SSR statica descritta in questo articolo. Sia la validazione per singolo campo sia la validazione dell'invio completo del modulo vengono eseguite in .NET tramite il EditContext del modulo.

Come funziona la convalida lato client

Quando un modulo SSR statico contiene un DataAnnotationsValidator componente, Blazor esegue il rendering delle regole di convalida del modulo nella pagina e le applica usando JavaScript prima dell'invio del modulo. L'utente vede gli errori di convalida senza dover effettuare un'andata e ritorno al server.

La convalida lato client viene attivata automaticamente quando vengono soddisfatte le condizioni seguenti:

• Il componente di hosting del modulo utilizza SSR statico (nessuna direttiva @rendermode applicata al componente).
• Il modulo contiene un DataAnnotationsValidator componente.
• Il modello del modulo usa System.ComponentModel.DataAnnotations gli attributi di convalida.

Per il set predefinito di attributi di convalida, non è necessaria alcuna configurazione JavaScript, pacchetto aggiuntivo o registrazione del servizio. La sezione Regole di convalida lato client personalizzate descrive come aggiungere il supporto per gli attributi di convalida personalizzati.

Attributi di convalida supportati

Vengono applicati gli attributi seguenti System.ComponentModel.DataAnnotations sul lato client, che corrispondono al comportamento delle annotazioni dei dati sul lato server:

• RequiredAttribute
• StringLengthAttribute
• MinLengthAttribute
• MaxLengthAttribute
• RangeAttribute (solo quando il tipo di operando è numerico)
• RegularExpressionAttribute
• EmailAddressAttribute
• UrlAttribute
• PhoneAttribute
• CreditCardAttribute
• CompareAttribute
• FileExtensionsAttribute

Gli attributi di convalida che non compaiono in questo elenco, inclusi gli attributi personalizzati derivati da ValidationAttribute, non vengono applicati sul lato client per impostazione predefinita. Continuano a essere eseguiti sul lato server dopo l'invio del modulo. Per specificare una regola lato client per un attributo personalizzato, vedere la sezione Regole di convalida lato client personalizzate .

Tempistica di convalida

Un campo viene convalidato quando viene eseguito il commit del relativo valore. Per i campi di testo (elementi <input>), ciò si verifica quando il campo perde lo stato attivo. Le caselle di controllo e gli elenchi a discesa vengono convalidati immediatamente dopo la selezione.

Dopo che un campo ha visualizzato un errore di convalida o dopo l'invio del modulo almeno una volta, il campo viene convalidato nuovamente in ogni sequenza di tasti in modo che le correzioni vengano riflesse immediatamente.

L'invio del modulo convalida ogni campo monitorato. Se un campo non è valido, l'invio viene bloccato e il focus passa al primo campo non valido.

Messaggi di convalida, localizzazione e accessibilità

La convalida lato client usa ValidationMessage<TValue> per visualizzare i messaggi per i singoli campi e ValidationSummary per visualizzare i messaggi per l'intero modulo, che è lo stesso modo in cui la convalida interattiva segnala i messaggi agli utenti.

Quando la localizzazione della convalida è configurata, i messaggi di errore vengono localizzati nel server durante il rendering della pagina, quindi la convalida lato client visualizza le stesse stringhe localizzate dell'esperienza sul lato server. La localizzazione richiede Microsoft.Extensions.Validation. Per altre informazioni, vedere Convalida in ASP.NET Core.

Gli attributi ARIA sugli elementi di input e i contenitori dei messaggi di convalida sono gestiti automaticamente da Blazor, quindi le tecnologie assistive segnalano gli errori di convalida senza alcuna configurazione aggiuntiva.

Classi CSS dello stato di convalida

Il motore di convalida lato client applica le stesse classi BlazorCSS della convalida interattiva, illustrate nella tabella seguente.

La convalida lato client chiama anche l'API di convalida dei vincoli del browser, quindi le pseudoclassi :valid CSS standard e :invalid riflettono lo stato di convalida corrente di ogni input.

Disattivare la convalida lato client

La funzionalità può essere disabilitata a più livelli. La convalida lato server non è influenzata da una qualsiasi delle opzioni in questa sezione.

Rifiutare esplicitamente un singolo modulo

Impostare il parametro DisableClientValidation del componente DataAnnotationsValidator su true:

<DataAnnotationsValidator DisableClientValidation="true" />

Rifiutare esplicitamente l'intera app

Impostare DisableClientValidation su RazorComponentsServiceOptions quando Razor i servizi dei componenti vengono registrati nel Program file:

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

L'opzione globale ha la precedenza. Quando è impostato su true, i moduli non generano regole di convalida lato client.

Rifiutare esplicitamente un singolo pulsante di invio

Usare l'attributo HTML formnovalidate standard sul pulsante. Il modulo viene pubblicato senza un controllo sul lato client e la convalida sul lato server viene comunque eseguita dopo il post:

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

Può essere usato per implementare un pulsante "Salva bozza" o "Indietro" che non richiede un modulo completamente valido per l'esito positivo dell'invio.

Regole di convalida lato client personalizzate

Gli attributi di convalida personalizzati continuano a essere eseguiti nel server, ma non hanno un'implementazione lato client per impostazione predefinita. L'applicazione di una regola personalizzata nel browser prevede due passaggi: l'emissione della regola dall'attributo .NET e la registrazione di un validator JavaScript corrispondente. L'implementazione lato server rimane autorevole.

Generare la regola da .NET

Implementare IClientValidationRuleProvider nell'attributo di convalida e restituire una o più ClientValidationRule istanze. La regola Name identifica il validator lato client e Parameters fornisce i valori necessari per il validator.

Quanto segue StartsWithAttribute esegue la convalida lato server in IsValid e fornisce una regola lato client startswith con parametro 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 });
    }
}

Applicare l'attributo al modello nel modo consueto:

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; }
}

Registrare il validator JavaScript

In JavaScript chiamare Blazor.formValidation.addValidator(name, validator) per associare un nome di regola a una funzione validator. Il name deve corrispondere esattamente a ClientValidationRule.Name, incluse le maiuscole e minuscole. Le registrazioni valgono per l’intera app e registrare di nuovo lo stesso nome sostituisce il validatore precedente.

Registrare i validatori personalizzati una sola volta nel codice di avvio dell'app. Scegliere la posizione di registrazione in base a come si avvia Blazor, come descritto nella tabella seguente.

Un inizializzatore JavaScript è compatibile con entrambi gli stili di avvio. In un file denominato {ASSEMBLY NAME}.lib.module.js nella cartella dell'app 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) };
  });
}

Con l'avvio automatico, uno script di validator specifico dell'app può invece essere caricato immediatamente dopo blazor.web.js:

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

Il secondo script può chiamare Blazor.formValidation.addValidator direttamente.

Con l'avvio manuale, definire la registrazione in uno script dell'app:

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);
}

Carica gli script con l'avvio automatico disabilitato e registra i validatori dopo il completamento di Blazor.start():

<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>

Scrivere funzioni di convalida JavaScript

Il validator riceve un oggetto contesto con i membri seguenti, come illustrato nella tabella seguente.

Il validator deve restituire { success: true } quando il valore è valido. Restituire { success: false } per usare il messaggio della regola fornito dal server, oppure è possibile restituire { success: false, message: '...' } per sovrascrivere il messaggio per quella chiamata.

I valori vuoti dovrebbero normalmente essere considerati validi da regole diverse da required, consentendo a un campo facoltativo di rimanere vuoto e continuando comunque a convalidare i valori specificati.

Implementare la stessa semantica delle regole in .NET e JavaScript, tra cui distinzione tra maiuscole e minuscole, normalizzazione e gestione di valori vuoti. Se le implementazioni differiscono, il browser e la convalida sul lato server autorevole possono produrre risultati diversi.

Convalida modulo su richiesta

L'API Blazor.formValidation espone anche i metodi JavaScript per la convalida su richiesta, come illustrato nella tabella seguente.

Limitazioni

• Le regole lato client vengono generate solo per i campi inclusi anche nella convalida lato server. Senza Microsoft.Extensions.Validation, vengono convalidate solo le proprietà del modello di primo livello. La convalida di oggetti e raccolte annidati richiede che l'app chiami AddValidation e che il modello venga individuato. Per altre informazioni, vedere Convalida in ASP.NET Core. Si noti che questa limitazione è una funzionalità intenzionale per evitare bug in cui la convalida autorevole del server sarebbe mancante a causa di errori di configurazione.
• Gli input aggiunti a un modulo esistente da un successivo aggiornamento di rendering in streaming non vengono sottoposti alla convalida lato client. Un modulo inviato in un singolo batch in streaming viene elaborato normalmente.
• Solo gli attributi elencati in Attributi di convalida supportati hanno implementazioni lato client predefinite. Ad esempio, un RangeAttribute oggetto con un tipo di operando non numerico viene applicato solo al server. Altri attributi richiedono una regola di convalida lato client personalizzata.
• I validator JavaScript personalizzati sono sincroni. Le regole che richiedono una chiamata di rete o un altro lavoro asincrono devono essere eseguite nel server o usare la convalida asincrona con una modalità di rendering interattiva. Per altre informazioni, vedi ASP.NET Core validazione Blazor avanzata dei moduli.

Risorse aggiuntive

• Blazor convalida dei moduli ASP.NET Core
• ASP.NET Core Blazor validazione avanzata dei moduli
• Validazione in ASP.NET Core
• modalità di rendering di ASP.NET Core Blazor