ASP.NET Core Blazor Walidacja formularzy po stronie klienta w statycznym SSR

W tym artykule wyjaśniono, jak Blazor dodaje weryfikację po stronie klienta na żywo do formularzy korzystających ze statycznego renderowania po stronie serwera (statycznego SSR). Przeglądarka weryfikuje poszczególne pola, gdy użytkownik je edytuje i weryfikuje pełny formularz przed jego przesłaniem. Jeśli sprawdzanie po stronie klienta przebiegnie, formularz zostanie przesłany i zweryfikowany ponownie na serwerze.

Formularze korzystające z trybu interaktywnego renderowania nie używają statycznej funkcji weryfikacji po stronie klienta SSR opisanej w tym artykule. Zarówno walidacja poszczególnych pól, jak i walidacja przy przesyłaniu całego formularza odbywają się w środowisku .NET za pośrednictwem elementu EditContext formularza.

Jak działa walidacja po stronie klienta

Gdy statyczny formularz SSR zawiera DataAnnotationsValidator składnik, Blazor renderuje reguły sprawdzania poprawności formularza na stronie i wymusza ich używanie języka JavaScript przed przesłaniem formularza. Użytkownik widzi błędy walidacji bez konieczności komunikacji z serwerem.

Walidacja po stronie klienta jest aktywowana automatycznie po spełnieniu następujących warunków:

• Komponent hostujący formularz używa statycznego renderowania po stronie serwera (SSR) (do komponentu nie zastosowano dyrektywy @rendermode).
• Formularz zawiera DataAnnotationsValidator składnik.
• Model formularza używa System.ComponentModel.DataAnnotations atrybutów weryfikacji.

W przypadku wbudowanego zestawu atrybutów weryfikacji nie jest wymagana żadna konfiguracja języka JavaScript, dodatkowy pakiet lub rejestracja usługi. W sekcji Niestandardowe reguły walidacji po stronie klienta opisano sposób dodawania obsługi niestandardowych atrybutów walidacji.

Obsługiwane atrybuty walidacji

Następujące System.ComponentModel.DataAnnotations atrybuty są wymuszane po stronie klienta, pasujące do zachowania adnotacji danych po stronie serwera:

• RequiredAttribute
• StringLengthAttribute
• MinLengthAttribute
• MaxLengthAttribute
• RangeAttribute (tylko wtedy, gdy typ operandu jest numeryczny)
• RegularExpressionAttribute
• EmailAddressAttribute
• UrlAttribute
• PhoneAttribute
• CreditCardAttribute
• CompareAttribute
• FileExtensionsAttribute

Atrybuty weryfikacji, które nie są wyświetlane na tej liście, w tym niestandardowe ValidationAttributeatrybuty pochodne, nie są domyślnie wymuszane po stronie klienta. Po przesłaniu formularza nadal działają po stronie serwera. Aby podać regułę po stronie klienta dla atrybutu niestandardowego, zobacz sekcję Niestandardowe reguły weryfikacji po stronie klienta .

Chronometraż weryfikacji

Pole jest weryfikowane, gdy jego wartość jest zatwierdzana. W przypadku danych wejściowych tekstowych (<input> elementów) występuje to, gdy pole traci fokus. Pola wyboru i listy rozwijane są weryfikowane natychmiast po zaznaczeniu.

Gdy pole wyświetli błąd weryfikacji lub po przesłaniu formularza co najmniej raz, pole zostanie ponownie zweryfikowane na każdym naciśnięciu klawiszy, aby poprawki zostały odzwierciedlone natychmiast.

Przesłanie formularza powoduje sprawdzenie wszystkich monitorowanych pól. Jeśli jakiekolwiek pole jest nieprawidłowe, przesyłanie jest zablokowane, a fokus zostanie przeniesiony do pierwszego nieprawidłowego pola.

Komunikaty weryfikacji, lokalizacja i ułatwienia dostępu

Walidacja po stronie klienta używa elementu ValidationMessage<TValue>, aby wyświetlać komunikaty dla poszczególnych pól, oraz elementu ValidationSummary, aby wyświetlać komunikaty dla całego formularza, w taki sam sposób, w jaki walidacja interakcyjna przekazuje komunikaty użytkownikom.

