ASP.NET Core Blazor clientseitige Formularvalidierung in statischem SSR

In diesem Artikel wird erläutert, wie Blazor Formularen, die statisches serverseitiges Rendering (statische sSR) verwenden, eine clientseitige Liveüberprüfung hinzugefügt wird. Der Browser überprüft einzelne Felder, während der Benutzer sie bearbeitet, und überprüft das vollständige Formular, bevor es übermittelt wird. Wenn die clientseitige Überprüfung erfolgreich ist, wird das Formular gesendet und erneut auf dem Server überprüft.

Formulare, die einen interaktiven Rendermodus verwenden, nutzen nicht das in diesem Artikel beschriebene Feature zur statischen clientseitigen SSR-Validierung. Sowohl die feldweise Validierung als auch die Validierung beim Absenden des gesamten Formulars werden in .NET über das EditContext des Formulars ausgeführt.

Funktionsweise der clientseitigen Überprüfung

Wenn ein statisches SSR-Formular eine DataAnnotationsValidator Komponente enthält, Blazor rendert die Gültigkeitsprüfungsregeln des Formulars auf der Seite und erzwingt sie mithilfe von JavaScript, bevor das Formular übermittelt wird. Dem Benutzer werden Validierungsfehler angezeigt, ohne dass eine Serverrückfrage erforderlich ist.

Die clientseitige Überprüfung wird automatisch aktiviert, wenn die folgenden Bedingungen erfüllt sind:

• Die Hostkomponente des Formulars verwendet statische SSR (keine @rendermode Direktive, die auf die Komponente angewendet wird).
• Das Formular enthält eine DataAnnotationsValidator Komponente.
• Das Modell des Formulars verwendet System.ComponentModel.DataAnnotations Überprüfungsattribute.

Für die integrierte Gruppe von Überprüfungsattributen ist keine JavaScript-Konfiguration, kein zusätzliches Paket oder eine Dienstregistrierung erforderlich. Im Abschnitt "Benutzerdefinierte clientseitige Gültigkeitsprüfungsregeln " wird beschrieben, wie Unterstützung für benutzerdefinierte Überprüfungsattribute hinzugefügt wird.

Unterstützte Überprüfungsattribute

Die folgenden System.ComponentModel.DataAnnotations Attribute werden clientseitig erzwungen und entsprechen dem serverseitigen Datenanmerkungsverhalten:

• RequiredAttribute
• StringLengthAttribute
• MinLengthAttribute
• MaxLengthAttribute
• RangeAttribute (nur wenn der Operandtyp numerisch ist)
• RegularExpressionAttribute
• EmailAddressAttribute
• UrlAttribute
• PhoneAttribute
• CreditCardAttribute
• CompareAttribute
• FileExtensionsAttribute

Überprüfungsattribute, die in dieser Liste nicht angezeigt werden, einschließlich benutzerdefinierter ValidationAttributeabgeleiteter Attribute, werden standardmäßig nicht clientseitig erzwungen. Sie werden weiterhin serverseitig ausgeführt, nachdem das Formular übermittelt wurde. Informationen zum Bereitstellen einer clientseitigen Regel für ein benutzerdefiniertes Attribut finden Sie im Abschnitt "Benutzerdefinierte clientseitige Gültigkeitsprüfungsregeln" .

Überprüfungszeitpunkt

Ein Feld wird validiert, wenn sein Wert übernommen wird. Bei Texteingaben (<input> Elementen) tritt dies auf, wenn das Feld den Fokus verliert. Kontrollkästchen und Dropdownlisten werden unmittelbar nach der Auswahl überprüft.

Nachdem ein Feld einen Überprüfungsfehler angezeigt hat oder das Formular mindestens einmal übermittelt wurde, wird das Feld bei jedem Tastenanschlag erneut überprüft, sodass Korrekturen sofort wiedergegeben werden.

Beim Absenden des Formulars werden alle verfolgten Felder validiert. Wenn ein Feld ungültig ist, wird die Übermittlung blockiert, und der Fokus wird auf das erste ungültige Feld gesetzt.

Validierungsmeldungen, Lokalisierung und Barrierefreiheit

