Шаблоны отчетов
Настройка отображения отчётов выполняется путём редактирования файла шаблона, расположенного в папке ресурсов соответствующего отчёта. Этот шаблон представляет собой файл с подстановками — специальными кусками текста и команд, которые позволяют автоматически вставлять данные в итоговый документ.
Каждый отчёт имеет собственный шаблон, который находится в папке ресурсов отчёта, путь формируется по данным переданным при создании отчета.
Например:
/resources/reports/payments/[id отчета].docx
Правила при работе с шаблонами
Рассмотрим на примере следующего описания и параметров заданных в отчете. Описание содержит различные наборы данных, такие как заголовок, дата, сведения об организации, итоговая сумма, список платежей и заметки
Описания отчета в формате json
{
"dataset": [
{
"name": "report_title",
"type": "json",
"query": "Отчёт по оплатам"
},
{
"name": "report_date",
"type": "json",
"query": "2025-10-27"
},
{
"name": "organization",
"type": "json",
"query": {
"name": "ООО «Альфа",
"inn": 7701234567
}
},
{
"name": "summary",
"type": "json",
"query": {
"total_sum": 105833,
"currency": "RUB"
}
},
{
"name": "payments",
"type": "json",
"query": [
{
"accdocno": "УУК-2-13",
"eddate": "2025-10-01",
"sum": 50833,
"payer": "УФК по г. Москве",
"payee": "ПАО СБЕРБАНК Г.МОСКВА",
"tags": [
"компенсация",
"без НДС"
]
},
{
"accdocno": "УУК-2-14",
"eddate": "2025-10-03",
"sum": 55000.5,
"payer": "АО Газпромбанк",
"payee": "ООО «Альфа»",
"tags": [
"оплата",
"договор"
]
}
]
},
{
"name": "notes",
"type": "json",
"query": [
"Отчёт сформирован автоматически",
"Все суммы указаны в рублях"
]
},
{
"name": "entries",
"type": "json",
"query": {{ payments }}
}
]
}
Параметры отчета в формате json(для формирования отчета из документов)
{
"groups": [
{
"fields": [
{
"name": "payments",
"type": "textarea",
"dataType": "json",
"meta": {
"type": "dataset",
"format": "entries",
"fields": [
{
"name": "accdocno",
"type": "text"
},
{
"name": "eddate",
"type": "date"
},
{
"name": "sum",
"type": "number"
},
{
"name": "payer",
"type": "text"
},
{
"name": "payee",
"type": "text"
},
{
"tags": "tags",
"type": "select"
}
]
}
}
],
"label": "Основные"
}
]
}
В шаблонах используются три основных типа конструкций, которые помогают управлять выводом информации:
- Выражение для подстановки данных:
{{ … }}
Например, {{ report_title }} вставит наименование отчета "Отчёт по оплатам". В качестве выражений используется наименование датасета указанного в описании отчета (dataset.name)
Такой шаблон умеет подставлять только те данные, которые явно указаны, и не создает динамической структуры. Он подходит, если структура отчёта постоянна и не меняется в зависимости от данных.
Формирование выражений в зависимоти от типа данных:
- данные имеют тип Строка, Число, Дата, Время, Дата и время и Произвольное текстовое значение, то в шаблоне используется выражение
{{ key }}, на примере приведенного json применимо к {{ report_date }}, {{ report_title }}
- для объектов применяется конструкция {{ key(object).key(value) }}.
{{ organization.name }}, {{ summary.total_sum }} и т.д
- для массивов применимы циклы, в большинстве случаев используются управляющие конструкции для циклов, для вывода всез значений указанных в массиве
При постоянном наборе можно воспользоваться и обычными выражениями с указанием индекса списка
| {{ payments[0]['accdocno'] }} | {{ payments[0]['eddate'] }} | {{ payments[0]['sum'] }} | {{ payments[0]['payer'] }} | {{ payments[0]['payee'] }} | {{ payments[0]['tags'] }} |
При использовании таких выражений для вывода нужной вам информации придется ввести данное выражение со сменой идекса столько раз, сколько данных у вас есть в массиве.
Если генерация отчета вызывается из документа и указаны параметры, заданные выше, то вместо ключей выводимых подстановок указываются индексы
| {{ entries[0][0] }} | {{ entries[0][0] }} | {{ entries[0][0] }} | {{ entries[0][0] }} | {{ entries[0][0] }} | {{ entries[0][0] }} |
- Управляющие конструкции, такие как условия и циклы
{% … %}
Например, конструкция, описанная ниже, выведет все данные по ключу accdocno, указанные в списке датасета payments
{% for item in payments %}
{{ item.accdocno }}
{{% endfor %}`
Позволяют создавать гибкие, расширяемые отчёты. Внутри цикла for происходит обход набора данных — например, списка элементов — и для каждого элемента генерируется часть отчёта, например, строка таблицы.
- Комментарии, не отображаются в итоговом отчете и служат для пояснений внутри отчета
{# … #}
Виды подстановок данных в шаблонах
1. Автоматическая подстановка данных через выражения
В шаблоне указывается переменная, которая заменяется её значением при генерации отчёта.
Пример:
{{ title_report }} — здесь переменная total_report заменится на наименование шаблона.
Такой шаблон умеет отображать только те данные, которые явно указаны, и не создает динамической структуры. Он подходит, если структура отчёта постоянна и не меняется в зависимости от данных.
- Динамические таблицы и циклы
Позволяют создавать гибкие, расширяемые отчёты. Внутри цикла for происходит обход набора данных — например, списка элементов — и для каждого элемента генерируется часть отчёта, например, строка таблицы.
Пример:
text
{% for item in payments %}
| {{ item.accdocno }} | {{ item.eddate }} |
{% endfor %}
Вывод таблицы в различных типах отчетов
Работа с таблицами, примеры приведены на основе описания отчета приведенного выше и предоставляют возможность просмотра каким образом можно отобразить одни и те же данные в различных отчетах
HTML
<h2>Динамическая таблица платежей</h2>
<table>
<thead>
<tr>
<th>Номер документа</th>
<th>Дата</th>
<th>Плательщик</th>
<th>Получатель</th>
<th>Сумма</th>
<th>Теги</th>
</tr>
</thead>
<tbody>
{% for p in payments %}
<tr>
<td>{{ p.accdocno }}</td>
<td>{{ p.eddate }}</td>
<td>{{ p.payer }}</td>
<td>{{ p.payee }}</td>
<td>{{ p.sum }} ₽</td>
<td>{{ p.tags | join(', ') }}</td>
</tr>
{% endfor %}
</tbody>
</table>
Вывод:
DOCX
Стили заданные для переменных, при рендере будут использоваться стили заданные для переменных.
Для работы с таблицами в шаблонах используются специлизированные теги
- tr - добавлет строку
- tc - добавляет ячейку
Так как .docx хранить таблицы в XML, то при использовании циклов без тегов будут добавляться только новые строки, если нарушена структура то таблица может не отражаться вовсе или отображать некооректную структуру.
XLSX
Для отчетов с типом XLSX описание отличается и набор данных описывает внутри каждого листа шаблона
Описания отчета в формате json
{
"subsets": [
{
"dataset": [
{
"name": "payments",
"type": "json",
"query": [
{
"accdocno": "УУК-2-13",
"eddate": "2025-10-01",
"sum": 50833,
"payer": "УФК по г. Москве",
"payee": "ПАО СБЕРБАНК Г.МОСКВА",
"tags": [
"компенсация",
"без НДС"
]
},
{
"accdocno": "УУК-2-14",
"eddate": "2025-10-03",
"sum": 55000.5,
"payer": "АО Газпромбанк",
"payee": "ООО «Альфа»",
"tags": [
"оплата",
"договор"
]
}
]
}
],
"source": "Sheet1",
"target": "sheet1"
}
]
}
Для шаблонов используются дополнительные управляющие конструкции (задаются в виде комментариев)
beforerow,beforecell,aftercell- генерация строк и ячеек на основе итерируемых данных- генерация строк:
- итератор как комментарий в первой строке данных -
beforerow{% for row in rows[1:] %}
-
закрытие области итерации как комментарий в следующей строке -
beforerow{% endfor %} -
генерация ячеек по столбцам:
- итератор как комментарий в первой столбце данных -
beforecell{% for cell in cellss[1:] %}
- итератор как комментарий в первой столбце данных -
-
закрытие области итерации как комментарий в следующем столбце -
beforecell{% endfor %} -
range- задание диапазона (области действия) конструкции (диапазоны одного уровня вложенности не должны пересекаться) beforerange,afterrange- генерация строк в пределах диапазонов на основе итерируемых данных
