Auxiliares de marca em formulários no ASP.NET CoreTag Helpers in forms in ASP.NET Core

De Rick Anderson, N. Taylor Mullen, Dave Paquette e Jerrie PelserBy Rick Anderson, N. Taylor Mullen, Dave Paquette, and Jerrie Pelser

Este documento demonstra como é o trabalho com Formulários e os elementos HTML usados comumente em um Formulário.This document demonstrates working with Forms and the HTML elements commonly used on a Form. O elemento HTML Formulário fornece o mecanismo primário que os aplicativos Web usam para postar dados para o servidor.The HTML Form element provides the primary mechanism web apps use to post back data to the server. A maior parte deste documento descreve os Auxiliares de marca e como eles podem ajudar você a criar formulários HTML robustos de forma produtiva.Most of this document describes Tag Helpers and how they can help you productively create robust HTML forms. É recomendável que você leia Introdução ao auxiliares de marca antes de ler este documento.We recommend you read Introduction to Tag Helpers before you read this document.

Em muitos casos, os Auxiliares HTML fornecem uma abordagem alternativa a um Auxiliar de Marca específico, mas é importante reconhecer que os Auxiliares de Marca não substituem os Auxiliares HTML e que não há um Auxiliar de Marca para cada Auxiliar HTML.In many cases, HTML Helpers provide an alternative approach to a specific Tag Helper, but it's important to recognize that Tag Helpers don't replace HTML Helpers and there's not a Tag Helper for each HTML Helper. Quando existe um Auxiliar HTML alternativo, ele é mencionado.When an HTML Helper alternative exists, it's mentioned.

O Auxiliar de marca de formulárioThe Form Tag Helper

O Auxiliar de marca de formulário:The Form Tag Helper:

  • Gera o valor do atributo HTML <FORM> action para uma ação do controlador MVC ou uma rota nomeadaGenerates the HTML <FORM> action attribute value for a MVC controller action or named route

  • Gera um Token de verificação de solicitação oculto para evitar a falsificação de solicitações entre sites (quando usado com o atributo [ValidateAntiForgeryToken] no método de ação HTTP Post)Generates a hidden Request Verification Token to prevent cross-site request forgery (when used with the [ValidateAntiForgeryToken] attribute in the HTTP Post action method)

  • Fornece o atributo asp-route-<Parameter Name>, em que <Parameter Name> é adicionado aos valores de rota.Provides the asp-route-<Parameter Name> attribute, where <Parameter Name> is added to the route values. Os parâmetros routeValues para Html.BeginForm e Html.BeginRouteForm fornecem funcionalidade semelhante.The routeValues parameters to Html.BeginForm and Html.BeginRouteForm provide similar functionality.

  • Tem uma alternativa de Auxiliar HTML Html.BeginForm e Html.BeginRouteFormHas an HTML Helper alternative Html.BeginForm and Html.BeginRouteForm

Exemplo:Sample:

<form asp-controller="Demo" asp-action="Register" method="post">
    <!-- Input and Submit elements -->
</form>

O Auxiliar de marca de formulário acima gera o HTML a seguir:The Form Tag Helper above generates the following HTML:

<form method="post" action="/Demo/Register">
    <!-- Input and Submit elements -->
    <input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</form>

O runtime do MVC gera o valor do atributo action dos atributos asp-controller e asp-action do Auxiliar de marca de formulário.The MVC runtime generates the action attribute value from the Form Tag Helper attributes asp-controller and asp-action. O Auxiliar de marca de formulário também gera um Token de verificação de solicitação oculto para evitar a falsificação de solicitações entre sites (quando usado com o atributo [ValidateAntiForgeryToken] no método de ação HTTP Post).The Form Tag Helper also generates a hidden Request Verification Token to prevent cross-site request forgery (when used with the [ValidateAntiForgeryToken] attribute in the HTTP Post action method). É difícil proteger um Formulário HTML puro contra falsificação de solicitações entre sites e o Auxiliar de marca de formulário fornece este serviço para você.Protecting a pure HTML Form from cross-site request forgery is difficult, the Form Tag Helper provides this service for you.

Usando uma rota nomeadaUsing a named route

O atributo do Auxiliar de Marca asp-route também pode gerar a marcação para o atributo HTML action.The asp-route Tag Helper attribute can also generate markup for the HTML action attribute. Um aplicativo com uma rota chamada register poderia usar a seguinte marcação para a página de registro:An app with a route named register could use the following markup for the registration page:

<form asp-route="register" method="post">
    <!-- Input and Submit elements -->
</form>

Muitas das exibições na pasta Modos de Exibição/Conta (gerada quando você cria um novo aplicativo Web com Contas de usuário individuais) contêm o atributo asp-route-returnurl:Many of the views in the Views/Account folder (generated when you create a new web app with Individual User Accounts) contain the asp-route-returnurl attribute:

<form asp-controller="Account" asp-action="Login"
     asp-route-returnurl="@ViewData["ReturnUrl"]"
     method="post" class="form-horizontal" role="form">

Observação

Com os modelos internos, returnUrl só é preenchido automaticamente quando você tenta acessar um recurso autorizado, mas não está autenticado ou autorizado.With the built in templates, returnUrl is only populated automatically when you try to access an authorized resource but are not authenticated or authorized. Quando você tenta fazer um acesso não autorizado, o middleware de segurança o redireciona para a página de logon com o returnUrl definido.When you attempt an unauthorized access, the security middleware redirects you to the login page with the returnUrl set.

Auxiliar de Marcação de Ação de FormulárioThe Form Action Tag Helper

