Associar controles aos dados em aplicativos Blazor

Concluído

O Blazor permite que você associe controles HTML a propriedades, de modo que a alteração de valores seja exibida automaticamente na interface do usuário.

Vamos supor que você esteja desenvolvendo uma página que coleta informações de clientes sobre suas preferências de pizza. Você quer carregar as informações de um banco de dados e permitir que os clientes façam alterações, como gravar seus recheios preferidos. Quando o usuário fizer uma mudança ou houver uma atualização no banco de dados, você quer que os novos valores sejam exibidos na interface do usuário o mais rápido possível.

Nesta unidade, você aprenderá a usar a associação de dados no Blazor para associar elementos de interface do usuário a valores de dados, propriedades ou expressões.

O que é a associação de dados?

Se você quiser que um elemento HTML exiba um valor, poderá escrever código para alterar a exibição. Você precisará escrever código extra para atualizar a exibição quando o valor for atualizado. No Blazor, você pode usar a associação de dados para conectar um elemento HTML a um campo, propriedade ou expressão. Dessa forma, quando o valor for atualizado, o elemento HTML será atualizado automaticamente. A atualização geralmente ocorre rapidamente após a alteração e você não precisa escrever nenhum código de atualização.

Para associar um controle, você usará a diretiva @bind:

@page "/"

<p>
    Your email address is:
    <input @bind="customerEmail" />
</p>

@code {
    private string customerEmail = "user@contoso.com"
}

Na página anterior, sempre que a variável customerEmail alterar seu valor, o valor <input> será atualizado.

Observação

Controles, como <input>, atualizam a exibição somente quando o componente é renderizado e não quando o valor de um campo é alterado. Como os componentes Blazor são renderizados depois que qualquer código do manipulador de eventos é executado, na prática, as atualizações geralmente são exibidas rapidamente.

Associar elementos a eventos específicos

A diretiva @bind é inteligente e compreende os controles que usa. Por exemplo, quando você associa um valor a uma caixa de texto <input>, ele associa o atributo value. Uma caixa de seleção HTML <input> tem um atributo checked em vez de um atributo value. O atributo @bind usa automaticamente este atributo checked. Por padrão, o controle é associado ao evento DOM onchange. Por exemplo, considere esta página:

@page "/"

<h1>My favorite pizza is: @favPizza</h1>

<p>
    Enter your favorite pizza:
    <input @bind="favPizza" />
</p>

@code {
    private string favPizza { get; set; } = "Margherita"
}

Quando a página é renderizada, o valor padrão Margherita é exibido no elemento <h1> e na caixa de texto. Quando você inserir uma nova pizza preferida na caixa de texto, o elemento <h1> não será alterado até você sair da caixa de texto ou selecionar Enter, pois é nesse momento que o evento DOM onchange dispara.

Geralmente, esse é o comportamento desejado. Mas suponha que você queira que o elemento <h1> seja atualizado assim que você insere qualquer caractere na caixa de texto. Em vez disso, você pode obter esse resultado associando o evento DOM oninput. Para associar a esse evento, você deve usar as diretivas @bind-valuee @bind-value:event:

@page "/"

<h1>My favorite pizza is: @favPizza</h1>

<p>
    Enter your favorite pizza:
    <input @bind-value="favPizza" @bind-value:event="oninput" />
</p>

@code {
    private string favPizza { get; set; } = "Margherita"
}

Nesse caso, o título é alterado assim que você digita qualquer caractere na caixa de texto.

Formatar valores limitados

Se você exibir datas para o usuário, talvez queira usar um formato de dados localizado. Por exemplo, vamos supor que você escreva uma página especificamente para usuários do Reino Unido, que preferem escrever datas usando o dia primeiro. Você pode usar a diretiva @bind:format para especificar uma cadeia de caracteres de formato de data única:

@page "/ukbirthdaypizza"

<h1>Order a pizza for your birthday!</h1>

<p>
    Enter your birth date:
    <input @bind="birthdate" @bind:format="dd-MM-yyyy" />
</p>

@code {
    private DateTime birthdate { get; set; } = new(2000, 1, 1);
}

Observação

No momento da gravação, as cadeias de caracteres de formato só têm suporte com valores de data. Formatos de moeda, formatos de número e outros formatos podem ser adicionados posteriormente. Para verificar as informações mais recentes sobre formatos de associação, confira Formatar cadeias de caracteres na documentação do Blazor.

Como alternativa ao uso da diretiva @bind:format, você pode escrever código em C# para formatar um valor associado. Use os acessadores get e set na definição de membro, como neste exemplo:

@page "/pizzaapproval"
@using System.Globalization

<h1>Pizza: @PizzaName</h1>

<p>Approval rating: @approvalRating</p>

<p>
    <label>
        Set a new approval rating:
        <input @bind="ApprovalRating" />
    </label>
</p>

@code {
    private decimal approvalRating = 1.0;
    private NumberStyles style = NumberStyles.AllowDecimalPoint | NumberStyles.AllowLeadingSign;
    private CultureInfo culture = CultureInfo.CreateSpecificCulture("en-US");
    
    private string ApprovalRating
    {
        get => approvalRating.ToString("0.000", culture);
        set
        {
            if (Decimal.TryParse(value, style, culture, out var number))
            {
                approvalRating = Math.Round(number, 3);
            }
        }
    }
}

Na próxima unidade, você aplicará o que aprendeu.