Перейти к основному содержанию
`Ctrl`+`K`

# Интерактивные отчёты

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

Изменённые пользователем данные либо передаются как параметры в отчёт, либо применяются к объектам, на основе которых строится отчёт. Это настраивается отдельно для каждого поля. Интерактивный режим есть только у Jasper-отчётов.

Интерактивные отчёты позволяют пользователям удобно настраивать параметры отчёта через интерактивную форму перед печатью.

## Основные возможности

- Редактирование параметров отчёта через интерактивную форму:

  - Расширение логики сеттеров с помощью jexl-скриптов.

- Пользовательские Jexl-операции для интерактивных отчётов:

  - Указание условий доступности операций.

  - Использование данных отчёта в операциях.

- Настройка пользовательской выборки для переопределения бизнес-логики.

## Объявление отчёта интерактивным

Для активации интерактивного режима в интерфейсе системы:

- Перейдите в `Отчёты > Настройка отчётных форм`.

- Найдите нужную отчётную форму.

- На детализации `Печатные формы отчёта` поставьте галочку «Интерактивный».

Отчёт определяется как интерактивный с помощью атрибута `bInteractive`.

Примечание

Построение интерактивных отчётов в фоновом режиме невозможно.

## Настройка интерактивного отчёта

### Предпочтительный способ

Создайте поле типа `TextField` и установите параметр `net.sf.jasperreports.export.html.class` со значением по шаблону:

`"[#" + Гид объекта + "#" + Наименование редактора + "#" + Наименование параметра/Название атрибута изменяемого объекта + "#" + Значение, которым будет инициализирован редактор + "/#]"`

Компоненты шаблона:

- Гид объекта: Гид изменяемого объекта, если указан атрибут для изменения.

- Наименование редактора: Тип редактора.

- Наименование параметра/атрибута:

  - Если строка начинается с «P_», то значение считывается как наименование параметра, который передаётся в печатную форму. В печатной форме его можно получить из карты параметров `REPORT_PARAMETERS_MAP`.

  - В остальных случаях значение интерпретируется как название атрибута объекта, гид которого был указан ранее, и при запуске операции печати в атрибут объекта устанавливается введенное значение.

- Значение инициализации: Начальное значение редактора.

Примечание

Обязательное требование: В TextField должно находиться какое-то значение (хотя бы пробел).

Преимущества предпочтительного способа:

- Проще в реализации и поддержке.

- Меньше вероятность ошибок позиционирования.

- Более чистая структура отчёта.

#### Типы редакторов

- `textArea` — текстовый редактор (многострочный текст);

- `checkBox` — флаговая кнопка (булево значение);

- `date` — редактор даты;

- `dateTime` — редактор даты и времени;

- `ref` — ссылочный редактор (выбор объекта).

Примечание

Примечание: в именах редакторов учитывается регистр — используйте точные названия как в примерах.

### Альтернативный (устаревший) способ настройки

Используйте только для совместимости со старыми отчётами:

1. Создайте два поля в одном фрейме, дублирующих размер и положение.

2. Первое поле — выводит финальное значение из параметра/объекта.

3. Второе поле — содержит строку интерактивности с условием видимости: `$P{FILENAME}.equals(".html")`.

4. Для второго поля установите `TextAdjust = ScaleFont`.

5. Оба поля должны содержать значение (хотя бы пробел).

## Изменение параметров интерактивного отчёта

Чтобы сделать поле изменяемым в выборке интерактивного отчёта, оно должно содержать строку в следующем формате: `[#{gid}#{тип_редактора}#{имя}#{значение}/#]` (вводится в одно из полей в JasperSoft Studio).

Если указан `gid`-объекта и имя не начинается с `P_`, то при изменении значения параметра в выборке будет вызван стандартный сеттер `ru.bitec.app.btk.class_.attr.AttrApi#setAttrValue`.

