Перейти к содержанию

Справочник типов ДП

Источники: DDL (dbo.ExtParams), reference/database/extparams.md, тест (basic-admin-test-1.md)

Обзор типов

Тип ДП задаётся при создании и не может быть изменён после создания. Если тип выбран неверно --- удалить ДП и создать заново (удаление невозможно, если ДП используется в задачах).

Полный перечень типов

Тип ДП (рус.) ExtParamType (БД) Таблица значений Поле значения Денорм. тип
Текст Text ExtParamValues ExtParamValue, ExtParamValueForSort varchar/nvarchar
Большой текст с форматированием TextArea ExtParamValues ExtParamValue ---
Большой текст без форматирования TextareaWOFormat ExtParamValues ExtParamValue ---
Число NumericValue ExtParamValues DecimalValue decimal(18,N)
Деньги Money ExtParamValues MoneyValue money
Дата Date ExtParamValues DateTimeValue datetime
Дата и время Datetime ExtParamValues DateTimeValue datetime
Флажок (чекбокс) Checkbox ExtParamValues BoolValue / ExtParamValueForSort bit
Выпадающий список Select ExtParamValues ExtParamValue, DataSourceItemID varchar/nvarchar(1000)
Выпадающий список с редактированием Combobox ExtParamValues ExtParamValue, DataSourceItemID varchar/nvarchar(1000)
Дерево Tree ExtParamValues ExtParamValue, DataSourceItemID varchar/nvarchar(1000)
Lookup (поле подстановки) LookUpField ExtParamValueSelectedTasks SelectedTaskID int
Multilookup (выбор нескольких задач) MultiSlctSubcatTasks ExtParamValueSelectedTasks SelectedTaskID ---
Выбор пользователей SelectUsers ExtParamSelectUsersValues + ...Groups + ...OrgUnits UserID / GroupID / OrgUnitID ---
Таблица Table ExtParamTableValues Value (RowID, ColumnID) varbinary(max)
Файл File FileStorageFileToExtParamLinks FileId ---
Нумератор Numerator ExtParamValues ExtParamValue ---
URL (ссылка) URL ExtParamValues ExtParamValue ---
Адрес Address ExtParamValues + Address AddressId int
Адресаты email ExtParamAddressees ExtParamValues ExtParamValue ---
Сквозной Through --- (вычисляется) --- ---

Источник: DDL dbo.ExtParams.ExtParamType VARCHAR(20), SP cm_sp_generateFT_json, reference/database/extparams.md.

Типы ДП: детальное описание

ДП «Текст» (Text)

Максимальная длина: 8000 символов.

Хранение в БД: - ExtParamValues.ExtParamValue --- основное значение. - ExtParamValues.ExtParamValueForSort --- для сортировки. - ExtParams.MaxLength (INT, nullable) --- ограничение длины на уровне определения ДП.

Настройки: - Маска для ввода номера телефона --- только в ДП «Текст» поддерживается маска телефона. Источник: тест (Базовый, тест 1, вопрос 12, ответ B). - Регулярное выражение (ExtParams.RegExp) --- валидация введённого значения. - Сообщение об ошибке регулярного выражения (ExtParams.RegExpErrorMessage).

ДП «Большой текст с форматированием» (TextArea)

Описание: текст длиной свыше 1000 символов с возможностью форматирования, отключения тегов Microsoft Word и просмотра HTML-кода.

Хранение: ExtParamValues.ExtParamValue. Содержит HTML-разметку.

Ограничения: ДП типов TextArea и File/Table не индексируются при денормализации.

Источник: README.md.

ДП «Большой текст без форматирования» (TextareaWOFormat)

Описание: текст длиной свыше 1000 символов без возможности форматирования.

Хранение: ExtParamValues.ExtParamValue. Без HTML.

ДП «Число» (NumericValue)

Хранение: ExtParamValues.DecimalValue. Денормализация: decimal(18, N), где N = Scale из ExtParamNumericSettings (по умолчанию 8).

Диапазон: от --9 999 999 999 до 9 999 999 999. При вводе значения за границами --- автоматическая замена на граничное значение без предупреждения.

Режимы отображения: - Текстовое поле (по умолчанию). - Нумератор --- требуется указать min, max и шаг. - Слайдер --- визуальная шкала с шагом. Варианты цвета: без цвета, интенсивность цвета, температура.

