# Контролы формы: бизнес-логика

`form-controls` описывает поведение контролов дополнительных параметров в форме задачи:

- как пользователь вводит/редактирует значения;
- какие настройки типа ДП влияют на UI и валидацию;
- как отличать проблемы layout формы от проблем конкретного контрола.

Граница:

- `form-controls` = контроль и сохранение значения конкретного ДП;
- `task-forms` = контейнеры блоков и общий layout формы.

## Крупные группы контролов

Система различает четыре основные группы контролов по бизнес-назначению.

| Группа | Бизнес-назначение |
|---|---|
| File / MultiFile | Прикрепление и использование файлов в задаче |
| Lookup / MultiLookup | Выбор связанных задач из другой категории |
| SelectUsers | Выбор пользователей, групп и оргструктуры |
| Table EP | Структурированные табличные данные в карточке |

## Бизнес-правила по группам

### 1. File / MultiFile

Контролы вложений определяют, как пользователь прикрепляет файлы к задаче и ДП.

1. Тип определяется настройкой `IsMultifile` (один или несколько файлов).
2. Ограничения расширений и размера применяются до сохранения.
3. Один и тот же файл может быть связан с задачей и с ДП через link-таблицы.

### 2. Lookup / MultiLookup

Контролы выбора задач позволяют связывать текущую задачу с задачами из других категорий.

1. Lookup хранит одиночный выбор, MultiLookup — множественный.
2. Источник значений задается категорией/сводным разделом и может фильтроваться smart-условием.
3. Каскадные связи между ДП влияют на доступный набор значений в runtime.

### 3. SelectUsers

Контролы выбора людей позволяют назначить задаче пользователей, группы и подразделения.

1. Поддерживаются три подсистемы выбора: пользователи, группы, оргструктура.
2. В `SingleUserMode` сохраняется не более одного выбранного элемента.
3. Фильтрация может идти по группе, подразделению или смарт-фильтру.

### 4. Table EP

Табличный ДП структурирует произвольные данные в виде таблицы строк непосредственно в карточке задачи.

1. Таблица — это отдельный под-домен внутри ДП со схемой колонок и строк.
2. Колонки имеют типы, права, валидацию и настройку отображения.
3. Изменения строк проходят через отдельный pipeline сохранения и валидации.

## Сквозные пользовательские сценарии

Типовой сценарий взаимодействия пользователя с контролом формы задачи.

1. Пользователь открывает MTF/NTF и видит контролы по настройкам категории.
2. Пользователь меняет значение и сохраняет форму.
3. Сервер валидирует значение по типу ДП и записывает в таблицы значений.
4. UI получает новое состояние (pull/hybrid) и синхронизирует отображение.

В выпадающих списках Lookup, MultiLookup и SelectUsers выбор доступен с клавиатуры: стрелки вверх и вниз перебирают варианты, пропуская недоступные; Enter или пробел применяют выбранный вариант и закрывают список; Escape закрывает список, не применяя значение. В обоих случаях фокус возвращается на поле.

Список в контролах Lookup и MultiLookup открывается по клику на поле или на стрелку. Повторный клик по уже открытому списку ничего не меняет: список остаётся открытым, поле не выходит из режима редактирования (с версии 2.268). Закрыть список можно тремя способами: нажать Escape, кликнуть вне списка или выбрать значение. В мультивыборе клик по строке список не закрывает — следующие значения можно отмечать, не раскрывая список заново. У других выпадающих контролов (простой выпадающий список, выбор адреса, выбор пользователя) повторный клик по стрелке по-прежнему сворачивает список.

Простой выпадающий список (`vh-control-dropdown`) по умолчанию хранит выбранный элемент целиком. Если разработчик указал поле значения — в форме хранится только оно (например идентификатор), а в поле виден текст элемента. Во множественном выборе в поле видны все выбранные значения через запятую, список после отметки не закрывается — следующие значения отмечаются сразу. Если задан особый шаблон выбранного — вместо строки показывается он.

![Карточка задачи MTF с контролами ДП](https://help.1forma.ru/help-images/tasks/mtf-brand-01.png)

## Типовые инциденты

Наиболее частые симптомы при работе с контролами и их вероятные причины.

| Симптом | Наиболее вероятная причина |
|---|---|
| Поле видно, но не сохраняется | формат значения не соответствует ожиданию серверной части |
| Lookup пустой | фильтрация/каскад исключили данные источника |
| Список не закрывается повторным кликом по полю или стрелке | Штатное поведение с версии 2.268: повторный клик по открытому списку ничего не меняет, закрывать — Escape, кликом вне списка или выбором значения |
| SelectUsers показывает «не тех» | неверные allow/filtration настройки |
| Файл загрузился, но не отображается | link к ДП не создан или удален |
| Таблица отображает старые строки | не сработал refresh после update |