# ДП «Ссылка» (Lookup) и «Множественная ссылка» (MultiLookup) — справочник настроек

Оба типа выбирают значение из задач категории-источника и различаются количеством выбираемых задач: **Lookup** — одна задача, **MultiLookup** — несколько. Большинство настроек (источник данных, фильтры, иерархия, сортировка, подсказки) у них общие и хранятся в таблице `LookupParamSettings` — они собраны в разделе «Общие настройки (для обоих типов)» ниже. В разделах по типам описано только то, что специфично для каждого. Документ также описывает каскадные связи параметров и глобальные ключи `CustomSettings`.

## ДП «Ссылка» (Lookup)

Выбор **одной** задачи из категории или сводного раздела. Значение — ID выбранной задачи; на карточке отображается ссылкой (или текстом). Применяется, когда задаче нужна ссылка на одну связанную задачу: контрагент, договор, ответственный объект и т. п.

Базовые настройки (источник данных, иерархия, сортировка, подсказки, «Отображать в задаче») описаны в разделе «Общие настройки» ниже. Специфична для Lookup одна опция:

| Настройка | Поле БД | Описание |
|-----------|---------|----------|
| Отображать как радиокнопки | `ShowAsRadioButtons` (bit) | Значения выводятся блоком радиокнопок (до 10 пунктов). Повторный клик по выбранной радиокнопке снимает выбор; если ДП обязателен — снять выделение нельзя, только переключить. В режиме «только чтение» — обычный формат. Недоступно для MultiLookup |

