Отчёты и печатные формы — паттерны¶
Источники:
academy/admin-basic/06-reports.md(уроки 6.1--6.7),academy/admin-basic/07-print-forms.md(уроки 7.1--7.3)
1. FastReport -- создание отчёта¶
FastReport -- генератор отчётов, связывает шаблон с источником данных. Работает только на Windows (десктопный дизайнер).
Последовательность настройки¶
- Создать сущность отчёта: Администрирование - Отчёты - Создать
- Настроить права доступа: Действия - Права доступа - Право просмотра (добавить группы)
- Настроить контекст (если отчёт вызывается из задачи)
- Открыть дизайнер FR, настроить источник данных
- Настроить шаблон (таблица, заголовки, форматирование)
- Настроить фильтры
- Сохранить и проверить
Параметры контекста¶
| Параметр | Тип | Назначение |
|---|---|---|
@TaskID |
int | Номер задачи (если вызов из задачи) |
@UserID |
int | ID пользователя-владельца |
@CurrentUserID |
int | ID пользователя, открывшего отчёт |
Контекст задаётся для каждого отчёта отдельно в списке отчётов (колонка "Контекст").
2. Источники данных¶
Способы добавления источника¶
| Способ | Когда использовать |
|---|---|
| Мастер подключения | Выбор таблицы из БД. Быстро, но запрашивает все столбцы |
| SQL-запрос | Точная выборка нужных столбцов. Гибкость, JOIN, агрегация |
| Хранимая процедура | Сложная логика, параметризация |
Денормализованные таблицы¶
Для каждой категории автоматически создаётся таблица TasksInSubcat{ID}Denormalized. Содержит:
- Стандартные поля задач (TaskID, StateName, ResponsiblePerformerID и др.)
- ДП: ExtParam{ID}Value -- отображаемое значение, ExtParam{ID}NativeValue -- сырое значение (для Lookup -- TaskID связанной задачи)
Денормализация запускается при обновлении конфигурации; можно запустить вручную из настроек категории.
Пример SQL-источника с JOIN¶
SELECT
Application.ExtParam64Value + ' ' + Application.ExtParam65Value AS FIO,
Application.ExtParam69Value AS JobTitle,
Application.StateName AS ApplicationState,
Users.DisplayName AS PerformerFIO,
Account.StateName AS AccountState,
Pass.StateName AS PassState
FROM TasksInSubcat18Denormalized AS Application WITH (NOLOCK)
LEFT JOIN TasksInSubcat29Denormalized AS Pass
ON Pass.ExtParam114NativeValue = Application.TaskID
LEFT JOIN TasksInSubcat74Denormalized AS Account
ON Account.ExtParam114NativeValue = Application.TaskID
LEFT JOIN Users
ON Users.UserID = Application.ResponsiblePerformerId
WITH (NOLOCK) -- использовать для предотвращения блокировок (в редких случаях может вернуть неактуальные данные).
Связь между категориями через Lookup: ExtParam{LookupID}NativeValue = TaskID.
3. Связи таблиц -- конструктор FR vs SQL¶
Через конструктор FR¶
Действия - Новая связь - выбрать главную/подчинённую таблицу и колонки связи.
Особенность FR: терминология "главная/подчинённая" обратна интуитивной. Если данные из категории A доступны через категорию B (Lookup), то в FR "главная" = B, "подчинённая" = A.
Для связи через Lookup: колонка главной таблицы -- ExtParam{ID}NativeValue, подчинённой -- TaskID.
Через SQL-запрос¶
SQL-запрос с JOIN -- более явный и гибкий способ. Преимущества: точный набор столбцов, осмысленные алиасы, одна точка настройки.
Гиперссылки в отчёте¶
В SQL-запрос добавить колонку со ссылкой:
'/spa/tasks/' + CAST(Application.TaskID AS VARCHAR(50)) AS TaskLink
В свойствах ячейки FR: Hyperlink - указать параметр TaskLink.
4. Фильтры¶
Создание фильтра¶
Список отчётов - настройки отчёта - иконка фильтра - Создать - ввести имя.
Типы параметров фильтра¶
| Тип | Передаётся в FR как | Особенности |
|---|---|---|
| Период | datetime (@periodFrom, @periodTo) |
Формат 104. Конвертация: CONVERT(datetime, @periodFrom, 104) |
| Выпадающий список | varchar |
Мультивыбор: строка через запятую ('11,17,18'). NULL при пустом выборе |
Привязка фильтров к SQL-запросу FR¶
- ПКМ на источнике - Редактировать - Далее до параметров
- Добавить параметр ("+" ) - задать имя - присвоить значение из параметров отчёта
- Использовать в WHERE
Пример SQL с фильтрами¶
DECLARE
@fromPeriod datetime = CONVERT(datetime, @periodFrom, 104),
@toPeriod datetime = CONVERT(datetime, @periodTo, 104)
SELECT ...
FROM TasksInSubcat18Denormalized AS Application WITH (NOLOCK)
...
WHERE
(@Unit IS NULL OR @Unit = ''
OR Application.ExtParam69NativeValue IN (SELECT value FROM string_split(@Unit, ',')))
AND Application.ExtParam74NativeValue BETWEEN @fromPeriod AND @toPeriod
Smart для выпадающего списка¶
Тип фильтра "Выпадающий список" - Дополнительные параметры - Smart (режим TSQL):
SELECT TaskID, TaskText
FROM TasksInSubcat17Denormalized
"Свойство значения" = TaskID, "Свойство названия" = TaskText. Галочка "Мультивыбор", значение по умолчанию "Все".
5. Внешний вид отчётов¶
Шаблон отчёта¶
| Элемент | Бэнд | Назначение |
|---|---|---|
| Заголовок | Заголовок отчёта | Текст + шапка таблицы (скопировать из данных) |
| Таблица данных | Данные | Привязка к источнику, RowCount = 1 (FR формирует строки автоматически) |
| Нумерация | Подвал отчёта | Системная переменная Page# |
Форматирование¶
- Формат даты: пользовательский
dd.MM.yyyy(важно для экспорта в Excel 2007) - Чередование строк: создать стиль с заливкой, назначить через
EvenStyle - Сортировка: свойства бэнда "Данные" - вкладка "Сортировка"
- Управление пустым пространством: "Может расти", "Может сжиматься", "Может разрываться"
Экспорт¶
Поддерживается экспорт в Excel, PDF и другие форматы. При экспорте в Excel 2007 формат даты сбивается -- использовать пользовательский формат dd.MM.yyyy.
6. Печатные формы -- FastReport¶
FR можно использовать для печатных форм (в контексте задачи). Отличие от отчётов: преимущественно текстовые блоки, а не таблицы.
Автоматизация генерации¶
- Smart-действие "Создать файл отчёта" (указать задачу-контекст, имя файла, расширение: docx/PDF/xlsx)
- Smart-действие "Вложить файл" или "Вложить файл в ДП" (параметр "файл" = smart, переменная "результат действия" с номером предыдущего действия)
Типичные триггеры: переход по маршруту, изменение ДП, smart-кнопка.
7. Шаблонизатор печатных форм¶
Более простой и практичный способ создания печатных форм (по сравнению с FR). Шаблон -- файл Word (docx) с тегами.
Синтаксис тегов¶
Теги заключены в ##. Общая форма: ##<Параметр>## или ##<Параметр>|<Модификатор>## (модификатор после |).
Базовые теги:
| Тег | Значение |
|---|---|
##TaskId## |
Номер задачи |
##Task## |
Текст задачи |
##StateDescr## |
Текущий статус |
##CreatedTask## |
Дата создания |
##FullName## |
ФИО заказчика |
##NowTime## |
Текущее время (момент генерации файла) |
##ExtParam{ID}## |
ДП по идентификатору (например, ##ExtParam63##) |
##SMART{ID}## |
Результат smart-выражения по его идентификатору (например, ##SMART5385##) |
##Comments## / ##Comments_reverse## |
Все комментарии (по возрастанию / убыванию даты) |
Обращение к параметрам других задач: ##Task<ID задачи> <Имя параметра>##.
Модификаторы¶
Дата и время (DateFormat, DateInWords)¶
| Модификатор | Назначение |
|---|---|
\|DateFormat:dd.MM.yyyy |
Формат даты (синтаксис .NET) |
\|DateInWords |
Дата прописью |
Полный справочник форматов — MSDN: Custom Date and Time Format Strings.
Числа (NumberFormat)¶
| Шаблон | Эффект |
|---|---|
\|NumberFormat:{0:0.00} |
2 знака после запятой |
\|NumberFormat:{0:0,0} |
Разделитель разрядов (запятая в шаблоне → системный разделитель) |
\|NumberFormat:{0:0000} |
Дополнение до 4 цифр нулями |
Разделитель дробной части — точка в шаблоне; реальный символ берётся из системных настроек. Можно комбинировать.
Деньги (MoneyToString, MULTIPLY)¶
| Модификатор | Эффект |
|---|---|
\|MoneyToString:RUR / :USD / :EUR |
Сумма прописью на русском с указанием валюты |
\|MoneyToString:Number |
Сумма прописью без валюты |
\|MoneyToString:RUR,ENG (и аналоги) |
Сумма прописью на английском |
\|MULTIPLY:<число> |
Умножение перед выводом (для расчёта НДС и т.п.) |
Большие тексты (CLEAR_HTML)¶
##<Параметр>|CLEAR_HTML## — очищает HTML-разметку из ДП «Большой текст с форматированием»; теги <br> заменяются на \r\n.
Условный вывод (IF)¶
Абзац с тегом целиком показывается или скрывается в зависимости от значения параметра или результата smart-выражения.
| Синтаксис | Поведение |
|---|---|
##ExtParam{ID}\|IF=<значение>## |
Абзац виден, если значение ДП равно <значение>; иначе абзац скрывается полностью |
##SMART{ID}\|IF=<значение>## |
Абзац виден, если результат smart-выражения равен <значение>; иначе абзац скрывается полностью (v2.267+) |
Важно: если тег не выполняет условие — скрывается весь абзац вместе с тегом и текстом. В документе не остаётся ни самого тега, ни пустых строк от него.
Пример: шаблон договора с тремя вариантами блока «Покупатель»:
##SMART5385|IF=1## Общество с ограниченной ответственностью…
##SMART5385|IF=2## Индивидуальный предприниматель…
##SMART5385|IF=3## Физическое лицо…
При генерации документа в нём останется ровно тот блок, значение которого совпадает с результатом smart-выражения 5385.
До v2.267: синтаксис
##SMART{ID}|IF=<значение>##не обрабатывался — теги и текст оставались в документе при любом результате. Mustache-синтаксис{{smart...}}текст{{/smart...}}приfalse/nullтакже оставлял теги в документе. Начиная с v2.267|IF=поддерживается для smart-тегов и работает так же, как|IF=для ДП.
Информация о пользователе¶
Для тегов, ссылающихся на пользователя (заказчик, исполнитель, ДП «Выбор пользователей»), доступны вложенные параметры профиля: Login, Email, JobTitle, OrgUnit и др.
Для вывода всех значений из ДП «Выбор пользователей» используется циклический вывод абзацами или в таблицу (см. archived
ms_word_tags_cycle_text.md/ms_word_tags_cycle_table.md).
Цепочки Lookup¶
Тег ##Lookup{ID} ExtParam{ID}## извлекает ДП из задачи, на которую ссылается Lookup. Поддерживается любая глубина вложенности — можно идти по цепочке Lookup сколько угодно раз.
Стилизация¶
Теги поддерживают стилизацию текста (шрифт, размер, цвет) для основных и дополнительных параметров. Стиль сохраняется при генерации, если значение приводится к простой строке (Дата и время, имена пользователей и т.п.). Такие теги можно использовать в колонтитулах.
Базовые примеры¶
| Тег | Значение |
|---|---|
##CreatedTask\|DateFormat:dd.MM.yyyy## |
Дата создания в формате ДД.ММ.ГГГГ |
##ExtParam63## |
Значение ДП с ID=63 |
##Lookup114 ExtParam69## |
ДП 69 из задачи в Lookup с ID=114 |
Последовательность настройки¶
- Сгенерировать файл-подсказку: Настройки категории - Шаблоны файлов - "Сгенерировать шаблон" (перечень доступных тегов)
- Создать шаблон Word, заменить данные на теги
- Загрузить в систему: Шаблоны файлов - "Загрузите файл"
- Проверить: Карточка задачи - Файлы - Печать и экспорт - "Сгенерировать по шаблону"
Версионирование шаблона: при повторной загрузке файла с тем же именем система не создаёт новую запись, а добавляет новую версию к существующему шаблону. Идентификатор шаблона (
fileid) при этом не меняется — это важно для смарт-действий, ссылающихся на шаблон по ID.Конфликт стилей: теги поддерживают форматирование (шрифт/размер/цвет) только если значение параметра приводится к простой строке (Дата и время, имена пользователей). Если значение содержит разметку (текст задачи с HTML, ДП «Текст с форматированием») — сохраняется форматирование значения, а стиль шаблона игнорируется.
Автоматизация¶
Smart-действие "Сгенерировать файл по шаблону":
- ID шаблона = ID из таблицы шаблонов (или -1 для последнего загруженного)
- Целевой ДП = ID ДП типа "Файл" (если пусто -- вкладывается во вложения задачи)
- Галочка "Обрабатывать шаблон как docx документ"
Привязка к событиям¶
- Переход: Смарт - Правила - Создать - событие "После перехода" - выбрать переход - выбрать пакет
- Smart-кнопка: Настройки - Кнопки - Создать - привязать пакет, настроить доступ по статусам/ролям
Mustache в шаблонах¶
В шаблоне Word можно использовать элементы Mustache для вывода параметров задач или результатов smart-выражений.