O Auxiliar de Marcação de Ação de Formulário gera o atributo formaction na marcação <button ...> ou <input type="image" ...> gerada.The Form Action Tag Helper generates the formaction attribute on the generated <button ...> or <input type="image" ...> tag. O atributo formaction controla onde um formulário envia seus dados.The formaction attribute controls where a form submits its data. Ele se associa à <entrada > elementos do tipo image e elementos <botão >.It binds to <input> elements of type image and <button> elements. O Auxiliar de Marcação de Ação de Formulário permite o uso de vários atributos AnchorTagHelper asp- para controlar qual link formaction será gerado para o elemento correspondente.The Form Action Tag Helper enables the usage of several AnchorTagHelper asp- attributes to control what formaction link is generated for the corresponding element.

Atributos AnchorTagHelper com suporte para controlar o valor de formaction:Supported AnchorTagHelper attributes to control the value of formaction:

AtributoAttribute DescriçãoDescription
asp-controllerasp-controller O nome do controlador.The name of the controller.
asp-actionasp-action O nome do método de ação.The name of the action method.
asp-areaasp-area O nome da área.The name of the area.
asp-pageasp-page O nome da Página do Razor.The name of the Razor page.
asp-page-handlerasp-page-handler O nome do manipulador da Página do Razor.The name of the Razor page handler.
asp-routeasp-route O nome da rota.The name of the route.
asp-route-{value}asp-route-{value} Um único valor de rota de URL.A single URL route value. Por exemplo, asp-route-id="1234".For example, asp-route-id="1234".
asp-all-route-dataasp-all-route-data Todos os valores de rota.All route values.
asp-fragmentasp-fragment O fragmento de URL.The URL fragment.

Exemplo de Enviar ao controladorSubmit to controller example

A marcação a seguir envia o formulário à ação Index de HomeController quando a entrada ou botão são escolhidos:The following markup submits the form to the Index action of HomeController when the input or button are selected:

<form method="post">
    <button asp-controller="Home" asp-action="Index">Click Me</button>
    <input type="image" src="..." alt="Or Click Me" asp-controller="Home" 
                                asp-action="Index">
</form>

A marcação anterior gera o seguinte HTML:The previous markup generates following HTML:

<form method="post">
    <button formaction="/Home">Click Me</button>
    <input type="image" src="..." alt="Or Click Me" formaction="/Home">
</form>

Exemplo de Enviar a uma páginaSubmit to page example

A marcação a seguir envia o formulário à Página do Razor About:The following markup submits the form to the About Razor Page:

<form method="post">
    <button asp-page="About">Click Me</button>
    <input type="image" src="..." alt="Or Click Me" asp-page="About">
</form>

A marcação anterior gera o seguinte HTML:The previous markup generates following HTML:

<form method="post">
    <button formaction="/About">Click Me</button>
    <input type="image" src="..." alt="Or Click Me" formaction="/About">
</form>

Exemplo de Enviar a uma rotaSubmit to route example

Considere o ponto de extremidade /Home/Test:Consider the /Home/Test endpoint:

public class HomeController : Controller
{
    [Route("/Home/Test", Name = "Custom")]
    public string Test()
    {
        return "This is the test page";
    }
}

A marcação a seguir envia o formulário ao ponto de extremidade /Home/Test.The following markup submits the form to the /Home/Test endpoint.

<form method="post">
    <button asp-route="Custom">Click Me</button>
    <input type="image" src="..." alt="Or Click Me" asp-route="Custom">
</form>

A marcação anterior gera o seguinte HTML:The previous markup generates following HTML:

<form method="post">
    <button formaction="/Home/Test">Click Me</button>
    <input type="image" src="..." alt="Or Click Me" formaction="/Home/Test">
</form>

O auxiliar de marca de entradaThe Input Tag Helper

O Auxiliar de marca de entrada associa um elemento HTML <input> a uma expressão de modelo em sua exibição do Razor.The Input Tag Helper binds an HTML <input> element to a model expression in your razor view.

Sintaxe:Syntax:

<input asp-for="<Expression Name>">

O auxiliar de marca de entrada:The Input Tag Helper:

  • Gera os atributos HTML id e name para o nome da expressão especificada no atributo asp-for.Generates the id and name HTML attributes for the expression name specified in the asp-for attribute. asp-for="Property1.Property2" equivale a m => m.Property1.Property2.asp-for="Property1.Property2" is equivalent to m => m.Property1.Property2. O nome da expressão é o que é usado para o valor do atributo asp-for.The name of the expression is what is used for the asp-for attribute value. Consulte a seção Nomes de expressão para obter informações adicionais.See the Expression names section for additional information.

  • Define o valor do atributo HTML type com base nos atributos de tipo de modelo e anotação de dados aplicados à propriedade de modeloSets the HTML type attribute value based on the model type and data annotation attributes applied to the model property

  • O valor do atributo HTML type não será substituído quando um for especificadoWon't overwrite the HTML type attribute value when one is specified

  • Gera atributos de validação HTML5 de atributos de anotação de dados aplicados a propriedades de modeloGenerates HTML5 validation attributes from data annotation attributes applied to model properties

  • Tem uma sobreposição de recursos de Auxiliar HTML com Html.TextBoxFor e Html.EditorFor.Has an HTML Helper feature overlap with Html.TextBoxFor and Html.EditorFor. Consulte a seção Alternativas de Auxiliar HTML ao Auxiliar de marca de entrada para obter detalhes.See the HTML Helper alternatives to Input Tag Helper section for details.

  • Fornece tipagem forte.Provides strong typing. Se o nome da propriedade for alterado e você não atualizar o Auxiliar de marca, você verá um erro semelhante ao seguinte:If the name of the property changes and you don't update the Tag Helper you'll get an error similar to the following:

An error occurred during the compilation of a resource required to process
this request. Please review the following specific error details and modify
your source code appropriately.

Type expected
 'RegisterViewModel' does not contain a definition for 'Email' and no
 extension method 'Email' accepting a first argument of type 'RegisterViewModel'
 could be found (are you missing a using directive or an assembly reference?)

O Auxiliar de marca Input define o atributo HTML type com base no tipo .NET.The Input Tag Helper sets the HTML type attribute based on the .NET type. A tabela a seguir lista alguns tipos .NET comuns e o tipo HTML gerado (não estão listados todos os tipos .NET).The following table lists some common .NET types and generated HTML type (not every .NET type is listed).

Tipo .NET.NET type Tipo de entradaInput Type
BoolBool type="checkbox"type="checkbox"
Cadeia de CaracteresString type="text"type="text"
DateTimeDateTime type="datetime-local"type="datetime-local"
ByteByte type="number"type="number"
IntInt type="number"type="number"
Single e DoubleSingle, Double type="number"type="number"

A tabela a seguir mostra alguns atributos de anotações de dados comuns que o auxiliar de marca de entrada mapeará para tipos de entrada específicos (não são listados todos os atributos de validação):The following table shows some common data annotations attributes that the input tag helper will map to specific input types (not every validation attribute is listed):

AtributoAttribute Tipo de entradaInput Type
[EmailAddress][EmailAddress] type="email"type="email"
[Url][Url] type="url"type="url"
[HiddenInput][HiddenInput] type="hidden"type="hidden"
[Phone][Phone] type="tel"type="tel"
[DataType(DataType.Password)][DataType(DataType.Password)] type="password"type="password"
[DataType(DataType.Date)][DataType(DataType.Date)] type="date"type="date"
[DataType(DataType.Time)][DataType(DataType.Time)] type="time"type="time"

Exemplo:Sample:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
    public class RegisterViewModel
    {
        [Required]
        [EmailAddress]
        [Display(Name = "Email Address")]
        public string Email { get; set; }

        [Required]
        [DataType(DataType.Password)]
        public string Password { get; set; }
    }
}
@model RegisterViewModel

<form asp-controller="Demo" asp-action="RegisterInput" method="post">
    Email:  <input asp-for="Email" /> <br />
    Password: <input asp-for="Password" /><br />
    <button type="submit">Register</button>
</form>

O código acima gera o seguinte HTML:The code above generates the following HTML:

  <form method="post" action="/Demo/RegisterInput">
      Email:
      <input type="email" data-val="true"
             data-val-email="The Email Address field is not a valid email address."
             data-val-required="The Email Address field is required."
             id="Email" name="Email" value=""><br>
      Password:
      <input type="password" data-val="true"
             data-val-required="The Password field is required."
             id="Password" name="Password"><br>
      <button type="submit">Register</button>
      <input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
   </form>

As anotações de dados aplicadas às propriedades Email e Password geram metadados no modelo.The data annotations applied to the Email and Password properties generate metadata on the model. O Auxiliar de marca de entrada consome os metadados do modelo e produz atributos HTML5 data-val-* (consulte Validação de modelo).The Input Tag Helper consumes the model metadata and produces HTML5 data-val-* attributes (see Model Validation). Esses atributos descrevem os validadores a serem anexados aos campos de entrada.These attributes describe the validators to attach to the input fields. Isso fornece validação de jQuery e HTML5 discreto.This provides unobtrusive HTML5 and jQuery validation. Os atributos discretos têm o formato data-val-rule="Error Message", em que Rule é o nome da regra de validação (como data-val-required, data-val-email, data-val-maxlength, etc.) Se uma mensagem de erro for fornecida no atributo, ela será exibida como o valor para o atributo data-val-rule.The unobtrusive attributes have the format data-val-rule="Error Message", where rule is the name of the validation rule (such as data-val-required, data-val-email, data-val-maxlength, etc.) If an error message is provided in the attribute, it's displayed as the value for the data-val-rule attribute. Também há atributos do formulário data-val-ruleName-argumentName="argumentValue" que fornecem detalhes adicionais sobre a regra, por exemplo, data-val-maxlength-max="1024".There are also attributes of the form data-val-ruleName-argumentName="argumentValue" that provide additional details about the rule, for example, data-val-maxlength-max="1024" .

Alternativas de Auxiliar HTML ao Auxiliar de marca de entradaHTML Helper alternatives to Input Tag Helper

Html.TextBox, Html.TextBoxFor, Html.Editor e Html.EditorFor têm recursos que se sobrepõem aos di Auxiliar de marca de entrada.Html.TextBox, Html.TextBoxFor, Html.Editor and Html.EditorFor have overlapping features with the Input Tag Helper. O Auxiliar de marca de entrada define automaticamente o atributo type; Html.TextBox e Html.TextBoxFor não o fazem.The Input Tag Helper will automatically set the type attribute; Html.TextBox and Html.TextBoxFor won't. Html.Editor e Html.EditorFor manipulam coleções, objetos complexos e modelos; o Auxiliar de marca de entrada não o faz.Html.Editor and Html.EditorFor handle collections, complex objects and templates; the Input Tag Helper doesn't. O Auxiliar de marca de entrada, Html.EditorFor e Html.TextBoxFor são fortemente tipados (eles usam expressões lambda); Html.TextBox e Html.Editor não usam (eles usam nomes de expressão).The Input Tag Helper, Html.EditorFor and Html.TextBoxFor are strongly typed (they use lambda expressions); Html.TextBox and Html.Editor are not (they use expression names).

HtmlAttributesHtmlAttributes

