Элементы управления форм

Обзор встроенных элементов управления формой.

addText(string|int $name, $label=null): TextInput

Добавляет однострочное текстовое поле (класс TextInput). Если пользователь не заполнил поле, возвращается пустая строка '', или используйте setNullable() для возврата null.

$form->addText('name', 'Имя:')
	->setRequired()
	->setNullable();

Этот метод автоматически проверяет UTF-8, обрезает левые и правые пробелы и удаляет переносы строк, которые могут быть отправлены злоумышленником.

Максимальная длина может быть ограничена с помощью setMaxLength(). Функция addFilter() позволяет изменить введенное пользователем значение.

Используйте setHtmlType() для изменения типа элемента ввода на search, tel, url, range, date, datetime-local, month, time, week, color. Вместо типов number и email мы рекомендуем использовать addInteger и addEmail, которые обеспечивают валидацию на стороне сервера.

$form->addText('color', 'Выберите цвет:')
	->setHtmlType('color')
	->addRule($form::Pattern, 'недопустимое значение', '[0-9a-f]{6}');

Для элемента может быть установлено так называемое «пустое значение», которое является чем-то вроде значения по умолчанию, но если пользователь не перезаписывает его, возвращает пустую строку или null.

$form->addText('phone', 'Телефон:')
	->setHtmlType('tel')
	->setEmptyValue('+420');

addTextArea(string|int $name, $label=null): TextArea

Добавляет многострочное текстовое поле (класс TextArea). Если пользователь не заполнил поле, возвращается пустая строка '', или используйте setNullable() для возврата null.

$form->addTextArea('note', 'Примечание:')
	->addRule($form::MaxLength, 'Ваша заметка слишком длинная', 10000);

Автоматически проверяет UTF-8 и нормализует переносы строк до \n. В отличие от однострочного поля ввода, в нем не обрезаются пробельные символы.

Максимальная длина может быть ограничена с помощью setMaxLength(). Функция addFilter() позволяет изменить введенное пользователем значение. Вы можете установить так называемое «пустое значение», используя setEmptyValue().

addInteger(string|int $name, $label=null): TextInput

Добавляет поле ввода для целого числа (класс TextInput). Возвращает либо целое число, либо null, если пользователь ничего не ввел.

$form->addInteger('level', 'Уровень:')
	->setDefaultValue(0)
	->addRule($form::Range, 'Уровень должен быть между %d и %d.', [0, 100]);

addEmail(string|int $name, $label=null): TextInput

Добавляет поле адреса электронной почты с проверкой достоверности (класс TextInput). Если пользователь не заполнил поле, возвращается пустая строка '', или используйте setNullable() для возврата null.

$form->addEmail('email', 'Имейл:');

Проверяет, что значение является действительным адресом электронной почты. Он не проверяет, существует ли домен на самом деле, проверяется только синтаксис. Автоматически проверяет UTF-8, обрезает левые и правые пробелы.

addPassword(string|int $name, $label=null): TextInput

Добавляет поле пароля (класс TextInput).

$form->addPassword('password', 'Пароль:')
	->setRequired()
	->addRule($form::MinLength, 'Пароль должен быть длиной не менее %d символов', 8)
	->addRule($form::Pattern, 'Пароль должен содержать цифры', '.*[0-9].*');

При повторной отправке формы ввод будет пустым. Он автоматически проверяет UTF-8, обрезает левые и правые пробелы и удаляет переносы строк, которые могут быть отправлены злоумышленником.

addCheckbox(string|int $name, $caption=null): Checkbox

Добавляет флажок (класс Checkbox). Поле возвращает либо true, либо false, в зависимости от того, проверено ли оно.

$form->addCheckbox('agree', 'Я согласен с условиями')
	->setRequired('Вы должны согласиться с нашими условиями');

addCheckboxList(string|int $name, $label=null, array $items=null): CheckboxList

Добавляет список флажков для выбора нескольких элементов (класс CheckboxList). Возвращает массив ключей выбранных элементов. Метод getSelectedItems() возвращает значения вместо ключей.

