Вспомогательные функции тегов в формах в ASP.NET CoreTag Helpers in forms in ASP.NET Core

Авторы: Рик Андерсон (Rick Anderson), Н. Тейлор Маллен (N. Taylor Mullen), Дейв Пакетт (Dave Paquette) и Джерри Пелсер (Jerrie Pelser)By Rick Anderson, N. Taylor Mullen, Dave Paquette, and Jerrie Pelser

В этом документе приводятся сведения о работе с формами и элементами HTML, часто используемыми в формах.This document demonstrates working with Forms and the HTML elements commonly used on a Form. Элемент HTML форма предоставляет основной механизм, используемый веб-приложениями для отправки данных на сервер.The HTML Form element provides the primary mechanism web apps use to post back data to the server. В большей части этого документа описываются вспомогательные функции тегов и их применение для создания надежных форм HTML.Most of this document describes Tag Helpers and how they can help you productively create robust HTML forms. Перед прочтением этого документа рекомендуется изучить статью Общие сведения о вспомогательных функциях тегов.We recommend you read Introduction to Tag Helpers before you read this document.

Во многих случаях вспомогательные методы HTML располагают альтернативными вариантами для определенной вспомогательной функции тега, но следует отметить, что вспомогательные функции тегов не заменяют вспомогательные методы HTML и для каждого вспомогательного метода 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. Если есть альтернатива вспомогательному методу HTML, она будет указана.When an HTML Helper alternative exists, it's mentioned.

Вспомогательная функция тега формыThe Form Tag Helper

Вспомогательная функция тега формы:The Form Tag Helper:

  • Создает значение атрибута HTML <FORM> action для действия контроллера MVC или именованного маршрута.Generates the HTML <FORM> action attribute value for a MVC controller action or named route

  • Создает скрытый токен проверки запроса для предотвращения подделки межсайтовых запросов (при использовании с атрибутом [ValidateAntiForgeryToken] в методе действия 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)

  • Предоставляет атрибут asp-route-<Parameter Name>, где <Parameter Name> добавляется в значения маршрута.Provides the asp-route-<Parameter Name> attribute, where <Parameter Name> is added to the route values. Параметры routeValues для Html.BeginForm и Html.BeginRouteForm предоставляют аналогичные функциональные возможности.The routeValues parameters to Html.BeginForm and Html.BeginRouteForm provide similar functionality.

  • Располагает альтернативой вспомогательному методу HTML — Html.BeginForm и Html.BeginRouteForm.Has an HTML Helper alternative Html.BeginForm and Html.BeginRouteForm

Пример:Sample:

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

Приведенная выше вспомогательная функция тега формы создает следующий код HTML: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>

Среда выполнения MVC генерирует значение атрибута action на основе атрибутов вспомогательной функции тега формы asp-controller и asp-action.The MVC runtime generates the action attribute value from the Form Tag Helper attributes asp-controller and asp-action. Вспомогательная функция тега формы также создает скрытый токен проверки запроса для предотвращения подделки межсайтовых запросов (при использовании с атрибутом [ValidateAntiForgeryToken] в методе действия 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). Защита чистой формы HTML от подделки межсайтовых запросов является трудной задачей, поэтому для ее решения используется вспомогательная функция тега формы.Protecting a pure HTML Form from cross-site request forgery is difficult, the Form Tag Helper provides this service for you.

Использование именованного маршрутаUsing a named route

Атрибут asp-route вспомогательной функции тега также может создавать разметку для атрибута HTML action.The asp-route Tag Helper attribute can also generate markup for the HTML action attribute. Приложение с маршрутом с именем register использует следующую разметку для страницы регистрации: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>

Многие представления в папке Views/Account (сформированные при создании веб-приложения с учетными записями отдельных пользователей) содержат атрибут 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">

Примечание

При использовании встроенных шаблонов returnUrl заполняется автоматически только в случае, если вы пытаетесь получить доступ к авторизованному ресурсу, но не прошли проверку подлинности или авторизацию.With the built in templates, returnUrl is only populated automatically when you try to access an authorized resource but are not authenticated or authorized. При попытке несанкционированного доступа ПО безопасности промежуточного слоя перенаправит вас на страницу входа с заданным returnUrl.When you attempt an unauthorized access, the security middleware redirects you to the login page with the returnUrl set.

