Компонент Select

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

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

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

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

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

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

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

  • Display

  • Data

  • Validation

  • API

  • Conditions

  • Logic

  • 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. Ці умови визначають, коли компонент стає видимим, доступним для вибору, або коли він повинен мати певне значення на основі умов, виразів або логіки.

  • Advanced Logic: в контексті компонентів веб-форм означає більш складні та гнучкі умови і правила, які можна встановити для взаємодії елементів форми між собою. означає, що можна налаштовувати не тільки прості відображення чи приховування полів на основі одного-двох умов, але й створювати більш складні логічні вирази, які реагують на різні стани та вхідні дані.

    • Logic Name: назва логічного блоку або умови, яку ви встановлюєте. Вона використовується для ідентифікації цієї конкретної логіки або умови в межах вашої форми.

    • Trigger: умова або подія, яка викликає виконання екшену (дії). Тригер може бути будь-яким станом форми (наприклад, значенням певного поля) або подією (наприклад, подія "клік" чи "введення" в конкретному полі).

      • Type: параметр, який вказує, який тип логіки ви використовуєте. Simple: проста логіка, де ви вказуєте одну умову або правило для тригера. Javascript: логіка з використовуванням JavaScript код для складніших умов та правил. Детальніше див. Змінні у JS-вставках.

      • When the form component: вказує на те, коли ця логіка або умова буде застосована. Відображається для типу Simple.

      • Has the value: вказує на конкретне значення, яке ви очікуєте від компонента форми для виконання цієї умови чи тригера. Відображається для типу Simple.

    • Action: дія, яка виконується, коли відбувається тригер. Екшин може бути різними діями над формою.

      • Action Name: назва для ідентифікації цієї конкретної дії в межах вашої форми.

      • Type: тип дії, яку ви хочете виконати. Доступно Property (вказує на конкретну властивість компонента форми, яку ви хочете змінити.)

      • Component Property: вказує на конкретну властивість компонента форми, яку ви хочете змінити. Відображається для типу Property. Disabled: заблокований стан компонента. Можливо встановити true або false.

  • 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-вставках.