Ringkasan formulir ASP.NET Core Blazor

Artikel ini menjelaskan cara menggunakan formulir di Blazor.

Komponen dan formulir input

Blazor Kerangka kerja mendukung formulir dan menyediakan komponen input bawaan:

• Terikat ke objek atau model yang dapat menggunakan anotasi data.
  • Formulir HTML dengan <form> elemen .
  • EditForm Komponen.
• Komponen input bawaan.

Catatan

Fitur validasi ASP.NET Core yang tidak didukung tercakup di bagian Fitur validasi yang tidak didukung.

Namespace Microsoft.AspNetCore.Components.Forms layanan menyediakan:

• Kelas untuk mengelola elemen formulir, status, dan validasi.
• Akses ke komponen bawaan Input* .

Proyek yang dibuat dari Blazor templat proyek menyertakan namespace layanan dalam file aplikasi _Imports.razor , yang membuat namespace tersedia untuk komponen aplikasi Razor .

Formulir HTML standar didukung. Buat formulir menggunakan tag HTML <form> normal dan tentukan @onsubmit handler untuk menangani permintaan formulir yang dikirimkan.

StarshipPlainForm.razor:

@page "/starship-plain-form"
@inject ILogger<StarshipPlainForm> Logger

<form method="post" @onsubmit="Submit" @formname="starship-plain-form">
    <AntiforgeryToken />
    <div>
        <label>
            Identifier: 
            <InputText @bind-Value="Model!.Id" />
        </label>
    </div>
    <div>
        <button type="submit">Submit</button>
    </div>
</form>

@code {
    [SupplyParameterFromForm]
    private Starship? Model { get; set; }

    protected override void OnInitialized() => Model ??= new();

    private void Submit() => Logger.LogInformation("Id = {Id}", Model?.Id);

    public class Starship
    {
        public string? Id { get; set; }
    }
}

Di komponen sebelumnya StarshipPlainForm :

• Formulir dirender di <form> mana elemen muncul. Formulir dinamai dengan atribut direktif @formname , yang secara unik mengidentifikasi formulir ke Blazor kerangka kerja.
• Model dibuat di blok komponen @code dan disimpan di properti publik (Model). Atribut [SupplyParameterFromForm] menunjukkan bahwa nilai properti terkait harus disediakan dari data formulir. Data dalam permintaan yang cocok dengan nama properti terikat ke properti .
• Komponen InputText adalah komponen input untuk mengedit nilai string. Atribut @bind-Value direktif mengikat Model.Id properti model ke InputText properti komponen Value .
• Metode Submit ini terdaftar sebagai handler untuk @onsubmit panggilan balik. Handler dipanggil ketika formulir dikirimkan oleh pengguna.

Penting

Selalu gunakan atribut direktif @formname dengan nama formulir yang unik.

Blazor meningkatkan navigasi halaman dan penanganan formulir dengan mencegat permintaan untuk menerapkan respons ke DOM yang ada, mempertahankan sebanyak mungkin formulir yang dirender. Peningkatan menghindari kebutuhan untuk sepenuhnya memuat halaman dan memberikan pengalaman pengguna yang jauh lebih lancar, mirip dengan aplikasi satu halaman (SPA), meskipun komponen dirender di server. Untuk informasi selengkapnya, lihat perutean dan navigasi ASP.NET CoreBlazor.

Penyajian streaming didukung untuk formulir HTML biasa.

Catatan

Tautan dokumentasi ke sumber referensi .NET biasanya memuat cabang default repositori, yang mewakili pengembangan saat ini untuk rilis .NET berikutnya. Untuk memilih tag rilis tertentu, gunakan daftar dropdown Beralih cabang atau tag. Untuk informasi lebih lanjut, lihat Cara memilih tag versi kode sumber ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Contoh sebelumnya mencakup dukungan antiforgery dengan menyertakan AntiforgeryToken komponen dalam formulir. Dukungan antiforgery dijelaskan lebih lanjut di bagian dukungan Antiforgery dari artikel ini.

Untuk mengirimkan formulir berdasarkan peristiwa DOM elemen lain, misalnya oninput atau , gunakan JavaScript untuk mengirimkan formulir (submit (dokumentasi MDN)onblur).

Alih-alih menggunakan formulir biasa dalam Blazor aplikasi, formulir biasanya didefinisikan dengan Blazordukungan formulir bawaan menggunakan komponen kerangka kerja EditForm . Komponen berikut Razor menunjukkan elemen, komponen, dan Razor kode umum untuk merender bentuk web menggunakan EditForm komponen.

Starship1.razor:

@page "/starship-1"
@inject ILogger<Starship1> Logger