Вспомогательная функция тега действий формыThe Form Action Tag Helper

Вспомогательная функция тега действий формы создает атрибут formaction в созданном теге <button ...> или <input type="image" ...>.The Form Action Tag Helper generates the formaction attribute on the generated <button ...> or <input type="image" ...> tag. Атрибут formaction определяет, куда форма отправляет свои данные.The formaction attribute controls where a form submits its data. Он выполняет привязку к элементам <input> типа image и элементам <button>.It binds to <input> elements of type image and <button> elements. Вспомогательная функция тега действий формы позволяет использовать несколько атрибутов asp- AnchorTagHelper для управления выходными данными ссылки formaction для соответствующего элемента.The Form Action Tag Helper enables the usage of several AnchorTagHelper asp- attributes to control what formaction link is generated for the corresponding element.

Ниже перечислены поддерживаемые атрибуты AnchorTagHelper для управления значением formaction.Supported AnchorTagHelper attributes to control the value of formaction:

АтрибутAttribute ОписаниеDescription
asp-controllerasp-controller Имя контроллера.The name of the controller.
asp-actionasp-action Имя метода действия.The name of the action method.
asp-areaasp-area Имя области.The name of the area.
asp-pageasp-page Имя страницы с кодом Razor.The name of the Razor page.
asp-page-handlerasp-page-handler Имя обработчика страницы с кодом Razor.The name of the Razor page handler.
asp-routeasp-route Имя маршрута.The name of the route.
asp-route-{value}asp-route-{value} Одно значение URL-адреса маршрута.A single URL route value. Например, asp-route-id="1234".For example, asp-route-id="1234".
asp-all-route-dataasp-all-route-data Все значения маршрута.All route values.
asp-fragmentasp-fragment Фрагмент URL-адреса.The URL fragment.

Отправка формы в пример контроллераSubmit to controller example

Следующая разметка отправляет форму в действие Index, выполняемое HomeController, если выбран ввод или кнопка.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>

Предыдущая разметка создает следующий код 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>

Отправка формы в пример страницыSubmit to page example

Следующая разметка отправляет форму в страницу 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>

Предыдущая разметка создает следующий код 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>

Отправка формы в пример маршрутаSubmit to route example

Рассмотрим конечную точку /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";
    }
}

Следующая разметка отправляет форму в конечную точку /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>

Предыдущая разметка создает следующий код 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>

Вспомогательная функция тега входных данныхThe Input Tag Helper

Вспомогательная функция тега входных данных привязывает элемент HTML <input> к модели выражения в представлении Razor.The Input Tag Helper binds an HTML <input> element to a model expression in your razor view.

Синтаксис:Syntax:

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

Вспомогательная функция тега входных данных:The Input Tag Helper:

  • Создает атрибуты HTML id и name для имени выражения, указанного в атрибуте asp-for.Generates the id and name HTML attributes for the expression name specified in the asp-for attribute. asp-for="Property1.Property2" равно m => m.Property1.Property2.asp-for="Property1.Property2" is equivalent to m => m.Property1.Property2. Имя выражения совпадает со значением атрибута asp-for.The name of the expression is what is used for the asp-for attribute value. Дополнительные сведения см. в разделе Имена выражений .See the Expression names section for additional information.

  • Задает значение атрибута HTML type на основе атрибутов типа модели и заметок к данным, примененным к свойству модели.Sets the HTML type attribute value based on the model type and data annotation attributes applied to the model property

  • Значение атрибута HTML type не перезаписывается, если оно указано.Won't overwrite the HTML type attribute value when one is specified

  • Создает атрибуты проверки HTML5 из атрибутов заметок к данным, примененным к свойствам модели.Generates HTML5 validation attributes from data annotation attributes applied to model properties

  • Располагает перекрытием вспомогательного метода HTML с Html.TextBoxFor и Html.EditorFor.Has an HTML Helper feature overlap with Html.TextBoxFor and Html.EditorFor. Дополнительные сведения см. в разделе Альтернативы вспомогательного метода HTML вспомогательной функции тега входных данных.See the HTML Helper alternatives to Input Tag Helper section for details.

  • Обеспечивает строгую типизацию.Provides strong typing. Если после изменения имени свойства не выполнить обновление вспомогательной функции тега, возникнет ошибка следующего вида: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?)