![«Основные настройки» ДП «Ссылка» (Lookup): «Отображать в задаче», «Отображать как радио кнопки», «Быстрые подсказки»](https://help.1forma.ru/help-images/ext-params/dp_edit_more_lookup-general-0.png)

В карточке задачи режим радиокнопок выглядит так:

![ДП «Ссылка» в виде радиокнопок: выбор одного значения](https://help.1forma.ru/help-images/ext-params/lookup_radiobutton.png)

**Хранение.** Значение: `ExtParamValues.SelectedTaskID` (int) — ID выбранной задачи. В денормализации: `TasksInSubcatXXXDenormalized.ExtParamYYYNativeValue` = SelectedTaskID, `ExtParamYYYValue` = текст задачи.

## ДП «Множественная ссылка» (MultiLookup)

Выбор **нескольких** задач из категории или сводного раздела. Применяется для списков связанных задач, табличных подборок и чек-листов. Базовые настройки — в разделе «Общие настройки» ниже; здесь — специфичное для MultiLookup.

### Схема оформления

Способ отображения выбранных задач на карточке:

| Схема | Описание |
|-------|----------|
| По умолчанию (таблица) | Табличное представление выбранных задач |
| Облако тегов | Компактное отображение тегами |
| LookUp | В новом интерфейсе = Облако тегов; в старом = По умолчанию. **Будет удалено** |
| Список задач (To-do) | Чек-лист — см. раздел «Чек-лист» ниже |
| Чекбоксы | До 10 значений; автосохранение; в режиме чтения → облако тегов. **В разработке** |

### Параметры в гриде

**Кто читает настройки.** Настройки блока — состав и подписи колонок, размер страницы — без номера задачи отдаются только тому, у кого есть право просмотра или создания на категорию, и только если параметр в этой категории размещён. Право на другую категорию настройки чужого параметра не открывает. Выгрузка в Excel без номера задачи подчиняется тому же правилу. Если номер задачи передан, действует право на задачу. Строки выбранных задач читаются отдельно и только по праву на эти задачи.

Добавление колонок из категории-источника в табличное представление выбранных задач: системные параметры (Дата начала, Срок, Статус) и ДП категории. Колонка «Значение» (текст задачи) отображается всегда, удалить её нельзя. Кнопка «Добавить» (ранее «Создать») открывает выбор доступных параметров (с поиском по названию); удаление колонки — через контекстное меню строки. Настройка участвует в экспорте/импорте конфигурации: при переносе MultiLookup «Параметры в табличном представлении» включаются в пакет и восстанавливаются на целевой площадке автоматически. Это настройка колонок табличного представления выбранных задач внутри параметра; настройки табличного представления самого источника данных — отдельная сущность (см. вкладку «Источник данных» ниже). **Порядок колонок.** Колонки идут в том порядке, в котором перечислены в настройке; порядок меняется перетаскиванием строки параметра на нужное место и сохраняется вместе с остальными настройками ДП. После сохранения новый порядок действует и в форме настроек, и в табличном представлении выбранных задач в карточке.

Колонки ДП поддерживаемых типов пользователь может редактировать прямо в таблице, если ему разрешено менять этот ДП в задаче-источнике; отдельной настройки для этого нет. Какие типы редактируются — в [бизнес-описании ДП](https://help.1forma.ru/domains/ext-params/business.md), раздел «Табличный вид параметра Multilookup».

Формат числовых значений в колонках — в [бизнес-описании ДП](https://help.1forma.ru/domains/ext-params/business.md), раздел «Табличный вид параметра Multilookup».

![Вкладка «Параметры в гриде» MultiLookup: список добавленных в табличное представление параметров (ID, имя), кнопка «Создать»](https://help.1forma.ru/help-images/ext-params/dp_edit_more_multilookup-04.png)

| Настройка | Описание |
|-----------|----------|
| Количество строк на странице | Сколько строк таблица выбранных значений показывает без прокрутки; 0 — 20 строк. Остальные строки листаются прокруткой и подгружаются с сервера. Только для схемы «По умолчанию». Тестовый режим |

**Порядок строк и счётчик при ограниченном доступе.** Если пользователь не читает значения колонки таблицы, сортировка и фильтр по ней не применяются, а порядок строк и общее число строк считаются по всему набору выбранных значений. Подробно — в бизнес-описании ДП, раздел «Табличный вид параметра Multilookup».

**Кнопка «Развернуть».** Если выбрана схема «По умолчанию (таблица)» и в задаче выбрано больше 10 значений, в блоке таблицы появляется кнопка «Развернуть». Она открывает тот же отдельный экран параметра, что и у ДП «Таблица», в модальном окне на всю ширину экрана: там нет постраничного вывода — все выбранные значения листаются сплошной прокруткой, и самой кнопки «Развернуть» на этом экране уже нет. Текущая сортировка в развёрнутое окно не переносится: экран открывается заново. На форме создания задачи кнопка не показывается — только в сохранённой задаче.

Развёрнутое окно закрывается крестиком или клавишей Esc; клик по затемнённому фону его не закрывает.

В колонки выводится и сквозной ДП: в табличном представлении он показывает значение ДП-источника. Числовое значение подставляется для источников типов «Число» и «Деньги»; у сквозного над лукапом, галочкой или файлом числового значения в колонке нет.

### Чек-лист (схема оформления «Список задач», To-do)

При схеме оформления «Список задач (To-do)» MultiLookup отображается как чек-лист: выбранные задачи показываются пунктами с прогрессом, сроками и исполнителями. Чек-лист выводится в верхней части формы задачи, независимо от порядка ДП. ⚠️ MultiLookup со схемой «To-do» нельзя добавить в блоки ДП.

**Настройка чек-листа в категории.**

1. Создать категорию-справочник для задач чек-листа (из неё берутся пункты).
2. Выдать группам пользователей права в этой категории: «Создавать задачи», «Исполнять», «Пакетная обработка», «Просмотр всех задач». ⚠️ В чек-листах пользователь по умолчанию работает только с задачами, на которые у него есть права, — независимо от настройки MultiLookup «Отображать только доступные».
3. Включить в основных настройках категории опцию «Разрешено устанавливать срок при постановке». ⚠️ Обязательность срока и исполнителя в пункте чек-листа наследуется из настроек категории-источника: если там они обязательны, кнопка «Добавить» неактивна до их заполнения.
4. Настроить маршрут переходами: «Новая → Отклонена» (кнопка «Отклонить»), «Отклонена → Новая» («Обжаловать»), «Новая → Завершена» («Завершить»), «Завершена → Новая» («Обжаловать»). ⚠️ При отсутствии любого из этих переходов изменение прогресса чек-листа в интерфейсе вызовет ошибку.
5. Добавить в справочник ДП «Комментарий к задаче» (в системной категории «Задачи шаблонов ToDo list» оно уже создано — заново создавать не нужно).
6. В целевой категории создать ДП типа MultiLookup; на вкладке «Источник данных» указать категорию-справочник и отметить нужные статусы; на вкладке «Вид отображения» выбрать схему оформления «ToDo list».

**Чек-лист по шаблону.** Чтобы добавлять пункты пачкой по шаблону, настраиваются системные категории «Шаблоны ToDo list» и «Задачи шаблонов ToDo list» (права групп: «Создавать», «Исполнять», «Пакетная обработка», «Просмотр всех задач»; опция категории «Разрешено устанавливать срок при постановке»). Их идентификаторы и связанные ДП хранятся в пользовательском ключе `ToDoListSettings`. ⚠️ Если в нём не задан `TemplatesSubcatId`, кнопка «Добавить по шаблону» в ДП не отображается (в самой системной категории она недоступна по умолчанию). Эти системные категории используются только для создания задач по шаблону — для конкретного процесса создаются свои категории.

![Чек-лист по шаблону: системная категория «Шаблоны ToDo list» и кнопка «Добавить по шаблону» со списком шаблонов в задаче](https://help.1forma.ru/help-images/ext-params/template_todolist.png)

### Хранение

Значения — в отдельной таблице `MultiLookupValues`:

- `TaskID` — задача-владелец
- `ExtParamID` — ID ДП
- `SelectedTaskID` — выбранная задача
- `Comment` — комментарий к выбранному значению

В `ExtParamValues.SelectedTaskID` хранится **одно** из значений (для обратной совместимости).

## Общие настройки (для обоих типов)

Хранятся в таблице `LookupParamSettings`, применяются и к Lookup, и к MultiLookup (если в строке не указано иное).

### Вкладка «Основные настройки»

| Настройка | Поле БД | Тип | Описание |
|-----------|---------|-----|----------|
| Отображать в задаче | `DisplayInTask` | int | 0=Текст, 1=Текст+цвет, 2=Иконка+цвет, 3=Только иконка |
| Быстрые подсказки | `QuickHints` | bit | 3 последних выбранных значения для быстрого выбора. В Lookup подсказки сверяются с текущим отбором значений параметра: значение вне отбора не показывается и не выбирается по подсказке. **Не заменяют проверку прав** — доступность задач определяется настройками доступа категории-источника. Не работают при наличии активной связи параметров |

![«Основные настройки» ДП MultiLookup: «Отображать в задаче» и «Быстрые подсказки»](https://help.1forma.ru/help-images/ext-params/dp_edit_more_multilookup-general.png)

Для Lookup на этой вкладке есть ещё опция «Отображать как радиокнопки» (см. раздел «ДП «Ссылка» (Lookup)»).

Режимы «Отображать в задаче» (на примере MultiLookup-поля):

**Отображать текст** (`0`) — только названия задач, без цвета и иконки.

![Режим «Отображать текст»: названия задач без цвета](https://help.1forma.ru/help-images/ext-params/multilookup_task_view-1.png)

**Отображать текст и цвет** (`1`) — названия с цветом аватара задачи (по умолчанию серый).

![Режим «Отображать текст и цвет»: названия с цветом аватара](https://help.1forma.ru/help-images/ext-params/multilookup_task_view-2.png)

**Отображать только иконку** (`3`) — иконка аватара задачи (по умолчанию стандартная), без названия и цвета.

![Режим «Отображать только иконку»: иконки аватара без цвета](https://help.1forma.ru/help-images/ext-params/multilookup_task_view-5.png)

**Отображать иконку и цвет** (`2`) — иконка с цветом аватара задачи, без названия.

![Режим «Отображать иконку и цвет»: иконки с цветом аватара](https://help.1forma.ru/help-images/ext-params/multilookup_task_view-4.png)

Независимо от настроек табличного вида окно выбора параметра «Множественная ссылка» при каждом открытии группируется по сохранённым значениям: колонка «Выбор», группа «Сохраненные значения» сверху и «Доступно для выбора» ниже. Это поведение задано кодом и настройками не меняется; пользователь может снять группировку на время открытого окна.

### Вкладка «Источник данных»

Откуда берутся задачи для выбора и как они фильтруются:

![Вкладка «Источник данных» ДП «Ссылка»: категория или сводный раздел, фильтр по статусам, доступ и режим текста](https://help.1forma.ru/help-images/ext-params/lookup_source_settings.png)

| Настройка | Поле БД | Тип | Описание | Ограничения |
|----------------|---------|-----|----------|-------------|
| Категория | `SubcatId` | int FK → Subcategories | Категория-источник задач | Для категорий-источников учитывайте настройку категории «Разрешить HTML в тексте задачи» |
| Сводный раздел | `UnionId` | int FK → Unions | Сводный раздел вместо категории | Взаимоисключающе с Категорией |
| Включая статусы | `StatusFilter` / связь через `LookupParamAllowedStates` | — | Допустимые статусы задач в списке выбора. **В иерархическом режиме:** фильтр применяется к узлам дерева — папка в неразрешённом статусе скрывается целиком вместе с вложенными элементами. При текстовом поиске внутри иерархии фильтр по статусам не применяется. | |
| Смарт-фильтр | `SmartFilterId` | int FK → SmartFilters | Условия отбора задач | Работает только в карточке **существующей** задачи. Для НТФ → связи параметров |
| Отображать только доступные | `ShowOnlyAccessible` | bit | Только задачи с правами доступа (в ДП и в окне выбора) | **Только MultiLookup**. Не распространяется на список задач (To-do) |

Контекстные параметры смарт-фильтра:

- `@eventParam1` — ID текущей категории
- `@eventParam2` — ID задачи-источника
- `@eventParam3` — JSON значений строки таблицы (если Lookup в колонке ДП Таблица)
- `@eventParam4` — ID блока используется

**Перенос конфигурации.** Админские настройки табличного представления источника данных — состав и порядок колонок, «Доступность», «Видимость по умолчанию», «Стиль», «Выравнивание», «Ширина», «Тип фильтра», а также «Тип статуса», «Группировать по», «Группировать одной строкой» и «Позиция закрепления» — переносятся между площадками вместе с параметром. Личные настройки пользователей остаются на своей площадке. Если у параметра на приёмнике уже была сохранена своя настройка источника, она заменяется настройкой с площадки-источника. Категорию-источник после переноса выбирают заново — см. [правила переноса конфигурации](https://help.1forma.ru/domains/migration/README.md).

### Вкладка «Вид отображения»

Форма представления списка значений (плоский список, дерево, сортировка):

![Вкладка «Вид отображения» ДП «Ссылка»: иерархический режим, выпадающий список, колонка сортировки и схема оформления](https://help.1forma.ru/help-images/ext-params/lookup_display_settings.png)

| Настройка | Поле БД | Тип | Описание |
|----------------|---------|-----|----------|
| Иерархический | `IsHierarchical` | bit | Дерево; настройки в категории → вкладка «Иерархический справочник» |
| Запретить выбирать папки | `DenySelectFolders` | bit | Только конечные элементы (при иерархическом) |
| Выпадающий список | — | bit | Значения для выбора отображаются выпадающим списком |
| Колонка сортировки | `SortColumnId`, `OrderTaskParam` | int FK · int | Чем упорядочиваются значения: дополнительным параметром категории-источника (`SortColumnId`) или свойством задачи (`OrderTaskParam`). Это один выбор: либо ДП, либо свойство задачи, одновременно они не задаются. Выбор не зависит от «Параметров в табличном представлении» — один и тот же ДП можно одновременно вывести в табличное представление и использовать для сортировки. Применяется по умолчанию при отображении на карточке задачи. Контрол выбора поддерживает поиск по названию ДП. При сводном разделе: только ДП из всех категорий. В Канбан-представлении категории с фильтрацией по этому ДП колонки канбана упорядочиваются согласно «Колонке сортировки». НЕ допустимы: URL, Адрес, Email, Users, MultiLookup, Чекбокс, Дерево, Сквозной, Таблица, Файл |
| Отображать как текст | `DisplayAsText` | bit | Значение отображается текстом, не ссылкой. Если в списке задач включена группировка по этому ДП — группирующая задача тоже отображается не ссылкой |

#### Сортировка по свойствам задачи

Кроме дополнительного параметра категории-источника значения лукапа и мультилукапа можно упорядочить по свойству самой задачи. В выборе «Колонка сортировки» доступны три свойства: **Текст задачи**, **Номер задачи** и **OrderID**.

- **Текст задачи** — значения упорядочены по тексту задачи.
- **Номер задачи** — по номеру задачи.
- **OrderID** — по порядковому номеру задачи.

Свойство задачи и дополнительный параметр взаимоисключающие: при выборе свойства задачи идентификатор ДП очищается, при выборе ДП очищается свойство задачи. Один выбор — одно значение.

Если настройка не заполнена, поведение прежнее: лукап показывает значения по тексту задачи, мультилукап сохраняет своё прежнее упорядочивание.

При постраничной выдаче порядок устойчив: при равных значениях колонки сортировки строки упорядочиваются по номеру задачи, поэтому строки не дублируются и не пропадают при переходе между страницами.

⚠️ Иерархическое представление лукапа сортировку по свойству задачи не учитывает — оно доводится отдельной доработкой. На плоский список, окно выбора и табличное представление выбранных значений мультилукапа правило распространяется.

> **Иерархический режим + фильтр по статусам:** если одновременно включены «Иерархический» и «Включая статусы», дерево отображает только задачи в разрешённых статусах. Папка (узел-родитель) в запрещённом статусе скрывается вместе со всей подветкой. При текстовом поиске в иерархическом лукапе фильтр по статусам не применяется.

**Дополнительные настройки иерархического режима.** При включённом «Иерархический», помимо «Запретить выбирать папки», доступны: «Отображать отфильтрованные части веток» (устаревшая, больше не используется — скрывала участки ветвей от корня до первого видимого элемента), «Максимальное количество элементов иерархии» (лимит задач, подгружаемых из дерева, — позволяет видеть полный список даже в больших категориях) и «Загружать все дерево». При включённом «Загружать все дерево» дерево загружается целиком; при выключенном — узлы подгружаются по уровням по мере раскрытия, а поиск по элементам выполняется на стороне сервера (полезно для больших справочников). Настройка распространяется и на Lookup-колонки ДП «Таблица», ссылающиеся на иерархический Lookup.

**Поведение иерархического выбора.** Голубым выделяется элемент, который будет сохранён в ДП (тот, на который кликнули); галочка/минус/пустой квадрат отражают подчинённость в иерархии и служат для выбора, но не показывают, что именно сохранится. При клике на родителя он выделяется голубым и галочкой, потомки помечаются галочками каскадно, но голубым не выделяются — по «Ок» сохранится только сам родитель. Если у выбранного родителя снять галочку с одного потомка — голубое выделение с родителя снимается, галочка меняется на «минус», остальные потомки выделяются голубым, и в ДП попадают все элементы, кроме снятого.

**Путь значения.** В иерархическом режиме значение показывается вместе с полным путём в дереве: в выпадающем списке путь выводится подписью под названием, а в выбранном (закрытом) значении — рядом с названием. Это помогает различать одноимённые значения на разных уровнях иерархии, в том числе в результатах текстового поиска, где дерево не показано.

Настройка окна выбора значений в виде таблицы (вкладка «Табличный вид»):

| Настройка | Описание |
|----------------|----------|
| Табличный вид | Настройка таблицы для окна выбора значений (как табличный вид категории); показываются только колонки с включённой «Видимость по умолчанию». Персональные настройки сохраняются локально |
| Сворачивать группы | Группы свёрнуты по умолчанию (только для стандартного представления категории) |

![Вкладка «Табличный вид» MultiLookup: ссылка «Настройки» табличного представления, «Сворачивать группы», «Кол-во выводимых записей»](https://help.1forma.ru/help-images/ext-params/dp_edit_more_multilookup-5.png)

Как ведёт себя группировка строк по колонкам в окне выбора значений — в [Гриды — бизнес-логика](https://help.1forma.ru/domains/grids/business.md), раздел «Группировка».

## Связи параметров (каскадные зависимости)

Настраиваются через отдельный интерфейс «Связи между параметрами» (dp_links).

| Настройка | Описание |
|-----------|----------|
| Родительский параметр | ДП-источник |
| Подчинённый параметр | ДП, значения которого фильтруются |
| Источник данных | Таблица или представление БД для связи (ExtParamValues, TasksInSubcatXXXDenormalized, пользовательское представление) |
| Колонка для отбора | Столбец со значением родительского ДП |
| Значение подчинённого | Столбец со значением подчинённого ДП |
| Текст подчинённого | Столбец с отображаемым текстом. Значения списка показываются на языке пользователя, если у подчинённого параметра нет собственного источника значений; если источник задан у самого параметра, текст выводится как есть |
| Жёсткая связь | Да = дочерний пуст без родителя; Нет = фильтрация по заполненным родителям |
| Активно | Временное отключение связи |

### Допустимые комбинации и ограничения связей

Какие типы родительского и подчинённого ДП можно связать. В колонке «Типы связей»: **Ж** — жёсткая связь (подчинённый пуст без родителя), **С** — связь по заполненным родителям. Двухбуквенные коды (ЖЖ, ЖС, СЖ) описывают сочетание для второго (дополнительного) родителя.

| Родитель | Подчинённый | Типы связей | Доп. родитель |
|----------|-------------|-------------|---------------|
| Lookup | Lookup | Ж, С | Выпадающий список (ЖЖ, ЖС, СЖ) |
| Выпадающий список | Lookup | Ж, С | Текст/Число (ЖЖ, ЖС, СЖ) |
| Lookup | Выпадающий список | Ж, С | |
| Выпадающий список | Выпадающий список | Ж | |
| Текст/Число | Lookup | Ж, С | Текст/Число (ЖЖ, ЖС, СЖ) |
| Текст/Число | MultiLookup | Ж, С | Текст/Число (ЖЖ, ЖС, СЖ) |
| MultiLookup | Выпадающий список | Ж, С | |
| MultiLookup | Lookup | Ж, С | |
| Выпадающий список | MultiLookup | Ж, С | |
| Lookup | MultiLookup | Ж, С | Текст/Число (ЖЖ, ЖС, СЖ) |

Правила, которые нужно учитывать при настройке связей:

- Нельзя создать цикл (A→B и B→A)
- Нельзя: подчинённый в таблице, родитель вне таблицы
- При наличии связи подсказки не отображаются для подчинённых
- Связи внутри строки ДП Таблица поддерживаются (колонка → колонка)

## Глобальные настройки (CustomSettings)

Ключи, влияющие на поведение ДП «Ссылка» во всей системе:

| Ключ | Тип | Описание |
|---|---|---|
| `AllLocalesSearchEpIds` | `int[]` | Список ID Lookup-ДП, в которых текстовый поиск проверяет совпадение по локализованным значениям всех настроенных локалей задачи-источника (а не только по локали пользователя). Применяется к выпадающему списку и к фильтрам lookup-колонок в таблицах. По умолчанию — пустой массив (поиск идёт только в текущей локали). Подробнее: [Кастомные настройки → AllLocalesSearchEpIds](https://help.1forma.ru/domains/system/settings-custom.md#alllocalessearchepids) |
| `MultiLookupChooseAllLimit` | `int` | Максимальное число задач, выбираемых кнопкой «Выбрать все» в MultiLookup (с учётом фильтрации). По умолчанию — 10 000. Подробнее: [Кастомные настройки → MultiLookupChooseAllLimit](https://help.1forma.ru/domains/system/settings-custom.md#multilookupchoosealllimit) |

## Порядок значений в выпадающем списке

Порядок задач в выпадающем списке и в табличной части множественной ссылки настраивается в поле «Колонка сортировки»: значения можно упорядочить по дополнительному параметру категории-источника или по свойству самой задачи — по алфавиту названия, по номеру задачи или по её порядковому номеру. Выбор взаимоисключающий: указывается либо параметр, либо свойство задачи. Если колонка не выбрана, действует стандартный порядок — у ссылки по тексту задачи, у множественной ссылки по номеру задачи. В иерархическом представлении сортировка по свойствам задачи не применяется. При постраничной подгрузке больших списков порядок сохраняется: строки не перемешиваются между страницами.