Елементи керування форм

Огляд вбудованих елементів керування формою.

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):

Рендеринг:

Валідація:

Наступні методи можуть бути викликані для елементів addText(), addPassword(), addTextArea(), addEmail(), addInteger():

Опущені значення

Якщо вас не цікавить значення, введене користувачем, ми можемо використовувати 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 безпосередньо, якщо ви хочете отримувати безпечні дані.