Елементи керування форм
Огляд вбудованих елементів керування формою.
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() |
відключення входів |
Рендеринг:
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
безпосередньо, якщо ви хочете отримувати
безпечні дані.