$form->addCheckboxList('colors', 'Цвета:', [
	'r' => 'red',
	'g' => 'green',
	'b' => 'blue',
]);

Мы передаем массив элементов в качестве третьего параметра или методом setItems().

Вы можете использовать setDisabled(['r', 'g']) для отключения отдельных элементов.

Элемент автоматически проверяет, что не было подделки и что выбранные элементы действительно являются одними из предложенных и не были отключены. Метод getRawValue() может быть использован для получения отправленных элементов без этой важной проверки.

При установке значений по умолчанию также проверяется, что они являются одним из предлагаемых элементов, в противном случае возникает исключение. Эта проверка может быть отключена с помощью checkDefaultValue(false).

addRadioList(string|int $name, $label=null, array $items=null): RadioList

Добавляет радиокнопки (класс RadioList). Возвращает ключ выбранного элемента или null, если пользователь ничего не выбрал. Метод getSelectedItem() возвращает значение вместо ключа.

$sex = [
	'm' => 'male',
	'f' => 'female',
];
$form->addRadioList('gender', 'Пол:', $sex);

Мы передаем массив элементов в качестве третьего параметра или методом setItems().

Вы можете использовать setDisabled(['m']) для отключения отдельных элементов.

Элемент автоматически проверяет, что не было подделки и что выбранный элемент действительно является одним из предложенных и не был отключен. Метод getRawValue() может быть использован для получения отправленного элемента без этой важной проверки.

При установке значения по умолчанию проверяется, что оно является одним из предлагаемых элементов, в противном случае возникает исключение. Эта проверка может быть отключена с помощью checkDefaultValue(false).

addSelect(string|int $name, $label=null, array $items=null): SelectBox

Добавляет поле выбора (класс SelectBox). Возвращает ключ выбранного элемента или null, если пользователь ничего не выбрал. Метод getSelectedItem() возвращает значение вместо ключа.

$countries = [
	'CZ' => 'Чешская республика',
	'SK' => 'Словакия',
	'GB' => 'Великобритания',
];

$form->addSelect('country', 'Страна:', $countries)
	->setDefaultValue('SK');

Мы передаем массив элементов в качестве третьего параметра или методом setItems(). Массив элементов также может быть двумерным:

$countries = [
	'Europe' => [
		'CZ' => 'Чешская республика',
		'SK' => 'Словакия',
		'GB' => 'Великобритания',
	],
	'CA' => 'Канада',
	'US' => 'США',
	'?'  => 'другая',
];

В блоках выбора первый элемент часто имеет особое значение, он служит призывом к действию. Используйте метод setPrompt() для добавления такой записи.

$form->addSelect('country', 'Страна:', $countries)
	->setPrompt('Выберите страну');

Вы можете использовать setDisabled(['CZ', 'SK']) для отключения отдельных элементов.

addMultiSelect(string|int $name, $label=null, array $items=null): MultiSelectBox

Добавляет окно выбора нескольких вариантов (класс MultiSelectBox). Возвращает массив ключей выбранных элементов. Метод getSelectedItems() возвращает значения вместо ключей.

$form->addMultiSelect('countries', 'Страны:', $countries);

Мы передаем массив элементов в качестве третьего параметра или методом setItems(). Массив элементов также может быть двумерным.

Вы можете использовать setDisabled(['CZ', 'SK']) для отключения отдельных элементов.

addUpload(string|int $name, $label=null): UploadControl

Добавляет поле загрузки файлов (класс UploadControl). Возвращает объект FileUpload, даже если пользователь не загрузил файл, что можно выяснить с помощью метода FileUpload::hasFile().

$form->addUpload('avatar', 'Аватар:')
	->addRule($form::Image, 'Аватар должен быть в формате JPEG, PNG, GIF или WebP')
	->addRule($form::MaxFileSize, 'Максимальный размер - 1 МБ', 1024 * 1024);