@Html.Editor() e @Html.EditorFor() usam uma entrada ViewDataDictionary especial chamada htmlAttributes ao executar seus modelos padrão.@Html.Editor() and @Html.EditorFor() use a special ViewDataDictionary entry named htmlAttributes when executing their default templates. Esse comportamento pode ser aumentado usando parâmetros additionalViewData.This behavior is optionally augmented using additionalViewData parameters. A chave "htmlAttributes" diferencia maiúsculas de minúsculas.The key "htmlAttributes" is case-insensitive. A chave "htmlAttributes" é tratada de forma semelhante ao objeto htmlAttributes passado para auxiliares de entrada como @Html.TextBox().The key "htmlAttributes" is handled similarly to the htmlAttributes object passed to input helpers like @Html.TextBox().

@Html.EditorFor(model => model.YourProperty, 
  new { htmlAttributes = new { @class="myCssClass", style="Width:100px" } })

Nomes de expressãoExpression names

O valor do atributo asp-for é um ModelExpression e o lado direito de uma expressão lambda.The asp-for attribute value is a ModelExpression and the right hand side of a lambda expression. Portanto, asp-for="Property1" se torna m => m.Property1 no código gerado e é por isso você não precisa colocar o prefixo Model.Therefore, asp-for="Property1" becomes m => m.Property1 in the generated code which is why you don't need to prefix with Model. Você pode usar o caractere "@" para iniciar uma expressão embutida e mover para antes de m.:You can use the "@" character to start an inline expression and move before the m.:

@{
       var joe = "Joe";
   }
   <input asp-for="@joe">

Gera o seguinte:Generates the following:

<input type="text" id="joe" name="joe" value="Joe">

Com propriedades de coleção, asp-for="CollectionProperty[23].Member" gera o mesmo nome que asp-for="CollectionProperty[i].Member" quando i tem o valor 23.With collection properties, asp-for="CollectionProperty[23].Member" generates the same name as asp-for="CollectionProperty[i].Member" when i has the value 23.

Quando o ASP.NET Core MVC calcula o valor de ModelExpression, ele inspeciona várias fontes, inclusive o ModelState.When ASP.NET Core MVC calculates the value of ModelExpression, it inspects several sources, including ModelState. Considere o <input type="text" asp-for="@Name">.Consider <input type="text" asp-for="@Name">. O atributo value calculado é o primeiro valor não nulo:The calculated value attribute is the first non-null value from:

  • Da entrada de ModelState com a chave "Name".ModelState entry with key "Name".
  • Do resultado da expressão Model.Name.Result of the expression Model.Name.

Você também pode navegar para propriedades filho usando o caminho da propriedade do modelo de exibição.You can also navigate to child properties using the property path of the view model. Considere uma classe de modelo mais complexa que contém uma propriedade Address filho.Consider a more complex model class that contains a child Address property.

public class AddressViewModel
{
    public string AddressLine1 { get; set; }
}
public class RegisterAddressViewModel
{
    public string Email { get; set; }

    [DataType(DataType.Password)]
    public string Password { get; set; }

    public AddressViewModel Address { get; set; }
}

Na exibição, associamos a Address.AddressLine1:In the view, we bind to Address.AddressLine1:

@model RegisterAddressViewModel

<form asp-controller="Demo" asp-action="RegisterAddress" method="post">
    Email:  <input asp-for="Email" /> <br />
    Password: <input asp-for="Password" /><br />
    Address: <input asp-for="Address.AddressLine1" /><br />
    <button type="submit">Register</button>
</form>

O HTML a seguir é gerado para Address.AddressLine1:The following HTML is generated for Address.AddressLine1:

<input type="text" id="Address_AddressLine1" name="Address.AddressLine1" value="">

Nomes de expressão e coleçõesExpression names and Collections

Exemplo, um modelo que contém uma matriz de Colors:Sample, a model containing an array of Colors:

public class Person
{
    public List<string> Colors { get; set; }

    public int Age { get; set; }
}

O método de ação:The action method:

public IActionResult Edit(int id, int colorIndex)
   {
       ViewData["Index"] = colorIndex;
       return View(GetPerson(id));
   }

O Razor a seguir mostra como você acessa um elemento Color específico:The following Razor shows how you access a specific Color element:

@model Person
@{
    var index = (int)ViewData["index"];
}

<form asp-controller="ToDo" asp-action="Edit" method="post">
    @Html.EditorFor(m => m.Colors[index])
    <label asp-for="Age"></label>
    <input asp-for="Age" /><br />
    <button type="submit">Post</button>
</form>

O modelo Views/Shared/EditorTemplates/String.cshtml:The Views/Shared/EditorTemplates/String.cshtml template:

@model string

<label asp-for="@Model"></label>
<input asp-for="@Model" /> <br />

Exemplo usando List<T>:Sample using List<T>:

public class ToDoItem
{
    public string Name { get; set; }

    public bool IsDone { get; set; }
}

O Razor a seguir mostra como iterar em uma coleção:The following Razor shows how to iterate over a collection:

@model List<ToDoItem>

<form asp-controller="ToDo" asp-action="Edit" method="post">
    <table>
        <tr> <th>Name</th> <th>Is Done</th> </tr>

        @for (int i = 0; i < Model.Count; i++)
        {
            <tr>
                @Html.EditorFor(model => model[i])
            </tr>
        }

    </table>
    <button type="submit">Save</button>
</form>

O modelo Views/Shared/EditorTemplates/ToDoItem.cshtml:The Views/Shared/EditorTemplates/ToDoItem.cshtml template:

@model ToDoItem

<td>
    <label asp-for="@Model.Name"></label>
    @Html.DisplayFor(model => model.Name)
</td>
<td>
    <input asp-for="@Model.IsDone" />
</td>

@*
    This template replaces the following Razor which evaluates the indexer three times.
    <td>
         <label asp-for="@Model[i].Name"></label>
         @Html.DisplayFor(model => model[i].Name)
     </td>
     <td>
         <input asp-for="@Model[i].IsDone" />
     </td>
*@

foreach deve ser usado, se possível, quando o valor está prestes a ser usado em um contexto equivalente asp-for ou Html.DisplayFor.foreach should be used if possible when the value is going to be used in an asp-for or Html.DisplayFor equivalent context. Em geral, for é melhor do que foreach (se o cenário permitir) porque não é necessário alocar um enumerador; no entanto, avaliar um indexador em uma expressão LINQ pode ser caro, o que deve ser minimizado.In general, for is better than foreach (if the scenario allows it) because it doesn't need to allocate an enumerator; however, evaluating an indexer in a LINQ expression can be expensive and should be minimized.

 

Observação

O código de exemplo comentado acima mostra como você substituiria a expressão lambda pelo operador @ para acessar cada ToDoItem na lista.The commented sample code above shows how you would replace the lambda expression with the @ operator to access each ToDoItem in the list.

Auxiliar de marca de área de textoThe Textarea Tag Helper

O auxiliar de marca Textarea Tag Helper é semelhante ao Auxiliar de marca de entrada.The Textarea Tag Helper tag helper is similar to the Input Tag Helper.

  • Gera os atributos id e name, bem como os atributos de validação de dados do modelo para um elemento <textarea>.Generates the id and name attributes, and the data validation attributes from the model for a <textarea> element.

  • Fornece tipagem forte.Provides strong typing.

  • Alternativa de Auxiliar HTML: Html.TextAreaForHTML Helper alternative: Html.TextAreaFor

Exemplo:Sample:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
    public class DescriptionViewModel
    {
        [MinLength(5)]
        [MaxLength(1024)]
        public string Description { get; set; }
    }
}
@model DescriptionViewModel

<form asp-controller="Demo" asp-action="RegisterTextArea" method="post">
    <textarea asp-for="Description"></textarea>
    <button type="submit">Test</button>
</form>

O HTML a seguir é gerado:The following HTML is generated:

<form method="post" action="/Demo/RegisterTextArea">
  <textarea data-val="true"
   data-val-maxlength="The field Description must be a string or array type with a maximum length of &#x27;1024&#x27;."
   data-val-maxlength-max="1024"
   data-val-minlength="The field Description must be a string or array type with a minimum length of &#x27;5&#x27;."
   data-val-minlength-min="5"
   id="Description" name="Description">
  </textarea>
  <button type="submit">Test</button>
  <input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</form>

O auxiliar de marca de rótuloThe Label Tag Helper

  • Gera a legenda do rótulo e o atributo for em um elemento <rótulo> para um nome de expressãoGenerates the label caption and for attribute on a <label> element for an expression name

  • Alternativa de Auxiliar HTML: Html.LabelFor.HTML Helper alternative: Html.LabelFor.

O Label Tag Helper fornece os seguintes benefícios em comparação com um elemento de rótulo HTML puro:The Label Tag Helper provides the following benefits over a pure HTML label element:

  • Você obtém automaticamente o valor do rótulo descritivo do atributo Display.You automatically get the descriptive label value from the Display attribute. O nome de exibição desejado pode mudar com o tempo e a combinação do atributo Display e do Auxiliar de Marca de Rótulo aplicará Display em qualquer lugar em que for usado.The intended display name might change over time, and the combination of Display attribute and Label Tag Helper will apply the Display everywhere it's used.

  • Menos marcação no código-fonteLess markup in source code

  • Tipagem forte com a propriedade de modelo.Strong typing with the model property.

Exemplo:Sample:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
    public class SimpleViewModel
    {
        [Required]
        [EmailAddress]
        [Display(Name = "Email Address")]
        public string Email { get; set; }
    }
}

@model SimpleViewModel

<form asp-controller="Demo" asp-action="RegisterLabel" method="post">
    <label asp-for="Email"></label>
    <input asp-for="Email" /> <br />
</form>

O HTML a seguir é gerado para o elemento <label>:The following HTML is generated for the <label> element:

<label for="Email">Email Address</label>

O Auxiliar de marca de rótulo gerou o valor do atributo for de "Email", que é a ID associada ao elemento <input>.The Label Tag Helper generated the for attribute value of "Email", which is the ID associated with the <input> element. Auxiliares de marca geram elementos id e for consistentes para que eles possam ser associados corretamente.The Tag Helpers generate consistent id and for elements so they can be correctly associated. A legenda neste exemplo é proveniente do atributo Display.The caption in this sample comes from the Display attribute. Se o modelo não contivesse um atributo Display, a legenda seria o nome da propriedade da expressão.If the model didn't contain a Display attribute, the caption would be the property name of the expression.

Os auxiliares de marca de validaçãoThe Validation Tag Helpers

Há dois auxiliares de marca de validação.There are two Validation Tag Helpers. O Validation Message Tag Helper (que exibe uma mensagem de validação para uma única propriedade em seu modelo) e o Validation Summary Tag Helper (que exibe um resumo dos erros de validação).The Validation Message Tag Helper (which displays a validation message for a single property on your model), and the Validation Summary Tag Helper (which displays a summary of validation errors). O Input Tag Helper adiciona atributos de validação do lado do cliente HTML5 para elementos de entrada baseados em atributos de anotação de dados em suas classes de modelo.The Input Tag Helper adds HTML5 client side validation attributes to input elements based on data annotation attributes on your model classes. A validação também é executada no servidor.Validation is also performed on the server. O Auxiliar de marca de validação exibe essas mensagens de erro quando ocorre um erro de validação.The Validation Tag Helper displays these error messages when a validation error occurs.

O Auxiliar de marca de mensagem de validaçãoThe Validation Message Tag Helper

  • Adiciona o atributo data-valmsg-for="property" HTML5 ao elemento span, que anexa as mensagens de erro de validação no campo de entrada da propriedade do modelo especificado.Adds the HTML5 data-valmsg-for="property" attribute to the span element, which attaches the validation error messages on the input field of the specified model property. Quando ocorre um erro de validação do lado do cliente, jQuery exibe a mensagem de erro no elemento <span>.When a client side validation error occurs, jQuery displays the error message in the <span> element.

  • A validação também é feita no servidor.Validation also takes place on the server. Os clientes poderão ter o JavaScript desabilitado e parte da validação só pode ser feita no lado do servidor.Clients may have JavaScript disabled and some validation can only be done on the server side.

  • Alternativa de Auxiliar HTML: Html.ValidationMessageForHTML Helper alternative: Html.ValidationMessageFor

O Validation Message Tag Helper é usado com o atributo asp-validation-for em um elemento HTML span.The Validation Message Tag Helper is used with the asp-validation-for attribute on a HTML span element.

<span asp-validation-for="Email"></span>

O Auxiliar de marca de mensagem de validação gerará o HTML a seguir:The Validation Message Tag Helper will generate the following HTML:

<span class="field-validation-valid"
  data-valmsg-for="Email"
  data-valmsg-replace="true"></span>

Geralmente, você usa o Validation Message Tag Helper após um Auxiliar de marca Input para a mesma propriedade.You generally use the Validation Message Tag Helper after an Input Tag Helper for the same property. Fazer isso exibe as mensagens de erro de validação próximo à entrada que causou o erro.Doing so displays any validation error messages near the input that caused the error.

Observação

É necessário ter uma exibição com as referências de script jQuery e JavaScript corretas em vigor para a validação do lado do cliente.You must have a view with the correct JavaScript and jQuery script references in place for client side validation. Consulte Validação de Modelo para obter mais informações.See Model Validation for more information.

Quando ocorre um erro de validação do lado do servidor (por exemplo, quando você tem validação do lado do servidor personalizada ou a validação do lado do cliente está desabilitada), o MVC coloca essa mensagem de erro como o corpo do elemento <span>.When a server side validation error occurs (for example when you have custom server side validation or client-side validation is disabled), MVC places that error message as the body of the <span> element.

<span class="field-validation-error" data-valmsg-for="Email"
            data-valmsg-replace="true">
   The Email Address field is required.
</span>

Auxiliar de marca de resumo de validaçãoThe Validation Summary Tag Helper

  • Tem como alvo elementos <div> com o atributo asp-validation-summaryTargets <div> elements with the asp-validation-summary attribute

  • Alternativa de Auxiliar HTML: @Html.ValidationSummaryHTML Helper alternative: @Html.ValidationSummary

O Validation Summary Tag Helper é usado para exibir um resumo das mensagens de validação.The Validation Summary Tag Helper is used to display a summary of validation messages. O valor do atributo asp-validation-summary pode ser qualquer um dos seguintes:The asp-validation-summary attribute value can be any of the following:

asp-validation-summaryasp-validation-summary Mensagens de validação exibidasValidation messages displayed
ValidationSummary.AllValidationSummary.All Nível da propriedade e do modeloProperty and model level
ValidationSummary.ModelOnlyValidationSummary.ModelOnly ModeloModel
ValidationSummary.NoneValidationSummary.None {1>Nenhum<1}None

AmostraSample

No exemplo a seguir, o modelo de dados tem atributos DataAnnotation, que geram mensagens de erro de validação no elemento <input>.In the following example, the data model has DataAnnotation attributes, which generates validation error messages on the <input> element. Quando ocorre um erro de validação, o Auxiliar de marca de validação exibe a mensagem de erro:When a validation error occurs, the Validation Tag Helper displays the error message:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
    public class RegisterViewModel
    {
        [Required]
        [EmailAddress]
        [Display(Name = "Email Address")]
        public string Email { get; set; }

        [Required]
        [DataType(DataType.Password)]
        public string Password { get; set; }
    }
}
@model RegisterViewModel

<form asp-controller="Demo" asp-action="RegisterValidation" method="post">
    <div asp-validation-summary="ModelOnly"></div>
    Email:  <input asp-for="Email" /> <br />
    <span asp-validation-for="Email"></span><br />
    Password: <input asp-for="Password" /><br />
    <span asp-validation-for="Password"></span><br />
    <button type="submit">Register</button>
</form>

O código HTML gerado (quando o modelo é válido):The generated HTML (when the model is valid):

<form action="/DemoReg/Register" method="post">
  <div class="validation-summary-valid" data-valmsg-summary="true">
  <ul><li style="display:none"></li></ul></div>
  Email:  <input name="Email" id="Email" type="email" value=""
   data-val-required="The Email field is required."
   data-val-email="The Email field is not a valid email address."
   data-val="true"><br>
  <span class="field-validation-valid" data-valmsg-replace="true"
   data-valmsg-for="Email"></span><br>
  Password: <input name="Password" id="Password" type="password"
   data-val-required="The Password field is required." data-val="true"><br>
  <span class="field-validation-valid" data-valmsg-replace="true"
   data-valmsg-for="Password"></span><br>
  <button type="submit">Register</button>
  <input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</form>

