Компонент Select

🌐 Цей документ доступний українською та англійською мовами. Використовуйте перемикач у правому верхньому куті, щоб змінити версію.

1. Опис компонента

Компонент Select є елементом інтерфейсу для роботи зі списками, з яких можна вибрати одну або кілька елементів. Цей список відображається у вигляді закритого блоку з одним або декількома елементами, і коли натиснути на поле вводу, список розкривається. На початку вводу список фільтрується. Компонент дозволяє вам налаштувати відображення, валідацію та завантаження даних з url.

Розширення стандартного компонента Select включає додавання додаткових опцій, які спрощують моделювання. Це дозволяє розробникам та моделювальникам регламенту використовувати цей компонент більш гнучко та підлаштувати його під специфічні потреби різноманітних бізнес-сценаріїв.

Використовуйте Select з переліку Оновлених компонентів.

2. Основні функції

Компонент Select підтримує велику кількість опцій для застосування при взаємодії із формою процесу, які розподілені за вкладками.

  • Display

  • Data

  • Validation

  • API

  • Conditions

  • Table

  • Label: назва компонента, яка відображається поряд з ним.

  • Label Position: визначає положення назви відносно компонента (верх, праворуч, зліва, або внизу).

    • Для опцій Left (Left-aligned), Left (Right-aligned), Right (Left-aligned), Right (Right-aligned).

      • Label Width: встановлює ширину яку займає Label у відсотках відносно input.

      • Label Margin: встановлює відступ між Label та input у відсотках.

  • Placeholder: це текст, який відображається у полі коли воно пусте (незаповнене).

  • Description: опис компонента, який може допомогти користувачам зрозуміти його призначення.

  • Tooltip: текст, який відображається при наведенні курсора на компонент.

  • Tab Index: html атрибут який дозволяє контролювати навігацію по полям вводу за допомогою клавіатури. Детальніше можна почитати про нього в документації по html наприклад тут.

  • Hidden: поля, які приховані від користувача, але все ще є частинами форми й будуть передані при відправленні форми. Не забудьте прибрати прапорець в Clear when hidden, інакше будь-яке значення цього компонента буде порожнім.

  • Disabled: забороняє редагування.

  • Multiple Values: дозволяє вибрати декілька значень.

  • Data Source Type: визначає звідки брати значення. Щоб отримувати дані з серверу Див.

  • Default Values: визначте Value Property — назва властивості із JSON-відповіді ендпоінту, яка зберігатиметься як значення після селекту (наприклад, formKey).

  • Data Source Values: перелік значень, які відображаються в полі вибору.

  • Item Template: дозволяє налаштувати вигляд кожного елемента у випадаючому списку компонента Select. Кожен елемент списку може включати не тільки текст, але й додаткові візуальні елементи, такі як значки, зображення або інші HTML-елементи.

  • Refresh Options On: перемальовує компонент, якщо інший компонент змінюється Див.

  • Refresh Options On Blur: контролює, коли компонент Select оновлює свої варіанти вибору.

  • Clear value when on refresh options: дозволяє визначити поведінку щодо видалення вибраного значення, коли відбувається оновлення опцій для вибору.

  • Clear value when hidden: визначає, як буде поводитись вибране значення, коли компонент стає прихованим на сторінці.

  • Custom default value: дозволяє налаштувати власне, користувацьке значення за замовчуванням для компонента Select. Детальніше Custom default value.

  • Calculated value: дозволяє обчислювати значення компонента Select на підставі інших даних або умов. Детальніше Calculated value.

  • Allow manual override of calculated value: дозволяє користувачам вручну перевизначити обчислене значення компонента.

  • Validate On: визначає, коли цей компонент повинен активувати валідацію на клієнті (опції Зміна або Розмиття).

  • Required: поле обов’язкове для заповнення перед відправленням форми.

  • Custom error message: спеціальне повідомлення про помилку, яке відображається, коли дані не проходять валідацію.

  • Custom validation: власна валідація, яка дозволяє вам створити специфічні для ваших потреб перевірки на валідність.

  • JSONLogic Validation: дозволяє описати логіку перевірки у форматі JSON, що спрощує створення та управління правилами валідації даних.

  • Property name: ім’я цього поля для API-ендпоінту, яке відповідає назві таблиці у базі даних реєстру. Наприклад, licenses.

  • Advanced Conditions: дозволяють вам налаштовувати складні умови для компонента Select. Ці умови визначають, коли компонент стає видимим, доступним для вибору, або коли він повинен мати певне значення на основі умов, виразів або логіки.

  • Table View: визначає, чи відображувати елемент в таблиці та в EditGrid.

  • Table column width: дозволяє налаштовувати ширину стовпця у таблиці, яка відображається під час використання компонента Select в EditGrid.

  • Sort As Number: визначає, чи сортурувати значення як строку або як число при використані Select в EditGrid.

3. Формат даних

Компонент приймає масив об’єктів. Кожен об’єкт у масиві може містити різні поля та їх значення. У прикладі нижче наведено один об’єкт з полем "value" та значенням '123'. Label те що буде відображатися у списку.

Submission
Object
// Приклад: [{ value: 123, label: 'Label' }]

4. Основні положення

4.1. Custom default value

value = instance.getOriginalValues()[0].value

У цій функції використовується JS вставка. Див.

4.2. Calculated value

Досить часто необхідно відфільтрувати з API один елемент та одразу обрати його. Так можно організувати сценарій однозначного вибору одного поля відповідно до значення іншого. Можна використати перевірку instance.getOriginalValues().length === 1 - якщо у нас в списку тільки один елемент, ми одразу присвоюємо цей елемент в значення value.

Необхідно заповнити значення параметра Calculated Value таким чином:

Latest Select
if (instance.getOriginalValues().length === 1) {
  value = instance.getOriginalValues()[0].value;
}
Legacy Select
if (instance.selectOptions.length === 1) {
  value = instance.selectOptions[0].value;
}
У цій функції використовується JS-вставка. Див.Змінні у JS-вставках.