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