Чтобы получить введённые пользователем параметры В Jasper Reports, нужно добавить новый параметр отчёта в списке `Parameters` или получить его из `REPORT_PARAMETERS_MAP` типа `java.util.Map`, при чём имя в поле должно совпадать с именем в списке параметров.

Примечание

- Если имя атрибута начинается с `P_`, карта параметров обновляется, минуя сеттер по `gid`.

- В JasperSoft Studio все параметры указываются в верхнем регистре.

Для примера, нескольких параметров:

- `IDSRCOBJ` - вызывающий сеттер по гиду параметр:

  - `$P{IDSRCOBJ}` - получение значения изменённого пользователем параметра.

  - `"[#" + $P{GIDOBJ} + "#textArea#IDSRCOBJEDITED#"+ $P{IDSCROBJ} +"/#]"` - содержание редактируемого поля в JasperSoft Studio.

    - `GIDOBJ` - параметр отчёта, содержащий gid объекта с параметром `IDSRCOBJ`, в который будет устанавливаться его значение при изменении поля интерактивного отчёта.

    - `IDSCROBJ` - параметр отчёта, содержащий изначальное значение изменяемого поля интерактивного отчёта.

    - `IDSRCOBJEDITED` - имя, по которому можно обратиться к изменённому пользователем в интерактивном отчёте параметру.

- `$P{P_NTOTAL}` - не вызывающий сеттер параметр.

- `(java.util.Date) $P{REPORT_PARAMETERS_MAP}.get("P_DDATE")` - получение параметра `P_DDATE` и приведение его к нужному типу `java.util.Date`.

Функция парсинга изменяемых полей

Изменяемые поля из полученной от Jasper Reports `HTML`-разметки парсятся в функции `ru.bitec.app.rpt.interactive.Rpt_HtmlReportHelper#replaceTags`.

### Расширение сеттеров

Можно задать кастомную логику для сеттера параметра отчёта `setByTagId` с помощью JEXL-скриптов. Скрипты выполняются до вызова сеттера `setByTagId`.

В контексте JEXL-скрипта доступны параметры атрибута:

- `gid` - глобальный идентификатор объекта;

- `sAttrName` - имя атрибута.

## Пользовательские JEXL-операции

Операции могут быть добавлены на тулбар формы интерактивного отчёта через детализацию `Процедуры интерактивного отчёта` в `Отчёты > Настройка отчётных форм`. Это происходит с помощью клонируемой операции `userDefinedProcedures`. Настройка привязывается к `Rpt_EntityReport` и содержит:

- № п/п (порядок отображения).

- Иконка (номер иконки).

- Наименование.

- Признак «Выводить текст операции на панели».

- Ссылка на `Bts_Procedure`, в которой указан JEXL-скрипт (исполняется в контексте выборки).

### Контекст операций

В настраиваемых операциях интерактивных отчётов доступны:

- Значения изменяемых полей - по имени параметра в селекционном экране \ параметра произвольного отчёта.

- Значения неизменяемых полей Jasper-отчёта - для полей, отмеченных специальными тегами.

- Список всех имён доступных параметров - по алиасу `PARAMS`.

- Методы выборки и сессии - `dialogs`, `commit()`, `flush()` и др.

### Получение неизменяемых параметров

Чтобы получить неизменяемые параметры из Jasper-отчёта и использовать их в пользовательских операциях, необходимо задать следующие свойства для поля в Jasper Reports:

- `net.sf.jasperreports.export.html.class` = `parse` - обозначает, что поле будет доступно в jexl-операциях.

- `net.sf.jasperreports.export.html.id` = `{имя атрибута}` - имя, по которому можно будет получить значение поля.

### Условия отображения

Условия доступности операций задаются в детализации `Условие доступности процедуры`, находящейся в форме `Настройка отчётных форм`, в детализации `Процедуры интерактивного отчёта`.

Условия указываются как JEXL-скрипт, который должен возвращать:

- `true` - операция активна;

- `false` - операция недоступна.

Скрипт может использовать JSON с параметрами из селекционного экрана или свободного отчёта.