Вспомогательная функция тега Input задает атрибут HTML type на основе типа .NET.The Input Tag Helper sets the HTML type attribute based on the .NET type. В следующей таблице перечислены некоторые распространенные типы .NET и созданный тип HTML (указаны не все типы .NET).The following table lists some common .NET types and generated HTML type (not every .NET type is listed).

Тип .NET.NET type Тип входных данныхInput Type
BoolBool type="checkbox"type="checkbox"
СтрокаString type="text"type="text"
DateTimeDateTime type="datetime-local"type="datetime-local"
ByteByte type="number"type="number"
IntInt type="number"type="number"
Single, DoubleSingle, Double type="number"type="number"

В следующей таблице приведены некоторые наиболее распространенные атрибуты заметок к данным, которые вспомогательная функция тега входных данных будет сопоставлять с определенными типами входных данных (указаны не все атрибуты проверки):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):

АтрибутAttribute Тип входных данныхInput 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"

Пример: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>

Приведенный выше код создает следующий 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>

Заметки данных применяются к свойствам Email и Password, создающим метаданные для модели.The data annotations applied to the Email and Password properties generate metadata on the model. Вспомогательная функция тега входных данных использует метаданные модели и создает атрибуты data-val-* HTML5 (см. статью о проверке модели).The Input Tag Helper consumes the model metadata and produces HTML5 data-val-* attributes (see Model Validation). Эти атрибуты описывают проверяющие элементы управления, присоединяемые к полям входных данных.These attributes describe the validators to attach to the input fields. Это обеспечивает ненавязчивую проверку HTML5 и jQuery.This provides unobtrusive HTML5 and jQuery validation. Ненавязчивые атрибуты имеют формат data-val-rule="Error Message", где правило — это имя правила проверки (например, data-val-required, data-val-email, data-val-maxlength и т. д.). Если в атрибуте приводится сообщение об ошибке, оно отображается как значение атрибута 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. Также существуют атрибуты формы data-val-ruleName-argumentName="argumentValue", которые содержат дополнительные сведения о правиле, например 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" .

Альтернативы вспомогательного метода HTML вспомогательной функции тега входных данныхHTML Helper alternatives to Input Tag Helper

Html.TextBox, Html.TextBoxFor, Html.Editor и Html.EditorFor имеют функции, перекрывающиеся со вспомогательной функцией тега входных данных.Html.TextBox, Html.TextBoxFor, Html.Editor and Html.EditorFor have overlapping features with the Input Tag Helper. Вспомогательная функция тега входных данных будет автоматически задавать атрибут type, а Html.TextBox и Html.TextBoxFor — нет.The Input Tag Helper will automatically set the type attribute; Html.TextBox and Html.TextBoxFor won't. Html.Editor и Html.EditorFor обрабатывают коллекции, сложные объекты и шаблоны, а вспомогательная функция тега входных данных не делает этого.Html.Editor and Html.EditorFor handle collections, complex objects and templates; the Input Tag Helper doesn't. Вспомогательная функция тега входных данных, Html.EditorFor и Html.TextBoxFor являются строго типизированными (они используют лямбда-выражения); а Html.TextBox и Html.Editor не являются таковыми (они используют имена выражений).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() и @Html.EditorFor() используют специальную запись ViewDataDictionary с именем htmlAttributes.@Html.Editor() and @Html.EditorFor() use a special ViewDataDictionary entry named htmlAttributes when executing their default templates. Это поведение дополняется параметрами additionalViewData.This behavior is optionally augmented using additionalViewData parameters. Ключ "htmlAttributes" не учитывает регистр.The key "htmlAttributes" is case-insensitive. Ключ "htmlAttributes" обрабатывается так же, как htmlAttributes объект, передаваемый во вспомогательные функции входных данных, такие как @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" } })

Имена выраженийExpression names

