ASP.NET Componentes de entrada principais Blazor

Este artigo descreve os componentes de entrada internos do Blazor.

Componentes de entrada

A Blazor estrutura fornece componentes de entrada internos para receber e validar a entrada do usuário. Os componentes de entrada embutidos na tabela a seguir são suportados em EditForm com EditContext.

Os componentes na tabela também são suportados fora de um formulário em marcação de componente Razor. As entradas são validadas quando são alteradas e quando um formulário é enviado.

Componente de entrada	Renderizado como...
InputCheckbox	<input type="checkbox">
InputDate<TValue>	<input type="date">
InputFile	<input type="file">
InputNumber<TValue>	<input type="number">
InputRadio<TValue>	<input type="radio">
InputRadioGroup<TValue>	Grupo de crianças InputRadio<TValue>
InputSelect<TValue>	<select>
InputText	<input>
InputTextArea	<textarea>

Para obter mais informações sobre o componente InputFile, consulte carregamentos de ficheiros no ASP.NET CoreBlazor.

Todos os componentes de entrada, incluindo EditForm, suportam atributos arbitrários. Qualquer atributo que não corresponda a um parâmetro de componente é adicionado ao elemento HTML renderizado.

Os componentes de entrada fornecem um comportamento padrão para validar quando um campo é alterado:

• Para componentes de entrada em um formulário com um EditContext, o comportamento de validação padrão inclui a atualização da classe CSS do campo para refletir o estado do campo como válido ou inválido com o estilo de validação do elemento HTML subjacente.
• Para controles que não têm um EditContext, a validação padrão reflete o estado válido ou inválido, mas não fornece estilo de validação para o elemento HTML subjacente.

Alguns componentes incluem lógica de análise útil. Por exemplo, InputDate<TValue> e InputNumber<TValue> lidam de forma eficiente com valores não analisáveis registando-os como erros de validação. Os tipos que podem aceitar valores nulos também oferecem suporte à anulabilidade do campo de destino (por exemplo, int? para um inteiro anulável).

O InputNumber<TValue> componente suporta o atributo type="range", que cria um campo de intervalo que suporta vinculação de modelo e validação de formulário, normalmente renderizado como um controlo deslizante ou dial em vez de uma caixa de texto.

<InputNumber @bind-Value="..." max="..." min="..." step="..." type="range" />

Para obter mais informações sobre o componente InputFile, consulte carregamentos de ficheiros no ASP.NET CoreBlazor.

Formulário de exemplo

O tipo Starship a seguir, que é usado em vários exemplos deste artigo e em exemplos de outros artigos do nó Forms, define um conjunto diversificado de propriedades com anotações de dados:

• Id é necessário porque está anotado com o RequiredAttribute. Id requer um valor de pelo menos um caractere, mas não mais de 16 caracteres usando o StringLengthAttribute.
• Description é opcional porque não está anotado com o RequiredAttribute.
• Classification é obrigatório.
• O MaximumAccommodation padrão da propriedade é zero, mas requer um valor de um a 100.000 conforme o seu RangeAttribute.
• IsValidatedDesign requer que a propriedade tenha um true valor, que corresponda a um estado selecionado quando a propriedade está vinculada a uma caixa de seleção na interface do usuário (<input type="checkbox">).
• ProductionDate é um DateTime e obrigatório.

Starship.cs:

using System.ComponentModel.DataAnnotations;

namespace BlazorSample;

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

    public string? Description { get; set; }

    [Required]
    public string? Classification { get; set; }

    [Range(1, 100000, ErrorMessage = "Accommodation invalid (1-100000).")]
    public int MaximumAccommodation { get; set; }

    [Required]
    [Range(typeof(bool), "true", "true", ErrorMessage = "Approval required.")]
    public bool IsValidatedDesign { get; set; }

    [Required]
    public DateTime ProductionDate { get; set; }
}

O formulário a seguir aceita e valida a entrada do usuário usando:

• As propriedades e validação definidas no modelo anterior Starship .
• Vários dos componentes de entrada integrados de Blazor.

Quando a propriedade do modelo para a classificação do navio (Classification) é definida, a opção correspondente ao modelo é marcada. Por exemplo, checked="@(Model!.Classification == "Exploration")" para a classificação de um navio de exploração. A razão para definir explicitamente a opção marcada é que o valor de um <select> elemento só está presente no navegador. Se o formulário for renderizado no servidor depois de enviado, qualquer estado do cliente será substituído pelo estado do servidor, que normalmente não marca uma opção como marcada. Ao definir a opção marcada da propriedade do modelo, a classificação sempre reflete o estado do modelo. Isto preserva a seleção de classificação nas submissões de formulários que levam à rerenderização do formulário no servidor. Em situações em que o formulário não é reprocessado no servidor, como quando o modo de renderização do Servidor Interativo é aplicado diretamente ao componente, a atribuição explícita da opção marcada do modelo não é necessária porque Blazor preserva o estado do <select> elemento no cliente.

