ASP.NET Core Blazor klientsidig formulärvalidering i statisk SSR

Den här artikeln förklarar hur Blazor du lägger till liveverifiering på klientsidan i formulär som använder statisk återgivning på serversidan (statisk SSR). Webbläsaren validerar enskilda fält när användaren redigerar dem och verifierar det fullständiga formuläret innan det skickas. Om kontrollen på klientsidan godkänns skickas formuläret och verifieras igen på servern.

Formulär som använder ett interaktivt återgivningsläge använder inte den statiska valideringsfunktionen på SSR-klientsidan som beskrivs i den här artikeln. Både validering per fält och validering av fullständiga formulär körs i .NET via formulärets EditContext.

Så här fungerar verifiering på klientsidan

När ett statiskt SSR-formulär innehåller en DataAnnotationsValidator komponent Blazor renderar formulärets valideringsregler till sidan och framtvingar dem med JavaScript innan formuläret skickas. Användaren ser valideringsfel utan att behöva skicka en begäran till servern.

Validering på klientsidan aktiveras automatiskt när följande villkor uppfylls:

• Formulärets värdkomponent använder statisk SSR (inget @rendermode direktiv tillämpas på komponenten).
• Formuläret innehåller en DataAnnotationsValidator komponent.
• Formulärets modell använder System.ComponentModel.DataAnnotations valideringsattribut.

För den inbyggda uppsättningen valideringsattribut krävs ingen JavaScript-konfiguration, ytterligare paket- eller tjänstregistrering. I avsnittet Anpassade verifieringsregler på klientsidan beskrivs hur du lägger till stöd för anpassade valideringsattribut.

Valideringsattribut som stöds

Följande System.ComponentModel.DataAnnotations attribut tillämpas på klientsidan och matchar beteendet för dataanteckningar på serversidan:

• RequiredAttribute
• StringLengthAttribute
• MinLengthAttribute
• MaxLengthAttribute
• RangeAttribute (endast när operandtypen är numerisk)
• RegularExpressionAttribute
• EmailAddressAttribute
• UrlAttribute
• PhoneAttribute
• CreditCardAttribute
• CompareAttribute
• FileExtensionsAttribute

Valideringsattribut som inte visas i den här listan, inklusive anpassade ValidationAttribute-härledda attribut, tillämpas inte på klientsidan som standard. De fortsätter att köra serversidan när formuläret har skickats. Information om hur du anger en regel på klientsidan för ett anpassat attribut finns i avsnittet Anpassade verifieringsregler på klientsidan .

Tidsinställning för validering

Ett fält valideras när dess värde bekräftas. För textinmatningar (<input> element) inträffar detta när fältet förlorar fokus. Kryssrutor och listristor valideras omedelbart efter att de har valts.

När ett fält har visat ett valideringsfel eller efter att formuläret har skickats minst en gång verifieras fältet igen vid varje tangenttryckning så att korrigeringarna återspeglas omedelbart.

När formuläret skickas verifieras varje spårat fält. Om ett fält är ogiltigt blockeras överföringen och fokus flyttas till det första ogiltiga fältet.

Valideringsmeddelanden, lokalisering och hjälpmedel

Validering på klientsidan används ValidationMessage<TValue> för att visa meddelanden för enskilda fält och ValidationSummary för att visa meddelanden för hela formuläret, vilket är samma sätt som interaktiv validering rapporterar meddelanden till användare.

När verifieringslokalisering har konfigurerats lokaliseras felmeddelanden på servern när sidan återges, så validering på klientsidan visar samma lokaliserade strängar som på serversidan. Lokalisering kräver Microsoft.Extensions.Validation. Mer information finns i Validering i ASP.NET Core.

ARIA-attribut på indataelement och valideringsmeddelandecontainrar Blazor hanteras automatiskt, så hjälptekniker meddelar valideringsfel utan ytterligare konfiguration.

CSS-klasser för valideringstillstånd

Valideringsmotorn på klientsidan tillämpar samma CSS-klasser som Blazorinteraktiv validering, som visas i följande tabell.

Validering på klientsidan anropar också webbläsarens API för begränsningsverifiering, så standard-CSS pseudoklasser :valid och :invalid återspeglar varje indatas aktuella valideringstillstånd.

Avregistrera dig från validering på klientsidan

Funktionen kan inaktiveras på flera nivåer. Validering på serversidan påverkas inte av något av alternativen i det här avsnittet.

Avregistrera dig från ett specifikt formulär

Ange parametern DisableClientValidation för komponenten DataAnnotationsValidator till true:

<DataAnnotationsValidator DisableClientValidation="true" />

Avregistrera dig för hela appen

Ange DisableClientValidation på RazorComponentsServiceOptions när Razor-komponenttjänster registreras i filen Program:

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

Det globala alternativet har företräde. När det är inställt på truegenererar formulär inte verifieringsregler på klientsidan.

Välj bort en enda Skicka-knapp

Använd html-standardattributetformnovalidate på knappen. Formuläret publiceras utan en kontroll på klientsidan och verifieringen på serversidan körs fortfarande efter inlägget:

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

Detta kan användas för att implementera en "Spara utkast"- eller "Tillbaka"-knapp som inte kräver ett helt giltigt formulär för att formuläret ska kunna skickas.

Anpassade verifieringsregler på klientsidan

Anpassade valideringsattribut fortsätter att köras på servern men har ingen implementering på klientsidan som standard. Att framtvinga en anpassad regel i webbläsaren omfattar två steg: att generera regeln från attributet .NET och registrera en matchande JavaScript-validator. Implementeringen på serversidan är fortfarande auktoritativ.

Generera regeln från .NET

Implementera IClientValidationRuleProvider på valideringsattributet och returnera en eller flera ClientValidationRule instanser. Regeln identifierar Name validatorn på klientsidan och Parameters tillhandahåller värden som validatorn behöver.

Följande StartsWithAttribute validerar serversidan i IsValid och bidrar med en startswith regel på klientsidan med en prefix parameter:

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

Använd attributet på modellen på vanligt sätt:

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

Registrera JavaScript-validatorn

I JavaScript anropar du Blazor.formValidation.addValidator(name, validator) för att associera ett regelnamn med en validatorfunktion. Måste name exakt matcha ClientValidationRule.Name, inklusive hölje. Registreringar är appomfattande och om du registrerar samma namn igen ersätts den tidigare validatorn.

Registrera anpassade validerare bara en gång i appens startkod. Välj registreringsplatsen baserat på hur Blazor startar, enligt beskrivningen i följande tabell.

En JavaScript-initiering fungerar med båda startformaten. I en fil med namnet {ASSEMBLY NAME}.lib.module.js i appens wwwroot mapp:

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

Med automatisk start kan ett appspecifikt valideringsskript i stället läsas in direkt efter blazor.web.js:

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

Det andra skriptet kan anropa Blazor.formValidation.addValidator direkt.

Med manuell start definierar du registreringen i ett appskript:

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

Läs in skripten med automatisk start inaktiverad och registrera validatorerna efter att Blazor.start() har slutförts:

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

Skriv valideringsfunktioner i JavaScript

Validatorn tar emot ett kontextobjekt med följande medlemmar, enligt följande tabell.

Validatorn förväntas returnera { success: true } när värdet är giltigt. Returnera { success: false } för att använda regelns serverlevererade meddelande, eller så kan du returnera { success: false, message: '...' } för att åsidosätta meddelandet för just det anropet.

Tomma värden bör normalt behandlas som giltiga av andra regler än required, vilket gör att ett valfritt fält kan förbli tomt samtidigt som värden som anges verifieras.

Implementera samma regelsemantik i .NET och JavaScript, inklusive skiftlägeskänslighet, normalisering och hantering av tomma värden. Om implementeringarna skiljer sig åt kan webbläsaren och den auktoritativa verifieringen på serversidan ge olika resultat.

Verifiera formulär på begäran

API:et Blazor.formValidation exponerar även JavaScript-metoder för validering på begäran, vilket visas i följande tabell.

Limitations

• Regler på klientsidan genereras endast för fält som ingår i validering på serversidan. Utan Microsoft.Extensions.Validationverifieras endast modellegenskaper på den översta nivån. För att verifiera kapslade objekt och samlingar krävs att appen anropar AddValidation och att modellen identifieras. Mer information finns i Validering i ASP.NET Core. Observera att den här begränsningen är en avsiktlig funktion för att förhindra buggar där den auktoritativa serververifieringen skulle saknas på grund av felkonfiguration.
• Indata som läggs till i ett befintligt formulär av en senare uppdatering av direktuppspelningsåtergivning tar inte emot validering på klientsidan. Ett formulär som levereras som en enda strömmad batch hanteras normalt.
• Endast de attribut som anges i Valideringsattribut som stöds har inbyggda implementeringar på klientsidan. Till exempel tillämpas en RangeAttribute med en icke-numerisk operandtyp endast på servern. Andra attribut kräver en anpassad verifieringsregel på klientsidan.
• Anpassade JavaScript-validatorer är synkrona. Regler som kräver ett nätverksanrop eller annat asynkront arbete måste köras på servern eller använda asynkron validering med ett interaktivt återgivningsläge. Mer information finns i ASP.NET Core Blazor avancerad formulärverifiering.

Relaterat innehåll

• validering av Blazor ASP.NET Core formulär
• Blazor ASP.NET Core avancerad formulärverifiering
• Validering i ASP.NET Core
• ASP.NET Core-återgivningslägen Blazor