Настройки: - Длина дробной части (макс. 8 знаков). Настройка не ограничивает ввод --- оригинальное значение хранится без округления и видно при редактировании. - Использовать 0 для пустых значений (по умолчанию null).

При включённой настройке пустое значение (null) отображается в табличном представлении как 0. Фильтрация по значению 0 (равно, меньше или равно, больше или равно, содержит) одновременно находит и задачи с реальным значением 0, и задачи с пустым значением. Исключение значения 0 (не равно, не содержит) исключает оба варианта. - Разделитель групп разрядов (пробел). - Отображать с дробной частью / без.

Источник: admin.md.

ДП «Деньги» (Money)

Хранение: ExtParamValues.MoneyValue. Денормализация: money.

Диапазон: от --922 337 203 685 477 до 922 337 203 685 477. Автоматическая замена на граничное при превышении, без предупреждения.

Настройки: - Длина дробной части (макс. 8). По умолчанию 2. - Минимальное / максимальное значение. - Шаг --- не работает для данного типа. - Использовать 0 для пустых значений.

При включённой настройке пустое значение (null) отображается в табличном представлении как 0. Фильтрация по значению 0 (равно, меньше или равно, больше или равно, содержит) одновременно находит и задачи с реальным значением 0, и задачи с пустым значением. Исключение значения 0 (не равно, не содержит) исключает оба варианта. - Разделитель групп разрядов. - Отображать с дробной частью / без.

Поведение при вводе (MTF/NTF):

Компонент ControlMoneyComponent (control-money.component.ts) сохраняет введённое значение при следующих событиях: - клик вне поля (pointerdown за пределами инпута); - Enter; - потеря фокуса (blur); - Tab (v2.267+).

До v2.267 нажатие Tab не вызывало сохранение: панель ДП успевала уничтожить компонент через *ngIf="viewModeWrite$ | async" раньше, чем blur-подписка срабатывала. Начиная с v2.267 Tab обрабатывается явно — по аналогии с ДП «Число» (ControlNumberComponent).

Источник: README.md.

ДП «Дата» (Date)

Хранение: ExtParamValues.DateTimeValue. Денормализация: datetime.

Настройки: - Видимые даты --- диапазон отображаемых дат (от / до). - Доступные даты --- диапазон выбираемых дат (подмножество видимых).

Валидация при ручном вводе. При ручном вводе даты в поле (а не выборе через календарь) ограничения «Доступные даты» и «Видимые даты» применяются так же, как при выборе через календарь: после снятия фокуса значение вне диапазона не применяется и не сохраняется в задачу. Ограничение «Видимые даты» теперь блокирует не только отображение в календаре, но и выбор/ввод даты вне заданного диапазона. Поведение единое для ДП «Дата» и компонента даты в ДП «Дата и время».

  • Режимы границ: фиксированная дата, относительная (Вчера/Сегодня/Завтра), смарт-выражение.
  • Относительные даты определяются по часовому поясу сервера.

Источник: README.md.

ДП «Дата и время» (Datetime)

Аналогично ДП «Дата», но включает компонент времени.

Хранение: ExtParamValues.DateTimeValue. Денормализация: datetime.

ДП «Флажок / Чекбокс» (Checkbox)

Допустимые значения при передаче: 1, 0, false, true, да, нет.

Хранение: ExtParamValues.BoolValue / ExtParamValueForSort. Денормализация: bit.

Стили отображения: - Чекбокс --- стандартный квадрат с галочкой (по умолчанию). - Свитчер --- переключатель вкл/выкл. - Радио выбор --- два варианта «Да» / «Нет».

Источник: README.md.

ДП «Выпадающий список» (Select)

Описание: выбор одного значения из фиксированного перечня.

Максимальная длина значения: 200 символов. Источник: README.md.

Хранение: ExtParamValues.ExtParamValue (текст) + DataSourceItemID (ID элемента). Денормализация: varchar/nvarchar(1000).

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

PostgreSQL-совместимость (v2.267+): при источнике «Из таблицы» на PostgreSQL-инсталляции система корректно обрабатывает текстовые значения в valueColumn. До v2.267 при текстовых значениях (например, «Тест 1») в НТФ возникала ошибка «Произошла ошибка. Обратитесь в техническую поддержку.» из-за попытки привести строку к типу int. Исправлено введением явного приведения valueColumn::text = @ChildValue в запросе к источнику.

