ASP.NET Core Blazor formlara genel bakış

Bu makalede, içindeki Blazorformların nasıl kullanılacağı açıklanmaktadır.

Giriş bileşenleri ve formları

Çerçeve Blazor formları destekler ve yerleşik giriş bileşenleri sağlar:

• Veri ek açıklamalarını kullanabilen bir nesneye veya modele bağlı
  • öğesini içeren <form> HTML formları
  • EditForm bileşenleri
• Yerleşik giriş bileşenleri

Ad Microsoft.AspNetCore.Components.Forms alanı aşağıdakileri sağlar:

• Form öğelerini, durumunu ve doğrulamasını yönetmeye yönelik sınıflar.
• Yerleşik Input* bileşenlere erişim.

Proje şablonundan Blazor oluşturulan bir proje, ad alanını uygulamanın _Imports.razor dosyasında varsayılan olarak içerir ve bu da ad alanını uygulamanın Razor bileşenleri için kullanılabilir hale getirir.

Standart HTML formları desteklenir. Normal HTML <form> etiketini kullanarak bir form oluşturun ve gönderilen form isteğini işlemek için bir @onsubmit işleyici belirtin.

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

Önceki StarshipPlainForm bileşende:

• Form, öğenin göründüğü yerde <form> işlenir. Form, formu çerçeveye @formname benzersiz olarak tanımlayan Blazor yönerge özniteliğiyle adlandırılır.
• Model, bileşenin @code bloğunda oluşturulur ve bir ortak özellikte (Model ) tutulur. özniteliği, [SupplyParameterFromForm] ilişkili özelliğin değerinin form verilerinden sağlanması gerektiğini gösterir. İstekteki, özelliğin adıyla eşleşen veriler özelliğine bağlıdır.
• Bileşen InputText , dize değerlerini düzenlemeye yönelik bir giriş bileşenidir. @bind-Value yönerge özniteliği model özelliğini bileşenin Value özelliğine InputText bağlarModel.Id.
• Submit yöntemi, geri çağırma için @onsubmit işleyici olarak kaydedilir. İşleyici, form kullanıcı tarafından gönderildiğinde çağrılır.

Önemli

Yönerge özniteliğini @formname her zaman benzersiz bir form adıyla kullanın.

Blazor , yanıtı mevcut DOM'a uygulamak için isteği keserek sayfa gezintisini ve form işlemeyi geliştirir ve işlenen formun mümkün olduğunca çoğunu korur. Geliştirme, sayfayı tam olarak yükleme gereksinimini önler ve bileşen sunucuda işlenmiş olsa da tek sayfalı bir uygulamaya (SPA) benzer şekilde çok daha sorunsuz bir kullanıcı deneyimi sağlar. Daha fazla bilgi için bkz . ASP.NET Temel Blazor yönlendirme ve gezinti.

Akış işleme , düz HTML formları için desteklenir.

Not

.NET başvuru kaynağına yönelik belge bağlantıları genellikle deponun varsayılan dalını yükler ve bu dal .NET'in sonraki sürümü için geçerli geliştirmeyi temsil eder. Belirli bir sürümün etiketini seçmek için Dalları veya etiketleri değiştir açılan listesini kullanın. Daha fazla bilgi için bkz. ASP.NET Core kaynak kodunun sürüm etiketini seçme (dotnet/AspNetCore.Docs #26205).

Yukarıdaki örnek, forma bir AntiforgeryToken bileşen ekleyerek antiforgery desteğini içerir. Antiforgery desteği, bu makalenin Antiforgery desteği bölümünde daha ayrıntılı olarak açıklanmıştır.

Örneğin oninput veya gibi başka bir öğenin DOM olaylarını temel alan bir form göndermek için JavaScript kullanarak formu gönderin (submit (MDN belgeleri)).onblur

Uygulamalarda düz formlar Blazor kullanmak yerine, bir form genellikle çerçevenin EditForm bileşeni kullanılarak 'nin yerleşik form desteğiyle Blazortanımlanır. Aşağıdaki Razor bileşen, bir bileşeni kullanarak EditForm bir web formunu işlemek için tipik öğeleri, bileşenleri ve Razor kodu gösterir.

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

Önceki Starship1 bileşende:

• EditForm Bileşen, öğenin göründüğü yerde <EditForm> işlenir. Form, formu çerçeveye @formname benzersiz olarak tanımlayan Blazor yönerge özniteliğiyle adlandırılır.
• Model, bileşenin @code bloğunda oluşturulur ve bir ortak özellikte (Model ) tutulur. özelliği parametresine EditForm.Model atanır. özniteliği, [SupplyParameterFromForm] ilişkili özelliğin değerinin form verilerinden sağlanması gerektiğini gösterir. İstekteki, özelliğin adıyla eşleşen veriler özelliğine bağlıdır.
• Bileşen InputText , dize değerlerini düzenlemeye yönelik bir giriş bileşenidir . @bind-Value yönerge özniteliği model özelliğini bileşenin Value özelliğine InputText bağlarModel.Id.
• Submit yöntemi, geri çağırma için OnSubmit işleyici olarak kaydedilir. İşleyici, form kullanıcı tarafından gönderildiğinde çağrılır.

Önemli

Yönerge özniteliğini @formname her zaman benzersiz bir form adıyla kullanın.

Blazor , bileşenler için EditForm sayfa gezintisini ve form işlemeyi geliştirir. Daha fazla bilgi için bkz . ASP.NET Temel Blazor yönlendirme ve gezinti.

Akış işleme için desteklenir EditForm.

Not

.NET başvuru kaynağına yönelik belge bağlantıları genellikle deponun varsayılan dalını yükler ve bu dal .NET'in sonraki sürümü için geçerli geliştirmeyi temsil eder. Belirli bir sürümün etiketini seçmek için Dalları veya etiketleri değiştir açılan listesini kullanın. Daha fazla bilgi için bkz. ASP.NET Core kaynak kodunun sürüm etiketini seçme (dotnet/AspNetCore.Docs #26205).

† Özellik bağlama hakkında daha fazla bilgi için bkz . ASP.NET Core Blazor veri bağlama.

Sonraki örnekte, önceki bileşen, bileşeninde Starship2 formu oluşturmak için değiştirilmiştir:

• OnSubmit , form kullanıcı tarafından gönderildiğinde geçerliyse atanan olay işleyicisini işleyen ile OnValidSubmitdeğiştirilir.
• ValidationSummary Form gönderiminde form geçersiz olduğunda doğrulama iletilerini görüntülemek için bir bileşen eklenir.
• Veri ek açıklamaları doğrulayıcı (DataAnnotationsValidator bileşen†), veri ek açıklamalarını kullanarak doğrulama desteği ekler:
  • <input> Düğme seçildiğinde form alanı boş Submit bırakılırsa, doğrulama özetinde (ValidationSummarybileşen‡) ("The Id field is required.") bir hata görüntülenir ve Submitçağrılmaz.
  • <input> Düğme seçildiğinde form alanı on karakterden fazla karakter Submit içeriyorsa, doğrulama özetinde ("Id is too long.") bir hata görüntülenir. Submitçağrılmaz.
  • <input> Düğme seçildiğinde form alanı geçerli bir değer Submit içeriyorsa, Submit çağrılır.

†BirleşenDataAnnotationsValidator, Validator bileşeni bölümünde ele alınmıştır. ValidationSummary‡Bileşen, Doğrulama Özeti ve Doğrulama İletisi bileşenleri bölümünde ele alınmıştır.

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

Form gönderimini işleme

form EditForm gönderimini işlemek için aşağıdaki geri çağırmaları sağlar:

• Geçerli alanları olan bir form gönderildiğinde çalıştırılacak bir olay işleyicisi atamak için kullanın OnValidSubmit .
• Geçersiz alanlara sahip bir form gönderildiğinde çalıştırılacak bir olay işleyicisi atamak için kullanın OnInvalidSubmit .
• Form alanlarının doğrulama durumundan bağımsız olarak çalıştırılacak bir olay işleyicisi atamak için kullanın OnSubmit . Form, olay işleyicisi yönteminde çağrılarak EditContext.Validate doğrulanır. döndürürse Validatetrue, form geçerli olur.

Form veya alanı temizleme

Modeli varsayılan durumuna geri döndürerek formu sıfırlayın; bu durum bir EditFormişaretlemenin içinde veya dışında gerçekleştirilebilir:

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

...

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

Alternatif olarak, açık Razor bir ifade kullanın:

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

Model değerini varsayılan durumuna döndürerek bir alanı sıfırlayın:

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

...

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

Alternatif olarak, açık Razor bir ifade kullanın:

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

Bir olay işleyicisi çağrıldıktan sonra bileşeni yeniden başlatmak için çerçeve tarafından Blazor otomatik olarak çağrıldığından yukarıdaki örneklerde StateHasChanged çağrı StateHasChanged yapmanız gerekmez. Bir form veya alanı temizleyen yöntemleri çağırmak için bir olay işleyicisi kullanılmıyorsa geliştirici kodu bileşeni yeniden oluşturmak için çağırmalıdır StateHasChanged .

Antiforgery desteği