Значением атрибута asp-for является ModelExpression и правая часть лямбда-выражения.The asp-for attribute value is a ModelExpression and the right hand side of a lambda expression. Таким образом, asp-for="Property1" становится m => m.Property1 в созданном коде, поэтому нет необходимости добавлять префикс Model.Therefore, asp-for="Property1" becomes m => m.Property1 in the generated code which is why you don't need to prefix with Model. Чтобы начать встроенное выражение и переместить его перед m., используется символ @.You can use the "@" character to start an inline expression and move before the m.:

@{
  var joe = "Joe";
}

<input asp-for="@joe">

Выводится следующий результат:Generates the following:

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

При использовании свойств коллекции asp-for="CollectionProperty[23].Member" генерирует то же самое имя, что и asp-for="CollectionProperty[i].Member", если i имеет значение 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.

Когда MVC ASP.NET Core рассчитывает значение ModelExpression, он оценивает несколько источников, включая ModelState.When ASP.NET Core MVC calculates the value of ModelExpression, it inspects several sources, including ModelState. Вы можете использовать <input type="text" asp-for="@Name">.Consider <input type="text" asp-for="@Name">. Рассчитанный атрибут value является первым значением, отличным от NULL, из:The calculated value attribute is the first non-null value from:

  • записи ModelState с ключом "Name";ModelState entry with key "Name".
  • результата выражения Model.Name.Result of the expression Model.Name.

Для перехода к дочерним свойствам можно также использовать путь к свойству модели представления.You can also navigate to child properties using the property path of the view model. Рассмотрим более сложный класс модели, который содержит дочернее свойство Address.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; }
}

В представлении выполняется привязка к 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>

Следующий HTML создан для Address.AddressLine1:The following HTML is generated for Address.AddressLine1:

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

Имена выражений и коллекцийExpression names and Collections

Пример модели, содержащей массив Colors:Sample, a model containing an array of Colors:

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

    public int Age { get; set; }
}

Метод действия:The action method:

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

В следующем коде Razor показано получение доступа к определенному элементу Color: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>

Шаблон Views/Shared/EditorTemplates/String.cshtml:The Views/Shared/EditorTemplates/String.cshtml template:

@model string

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

Пример с использованием List<T>:Sample using List<T>:

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

    public bool IsDone { get; set; }
}

В следующем коде Razor показана итерация по коллекции: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>

Шаблон 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, когда значение будет применяться в эквивалентном контексте asp-for или 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. Обычно лучше использовать for, чем foreach (если сценарий позволяет), так как ему не нужно выделять перечислитель. Тем не менее оценка индексатора в выражении LINQ может быть недешевой, поэтому ее нужно минимизировать.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.

 

Примечание

В приведенном выше комментированном коде показано, как заменить лямбда-выражение оператором @, чтобы получить доступ к каждому ToDoItem в списке.The commented sample code above shows how you would replace the lambda expression with the @ operator to access each ToDoItem in the list.

Вспомогательная функция тега TextareaThe Textarea Tag Helper

Вспомогательная функция тега Textarea Tag Helperаналогична вспомогательной функции тега входных данных.The Textarea Tag Helper tag helper is similar to the Input Tag Helper.

  • Создает атрибуты id и name, а также атрибуты проверки данных из модели для элемента <textarea>.Generates the id and name attributes, and the data validation attributes from the model for a <textarea> element.

  • Обеспечивает строгую типизацию.Provides strong typing.

  • Располагает альтернативой вспомогательному методу HTML — Html.TextAreaFor.HTML Helper alternative: Html.TextAreaFor

Пример: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>

Создается следующий HTML: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>

Вспомогательная функция тега меткиThe Label Tag Helper

  • Позволяет создать заголовок метки и атрибут for в элементе <label> для имени выражения.Generates the label caption and for attribute on a <label> element for an expression name

  • Располагает альтернативой вспомогательному методу HTML — Html.LabelFor.HTML Helper alternative: Html.LabelFor.

Label Tag Helper предоставляет следующие преимущества по сравнению с чистым элементом метки:The Label Tag Helper provides the following benefits over a pure HTML label element:

  • Вы автоматически получаете значение описательной метки из Display атрибута.You automatically get the descriptive label value from the Display attribute. Предполагаемое отображаемое имя может изменяться с течением времени, а сочетание атрибута Display и вспомогательной функции тега метки будет применять атрибут Display везде, где он используется.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.

  • Меньше разметки в исходном коде.Less markup in source code

  • Строгая типизация со свойством модели.Strong typing with the model property.