ДП «Выпадающий список с редактированием» (Combobox)

Аналогичен Select, но пользователь может ввести своё значение.

Максимальная длина: 200 символов.

ДП «Дерево» (Tree)

Описание: отображение древовидной структуры для выбора значения.

Хранение: ExtParamValues.ExtParamValue + DataSourceItemID. Денормализация: varchar/nvarchar(1000).

ДП «Lookup (поле подстановки)» (LookUpField)

Описание: выбор одной задачи из категории-источника. Единственным допустимым значением является ID существующей задачи.

Хранение: ExtParamValueSelectedTasks.SelectedTaskID. Денормализация: int.

Настройки (ключевые): - Источник данных: категория или сводный раздел + фильтр по статусам. - Смарт-фильтр (работает только в карточке уже созданной задачи). - Иерархический режим (отображение в виде дерева). - Колонка сортировки. - Отображать как радио кнопки (до 10 значений). - Быстрые подсказки (3 последних выбранных значения). - Отображение в задаче: текст, текст+цвет, иконка, иконка+цвет. - Табличный вид для выбора значений.

Источник: README.md.

ДП «Multilookup (выбор нескольких задач)» (MultiSlctSubcatTasks)

Описание: выбор нескольких задач из категории с возможностью добавления комментариев.

Хранение: ExtParamValueSelectedTasks --- несколько записей с одним TaskID + ExtParamID.

Схема To-do list: дополнительная таблица ExtParamValueSelectedTaskFolders (вкладки с именами).

Операции через API/SmartScript: - Добавить: ВСтроку(ID_задачи). - Удалить: '-' + ВСтроку(ID_задачи).

Источник: academy-patterns.md.

ДП «Выбор пользователей» (SelectUsers)

Описание: выбор пользователей, групп, элементов орг. структуры.

Хранение (три таблицы): - ExtParamSelectUsersValues --- пользователи (UserID). - ExtParamSelectUsersValuesGroups --- группы (GroupID). - ExtParamSelectUsersValuesOrgUnits --- орг. единицы (OrgStructureUnitID).

Денормализация в SelectUserValue / NativeValue: только если одновременно: (1) включен «Разрешить сохранять не более одного элемента» и (2) активна только одна из настроек: пользователи, группы или орг. единицы.

Настройки: - Разрешить сохранять не более одного элемента. - Разрешить выбирать пользователей / группы / орг. единицы (независимые флаги). - Ограничить выбор: без ограничений, членами группы, смарт-выражением. - Ограничить выбор орг. единиц: без ограничений, из подразделения, смарт-выражением. - Ограничить выбор типами орг. структуры.

Формат значения через API: 

{"Users":{"Deleted":[...],"Added":[...]},"Groups":{"Deleted":[...],"Added":[...]},"OrgUnits":{"Deleted":[...],"Added":[...]}}

JS API (ep.val()):

При передаче значения через JS API (JS-вставки) используйте объектный формат без обёртки в кавычки:

ep3606.val({"users":[{"userId": 4561}],"groups":[],"orgUnits":[]})

Источник: README.md, academy-patterns.md.

ДП «Таблица» (Table)

Описание: ввод данных в табличном виде. При действиях с ДП «Таблица» автоматически сохраняются другие ДП на карточке задачи.

Хранение: ExtParamTableValues (RowID, ColumnID, Value). Настройки колонок: ExtParamTableSettings. Денормализация: varbinary(max).

Типы колонок: Текст, Большой текст без форматирования, Выпадающий список, Текст с маской, Деньги, Дата и время, Дата, Телефон, Lookup, Чекбокс, Число, Файл, Виртуальная, Шаблонная, Блок кнопок, Выбор пользователей.

Скрытие колонок по статусу/группе: каждую колонку можно скрыть в зависимости от статуса задачи или группы текущего пользователя. Настраивается через «Дополнительные настройки блока» в настройках ДП в категории.

Доступ на чтение/редактирование по колонкам: для каждой колонки в «Дополнительных настройках блока» можно настроить доступ на чтение и редактирование отдельно.

Режимы колонки: Необязательно, Обязательно (в рамках таблицы), Только для чтения, Скрытая (нет доступа из автоматизаций), Невидимая (есть доступ из автоматизаций).

Режимы отображения таблицы: Таблица, Ссылка (открытие в новой вкладке), Динамический набор полей.