Die clientseitige Validierung verwendet ValidationMessage<TValue>, um Meldungen für einzelne Felder anzuzeigen, und ValidationSummary, um Meldungen für das gesamte Formular anzuzeigen. Dies geschieht auf dieselbe Weise, wie die interaktive Validierung den Benutzern Meldungen anzeigt.

Wenn die Validierungslokalisierung konfiguriert ist, werden Fehlermeldungen beim Rendern der Seite auf dem Server lokalisiert, sodass die clientseitige Überprüfung die gleichen lokalisierten Zeichenfolgen wie die serverseitige Erfahrung anzeigt. Lokalisierung erfordert Microsoft.Extensions.Validation. Weitere Informationen finden Sie unter "Überprüfung" in ASP.NET Core.

Die ARIA-Attribute auf Eingabeelementen und in Containern für Validierungsmeldungen werden von Blazor automatisch verwaltet, sodass assistive Technologien Validierungsfehler ohne zusätzliche Konfiguration ausgeben.

CSS-Klassen des Überprüfungszustands

Das clientseitige Überprüfungsmodul wendet dieselben CSS-Klassen wie Blazordie interaktive Überprüfung an, die in der folgenden Tabelle dargestellt sind.

Die clientseitige Überprüfung ruft auch die Einschränkungsüberprüfungs-API des Browsers auf, sodass die standardmäßigen CSS-Pseudoklassen :valid und :invalid den aktuellen Überprüfungsstatus der einzelnen Eingaben widerspiegeln.

Clientseitige Validierung deaktivieren

Das Feature kann auf mehreren Ebenen deaktiviert werden. Die serverseitige Überprüfung ist von allen Optionen in diesem Abschnitt nicht betroffen.

Abmelden für ein einzelnes Formular

Legen Sie den DisableClientValidation-Parameter der Komponente DataAnnotationsValidator auf true fest:

<DataAnnotationsValidator DisableClientValidation="true" />

Abmelden für die gesamte App

Legen Sie DisableClientValidation für RazorComponentsServiceOptions fest, wenn Razor Komponentenservices in der Datei Program registriert sind:

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

Die globale Option hat Vorrang. Wenn sie auf true festgelegt ist, geben Formulare keine clientseitigen Gültigkeitsprüfungsregeln aus.

Deaktivierung einer einzelnen Absenden-Schaltfläche

Verwenden Sie das standardmäßige HTML-Attributformnovalidate auf der Schaltfläche. Das Formular wird ohne clientseitige Überprüfung bereitgestellt, und die serverseitige Überprüfung wird nach dem Beitrag weiterhin ausgeführt:

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

Dies kann verwendet werden, um eine Schaltfläche "Entwurf speichern" oder "Zurück" zu implementieren, die kein vollständig gültiges Formular erfordert, damit die Übermittlung erfolgreich ist.

Benutzerdefinierte clientseitige Gültigkeitsprüfungsregeln

Benutzerdefinierte Überprüfungsattribute werden weiterhin auf dem Server ausgeführt, verfügen jedoch nicht standardmäßig über eine clientseitige Implementierung. Das Erzwingen einer benutzerdefinierten Regel im Browser umfasst zwei Schritte: Ausstellen der Regel aus dem attribut .NET und Registrieren eines übereinstimmenden JavaScript-Validators. Die serverseitige Implementierung bleibt autoritativ.

Die Regel aus .NET-Regel ausgeben

Implementieren Sie IClientValidationRuleProvider für das Validierungsattribut, und geben Sie eine oder mehrere Instanzen von ClientValidationRule zurück. Die Regel identifiziert den clientseitigen Validator und liefert Werte, die der Validator benötigt.The rule's Name identifies the client-side validator, and Parameters supplies values the validator needs.

Das folgende StartsWithAttribute validiert serverseitig in startswith und trägt clientseitig eine IsValid-Regel mit dem Parameter prefix bei:

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

Wenden Sie das Attribut auf das Modell in der üblichen Weise an:

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

Registrieren des JavaScript-Validators

Rufen Sie in JavaScript auf Blazor.formValidation.addValidator(name, validator) , um einen Regelnamen einer Validatorfunktion zuzuordnen. Die name muss genau mit ClientValidationRule.Name übereinstimmen, einschließlich der Groß-/Kleinschreibung. Registrierungen sind appweit und die Registrierung desselben Namens ersetzt erneut den vorherigen Validator.

