HTML-хелперы элементов форм

Данное руководство устарело. Актуальное руководство: Руководство по ASP.NET Core 7

Хотя мы можем создать любой необходимый хелпер, но в большинстве случаев нам не придется писать свои хелперы, потому что фреймворк MVC уже предоставляет большой набор встроенных html-хелперов, которые позволяют генерировать ту или иную разметку, например, код элеметов форм.

Хелпер Html.BeginForm

Пусть в контроллере определены две версии одного метода Create- для методов POST и GET, например:

[HttpGet]
public IActionResult Create()
{
	return View();
}
[HttpPost]
public IActionResult Create(string name, int age)
{
	return Content($"{name} - {age}");
}

В представлении для метода Create для создания формы ввода данных для последующей их отправки на post-версию метода Create мы вполне можем использовать стандартные элементы html, например:

<form method="post" action="~/Home/Create">
    <p>
        <label>Имя</label><br />
        <input type="text" name="name" />
    </p>
    <p>
        <label>Возраст</label><br />
        <input type="number" name="age" />
    </p>
    <p>
        <input type="submit" value="Отправить" />
    </p>
</form>

Это обычная html-форма, которая по нажатию на кнопку отправляет все введенные данные запросом POST на адрес /Home/Create. Встроенный хелпер BeginForm/EndForm позволяет создать ту же самую форму:

@using(Html.BeginForm("Create", "Home", FormMethod.Post))
{
    <p>
        <label>Имя</label><br />
        <input type="text" name="name" />
    </p>
    <p>
        <label>Возраст</label><br />
        <input type="number" name="age" />
    </p>
    <p>
        <input type="submit" value="Отправить" />
    </p>
}

Метод BeginForm принимает в качестве параметров имя метода действия и имя контроллера, а также тип запроса. Данный хелпер создает как открывающий тег <form>, так и закрывающий тег </form>. Поэтому при рендеринге представления в выходной поток у нас получится тот же самый html-код, что и с применением тега form. Поэтому оба способа идентичны.

Но вызов страницы с формой и отправка формы осуществляется одним и тем же действием (как в нашем случае действием Create), то в этом случае можно не указывать в хелпере Html.BeginForm параметры:

@using(Html.BeginForm())
{
    .............
}

Ввод информации

В предыдущем примере вместе с хелпером Html.BeginForm использовались стандартные элементы html. Однако набор html-хелперов содержит также хелперы для ввода информации пользователем. В MVC определен широкий набор хелперов ввода практически для каждого html-элемента. Что выбрать - хелпер или стандартный элементы ввода html, уже решает сам разработчик.

Вне зависимости от типа все базовые html-хелперы используют как минимум два параметра: первый параметр применяется для установки значений для атрибутов id и name, а второй параметр - для установки значения атрибута value

Html.TextBox

Хелпер Html.TextBox генерирует тег input со значением атрибута type равным text. Хелпер TextBox используют для получения ввода пользователем информации. Так, перепишем предыдущую форму с заменой полей ввода на хелпер Html.TextBox:

@using (Html.BeginForm("Create", "Home", FormMethod.Post))
{
    <p>
        <label>Имя</label><br />
        @Html.TextBox("Name")
    </p>
    <p>
        <label>Возраст</label><br />
        @Html.TextBox("Age","", new { type="number" })
    </p>
    <p>
        <input type="submit" value="Отправить" />
    </p>
}

Хелпер позволяет установить ряд дополнительных параметров с помощью перегружженных версий. Так, вызов хелпера:

@Html.TextBox("Price","", new { type="number" })

В качестве второго параметра устанавливает значение по умолчанию (здесь пустая строка). Третий параметр в виде анонимного объекта позволяет задать ряд атрибутов генерируемого html-элемента. Так, в данном случае мы указываем, что поле будет числовое, так как по умолчанию создаваемое поле расценивается как текстовое, то есть с атрибутом type="text".

В итоге мы получим практически аналогичный результат:

Html.Label

Хелпер Html.Label создает элемент <label/>, а передаваемый в хелпер параметр определяет значение атрибута for и одновременно текст на элементе. Перегруженная версия хелпера позволяет определить значение атрибута for и текст на метке независимо друг от друга. Например, объявление хелпера Html.Label("Name", "Имя") создает следующую разметку:

<label for="Name">Имя</label>

Элемент label представляет простую метку, предназначенную для прикрепления информации к элементам ввода, например, к текстовым полям. Атрибут for элемента label должен содержать id ассоциированного элемента ввода. Если пользователь нажимает на метку, то браузер автоматически передает фокус связанному с этой меткой элементу ввода.

Html.TextArea

Хелпер TextArea используется для создания элемента <textarea>, который представляет многострочное текстовое поле. Результатом выражения @Html.TextArea("text", "привет мир")

будет следующая html-разметка:

<textarea cols="20" id="text" name="text" rows="2">привет мир
</textarea>

Обратите внимание, что хелпер декодирует помещаемое в него значение, в том числе и html-теги, (все хелперы декодируют значения моделей и значения атрибутов). Другие версии хелпера TextArea позволяют указать число строк и столбцов, определяющих размер текстового поля.

@Html.TextArea("text", "привет мир", 5, 50, null)

Этот хелпер сгенерирует следующую разметку:

<textarea cols="50" id="text" name="text" rows="5">привет мир</textarea>

