Довідник JSON: поля клієнта (custom_fields_json)
Короткий опис властивостей об’єкта одного поля у налаштуваннях Поля клієнтів (/settings-page/client-fields). Збережена конфігурація містить обгортку з ключем custom_fields_json; усередині — об’єкт, де ключ — технічна назва поля (латиницею), значення — опис поля.
Покрокове налаштування: Як налаштувати поля клієнтів. Видимість можна змінити там само (одна кнопка «Зберегти» в заголовку) або на сторінці op-settings — той самий блок, інше збереження.
Структура збережених даних
Після збереження в налаштуваннях інстансу використовується параметр client_fields_json; усередині — об’єкт з полем custom_fields_json:
{
"custom_fields_json": {
"department": {
"type": "STRING",
"label": "Відділ"
}
}
}
Значення, які оператори вводять у картці клієнта, потрапляють у extra_data клієнта за ключами полів.
Базові властивості поля
| Властивість | Обов’язковість | Опис |
|---|---|---|
type | Фактично обов’язкове | Тип даних поля. Див. таблицю типів нижче. |
label | Рекомендовано | Підпис поля в інтерфейсі (картка клієнта, таблиці). |
Дозволені значення type
| Значення | Призначення |
|---|---|
STRING | Короткий текст |
TEXT | Багаторядковий текст |
SELECT | Вибір з фіксованого списку |
SELECTAPI | Вибір з джерела через API |
FILE | Файл |
INTEGER | Ціле число |
BIGINT | Велике ціле |
FLOAT | Дробове число |
DATE | Дата |
BOOLEAN | Логічне так/ні |
Додаткові властивості (форма та JSON)
На сторінці Поля клієнтів частину параметрів можна задати в картці поля (розділи форми); усі вони також можуть бути внесені або виправлені в JSON. У збереженому JSON багато перемикачів зберігаються як рядок "true"; якщо опція вимкнена — ключ зазвичай відсутній.
Загальні та редагування
| Ключ | Тип у JSON | Що робить |
|---|---|---|
default | рядок | Початкове значення при створенні / за замовчуванням (якщо підтримується сценарієм відображення). |
unique | "true" | Заборона дублікатів значення по полю (логіка перевірки залежить від сценаріїв використання). |
non_editable | "true" | Поле лише для перегляду: оператори не змінюють значення в інтерфейсі. |
Відображення в таблиці
| Ключ | Тип у JSON | Що робить |
|---|---|---|
sortable | "true" | Увімкнути сортування за колонкою в таблиці клієнтів. |
width | рядок | Ширина колонки в пікселях, наприклад "120". |
align | "" / "start" / "center" / "end" | Вирівнювання заголовка колонки. Порожнє — поведінка за замовчуванням. |
display_in_table | "" / "image" | Режим відображення в комірці: зокрема image — показ зображення (за наявності відповідних даних). |
display_type | "link" | Для рядкових полів: значення трактується як посилання, відкривається в новій вкладці. |
click_action | "open" | Для рядкових полів: по кліку відкривається модальне вікно редагування. Не комбінуйте з display_type: "link" — у формі вибір «дії при кліку» взаємовиключний. |
Видимість
| Ключ | Тип у JSON | Що робить |
|---|---|---|
hidden_all | "true" | Приховати поле скрізь у картці та пов’язаних формах (як у перемикача в інтерфейсі). |
hidden_in_table | "true" | Не показувати колонку у списку вибору колонок таблиці. |
hide_in_filter | "true" | Приховати поле у фільтрах. |
hidden_in_create_popup | "true" або true | Приховати поле у вікні швидкого створення (якщо використовується такий сценарій). |
Валідація: rules
Масив рядків — імена правил. Доступні значення в інтерфейсі підбору:
| Значення | Призначення |
|---|---|
required | Обов’язкове заповнення |
email | Формат email |
digits | Лише цифри |
latin | Лише латинські символи |
latinDigits | Латиниця та цифри |
stringMaxLength | Обмеження довжини рядка (потрібні додаткові параметри в конфігурації — у складних випадках правте JSON за зразками) |
json | Перевірка формату JSON |
Складні перехресні перевірки та умовна логіка можуть описуватися окремим об’єктом validate у JSON. Для таких сценаріїв використовуйте Приклади JSON на сторінці налаштувань або резервну копію перед змінами.
Приклад:
"email_field": {
"type": "STRING",
"label": "Email",
"rules": ["required", "email"]
}
Приклади JSON на сторінці
У нижній частині редактора — блок «Приклади JSON»: п’ять готових фрагментів тієї ж структури, що й у інструкції (розділ Приклади JSON). У документації до кожного сценарію додано розгорнутий опис призначення; у продукті залишаються лише короткі назви перемикача.
Обмеження та поради
- Невалідний JSON не зберігається: перевірте коми, лапки та дужки.
- Перед масовими змінами збережіть копію конфігурації.
- Видалення поля з конфігурації не видаляє автоматично ключ з налаштувань видимості картки; за потреби оновіть редактор полів у картці клієнта.