Registrieren Sie benutzerdefinierte Validatoren einmal aus dem App-Startcode. Wählen Sie den Registrierungsort danach aus, wie Blazor startet, wie in der folgenden Tabelle beschrieben.

Ein JavaScript-Initialisierer funktioniert mit beiden Startstilen. In einer Datei namens wwwroot im Ordner {ASSEMBLY NAME}.lib.module.js der App:

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

Beim automatischen Start kann ein app-spezifisches Validatorskript stattdessen unmittelbar nach folgendem blazor.web.jsGeladen werden:

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

Das zweite Skript kann Blazor.formValidation.addValidator direkt aufrufen.

Definieren Sie beim manuellen Start die Registrierung in einem App-Skript:

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

Laden Sie die Skripts bei deaktiviertem automatischem Start, und registrieren Sie die Validatoren nach Abschluss von 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>

Schreiben von JavaScript-Validatorfunktionen

Der Validator empfängt ein Kontextobjekt mit den folgenden Elementen, wie in der folgenden Tabelle dargestellt.

Der Validator sollte { success: true } zurückgeben, wenn der Wert gültig ist. Kehren Sie { success: false } zurück, um die vom Server bereitgestellte Nachricht der Regel zu verwenden, oder Sie können zurückkehren { success: false, message: '...' } , um die Nachricht für diesen Anruf außer Kraft zu setzen.

Leere Werte sollten normalerweise von anderen Regeln als required als gültig behandelt werden, sodass ein optionales Feld leer bleiben kann, während angegebene Werte, wenn welche vorhanden sind, weiterhin überprüft werden.

Implementieren Sie die gleiche Regelsemantik in .NET und JavaScript, einschließlich Groß-/Kleinschreibung, Normalisierung und Leerwertbehandlung. Wenn sich die Implementierungen unterscheiden, kann der Browser und die autorisierende serverseitige Überprüfung unterschiedliche Ergebnisse erzielen.

Formular bei Bedarf überprüfen

Die Blazor.formValidation API macht auch JavaScript-Methoden für die Überprüfung bei Bedarf verfügbar, wie in der folgenden Tabelle dargestellt.

Limitations

• Clientseitige Regeln werden nur für Felder ausgegeben, die auch in der serverseitigen Überprüfung enthalten sind. Ohne Microsoft.Extensions.Validationwerden nur Modelleigenschaften der obersten Ebene überprüft. Die Überprüfung geschachtelter Objekte und Sammlungen erfordert, dass die App AddValidation aufruft und dass das Modell erkannt wird. Weitere Informationen finden Sie unter "Überprüfung" in ASP.NET Core. Beachten Sie, dass diese Einschränkung ein absichtliches Feature ist, um Fehler zu verhindern, bei denen die autoritative Serverüberprüfung aufgrund einer fehlkonfigurierten Konfiguration fehlt.
• Eingaben, die einem vorhandenen Formular durch ein späteres Streamingrenderingupdate hinzugefügt wurden, erhalten keine clientseitige Überprüfung. Ein Formular, das in einem einzigen Streaming-Batch übermittelt wird, wird normal verarbeitet.
• Nur die in unterstützten Überprüfungsattributen aufgeführten Attribute verfügen über integrierte clientseitige Implementierungen. Beispielsweise wird ein RangeAttribute mit einem nicht numerischen Operandtyp nur auf dem Server erzwungen. Andere Attribute erfordern eine benutzerdefinierte clientseitige Gültigkeitsprüfungsregel.
• Benutzerdefinierte JavaScript-Validatoren sind synchron. Regeln, die einen Netzwerkaufruf oder eine andere asynchrone Arbeit erfordern, müssen auf dem Server ausgeführt werden oder eine asynchrone Überprüfung mit einem interaktiven Rendermodus verwenden. Weitere Informationen finden Sie unter ASP.NET Core Blazor erweiterten Formularüberprüfung.

Verwandte Inhalte

• Blazor ASP.NET Core Formularüberprüfung
• Blazor ASP.NET Core erweiterte Formularüberprüfung
• Überprüfung in ASP.NET Core
• ASP.NET Core-Render-Modi Blazor