Auxiliar de Marca de SeleçãoThe Select Tag Helper

  • Gera select e os elementos option associados para as propriedades do modelo.Generates select and associated option elements for properties of your model.

  • Tem uma alternativa de Auxiliar HTML Html.DropDownListFor e Html.ListBoxForHas an HTML Helper alternative Html.DropDownListFor and Html.ListBoxFor

O Select Tag Helper asp-for especifica o nome da propriedade do modelo para o elemento select e asp-items especifica os elementos option.The Select Tag Helper asp-for specifies the model property name for the select element and asp-items specifies the option elements. Por exemplo:For example:

<select asp-for="Country" asp-items="Model.Countries"></select> 

Exemplo:Sample:

using Microsoft.AspNetCore.Mvc.Rendering;
using System.Collections.Generic;

namespace FormsTagHelper.ViewModels
{
    public class CountryViewModel
    {
        public string Country { get; set; }

        public List<SelectListItem> Countries { get; } = new List<SelectListItem>
        {
            new SelectListItem { Value = "MX", Text = "Mexico" },
            new SelectListItem { Value = "CA", Text = "Canada" },
            new SelectListItem { Value = "US", Text = "USA"  },
        };
    }
}

O método Index inicializa o CountryViewModel, define o país selecionado e o transmite para a exibição Index.The Index method initializes the CountryViewModel, sets the selected country and passes it to the Index view.

public IActionResult Index()
{
    var model = new CountryViewModel();
    model.Country = "CA";
    return View(model);
}

O método Index HTTP POST exibe a seleção:The HTTP POST Index method displays the selection:

[HttpPost]
[ValidateAntiForgeryToken]
public IActionResult Index(CountryViewModel model)
{
    if (ModelState.IsValid)
    {
        var msg = model.Country + " selected";
        return RedirectToAction("IndexSuccess", new { message = msg });
    }

    // If we got this far, something failed; redisplay form.
    return View(model);
}

A exibição Index:The Index view:

@model CountryViewModel

<form asp-controller="Home" asp-action="Index" method="post">
    <select asp-for="Country" asp-items="Model.Countries"></select> 
    <br /><button type="submit">Register</button>
</form>

Que gera o seguinte HTML (com "CA" selecionado):Which generates the following HTML (with "CA" selected):

<form method="post" action="/">
     <select id="Country" name="Country">
       <option value="MX">Mexico</option>
       <option selected="selected" value="CA">Canada</option>
       <option value="US">USA</option>
     </select>
       <br /><button type="submit">Register</button>
     <input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
   </form>

Observação

Não é recomendável usar ViewBag ou ViewData com o Auxiliar de Marca de Seleção.We don't recommend using ViewBag or ViewData with the Select Tag Helper. Um modelo de exibição é mais robusto para fornecer metadados MVC e, geralmente, menos problemático.A view model is more robust at providing MVC metadata and generally less problematic.

O valor do atributo asp-for é um caso especial e não requer um prefixo Model, os outros atributos do Auxiliar de marca requerem (como asp-items)The asp-for attribute value is a special case and doesn't require a Model prefix, the other Tag Helper attributes do (such as asp-items)

<select asp-for="Country" asp-items="Model.Countries"></select> 

Associação de enumeraçãoEnum binding

Geralmente, é conveniente usar <select> com uma propriedade enum e gerar os elementos SelectListItem dos valores enum.It's often convenient to use <select> with an enum property and generate the SelectListItem elements from the enum values.

Exemplo:Sample:

    public class CountryEnumViewModel
    {
        public CountryEnum EnumCountry { get; set; }
    }
}
using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
    public enum CountryEnum
    {
        [Display(Name = "United Mexican States")]
        Mexico,
        [Display(Name = "United States of America")]
        USA,
        Canada,
        France,
        Germany,
        Spain
    }
}

O método GetEnumSelectList gera um objeto SelectList para uma enumeração.The GetEnumSelectList method generates a SelectList object for an enum.

@model CountryEnumViewModel

<form asp-controller="Home" asp-action="IndexEnum" method="post">
    <select asp-for="EnumCountry" 
            asp-items="Html.GetEnumSelectList<CountryEnum>()">
    </select> 
    <br /><button type="submit">Register</button>
</form>

Você pode marcar sua lista de enumeradores com o atributo Display para obter uma interface do usuário mais rica:You can mark your enumerator list with the Display attribute to get a richer UI:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
    public enum CountryEnum
    {
        [Display(Name = "United Mexican States")]
        Mexico,
        [Display(Name = "United States of America")]
        USA,
        Canada,
        France,
        Germany,
        Spain
    }
}

O HTML a seguir é gerado:The following HTML is generated:

  <form method="post" action="/Home/IndexEnum">
         <select data-val="true" data-val-required="The EnumCountry field is required."
                 id="EnumCountry" name="EnumCountry">
             <option value="0">United Mexican States</option>
             <option value="1">United States of America</option>
             <option value="2">Canada</option>
             <option value="3">France</option>
             <option value="4">Germany</option>
             <option selected="selected" value="5">Spain</option>
         </select>
         <br /><button type="submit">Register</button>
         <input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
    </form>

Grupo de opçõesOption Group

O elemento HTML <optgroup> é gerado quando o modelo de exibição contém um ou mais objetos SelectListGroup.The HTML <optgroup> element is generated when the view model contains one or more SelectListGroup objects.

O CountryViewModelGroup agrupa os elementos SelectListItem nos grupos "América do Norte" e "Europa":The CountryViewModelGroup groups the SelectListItem elements into the "North America" and "Europe" groups:

public class CountryViewModelGroup
{
    public CountryViewModelGroup()
    {
        var NorthAmericaGroup = new SelectListGroup { Name = "North America" };
        var EuropeGroup = new SelectListGroup { Name = "Europe" };

        Countries = new List<SelectListItem>
        {
            new SelectListItem
            {
                Value = "MEX",
                Text = "Mexico",
                Group = NorthAmericaGroup
            },
            new SelectListItem
            {
                Value = "CAN",
                Text = "Canada",
                Group = NorthAmericaGroup
            },
            new SelectListItem
            {
                Value = "US",
                Text = "USA",
                Group = NorthAmericaGroup
            },
            new SelectListItem
            {
                Value = "FR",
                Text = "France",
                Group = EuropeGroup
            },
            new SelectListItem
            {
                Value = "ES",
                Text = "Spain",
                Group = EuropeGroup
            },
            new SelectListItem
            {
                Value = "DE",
                Text = "Germany",
                Group = EuropeGroup
            }
      };
    }

    public string Country { get; set; }

    public List<SelectListItem> Countries { get; }

Os dois grupos são mostrados abaixo:The two groups are shown below:

exemplo de grupo de opções

O HTML gerado:The generated HTML:

 <form method="post" action="/Home/IndexGroup">
      <select id="Country" name="Country">
          <optgroup label="North America">
              <option value="MEX">Mexico</option>
              <option value="CAN">Canada</option>
              <option value="US">USA</option>
          </optgroup>
          <optgroup label="Europe">
              <option value="FR">France</option>
              <option value="ES">Spain</option>
              <option value="DE">Germany</option>
          </optgroup>
      </select>
      <br /><button type="submit">Register</button>
      <input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
 </form>

Seleção múltiplaMultiple select

O Auxiliar de Marca de Seleção gerará automaticamente o atributo multiple = "multiple" se a propriedade especificada no atributo asp-for for um IEnumerable.The Select Tag Helper will automatically generate the multiple = "multiple" attribute if the property specified in the asp-for attribute is an IEnumerable. Por exemplo, considerando o seguinte modelo:For example, given the following model:

using Microsoft.AspNetCore.Mvc.Rendering;
using System.Collections.Generic;

namespace FormsTagHelper.ViewModels
{
    public class CountryViewModelIEnumerable
    {
        public IEnumerable<string> CountryCodes { get; set; }

        public List<SelectListItem> Countries { get; } = new List<SelectListItem>
        {
            new SelectListItem { Value = "MX", Text = "Mexico" },
            new SelectListItem { Value = "CA", Text = "Canada" },
            new SelectListItem { Value = "US", Text = "USA"    },
            new SelectListItem { Value = "FR", Text = "France" },
            new SelectListItem { Value = "ES", Text = "Spain"  },
            new SelectListItem { Value = "DE", Text = "Germany"}
         };
    }
}

Com a seguinte exibição:With the following view:

@model CountryViewModelIEnumerable

<form asp-controller="Home" asp-action="IndexMultiSelect" method="post">
    <select asp-for="CountryCodes" asp-items="Model.Countries"></select> 
    <br /><button type="submit">Register</button>
</form>

Gera o seguinte HTML:Generates the following HTML:

<form method="post" action="/Home/IndexMultiSelect">
    <select id="CountryCodes"
    multiple="multiple"
    name="CountryCodes"><option value="MX">Mexico</option>
<option value="CA">Canada</option>
<option value="US">USA</option>
<option value="FR">France</option>
<option value="ES">Spain</option>
<option value="DE">Germany</option>
</select>
    <br /><button type="submit">Register</button>
  <input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</form>

Nenhuma seleçãoNo selection

Se acabar usando a opção "não especificado" em várias páginas, você poderá criar um modelo para eliminar o HTML de repetição:If you find yourself using the "not specified" option in multiple pages, you can create a template to eliminate repeating the HTML:

@model CountryViewModel

<form asp-controller="Home" asp-action="IndexEmpty" method="post">
    @Html.EditorForModel()
    <br /><button type="submit">Register</button>
</form>

O modelo Views/Shared/EditorTemplates/CountryViewModel.cshtml:The Views/Shared/EditorTemplates/CountryViewModel.cshtml template:

@model CountryViewModel

<select asp-for="Country" asp-items="Model.Countries">
    <option value="">--none--</option>
</select>

O acréscimo de elementos HTML <option> não está limitado ao caso de Nenhuma seleção.Adding HTML <option> elements isn't limited to the No selection case. Por exemplo, o seguinte método de ação e exibição gerarão HTML semelhante ao código acima:For example, the following view and action method will generate HTML similar to the code above:

public IActionResult IndexNone()
{
    var model = new CountryViewModel();
    model.Insert(0, new SelectListItem("<none>", ""));
    return View(model);
}
@model CountryViewModel

<form asp-controller="Home" asp-action="IndexEmpty" method="post">
    <select asp-for="Country">
        <option value="">&lt;none&gt;</option>
        <option value="MX">Mexico</option>
        <option value="CA">Canada</option>
        <option value="US">USA</option>
    </select> 
    <br /><button type="submit">Register</button>
</form>

O elemento <option> correto será selecionado (contém o atributo selected="selected") dependendo do valor atual de Country.The correct <option> element will be selected ( contain the selected="selected" attribute) depending on the current Country value.

public IActionResult IndexOption(int id)
{
    var model = new CountryViewModel();
    model.Country = "CA";
    return View(model);
}
 <form method="post" action="/Home/IndexEmpty">
      <select id="Country" name="Country">
          <option value="">&lt;none&gt;</option>
          <option value="MX">Mexico</option>
          <option value="CA" selected="selected">Canada</option>
          <option value="US">USA</option>
      </select>
      <br /><button type="submit">Register</button>
   <input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
 </form>

Recursos adicionaisAdditional resources