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

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

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

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

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

Цей метод автоматично перевіряє UTF-8, обрізає ліві та праві пропуски й видаляє перенесення рядків, які можуть бути надіслані зловмисником.

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

Ви можете змінити візуальний вигляд текстового поля на типи search, tel або url за допомогою setHtmlType(), як показано у специфікації. Пам'ятайте, що зміна типу є лише візуальною і не виконує функцій перевірки. Для типу url доречно додати спеціальне правило URL-адреси.

Для інших типів вводу, таких як number, range, email, date, datetime-local, time і color, використовуйте спеціалізовані методи, такі як addInteger, addFloat, addEmail, addDate, addTime, addDateTime і addColor, які забезпечують валідацію на стороні сервера. Типи month та week ще не повністю підтримуються всіма браузерами.

Для елемента може бути встановлено так зване “порожнє значення”, яке є чимось на зразок значення за замовчуванням, але якщо користувач не перезаписує його, повертає порожній рядок або 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]);

Елемент рендериться як <input type="numeric">. За допомогою методу setHtmlType() ви можете змінити тип на range для відображення у вигляді слайдера, або на text, якщо ви віддаєте перевагу стандартному текстовому полю без особливої поведінки numeric.

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, рекомендується встановити атрибут lang або для конкретного елемента, або, наприклад, для всієї сторінки, <html lang="cs">.

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

Додає поле адреси електронної пошти з перевіркою достовірності (клас TextInput). Якщо користувач не заповнив поле, повертається порожній рядок '', або використовуйте setNullable() для повернення null.

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

Перевіряє, що значення є дійсною адресою електронної пошти. Він не перевіряє, чи існує домен насправді, перевіряється тільки синтаксис. Автоматично перевіряє UTF-8, обрізає ліві та праві пробіли.

addPassword (string|int $name, $label=null, $cols, ?int $maxLength=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).

Якщо ви відправляєте форму методом GET, ви можете вибрати більш компактний метод передачі даних, який дозволяє заощадити на розмірі рядка запиту. Це активується за допомогою налаштування атрибута HTML форми:

$form->setHtmlAttribute('data-nette-compact');

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, ?int $size=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, ?int $size=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).

За замовчуванням приймаються або об'єкти, що реалізують DateTimeInterface, або рядок з часом, або число, що представляє часову мітку UNIX. Те саме стосується аргументів правила Min, Max або Range, які визначають мінімальну та максимальну допустиму дату.

$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()`	відключення входів

Рендеринг:

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