Html.Hidden

Хелпер Html.Hidden генерирует скрытое поле. Например, следующий вызов хелпера:

@Html.Hidden("UserId", "2")

сгенерирует разметку:

<input id="UserId" name="UserId" type="hidden" value="2" />

Html.Password

Html.Password создает поле для ввода пароля. Он похож на хелпер TextBox, но вместо введенных символов отображает маску пароля. Следующий код:

@Html.Password("UserPassword", "val")

генерирует разметку:

<input id="UserPassword" name="UserPassword" type="password" value="val" />

Html.RadioButton

Для создания переключателей применяется хелпер Html.RadioButton. Он генерирует элемент input со значением type="radio". Для создания группы переключателей, надо присвоить всем им одно и то же имя (свойство name):

@Html.RadioButton("color", "red")
<span>красный</span> <br />
@Html.RadioButton("color", "blue")
<span>синий</span> <br />
@Html.RadioButton("color", "green", true)
<span>зеленый</span>

Этот код создает следующую разметку:

<input id="color" name="color" type="radio" value="red" />
<span>красный</span> <br />
<input id="color" name="color" type="radio" value="blue" /> 
<span>синий</span> <br />
<input checked="checked" id="color" name="color" type="radio" value="green" />
<span>зеленый</span>

Html.CheckBox

Html.CheckBox применяется для создания элемента флажка или checkbox. Например, следующий код:

@Html.CheckBox("Enable", false)

будет генерировать следующий HTML:

<input id="Enable" name="Enable" type="checkbox" value="true">
<input name="Enable" type="hidden" value="false">

Фактически создается два элемента - собственно флажок и скрытое поле, которое обычно помещается в конец формы и используется для отслеживания изменений значения флажка.

Html.DropDownList

Хелпер Html.DropDownList создает выпадающий список, то есть элемент <select />. Для генерации такого списка нужна коллекция объектов SelectListItem, которые представляют элементы списка. Можно создать коллекцию объектов SelectListItem или использовать хелпер SelectList. Этот хелпер просматривает объекты IEnumerable и преобразуют их в последовательность объектов SelectListItem. Так, следующий код:

@Html.DropDownList("user", new SelectList(new string[] { "Tom", "Sam", "Bob", "Alice" }), "Выберите пользователя")

генерирует следующую разметку:

<select id="phone" name="phone"><option value="">Выберите пользователя</option>
<option>Tom</option>
<option>Sam</option>
<option>Bob</option>
<option>Alice</option>
</select>

Объект SelectListItem имеет свойства Text (отображаемый текст), Value (само значение, которое может не совпадать с текстом) и Selected. Теперь более сложный пример. Выведем в список коллекцию элементов User:

public class User
{
    public int Id { get; set; }
    public string Name { get; set; }
    public int Age { get; set; }
}

В контроллере передадим список объектов User через ViewBag:

public IActionResult Create()
{
    List<User> users = new List<User>
    {
        new User {Id=1, Name="Tom", Age=35 },
		new User {Id=2, Name="Alice", Age=29 },
		new User {Id=3, Name="Sam", Age=36 },
		new User {Id=4, Name="Bob", Age=31 },
	};
	ViewBag.Users = new SelectList(users, "Id", "Name");
    return View();
}

Здесь мы создаем объект SelectList, передавая в его конструктор набор значений (список users), название свойства модели User, которое будет использоваться в качестве значения (Id), и название свойства модели User, которое будет использоваться для отображения в списке. В данном случае необязательно устанавливать два разных свойства, можно было и одно установить и для значения и отображения.

Тогда в представлении мы можем так использовать этот SelectList:

@Html.DropDownList("userid", ViewBag.Users as SelectList)

И при рендеринге представления все элементы SelectList добавятся в выпадающий список

Html.ListBox

Хелпер Html.ListBox, также как и DropDownList, создает элемент <select />, но при этом делает возможным множественное выделение элементов (то есть для атрибута multiple устанавливается значение multiple). Для создания списка, поддерживающего множественное выделение, вместо SelectList можно использовать класс MultiSelectList:

@Html.ListBox("users", new MultiSelectList(new string[] { "Tom", "Sam", "Bob", "Alice" }))

Этот код генерирует следующую разметку:

<select id="users" multiple="multiple" name="users">
<option>Tom</option>
<option>Sam</option>
<option>Bob</option>
<option>Alice</option>
</select>

Html.GetEnumSelectList

Для создания выпадающего списка по перечислению применяется хелпер Html.GetEnumSelectList. Допустим, у нас есть следующее перечисление:

using System.ComponentModel.DataAnnotations;

namespace HtmlHelpersApp.App_Code
{
    public enum TimeOfDay
    {
        [Display(Name ="Утро")]
        Morning,
        [Display(Name = "День")]
        Afternoon,
        [Display(Name = "Вечер")]
        Evening,
        [Display(Name = "Ночь")]
        Night
    }
}

Тогда в представлении мы сможем вывести выпадающий список значений из этого перечисления:

@using HtmlHelpersApp.App_Code

@using (Html.BeginForm("Create", "Home", FormMethod.Post))
{
    @Html.DropDownList("daytime", Html.GetEnumSelectList(typeof(TimeOfDay)))
    <br />
    <p>
        <input type="submit" value="Отправить" />
    </p>
}