Настройки таблицы: - Ключевой столбец (для импорта/множественного выбора). - Максимальная высота в PX. - Экспорт / Импорт (Excel). - Сохранять строку после редактирования (автосохранение). - Создавать строки в модальном окне. - Секции столбцов. - Динамическая обязательность (условные правила обязательности ячеек).

Ограничение: настройка «Обязателен для завершения» (ExtParamsInSubcat.IsRequired) к ДП «Таблица» неприменима — тип является составным, механизм IsRequired для него не работает. Для контроля заполненности используйте обязательность колонок (режим «Обязательно») или динамическую обязательность. - Сортировка по умолчанию (один столбец). - Смарт-выражения для вычисления значений колонок. - Итоговая строка (для типов Число, Деньги).

Диапазон значений в колонках таблицы: - Число: от --99 999 999 999 999 до +99 999 999 999 999. - Деньги: от --922 337 203 685 476.99 до +922 337 203 685 476.99.

Операции через API/SmartScript: - Добавить строку: '+[{ID_колонки:{"First":"значение"}}]'. - Обновить строку: '={"First":"ID_строки","Second":{ID_колонки:{"First":"значение"}}}'. - Удалить строку: '-ID_строки'. - Полная перезапись: '|{...}' (удалить все + создать) или '#{...}' (diff).

First/Second — два уровня использования. Эта конструкция используется в двух разных контекстах и имеет разную семантику:

  • Уровень строки (операция «Обновить»): {"First": "RowID", "Second": {объект_колонок}} — здесь First — идентификатор обновляемой строки, Second — объект со значениями колонок.
  • Уровень значения ячейки: {"First": "значение", "Second": "доп.значение"} — здесь First — основное значение ячейки, Second — вспомогательное (используется только в отдельных типах колонок, см. таблицу ниже).

Формат значений по типам колонок:

Тип колонки First Second
Текст / Большой текст без форматирования строка —
Текст с маской / Телефон строка —
Число / Деньги число в виде строки ("7", "1234.56") — десятичный разделитель — точка —
Чекбокс "true" или "false" (строкой) —
Дата "yyyy-MM-dd" —
Дата и время "yyyy-MM-ddTHH:mm:ss" строка часового пояса (опционально)
Выпадающий список (Select, Combobox) Id варианта (рекомендуется) или текстовое значение —
Lookup (LookUpField) TaskID целевой задачи taskText для отображения (опционально)
Выбор пользователей (SelectUsers) список идентификаторов через запятую: UserID, g{GroupID}, o{OrgUnitID} (например "123,456,g78,o12") —
Файл FileID или массив FileID через запятую —

Пример добавления строки с несколькими типами колонок (псевдокод, ColumnID — числовые идентификаторы конкретных колонок):

'+[{
  101: {"First": "123,456"},
  102: {"First": "7"},
  103: {"First": "true"},
  104: {"First": "текст значение"},
  105: {"First": "2026-04-30"},
  106: {"First": "2080000", "Second": "Связанная задача"}
}]'

Где: 101 — колонка SelectUsers (IDs через запятую), 102 — Число, 103 — Чекбокс, 104 — Текст, 105 — Дата, 106 — Lookup (Second — отображаемый текст, опционально).