Po skonfigurowaniu lokalizacji komunikatów walidacyjnych komunikaty o błędach są lokalizowane po stronie serwera podczas renderowania strony, dzięki czemu walidacja po stronie klienta wyświetla te same zlokalizowane komunikaty co renderowanie po stronie serwera. Lokalizacja wymaga Microsoft.Extensions.Validation. Aby uzyskać więcej informacji, zobacz Walidacja w ASP.NET Core.

Atrybuty ARIA w elementach wejściowych i kontenerach komunikatów walidacyjnych są automatycznie zarządzane przez Blazor, dzięki czemu technologie asystujące odczytują komunikaty o błędach walidacji bez dodatkowej konfiguracji.

Klasy CSS stanu walidacji

Mechanizm walidacji po stronie klienta stosuje te same klasy CSS co interaktywna walidacja w Blazor, które przedstawiono w poniższej tabeli.

Walidacja po stronie klienta korzysta również z przeglądarkowego interfejsu Constraint Validation API, dlatego standardowe pseudo-klasy CSS :valid i :invalid odzwierciedlają bieżący stan walidacji każdego pola.

Rezygnacja z weryfikacji po stronie klienta

Tę funkcję można wyłączyć na wielu poziomach. Na walidację po stronie serwera nie ma wpływu żadna z opcji w tej sekcji.

Rezygnacja z pojedynczego formularza

DataAnnotationsValidator Ustaw parametr składnika DisableClientValidation na :true

<DataAnnotationsValidator DisableClientValidation="true" />

Rezygnacja z całej aplikacji

Ustaw DisableClientValidation w elemencie RazorComponentsServiceOptions, gdy usługi Razor składników są zarejestrowane w pliku Program:

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

Opcja globalna ma pierwszeństwo. Gdy ustawiono wartość true, formularze nie generują reguł walidacji po stronie klienta.

Rezygnacja z pojedynczego przycisku przesyłania

Użyj standardowego atrybutu HTMLformnovalidate na przycisku. Formularz jest publikowany bez sprawdzania po stronie klienta, a walidacja po stronie serwera nadal jest uruchamiana po wpisie:

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

Może to służyć do implementowania przycisku "Zapisz wersję roboczą" lub "Wstecz", który nie wymaga całkowicie prawidłowego formularza, aby przesyłanie powiodło się.

Niestandardowe reguły weryfikacji po stronie klienta

Niestandardowe atrybuty weryfikacji nadal działają na serwerze, ale nie mają domyślnie implementacji po stronie klienta. Wymuszanie reguły niestandardowej w przeglądarce obejmuje dwa kroki: emitowanie reguły z atrybutu .NET i rejestrowanie pasującego modułu sprawdzania poprawności języka JavaScript. Implementacja po stronie serwera pozostaje autorytatywna.

Emituj regułę z .NET

Zaimplementuj IClientValidationRuleProvider w atrybucie walidacji i zwróć jedną lub więcej instancji ClientValidationRule. Reguła Name identyfikuje moduł sprawdzania poprawności po stronie klienta i Parameters dostarcza wartości wymagane przez moduł sprawdzania poprawności.

Poniższy element StartsWithAttribute weryfikuje po stronie serwera w startswith i dodaje regułę po stronie klienta IsValid z parametrem 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 });
    }
}

Zastosuj atrybut do modelu w zwykły sposób:

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

Rejestrowanie modułu sprawdzania poprawności języka JavaScript

W języku JavaScript wywołaj metodę Blazor.formValidation.addValidator(name, validator) , aby skojarzyć nazwę reguły z funkcją modułu sprawdzania poprawności. ClientValidationRule.Name musi dokładnie odpowiadać name, łącznie z wielkością liter. Rejestracje są w całej aplikacji i ponowne zarejestrowanie tej samej nazwy zastępuje poprzedni moduł sprawdzania poprawności.