Starship3.razor:

@page "/starship-3"
@inject ILogger<Starship3> Logger

<h1>Starfleet Starship Database</h1>

<h2>New Ship Entry Form</h2>

<EditForm Model="Model" OnValidSubmit="Submit" FormName="Starship3">
    <DataAnnotationsValidator />
    <ValidationSummary />
    <div>
        <label>
            Identifier: 
            <InputText @bind-Value="Model!.Id" />
        </label>
    </div>
    <div>
        <label>
            Description (optional): 
            <InputTextArea @bind-Value="Model!.Description" />
        </label>
    </div>
    <div>
        <label>
            Primary Classification: 
            <InputSelect @bind-Value="Model!.Classification">
                <option value="">
                    Select classification ...
                </option>
                <option checked="@(Model!.Classification == "Exploration")" 
                    value="Exploration">
                    Exploration
                </option>
                <option checked="@(Model!.Classification == "Diplomacy")" 
                    value="Diplomacy">
                    Diplomacy
                </option>
                <option checked="@(Model!.Classification == "Defense")" 
                    value="Defense">
                    Defense
                </option>
            </InputSelect>
        </label>
    </div>
    <div>
        <label>
            Maximum Accommodation: 
            <InputNumber @bind-Value="Model!.MaximumAccommodation" />
        </label>
    </div>
    <div>
        <label>
            Engineering Approval: 
            <InputCheckbox @bind-Value="Model!.IsValidatedDesign" />
        </label>
    </div>
    <div>
        <label>
            Production Date: 
            <InputDate @bind-Value="Model!.ProductionDate" />
        </label>
    </div>
    <div>
        <button type="submit">Submit</button>
    </div>
</EditForm>

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

    protected override void OnInitialized() =>
        Model ??= new() { ProductionDate = DateTime.UtcNow };

    private void Submit()
    {
        Logger.LogInformation("Id = {Id} Description = {Description} " +
            "Classification = {Classification} MaximumAccommodation = " +
            "{MaximumAccommodation} IsValidatedDesign = " +
            "{IsValidatedDesign} ProductionDate = {ProductionDate}",
            Model?.Id, Model?.Description, Model?.Classification,
            Model?.MaximumAccommodation, Model?.IsValidatedDesign,
            Model?.ProductionDate);
    }
}

O EditForm exemplo anterior cria um EditContext com base na instância atribuída Starship (Model="...") e manipula um formulário válido. O próximo exemplo demonstra como atribuir um EditContext a um formulário e validar quando o formulário é enviado.

No exemplo a seguir:

• Uma versão abreviada do formulário anterior Starfleet Starship Database (Starship3 componente) é usada que só aceita um valor para o Id da nave estelar. As outras Starship propriedades recebem valores padrão válidos quando uma instância do Starship tipo é criada.
• O Submit método é executado quando o Submit botão é selecionado.
• O formulário é validado chamando EditContext.Validate no método Submit.
• O registo em log é realizado dependendo do resultado da validação.

Starship4.razor:

@page "/starship-4"
@inject ILogger<Starship4> Logger

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

@code {
    private EditContext? editContext;

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

    protected override void OnInitialized()
    {
        Model ??=
            new()
                {
                    Id = "NCC-1701",
                    Classification = "Exploration",
                    MaximumAccommodation = 150,
                    IsValidatedDesign = true,
                    ProductionDate = new DateTime(2245, 4, 11)
                };
        editContext = new(Model);
    }

    private void Submit()
    {
        if (editContext != null && editContext.Validate())
        {
            Logger.LogInformation("Submit: Form is valid");
        }
        else
        {
            Logger.LogInformation("Submit: Form is INVALID");
        }
    }
}

Observação

Não EditContext para alterar o depois que ele é atribuído.

Seleção de várias opções com o InputSelect componente

A vinculação suporta a seleção de opções com o componente multiple. O @onchange evento fornece uma matriz das opções selecionadas por meio de argumentos de evento (ChangeEventArgs). O valor deve ser associado a um tipo de matriz, o que faz com que o componente adicione automaticamente o atributo InputSelect<TValue> ao elemento multiple quando o componente é renderizado.

No exemplo a seguir, o usuário deve selecionar pelo menos duas classificações de naves estelares, mas não mais de três classificações.

Starship5.razor:

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

<h1>Bind Multiple <code>InputSelect</code> Example</h1>

