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

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

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, обрезает левые и правые пробелы.

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

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']) для отключения отдельных элементов.

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

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

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

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

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

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

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

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

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

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(), клиент может отправить вредоносное имя файла с намерением испортить или взломать ваше приложение.

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

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
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('Дата:');

Существует способ определения новых методов формы для добавления пользовательских элементов (например, ‘$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 напрямую, если вы хотите получать безопасные данные.