<EditForm Model="Model" OnSubmit="Submit" FormName="Starship1">
    <div>
        <label>
            Identifier:
            <InputText @bind-Value="Model!.Id" />
        </label>
    </div>
    <div>
        <button type="submit">Submit</button>
    </div>
</EditForm>

@code {
    [SupplyParameterFromForm]
    private Starship? Model { get; set; }

    protected override void OnInitialized() => Model ??= new();

    private void Submit() => Logger.LogInformation("Id = {Id}", Model?.Id);

    public class Starship
    {
        public string? Id { get; set; }
    }
}

Di komponen sebelumnya Starship1 :

• Komponen EditForm dirender di <EditForm> mana elemen muncul. Formulir dinamai dengan atribut direktif @formname , yang secara unik mengidentifikasi formulir ke Blazor kerangka kerja.
• Model dibuat di blok komponen @code dan disimpan di properti publik (Model). Properti ditetapkan ke EditForm.Model parameter . Atribut [SupplyParameterFromForm] menunjukkan bahwa nilai properti terkait harus disediakan dari data formulir. Data dalam permintaan yang cocok dengan nama properti terikat ke properti .
• Komponen InputText adalah komponen input untuk mengedit nilai string. Atribut @bind-Value direktif mengikat Model.Id properti model ke InputText properti komponen Value .
• Metode Submit ini terdaftar sebagai handler untuk OnSubmit panggilan balik. Handler dipanggil ketika formulir dikirimkan oleh pengguna.

Penting

Selalu gunakan atribut direktif @formname dengan nama formulir yang unik.

Blazor meningkatkan navigasi halaman dan penanganan formulir untuk EditForm komponen. Untuk informasi selengkapnya, lihat perutean dan navigasi ASP.NET CoreBlazor.

Penyajian streaming didukung untuk EditForm.

Catatan