<EditForm EditContext="editContext" OnValidSubmit="Submit" FormName="Starship5">
    <DataAnnotationsValidator />
    <ValidationSummary />
    <div>
        <label>
            Select classifications (Minimum: 2, Maximum: 3):
            <InputSelect @bind-Value="Model!.SelectedClassification">
                <option value="@Classification.Exploration">Exploration</option>
                <option value="@Classification.Diplomacy">Diplomacy</option>
                <option value="@Classification.Defense">Defense</option>
                <option value="@Classification.Research">Research</option>
            </InputSelect>
        </label>
    </div>
    <div>
        <button type="submit">Submit</button>
    </div>
</EditForm>

@if (Model?.SelectedClassification?.Length > 0)
{
    <div>@string.Join(", ", Model.SelectedClassification)</div>
}

@code {
    private EditContext? editContext;

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

    protected override void OnInitialized()
    {
        Model = new();
        editContext = new(Model);
    }

    private void Submit() => Logger.LogInformation("Submit: Processing form");

    private class Starship
    {
        [Required]
        [MinLength(2, ErrorMessage = "Select at least two classifications.")]
        [MaxLength(3, ErrorMessage = "Select no more than three classifications.")]
        public Classification[]? SelectedClassification { get; set; } =
            [ Classification.None ];
    }

    private enum Classification { None, Exploration, Diplomacy, Defense, Research }
}

Para obter informações sobre como cadeias de caracteres e null valores vazios são manipulados na vinculação de dados, consulte a seção Opções de vinculação InputSelect a valores de objeto null C# .

Vinculação de opções InputSelect a valores de objetos C# null

Para obter informações sobre como cadeias de caracteres vazias e valores null são manipulados na vinculação de dados, consulte ASP.NET Core vinculação de dadosBlazor.

Suporte para nomes de exibição

Vários componentes internos suportam nomes de exibição com o InputBase<TValue>.DisplayName parâmetro.

Starfleet Starship Database No formulário (Starship3componente) da seção Formulário de exemplo, a data de produção de uma nova nave estelar não especifica um nome para exibição:

<label>
    Production Date:
    <InputDate @bind-Value="Model!.ProductionDate" />
</label>

Se o campo contiver uma data inválida quando o formulário for enviado, a mensagem de erro não exibirá um nome amigável. O nome do campo, "ProductionDate" não tem um espaço entre "Production" e "Date" quando aparece no resumo de validação:

O campo ProductionDate deve ser uma data.

Defina a DisplayName propriedade para um nome amigável com um espaço entre as palavras "Production" e "Date":

<label>
    Production Date:
    <InputDate @bind-Value="Model!.ProductionDate" 
        DisplayName="Production Date" />
</label>

O resumo de validação exibe o nome amigável quando o valor do campo é inválido:

O campo Data de Produção deve ser uma data.

Suporte de modelo de mensagem de erro

InputDate<TValue> e InputNumber<TValue> suporte para modelos de mensagem de erro:

• InputDate<TValue>.ParsingErrorMessage
• InputNumber<TValue>.ParsingErrorMessage

Starfleet Starship Database No formulário (Starship3componente) da seção Formulário de exemplo com um nome de exibição amigável atribuído, o Production Date campo produz uma mensagem de erro usando o seguinte modelo de mensagem de erro padrão:

The {0} field must be a date.

A posição do espaço reservado {0} é onde o valor da propriedade DisplayName aparece quando o erro é exibido ao usuário.

<label>
    Production Date:
    <InputDate @bind-Value="Model!.ProductionDate" 
        DisplayName="Production Date" />
</label>

O campo Data de Produção deve ser uma data.

Atribua um modelo personalizado para ParsingErrorMessage fornecer uma mensagem personalizada:

<label>
    Production Date:
    <InputDate @bind-Value="Model!.ProductionDate" 
        DisplayName="Production Date" 
        ParsingErrorMessage="The {0} field has an incorrect date value." />
</label>

O campo Data de Produção tem um valor de data incorreto.

InputHidden para lidar com campos de entrada ocultos em formulários

O InputHidden componente fornece um campo de entrada oculto para armazenar valores de cadeia de caracteres.

No exemplo a seguir, um campo de entrada oculto é criado para a propriedade do Parameter formulário. Quando o formulário é enviado, o valor do campo oculto é exibido:

<EditForm Model="Parameter" OnValidSubmit="Submit" FormName="InputHidden Example">
    <InputHidden id="hidden" @bind-Value="Parameter" />
    <button type="submit">Submit</button>
</EditForm>

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

@code {
    private bool submitted;

    [SupplyParameterFromForm] 
    public string Parameter { get; set; } = "stranger";

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