Если файл загружен неправильно, форма не была отправлена успешно и отображается ошибка. Т. е. нет необходимости проверять метод FileUpload::isOk().

Не доверяйте оригинальному имени файла, возвращаемому методом FileUpload::getName(), клиент может отправить вредоносное имя файла с намерением испортить или взломать ваше приложение.

Правила MimeType и Image определяют необходимый тип файла или изображения по его сигнатуре. Целостность всего файла не проверяется. Вы можете узнать, не повреждено ли изображение, например, попытавшись загрузить его.

addMultiUpload(string|int $name, $label=null): UploadControl

Добавляет поле загрузки нескольких файлов (класс UploadControl). Возвращает массив объектов FileUpload. Метод FileUpload::hasFile() вернет true для каждого из них.

$form->addMultiUpload('files', 'Файлы:')
	->addRule($form::MaxLength, 'Может быть загружено не более %d файлов', 10);

Если один из файлов не загрузится правильно, форма не будет отправлена успешно и отобразится ошибка. Т. е. нет необходимости проверять метод FileUpload::isOk().

Не доверяйте оригинальным именам файлов, возвращаемым методом FileUpload::getName(), клиент может отправить вредоносное имя файла с намерением испортить или взломать ваше приложение.

addHidden(string|int $name, string $default=null): HiddenField

Добавляет скрытое поле (класс HiddenField).

$form->addHidden('userid');

Используйте setNullable(), чтобы изменить его так, чтобы он возвращал null вместо пустой строки. Функция addFilter() позволяет изменить представленное значение.

addSubmit(string|int $name, $caption=null): SubmitButton

Добавляет кнопку отправки (класс SubmitButton).

$form->addSubmit('submit', 'Зарегистрироваться');

В форме можно иметь более одной кнопки отправки:

$form->addSubmit('register', 'Зарегистрироваться');
$form->addSubmit('cancel', 'Отмена');

Чтобы узнать, какая из них была нажата, используйте:

if ($form['register']->isSubmittedBy()) {
  // ...
}

Если вы не хотите проверять форму при нажатии кнопки отправки (например, кнопки Отмена или Предварительный просмотр), вы можете отключить её с помощью setValidationScope().

addButton(string|int $name, $caption): Button

Добавляет кнопку (класс Button) без функции отправки. Это полезно для привязки другой функциональности к id, например, действия JavaScript.

$form->addButton('raise', 'Поднять зарплату')
	->setHtmlAttribute('onclick', 'raiseSalary()');

addImageButton(string|int $name, string $src=null, string $alt=null): ImageButton

Добавляет кнопку отправки в виде изображения (класс ImageButton).

$form->addImageButton('submit', '/path/to/image');

При использовании нескольких кнопок отправки можно узнать, какая из них была нажата с помощью $form['submit']->isSubmittedBy().

addContainer(string|int $name): Container

Добавляет подформу (класс Container), или контейнер, с которым можно обращаться так же, как и с формой. Это означает, что вы можете использовать такие методы, как setDefaults() или getValues().

$sub1 = $form->addContainer('first');
$sub1->addText('name', 'Ваше имя:');
$sub1->addEmail('email', 'Имейл:');

$sub2 = $form->addContainer('second');
$sub2->addText('name', 'Ваше имя:');
$sub2->addEmail('email', 'Имейл:');

Затем отправленные данные возвращаются в виде многомерной структуры:

[
	'first' => [
		'name' => /* ... */,
		'email' => /* ... */,
	],
	'second' => [
		'name' => /* ... */,
		'email' => /* ... */,
	],
]

Обзор настроек

Для всех элементов мы можем вызывать следующие методы (полный обзор см. в документации по API):

`setDefaultValue($value)`	устанавливает значение по умолчанию
`getValue()`	получить текущее значение
`setOmitted()`	omitted values
`setDisabled()`	disabling inputs

Рендеринг:

`setCaption()`	изменить заголовка элемента
`setTranslator()`	задает транслятор
`setHtmlAttribute()`	задает HTML атрибут элемента
`setHtmlId()`	задает HTML атрибут `id`
`setHtmlType()`	задает HTML атрибут `type`
`setHtmlName()`	задает HTML атрибут `name`
`setOption()`	задает рендеринг данных

Валидация:

`setRequired()`	обязательное поле
`addRule()`	установить правило проверки
`addCondition()`, `addConditionOn()`	установить условие проверки
`addError()`	передача сообщения об ошибке

Следующие методы могут быть вызваны для элементов addText(), addPassword(), addTextArea(), addEmail(), addInteger():

`setNullable()`	устанавливает, возвращает ли getValue() `null` вместо пустой строки
`setEmptyValue()`	устанавливает специальное значение, которое рассматривается как пустая строка
`setMaxLength()`	устанавливает максимальное количество разрешенных символов
`addFilter()`	изменение входных значений

Опущенные значения

Если вас не интересует значение, введенное пользователем, мы можем использовать setOmitted(), чтобы опустить его из результата, предоставляемого методом $form->getValues() или передаваемого обработчикам. Это подходит для различных паролей для проверки, антиспамовых полей и т. д.

$form->addPassword('passwordVerify', 'Повторите пароль:')
	->setRequired('Введите пароль ещё раз, чтобы проверить опечатку')
	->addRule($form::Equal, 'Несоответствие пароля', $form['password'])
	->setOmitted();

Отключение элементов ввода

Чтобы отключить вход, вы можете вызвать setDisabled(). Такое поле не может быть отредактировано пользователем.

$form->addText('username', 'Имя пользователя:')
	->setDisabled();

Обратите внимание, что браузер вообще не отправляет отключенные поля на сервер, поэтому вы даже не найдете их в данных, возвращаемых функцией $form->getValues().

Если вы устанавливаете значение по умолчанию для поля, вы должны сделать это только после его отключения:

$form->addText('username', 'Имя пользователя:')
	->setDisabled()
	->setDefaultValue($userName);

Пользовательские элементы управления

Помимо широкого спектра встроенных элементов управления формой, вы можете добавить свои элементы следующим образом:

$form->addComponent(new DateInput('Дата:'), 'date');
// альтернативный синтаксис: $form['date'] = new DateInput('Дата:');

Форма является потомком класса Container, а элементы являются потомками Component.

Существует способ определения новых методов формы для добавления пользовательских элементов (например, ‘$form->addZip()’). Это так называемые методы расширения. Недостатком является то, что подсказки кода в редакторах не будут работать для них.

use Nette\Forms\Container;

// добавляет метод addZip(string $name, string $label = null)
Container::extensionMethod('addZip', function (Container $form, string $name, string $label = null) {
	return $form->addText($name, $label)
		->addRule($form::Pattern, 'Не менее 5 номеров', '[0-9]{5}');
});

// использование
$form->addZip('zip', 'ZIP-код:');

Низкоуровневые поля

Чтобы добавить элемент в форму, не нужно вызывать ‘$form->addXyz()’. Вместо этого элементы формы могут быть введены исключительно в шаблоны. Это полезно, если вам, например, нужно создать динамические элементы:

{foreach $items as $item}
	<p><input type=checkbox name="sel[]" value={$item->id}> {$item->name}</p>
{/foreach}

После отправки можно получить значения:

$data = $form->getHttpData($form::DataText, 'sel[]');
$data = $form->getHttpData($form::DataText | $form::DataKeys, 'sel[]');

В первом параметре вы указываете тип элемента (DataFile для type=file, DataLine для однострочных вводов типа text, password или email и DataText для остальных). Второй параметр соответствует HTML-атрибуту name. Если вам нужно сохранить ключи, вы можете объединить первый параметр с DataKeys. Это полезно для select, radioList или checkboxList.

Функция getHttpData() возвращает обработанные данные. В этом случае это всегда будет массив допустимых строк UTF-8, независимо от того, что атакующий отправил через форму. Это альтернатива работе с $_POST или $_GET напрямую, если вы хотите получать безопасные данные.