Экранирование. В Lua ChangeExtParamValue и других SmartScript-движках строка-команда передаётся как обычный строковый литерал; внутренние двойные кавычки JSON экранируются по правилам языка-источника (\" в C#/Lua-string, \\" при двойной строковой обёртке). Спецсимволы внутри значений (", \, перевод строки) экранируются по стандарту JSON.

Поведение при ошибке. При невалидной структуре операции (неизвестный ColumnID, неподходящий тип значения, нарушение обязательности колонки, отсутствие прав на колонку) операция возвращает ошибку валидации и строка не сохраняется. Идентификатор проблемной колонки и причина возвращаются в тексте ошибки SmartScript-движка.

⚠️ Колонка SelectUsers ≠ самостоятельный ДП SelectUsers. Внутри табличного ДП колонка типа «Выбор пользователей» принимает строку идентификаторов через запятую ("123,456,g78,o12"), а не JSON. Самостоятельный ДП SelectUsers (вне таблицы) при модификации через ChangeExtParamValue ожидает JSON вида {"Users":[...], "Groups":[...], "OrgUnits":[...]}. Это разные форматы — не путать.

Источник: README.md, academy-patterns.md.

ДП «Файл» (File)

Описание: электронный файл любого разрешённого типа. Поддерживает мультифайл.

Хранение: FileStorageFileToExtParamLinks.FileId -> FileStorageFiles.

Настройки: - Мультифайл (несколько файлов в одном ДП). - Значение по умолчанию (файл). - Имя файла: не менять / добавить версию / фиксированное / смарт-выражение. - Логирование действий с файлами (журнал Диск). - Изображение --- ограничить только изображениями. - Максимальный размер файла (КБ). - Список допустимых расширений. - Защита от загрузки (только постраничный просмотр). - Файловый провайдер. - Работа с файлами Word: сравнение версий, объединение. - Сканирование (утилита 1Формы).

Источник: ../disk/admin.md.

ДП «Нумератор» (Numerator)

Описание: автоматический нумератор с шаблоном.

Хранение: ExtParamValues.ExtParamValue.

Шаблон нумератора: статический текст + вставки: - <number:X;Y> --- X = начальное значение, Y = шаг. - <datetime:dd.MM.yyyy> --- дата/время. - Пример: СЧЕТ<datetime:ddMMyy><number:1;1>.

Настройки: - Устанавливать только на переходе (не при создании задачи). - Обнулить текущее значение счётчика. - Привязка к конкретным категориям и статусам.

Источник: admin.md.

ДП «URL (ссылка)» (URL)

Описание: ссылка.

Хранение: ExtParamValues.ExtParamValue.

ДП «Адрес» (Address)

Описание: почтовый адрес в формате, совместимом с КЛАДР. Хранит координаты (широта, долгота) для позиционирования на карте.

Хранение: ExtParamValues.AddressId -> таблица Address. Денормализация: int.

Требование: для корректной работы необходим хотя бы один подключённый адресный провайдер.

Источник: README.md.

ДП «Адресаты email» (ExtParamAddressees)

Описание: e-mail адреса или имена пользователей.

Хранение: ExtParamValues.ExtParamValue.

ДП «Сквозной» (Through)

Описание: автоматическое вычисление значения на основании настроенной цепочки связей (через Lookup). Значения не хранятся --- вычисляются по цепочке.

Настройки: ExtParamTroughSettings. Связи: vwExtParamTroughLinks.

Пересчёт: SP PullThroughExtParam.

Источник: domains/ext-params/through.md.

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

Эти настройки задаются в свойствах ДП и действуют во всех категориях, где ДП используется:

Настройка Поле DDL Описание
Имя ДП ExtParamName VARCHAR(900) Название
Тип ExtParamType VARCHAR(20) Неизменяемый после создания
Мнемоника ExtParamMnemo VARCHAR(200) Для API и автоматизаций
Подсказка ToolTip VARCHAR(2000) Макс. 1000 символов (UI-ограничение); отображается иконкой
Только для чтения ReadOnly BIT По умолчанию: 1
RegExp RegExp VARCHAR(1000) Валидация значения
Сообщение ошибки RegExp RegExpErrorMessage VARCHAR(1000)
MaxLength MaxLength INT Для текстовых типов
Не копировать при создании DontCopySourceTaskValue BIT
Сортировка по алфавиту SortByAlphabet BIT Для списковых типов

Источник: DDL dbo.ExtParams.Table.sql.

Настройки ДП в категории (ExtParamsInSubcat)

Эти настройки индивидуальны для каждой привязки ДП к категории:

Настройка Область действия
Видимость (блок, порядок) Только эта категория
Обязательность Только эта категория
Доступ (по задаче / по группам / по матрице / по SQL-функции) Только эта категория
Синхронизация в родительскую / дочернюю Только эта категория
Значение по умолчанию Только эта категория
Подсказка (ДП в категории) Макс. 1000 символов
Новая задача: режим отображения на NTF Только эта категория

Источник: academy-patterns.md, архивная страница: cats-dp.md.

Типы доступа к ДП

Способ Когда применять
По задаче Нет специфических ограничений
Только по группам Доступ зависит только от группы
По матрице доступа Комбинация группа + роль + статус
По SQL-функции Доступ зависит от данных задачи

Уровни: 0 = нет доступа, 1 = чтение, 2 = редактирование. - README.md --- типы ДП (первоисточник)