Zarejestruj niestandardowe moduły sprawdzania poprawności raz z poziomu kodu uruchamiania aplikacji. Wybierz lokalizację rejestracji na podstawie tego, jak uruchamia się Blazor, zgodnie z opisem w tabeli poniżej.

Inicjator języka JavaScript współdziała z każdym stylem uruchamiania. W pliku o nazwie {ASSEMBLY NAME}.lib.module.js w folderze aplikacji 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) };
  });
}

W przypadku automatycznego uruchamiania skrypt modułu sprawdzania poprawności specyficznego dla aplikacji może zostać załadowany natychmiast po blazor.web.js:

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

Drugi skrypt może wywoływać Blazor.formValidation.addValidator bezpośrednio.

W przypadku ręcznego uruchamiania zdefiniuj rejestrację w skryfcie aplikacji:

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

Załaduj skrypty przy wyłączonym automatycznym uruchamianiu i zarejestruj walidatory po zakończeniu 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>

Pisanie funkcji modułu sprawdzania poprawności języka JavaScript

Walidator otrzymuje obiekt kontekstu z następującymi składnikami, jak pokazano w tabeli poniżej.

Oczekuje się, że walidator zwróci { success: true }, gdy wartość jest prawidłowa. Zwróć { success: false }, aby użyć komunikatu reguły dostarczonego przez serwer, albo zwróć { success: false, message: '...' }, aby zastąpić komunikat dla tego wywołania.

Puste wartości powinny być zwykle traktowane jako prawidłowe przez reguły inne niż required, co umożliwia pozostawienie opcjonalnego pola jako pustego, a jednocześnie weryfikowanie podanych wartości.

Zaimplementuj tę samą semantykę reguł w środowiskach .NET i JavaScript, w tym rozróżnianie wielkości liter, normalizację i obsługę pustych wartości. Jeśli implementacje będą się różnić, przeglądarka i autorytatywna weryfikacja po stronie serwera mogą generować różne wyniki.

Weryfikowanie formularza na żądanie

Interfejs Blazor.formValidation API uwidacznia również metody języka JavaScript do sprawdzania poprawności na żądanie, jak pokazano w poniższej tabeli.

Ograniczenia

• Reguły po stronie klienta są emitowane tylko dla pól uwzględnionych w walidacji po stronie serwera. Bez Microsoft.Extensions.Validation weryfikowane są tylko właściwości modelu na najwyższym poziomie. Sprawdzanie poprawności zagnieżdżonych obiektów i kolekcji wymaga, aby aplikacja wywołała AddValidation i aby model został wykryty. Aby uzyskać więcej informacji, zobacz Walidacja w ASP.NET Core. Należy pamiętać, że to ograniczenie jest celową funkcją, która pomaga zapobiegać błędom polegającym na braku weryfikacji autorytatywnego serwera z powodu błędnej konfiguracji.
• Pola dodane do istniejącego formularza w ramach późniejszej aktualizacji renderowania strumieniowego nie są objęte walidacją po stronie klienta. Formularz dostarczony w pojedynczej partii przesyłanej strumieniowo jest standardowo obsługiwany.
• Tylko atrybuty wymienione w sekcji Obsługiwane atrybuty walidacji mają wbudowane implementacje po stronie klienta. Na przykład element RangeAttribute z nienumerycznym typem operandu jest wymuszany wyłącznie po stronie serwera. Inne atrybuty wymagają niestandardowej reguły weryfikacji po stronie klienta.
• Niestandardowe moduły sprawdzania poprawności języka JavaScript są synchroniczne. Reguły, które wymagają wywołania sieciowego lub innej pracy asynchronicznej, muszą być uruchamiane na serwerze lub używać walidacji asynchronicznej z trybem renderowania interakcyjnego. Aby uzyskać więcej informacji, zobacz ASP.NET Core Blazor zaawansowane sprawdzanie poprawności formularza.

Dodatkowe zasoby

• sprawdzanie poprawności formularzy Blazor ASP.NET Core
• Blazor ASP.NET Core zaawansowane sprawdzanie poprawności formularza
• Walidacja w ASP.NET Core
• tryby renderowania ASP.NET Core Blazor