Antiforgery hizmetleri, dosyada Program çağrıldığında AddRazorComponents uygulamalara otomatik olarak eklenirBlazor.

Uygulama, dosyadaki istek işleme işlem hattını Program çağırarak UseAntiforgery Antiforgery Ara Yazılımını kullanır. UseAntiforgery çağrısından sonra çağrılır UseRouting. ve UseEndpointsçağrıları UseRouting varsa, çağrısı UseAntiforgery bunların arasına girmelidir. ve UseAuthorizationçağrılarının UseAntiforgery ardından için bir çağrı UseAuthentication yapılmalıdır.

Bileşen AntiforgeryToken , bir kötü amaçlı yazılımdan koruma belirtecini gizli bir alan olarak işler ve [RequireAntiforgeryToken] özniteliği, kötü amaçlı yazılımdan korumayı etkinleştirir. Bir antiforgery denetimi başarısız olursa, bir 400 - Bad Request yanıt oluşturulur ve form işlenmez.

tabanlı EditFormAntiforgeryToken formlar için bileşen ve [RequireAntiforgeryToken] öznitelik, varsayılan olarak kötü amaçlı yazılımdan koruma sağlamak üzere otomatik olarak eklenir.

HTML <form> öğesini temel alan formlar için, bileşeni forma el ile ekleyin AntiforgeryToken :

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

Uyarı

ya da EditForm HTML <form> öğesini temel alan formlar için, özniteliğine [RequireAntiforgeryToken] geçirilerek required: false sahte koruma devre dışı bırakılabilir. Aşağıdaki örnek, sahteciliği devre dışı bırakır ve genel uygulamalar için önerilmez :

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

Daha fazla bilgi için bkz . ASP.NET Çekirdek Blazor kimlik doğrulaması ve yetkilendirme.

Gelişmiş form işleme

Formlar için parametresiyle EditForm veya HTML formlarının özniteliğiyle Enhance form POST istekleri için gezintiyi geliştirin data-enhance (<form>):

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

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

❌Desteklenmeyen: Gelişmiş form işlemeyi etkinleştirmek için formun atası öğesinde gelişmiş gezinti ayarlayamazsınız.

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

Gelişmiş form gönderileri yalnızca uç noktalarla Blazor çalışır. Gelişmiş formu uç nokta olmayanBlazor bir forma göndermek hatayla sonuçlanır.

Gelişmiş form işlemeyi devre dışı bırakmak için:

• için EditForm, parametresini Enhance form öğesinden kaldırın (veya olarak falseayarlayın: Enhance="false").
• HTML <form>için, form öğesinden özniteliğini kaldırın data-enhance (veya olarak falseayarlayın: data-enhance="false").

Blazor'nin gelişmiş gezintisi ve form teslimi, güncelleştirilmiş içerik sunucu işlemenin parçası değilse DOM'da yapılan dinamik değişiklikleri geri alabilir. Bir öğenin içeriğini korumak için özniteliğini data-permanent kullanın.

Aşağıdaki örnekte, sayfa yüklendiğinde öğenin içeriği <div> bir betik tarafından dinamik olarak güncelleştirilir:

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

Gelişmiş gezinti ve form işlemeyi genel olarak devre dışı bırakmak için bkz . ASP.NET Core Blazor başlatma.

Gelişmiş sayfa güncelleştirmelerini dinlemek için olayı kullanma enhancedload hakkında yönergeler için bkz . ASP.NET Temel Blazor yönlendirme ve gezinti.

Örnekler

Örnekler, form POST istekleri için gelişmiş form işlemeyi benimsemez, ancak tüm örnekler Gelişmiş form işleme bölümündeki yönergeleri izleyerek gelişmiş özellikleri benimseyecek şekilde güncelleştirilebilir.

Formların veri ek açıklamaları doğrulamasıyla nasıl çalıştığını göstermek için örnek bileşenler API'yi System.ComponentModel.DataAnnotations kullanır. Veri ek açıklamalarını kullanan bileşenlerde fazladan bir kod satırından kaçınmak istiyorsanız, ad alanını uygulamanın bileşenlerinde içeri aktarma dosyasıyla (_Imports.razor):

@using System.ComponentModel.DataAnnotations

Form örnekleri, Star Trek evreninin referans yönleridir. Star Trek, CBS Studios ve Paramount'un telif hakkı ©1966-2023'tür.

Ek kaynaklar

• ASP.NET Core Blazor dosyası karşıya yüklemeleri
• Blazorörnekler GitHub deposu () (dotnet/blazor-samplesnasıl indirilir)
• ASP.NET Core GitHub deposu (dotnet/aspnetcore) test varlıklarını oluşturur