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

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

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

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

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

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

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

Используя метод setHtmlType(), можно изменить символ входного элемента на search, tel, url, range, month, week или color. Для других типов, таких как number, email, date, datetime-local и time, существуют отдельные методы addInteger, addFloat, addEmail, addDate, addTime и addDateTime, которые поставляются с проверкой на стороне сервера.

$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('year', 'Year:')
	->addRule($form::Range, 'Год должен быть в диапазоне от %d до %d.', [1900, 2023 |1900, 2023]);

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

Adds a field for entering a decimal number (TextInput class). Returns either float or null, if the user does not specify anything.

$form->addFloat('level', 'Level:')
	->setDefaultValue(0)
->addRule($form::Range, 'Уровень должен находиться в диапазоне от %d до %d.', [0, 100 |0, 100]);

Nette и Chrome принимают в качестве десятичного разделителя как запятую, так и точку. Для того чтобы Firefox также воспринимал запятую, необходимо задать соответствующий язык в HTML-атрибуте lang, либо непосредственно этому элементу, либо какому-либо родительскому элементу, например <html lang="cs">.

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

addDate(string|int $name, $label=null): DateTimeControl

Добавляет поле, позволяющее пользователю легко вводить дату, состоящую из года, месяца и дня (класс DateTimeControl).

В качестве значения по умолчанию он принимает либо объекты, реализующие DateTimeInterface, либо строку с временем, либо число, представляющее временную метку UNIX. То же самое относится и к аргументам правил Min, Max или Range, которые определяют минимально и максимально допустимую дату.

$form->addDate('date', 'Date:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'The date must be at least a month old.', new DateTime('-1 month'));

По умолчанию возвращается объект DateTimeImmutable. С помощью метода setFormat() можно задать текстовый формат или временную метку:

$form->addDate('date', 'Date:')
	->setFormat('Y-m-d');

addTime(string|int $name, $label=null, bool $withSeconds = false): DateTimeControl

Добавляет поле, позволяющее пользователю легко вводить время, состоящее из часов, минут и, по желанию, секунд (класс DateTimeControl).

В качестве значения по умолчанию оно принимает либо объекты, реализующие DateTimeInterface, либо строку с временем, либо число, представляющее временную метку UNIX. Используется только информация о времени из этих входов, дата игнорируется. То же самое относится и к аргументам правил Min, Max или Range, которые определяют минимальное и максимальное допустимое время. Если минимальное значение больше максимального, то создается временной диапазон, охватывающий полночь.

$form->addTime('time', 'Time:', withSeconds: true)
	->addRule($form::Range, 'Time must be between %d and %d.', ['12:30', '13:30']);

По умолчанию он возвращает объект DateTimeImmutable (с датой 1 января, год 1). С помощью метода setFormat() можно задать текстовый формат:

$form->addTime('time', 'Time:')
	->setFormat('H:i');

addDateTime(string|int $name, $label=null, bool $withSeconds = false): DateTimeControl

Добавляет поле, позволяющее пользователю легко вводить дату и время, состоящие из года, месяца, дня, часов, минут и, по желанию, секунд (класс DateTimeControl).

$form->addDateTime('datetime', 'Date and Time:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'The date must be at least a month old.', new DateTime('-1 month'));

$form->addDateTime('datetime')
	->setFormat(DateTimeControl::FormatTimestamp);

addColor(string|int $name, $label=null): ColorPicker

Добавляет поле выбора цвета (класс ColorPicker). Цвет представляет собой строку в формате #rrggbb. Если пользователь не делает выбора, то по умолчанию возвращается черный цвет #000000.

$form->addColor('color', 'Color:')
	->setDefaultValue('#3C8ED7');

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(). Однако если вы зададите setOmitted(false), Nette включит их значение по умолчанию в эти данные.

Когда вызывается setDisabled(), значение входных данных стирается в целях безопасности. Если вы устанавливаете значение по умолчанию, необходимо сделать это после его деактивации:

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

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

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

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

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