Пример: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>

Для элемента <label> создан следующий HTML:The following HTML is generated for the <label> element:

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

Вспомогательная функция тега метки сгенерировала для атрибута for значение "Email", представляющее собой идентификатор, связанный с элементом <input>.The Label Tag Helper generated the for attribute value of "Email", which is the ID associated with the <input> element. Вспомогательные функции тегов создают согласованные элементы id и for, чтобы обеспечить их правильное связывание.The Tag Helpers generate consistent id and for elements so they can be correctly associated. Заголовок в этом примере взят из атрибута Display.The caption in this sample comes from the Display attribute. Если модель не содержит атрибут Display, заголовком будет имя свойства выражения.If the model didn't contain a Display attribute, the caption would be the property name of the expression.

Вспомогательные функции тегов проверкиThe Validation Tag Helpers

Существует две вспомогательные функции тегов проверки.There are two Validation Tag Helpers. Validation Message Tag Helper отображает сообщение проверки для одного свойства в модели, Validation Summary Tag Helper отображает сводку ошибок проверки.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). Input Tag Helper добавляет клиентские атрибуты проверки HTML5 в элементы входных данных на основе атрибутов заметок к данным в классах модели.The Input Tag Helper adds HTML5 client side validation attributes to input elements based on data annotation attributes on your model classes. Проверка также выполняется на сервере.Validation is also performed on the server. Вспомогательная функция тега проверки отображает эти сообщения об ошибках при возникновении ошибки проверки.The Validation Tag Helper displays these error messages when a validation error occurs.

Вспомогательная функция тега сообщения о проверкеThe Validation Message Tag Helper

  • Добавляет атрибут data-valmsg-for="property" HTML5 в элемент span, который присоединяет сообщения об ошибках проверки к полю входных данных указанного свойства модели.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. При возникновении ошибки проверки на стороне клиента jQuery отображает сообщение об ошибке в элементе <span>.When a client side validation error occurs, jQuery displays the error message in the <span> element.

  • Проверка также выполняется на сервере.Validation also takes place on the server. На клиентах может быть отключена поддержка JavaScript, поэтому некоторые проверки выполняются только на стороне сервера.Clients may have JavaScript disabled and some validation can only be done on the server side.

  • Располагает альтернативой вспомогательному методу HTML — Html.ValidationMessageFor.HTML Helper alternative: Html.ValidationMessageFor

Validation Message Tag Helper используется с атрибутом asp-validation-for в элементе 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>

Вспомогательная функция тега сообщения о проверке создает следующий HTML:The Validation Message Tag Helper will generate the following HTML:

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

Как правило, Validation Message Tag Helper используется после вспомогательной функции тега Input для одного и того же свойства.You generally use the Validation Message Tag Helper after an Input Tag Helper for the same property. В этом случае сообщения об ошибках проверки отображаются рядом с входными данными, вызвавшими ошибку.Doing so displays any validation error messages near the input that caused the error.

Примечание

Для проверки на стороне клиента необходимо иметь представление с правильными ссылками на скрипты JavaScript и jQuery.You must have a view with the correct JavaScript and jQuery script references in place for client side validation. Дополнительные сведения см. в статье о проверке модели.See Model Validation for more information.

При возникновении ошибки проверки на стороне сервера (например, если выполняется пользовательская проверка на стороне сервера или проверка на стороне клиент отключена) MVC размещает сообщение об ошибке в тексте элемента <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>

Вспомогательная функция тега сводки по проверкеThe Validation Summary Tag Helper

  • Работает с элементами <div>, имеющими атрибут asp-validation-summary.Targets <div> elements with the asp-validation-summary attribute

  • Располагает альтернативой вспомогательному методу HTML — @Html.ValidationSummary.HTML Helper alternative: @Html.ValidationSummary

Validation Summary Tag Helper используется для отображения сводки по сообщениям проверки.The Validation Summary Tag Helper is used to display a summary of validation messages. Значением атрибута asp-validation-summary может быть любое из следующих:The asp-validation-summary attribute value can be any of the following:

asp-validation-summaryasp-validation-summary Отображаемые сообщения о проверкеValidation messages displayed
ValidationSummary.AllValidationSummary.All Свойство и уровень моделиProperty and model level
ValidationSummary.ModelOnlyValidationSummary.ModelOnly МодельModel
ValidationSummary.NoneValidationSummary.None ОтсутствуютNone

ПримерSample

В следующем примере модель данных имеет атрибуты DataAnnotation, в результате чего создаются сообщения об ошибках проверки для элемента <input>.In the following example, the data model has DataAnnotation attributes, which generates validation error messages on the <input> element. При возникновении ошибки проверки вспомогательная функция тега проверки отображает следующее сообщение об ошибке: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>

Созданный HTML (если модель является допустимой):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>

Вспомогательная функция тега SelectThe Select Tag Helper

  • Создает элемент select и связанные элементы option для свойств модели.Generates select and associated option elements for properties of your model.

  • Располагает альтернативой вспомогательному методу HTML — Html.DropDownListFor и Html.ListBoxFor.Has an HTML Helper alternative Html.DropDownListFor and Html.ListBoxFor

Select Tag Helper asp-for указывает имя свойства модели для элемента select, а asp-items указывает элементы option.The Select Tag Helper asp-for specifies the model property name for the select element and asp-items specifies the option elements. Пример:For example:

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

Пример: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"  },
        };
    }
}

Метод Index инициализирует CountryViewModel, задает выбранную страну и передает их в представление 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);
}

Метод HTTP POST Index отображает выбор: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);
}

Представление 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>

Создается следующий HTML (с выбранным значением "CA"):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>

Примечание

С вспомогательной функцией тега Select не рекомендуется использовать ViewBag или ViewData.We don't recommend using ViewBag or ViewData with the Select Tag Helper. Модель представления более надежна в процессе предоставления метаданных MVC и, как правило, менее проблематична.A view model is more robust at providing MVC metadata and generally less problematic.

Значение атрибута asp-for является особым случаем и не требует префикса Model, тогда как он необходим другим атрибутам вспомогательной функции тега (например, 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> 

Привязка перечисленияEnum binding

Часто бывает удобно использовать <select> со свойством enum и создавать элементы SelectListItem из значений enum.It's often convenient to use <select> with an enum property and generate the SelectListItem elements from the enum values.

Пример: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
    }
}

Метод GetEnumSelectList создает объект SelectList для перечисления.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>

Список перечислителя можно пометить атрибутом Display для формирования пользовательского интерфейса с более широкими функциональными возможностями: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
    }
}

Создается следующий HTML: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>

Группа параметровOption Group

Элемент HTML <optgroup> создается в том случае, если модель представления содержит один или несколько объектов SelectListGroup.The HTML <optgroup> element is generated when the view model contains one or more SelectListGroup objects.

CountryViewModelGroup группирует элементы SelectListItem в группы "North America" и "Europe":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; }

Ниже приведены две группы:The two groups are shown below:

пример группы параметров

Созданный HTML: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>

Множественный выборMultiple select

Вспомогательная функция Select автоматически создаст атрибут multiple = "multiple", если свойство, указанное в атрибуте asp-for, имеет значение IEnumerable.The Select Tag Helper will automatically generate the multiple = "multiple" attribute if the property specified in the asp-for attribute is an IEnumerable. Допустим, имеется такая модель: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"}
         };
    }
}

Со следующим представлением: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>

Генерирует следующий 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>

Не выбраноNo selection

Если вы используете параметр "not specified" (не выбрано) на нескольких страницах, можно создать шаблон, чтобы исключить повторяющийся HTML: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>

Шаблон 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>

Добавление элементов HTML <option> не ограничивается параметром No selection (Не выбрано).Adding HTML <option> elements isn't limited to the No selection case. Например, следующее представление и метод действия создадут HTML, аналогичный приведенному выше коду: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>

В зависимости от текущего значения Country будет выбран соответствующий элемент <option> (содержащий атрибут selected="selected").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>

Дополнительные ресурсыAdditional resources