Tautan dokumentasi ke sumber referensi .NET biasanya memuat cabang default repositori, yang mewakili pengembangan saat ini untuk rilis .NET berikutnya. Untuk memilih tag rilis tertentu, gunakan daftar dropdown Beralih cabang atau tag. Untuk informasi lebih lanjut, lihat Cara memilih tag versi kode sumber ASP.NET Core (dotnet/AspNetCore.Docs #26205).

†Untuk informasi selengkapnya tentang pengikatan properti, lihat pengikatan data ASP.NET CoreBlazor.

Dalam contoh berikutnya, komponen sebelumnya dimodifikasi untuk membuat formulir dalam Starship2 komponen:

• OnSubmit diganti dengan OnValidSubmit, yang memproses penanganan aktivitas yang ditetapkan jika formulir valid saat dikirimkan oleh pengguna.
• Komponen ValidationSummary ditambahkan untuk menampilkan pesan validasi ketika formulir tidak valid pada pengiriman formulir.
• Validator anotasi data (DataAnnotationsValidator komponen†) melampirkan dukungan validasi menggunakan anotasi data:
  • <input> Jika bidang formulir dibiarkan kosong saat tombol Submit dipilih, kesalahan muncul di ringkasan validasi (ValidationSummary komponen‡) ("The Id field is required.") dan Submit tidak dipanggil.
  • <input> Jika bidang formulir berisi lebih dari sepuluh karakter saat tombol Submit dipilih, kesalahan muncul di ringkasan validasi ("Id is too long."). Submittidak dipanggil.
  • <input> Jika bidang formulir berisi nilai yang valid saat tombol Submit dipilih, Submit dipanggil.

† Komponen DataAnnotationsValidator ini tercakup di bagian komponen Validator. ‡Komponen ValidationSummary tercakup dalam bagian Ringkasan Validasi dan Pesan Validasi.

Starship2.razor:

@page "/starship-2"
@using System.ComponentModel.DataAnnotations
@inject ILogger<Starship2> Logger

<EditForm Model="Model" OnValidSubmit="Submit" FormName="Starship2">
    <DataAnnotationsValidator />
    <ValidationSummary />
    <label>
        Identifier: 
        <InputText @bind-Value="Model!.Id" />
    </label>
    <button type="submit">Submit</button>
</EditForm>

@code {
    [SupplyParameterFromForm]
    private Starship? Model { get; set; }

    protected override void OnInitialized() => Model ??= new();

    private void Submit() => Logger.LogInformation("Id = {Id}", Model?.Id);

    public class Starship
    {
        [Required]
        [StringLength(10, ErrorMessage = "Id is too long.")]
        public string? Id { get; set; }
    }
}

Menangani pengiriman formulir

EditForm menyediakan panggilan balik berikut untuk menangani pengiriman formulir:

• Gunakan OnValidSubmit untuk menetapkan penanganan aktivitas untuk dijalankan saat formulir dengan bidang yang valid dikirimkan.
• Gunakan OnInvalidSubmit untuk menetapkan penanganan aktivitas untuk dijalankan saat formulir dengan bidang yang tidak valid dikirimkan.
• Gunakan OnSubmit untuk menetapkan penanganan aktivitas untuk dijalankan terlepas dari status validasi bidang formulir. Formulir divalidasi dengan memanggil EditContext.Validate dalam metode penanganan aktivitas. Jika Validate mengembalikan true, formulir valid.

Menghapus formulir atau bidang

Reset formulir dengan menghapus modelnya kembali status defaultnya, yang dapat dilakukan di dalam atau di luar EditFormmarkup:

<button @onclick="ClearForm">Clear form</button>

...

private void ClearForm() => Model = new();

Atau, gunakan ekspresi eksplisit Razor :

<button @onclick="@(() => Model = new())">Clear form</button>

Reset bidang dengan menghapus nilai modelnya kembali ke status defaultnya:

<button @onclick="ResetId">Reset Identifier</button>

...

private void ResetId() => Model!.Id = string.Empty;

Atau, gunakan ekspresi eksplisit Razor :

<button @onclick="@(() => Model!.Id = string.Empty)">Reset Identifier</button>

Tidak perlu memanggil StateHasChanged contoh sebelumnya karena StateHasChanged secara otomatis dipanggil oleh Blazor kerangka kerja untuk merender komponen setelah penanganan aktivitas dipanggil. Jika penanganan aktivitas tidak digunakan untuk memanggil metode yang menghapus formulir atau bidang, maka kode pengembang harus memanggil StateHasChanged untuk merender komponen.

Dukungan antiforgery

Layanan antiforgery secara otomatis ditambahkan ke Blazor aplikasi saat AddRazorComponents dipanggil dalam Program file.

Aplikasi ini menggunakan Antiforgery Middleware dengan memanggil UseAntiforgery dalam alur pemrosesan permintaannya dalam Program file. UseAntiforgery dipanggil setelah panggilan ke UseRouting. Jika ada panggilan ke UseRouting dan UseEndpoints, panggilan ke UseAntiforgery harus berada di antara mereka. Panggilan ke UseAntiforgery harus dilakukan setelah panggilan ke UseAuthentication dan UseAuthorization.

Komponen AntiforgeryToken ini merender token antiforgery sebagai bidang tersembunyi, dan [RequireAntiforgeryToken] atribut memungkinkan perlindungan antiforgery. Jika pemeriksaan antiforgery gagal, 400 - Bad Request respons akan dilemparkan dan formulir tidak diproses.

Untuk formulir berdasarkan EditForm, AntiforgeryToken komponen dan [RequireAntiforgeryToken] atribut secara otomatis ditambahkan untuk memberikan perlindungan antiforgery.

Untuk formulir berdasarkan elemen HTML <form> , tambahkan AntiforgeryToken komponen secara manual ke formulir:

<form method="post" @onsubmit="Submit" @formname="starshipForm">
    <AntiforgeryToken />
    <input id="send" type="submit" value="Send" />
</form>

@if (submitted)
{
    <p>Form submitted!</p>
}

@code{
    private bool submitted = false;

    private void Submit() => submitted = true;
}

Peringatan

Untuk formulir berdasarkan atau EditForm elemen HTML <form> , perlindungan antiforgery dapat dinonaktifkan dengan meneruskan required: false ke [RequireAntiforgeryToken] atribut . Contoh berikut menonaktifkan antiforgery dan tidak disarankan untuk aplikasi publik:

@using Microsoft.AspNetCore.Antiforgery
@attribute [RequireAntiforgeryToken(required: false)]

Untuk informasi selengkapnya, lihat autentikasi dan otorisasi ASP.NET CoreBlazor.

Mengurangi serangan overposting

Bentuk sisi server yang dirender secara statis, seperti yang biasanya digunakan dalam komponen yang membuat dan mengedit rekaman dalam database dengan model formulir, dapat rentan terhadap serangan overposting, juga dikenal sebagai serangan penugasan massal. Serangan overposting terjadi ketika pengguna berbahaya mengeluarkan POST formulir HTML ke server yang memproses data untuk properti yang bukan bagian dari formulir yang dirender dan bahwa pengembang tidak ingin mengizinkan pengguna untuk memodifikasi. Istilah "overposting" secara harfiah berarti bahwa pengguna jahat memiliki over-POSTed dengan formulir .

Overposting bukan masalah ketika model tidak menyertakan properti terbatas untuk operasi buat dan perbarui. Namun, penting untuk terus memposting berlebihan saat bekerja dengan bentuk berbasis Blazor SSR statis yang Anda pertahankan.

Untuk mengurangi overposting, sebaiknya gunakan model tampilan terpisah/objek transfer data (DTO) untuk formulir dan database dengan operasi buat (sisipkan) dan perbarui. Saat formulir dikirimkan, hanya properti model tampilan/DTO yang digunakan oleh komponen dan kode C# untuk memodifikasi database. Setiap data tambahan yang disertakan oleh pengguna berbahaya dibuang, sehingga pengguna berbahaya dicegah melakukan serangan overposting.

Penanganan formulir yang disempurnakan

Tingkatkan navigasi untuk permintaan POST formulir dengan Enhance parameter untuk EditForm formulir atau data-enhance atribut untuk formulir HTML (<form>):

<EditForm ... Enhance ...>
    ...
</EditForm>

<form ... data-enhance ...>
    ...
</form>

❌Tidak didukung: Anda tidak dapat mengatur navigasi yang ditingkatkan pada elemen leluhur formulir untuk mengaktifkan penanganan formulir yang ditingkatkan.

<div ... data-enhance ...>
    <form ...>
        <!-- NOT enhanced -->
    </form>
</div>

Posting formulir yang disempurnakan hanya berfungsi dengan Blazor titik akhir. Memposting formulir yang disempurnakan ke non-titikBlazor akhir menghasilkan kesalahan.

Untuk menonaktifkan penanganan formulir yang ditingkatkan:

• EditFormUntuk , hapus Enhance parameter dari elemen formulir (atau atur ke false: Enhance="false").
• Untuk HTML <form>, hapus data-enhance atribut dari elemen formulir (atau atur ke false: data-enhance="false").

BlazorNavigasi dan penyerahan formulir yang disempurnakan dapat membatalkan perubahan dinamis pada DOM jika konten yang diperbarui bukan bagian dari penyajian server. Untuk mempertahankan konten elemen, gunakan data-permanent atribut .

Dalam contoh berikut, konten elemen diperbarui <div> secara dinamis oleh skrip saat halaman dimuat:

<div data-permanent>
    ...
</div>

Untuk menonaktifkan navigasi dan penanganan formulir yang disempurnakan secara global, lihat startup ASP.NET CoreBlazor.

Untuk panduan tentang menggunakan peristiwa untuk mendengarkan pembaruan halaman yang enhancedload disempurnakan, lihat perutean dan navigasi Inti Blazor ASP.NET.

Contoh

Contoh tidak mengadopsi penanganan formulir yang ditingkatkan untuk permintaan POST formulir, tetapi semua contoh dapat diperbarui untuk mengadopsi fitur yang ditingkatkan dengan mengikuti panduan di bagian Penanganan formulir yang ditingkatkan.

Untuk menunjukkan cara kerja formulir dengan validasi anotasi data, contoh komponen mengandalkan System.ComponentModel.DataAnnotations API. Jika Anda ingin menghindari baris kode tambahan dalam komponen yang menggunakan anotasi data, buat namespace layanan tersedia di seluruh komponen aplikasi dengan file impor (_Imports.razor):

@using System.ComponentModel.DataAnnotations

Contoh formulir mereferensikan aspek alam semesta Star Trek . Star Trek adalah hak cipta ©1966-2023 dari CBS Studios dan Paramount.

Validasi sisi klien memerlukan sirkuit

Dalam Blazor Web Apphal ini, validasi sisi klien memerlukan sirkuit aktif BlazorSignalR . Validasi sisi klien tidak tersedia untuk formulir dalam komponen yang telah mengadopsi penyajian sisi server statis (SSR statis). Formulir yang mengadopsi SSR statis divalidasi di server setelah formulir dikirimkan.

Fitur validasi yang tidak didukung

Semua validator bawaan anotasi data didukung kecuali Blazor untuk [Remote] atribut validasi.

Validasi jQuery tidak didukung dalam Razor komponen. Kami merekomendasikan salah satu pendekatan berikut:

• Ikuti panduan dalam validasi formulir ASP.NET Core Blazor untuk:
  • Validasi sisi server Blazor Web App dalam yang mengadopsi mode render interaktif.
  • Validasi sisi klien di aplikasi Web Assembly mandiri Blazor .
• Gunakan atribut validasi HTML asli (lihat Validasi formulir sisi klien (dokumentasi MDN)).
• Mengadopsi pustaka JavaScript validasi pihak ketiga.

Untuk formulir yang dirender secara statis di server, mekanisme baru untuk validasi sisi klien sedang dipertimbangkan untuk .NET 10 pada akhir 2025. Untuk informasi selengkapnya, lihat Membuat formulir yang dirender server dengan validasi klien menggunakan Blazor tanpa sirkuit (dotnet/aspnetcore #51040).

Sumber Daya Tambahan:

• unggahan file ASP.NET Core Blazor
• Blazorsampel repositori GitHub () (dotnet/blazor-samplescara mengunduh)
• ASP.NET repositori Core GitHub (dotnet/aspnetcore) membentuk aset pengujian