## Переопределение выборки интерактивного отчёта

Для интерактивных отчётов предусмотрена возможность указания пользовательской выборки для переопределения бизнес-логики.

Примечание

В зависимости от типа объекта `Rpt_EntityReport`, для которого вы хотите переопределить выборку и отображения интерактивного отчёта, нужно наследоваться от:

- Отчёт с селекционным экраном: `InteractiveSelReportHtml`.

- Произвольный отчёт: `InteractiveFreeReportHtml`.

1. Указание кастомной выборки:

   - В классе `Rpt_EntityHtmlReportPkg` реализован метод `hasCustomInteractiveSelection`, который проверяет наличие кастомной выборки для интерактивного отчёта.

   - Если кастомная выборка указана, она открывается с переданными параметрами.

2. Пример использования:

   - Для задания кастомной выборки необходимо указать её имя и представление в объектных характеристиках `sSelectionInteractive` и `sRepresentationInteractive` класса `Rpt_EntityReport`.

   - При вызове метода `enterInteractiveMode` кастомная выборка будет автоматически открыта, если она указана.

- Параметры в выборку передаются через `selection.form.params` и сохраняются в JSON.

## Параметры для передачи в отображение интерактивного отчёта

### Отчёт с селекционным экраном

Обязательные:

- `IDENTITY#` - идентификатор отчёта;

- `IDREPORT#` - идентификатор печатной формы;

- `BWITHDOC#` - флаг: сохранение в документообороте/истории печати;

- `DREPORTVERSION#` - дата версии печатной формы.

Параметры для построения и печати отчёта:

- `JPARAMETERS` - параметры отчёта для истории (наименования как в селекционном экране);

- `LOGJPARAMS#` - параметры отчёта для печати (наименования как в Jaspersoft Studio).

### Произвольный отчёт

Обязательные:

- `IDENTITY#` — идентификатор отчёта;

- `IDREPORT#` — идентификатор печатной формы.

Параметры для построения и печати отчёта:

- `JPARAMETERS#` — параметры отчёта для печати (наименования как в Jaspersoft Studio).

## Ошибки отображения интерактивного отчёта

Внимание

При отображении особенно крупных интерактивных отчётов, браузерная вкладка может быть принудительно завершена из-за нехватки памяти.

22.08.2025 проведены испытания производительности. Результаты испытаний отображены на графиках ниже.

График ошибок отображения интерактивного отчёта:

График зависимости размера отчёта и памяти вкладки:

Система, на которой проводились испытания:

- Выпуск: Windows 11 Pro.

- Версия: 24H2.

- Процессор: 13th Gen Intel(R) Core(TM) i9-13900K (3.00 GHz).

- Видеоадаптер: Intel(R) UHD Graphics 770.

- Тип системы: 64-разрядная.

- Браузер: Яндекс 25.8.0.1908 (64-bit).

Испытания проводились при объёмах оперативной памяти: 6, 8, 16 и 64 GB.
Смещение критических точек (границ зон) в зависимости от объёма ОЗУ не зафиксировано.
Левая граница определена с точностью 0,47 MB.
Правая граница определена с точностью 2,38 MB.

SQL запрос, который использовался для генерации данных и настройки размерности отчёта:

    SELECT lpad(gs::text, CAST($P{MULTIPLY} AS int), '0') AS uniq_str
    FROM generate_series(1, $P{ROWCOUNT}) gs;

Примечание

При объёме отчёта в 16.21 MB, браузерная вкладка потребляет 2,9 GB ОЗУ, а сам браузер более 3 GB. Это максимальное зафиксированное значение. Объём памяти, используемый в момент критических ошибок, определить не удалось.

Примечание

- 16,21 МБ = 17 миллионов символов (1 символ = 1 байт).

- Это соответствует 170 тысячам строк текста по 100 символов.

- Для сравнения: все 4 тома «Война и мир» содержат около 3 миллионов символов.

Пример ошибки сети:

Пример ошибки памяти: