配置

应用程序属性

本节按字母顺序描述与报表扩展组件相关的应用程序属性。

jmix.reports.client.background-report-processing-timeout-ms

在 jmix.reports.client.use-background-report-processing 设置为 true 的情况下，用该参数定义报表执行过程的超时时限，单位为毫秒。

默认值：10000。

jmix.reports.client.enable-tab-symbol-in-data-set-editor

定义是否应将 TAB 键作为 \t 符号处理，而不是在报表详情视图的脚本字段中进行焦点切换。

默认值：false。

jmix.reports.client.llm-query-generation-timeout

Jmix 3.1+

定义在报表详情视图中生成一个 AI 生成的 JPQL 数据集 查询的最大时间。如果语言模型不能按时完成，视图中显示一个提示。

默认值：120s。

jmix.reports.client.show-report-table-view-in-menu

定义是否显示 Reports → Show tables 菜单项。

运行报表后，仍然可以使用该视图显示表格输出。如果用户需要从应用程序菜单直接访问表格输出视图，请将此属性设置为 true。

默认值：false。

jmix.reports.client.table-output-open-mode

定义表格输出报表在 ReportTableView 中打开的方式。

支持

  • DIALOG - 在模态窗打开表格输出。

  • NAVIGATION - 通过路由在页面打开表格输出。

默认值：DIALOG。

jmix.reports.client.use-background-report-processing

允许在将报表运行过程设置为后台任务。该属性是为了实现取消运行操作。

默认值：false。

jmix.reports.curl-path

报表扩展组件使用 cURL 工具运行外部报表。该属性值配置 cURL 的路径。

默认值：curl。

jmix.reports.display-device-available

如果是 false，则允许在服务器以无窗口界面的方式运行 LibreOffice。

默认值：false。

jmix.reports.doc-formatter-timeout

设置 LibreOffice 转换 DOCX/XLSX 为 HTML/PDF 的超时时限，单位是秒。

如果超时，用户会收到一个错误消息。

默认值：20。

jmix.reports.formulas-post-processing-evaluation-enabled

控制是否在报表文档形成后对 XLSX 中的公式进行重新计算。

启用（true）后，LibreOffice 或其他电子表格软件将重新计算 XLSX 报告中的所有公式，确保显示最新值。该功能可以在某些软件打开报表不会重新计算公式时使用。

默认值：false。

jmix.reports.groovy-enabled

启用报表中的 Groovy 执行功能。包括：Groovy 数据集查询语句、Groovy JSON 数据源、Groovy 值格式化、参数转换脚本、基于 Groovy 的自定义模板、Groovy HTML 模板以及由 Groovy 生成的自定义模板 URL。

当设置为 false 时，上述功能返回一个备用值（fallback）而不会执行 Groovy，每次 fallback 时都会记录警告，并且相关编辑器在 UI 中变为只读。

此功能也受全局 jmix.core.unsafe-runtime-features-enabled 开关控制。

默认值：true

jmix.reports.history-cleanup-max-days

计划任务会删除留存时间大于指定天数的所有 执行历史 记录。如果该属性的值是 0，计划任务在删除记录时，不会考虑该值的设定。

参阅 清理历史记录 了解设置计划任务的详情。

默认值：730。

jmix.reports.history-cleanup-max-items-per-report

计划任务会为每个报表保留不多于指定数量的 执行历史 记录。不建议为该属性设置大于 1000 的值。如果该属性的值是 0，计划任务在删除记录时，不会考虑该值的设定。对于经常运行的报表，比如邮件模板、账单模板等，该参数很有用。

参阅 清理历史记录 了解设置计划任务的详情。

默认值：1000。

jmix.reports.history-recording-enabled

启用 报表执行历史 机制。

默认值：false。

jmix.reports.multilineStringsProcessingEnabled

启用 DOCX 报表模板中参数值的多行字符串处理。启用时（true），参数值中的换行符（\n、\r\n）会在生成的 DOCX 文档中渲染为实际的换行。此功能仅在使用 DOCX 模板 时生效。

默认值：false。

jmix.reports.office-path

设置 LibreOffice 的路径。

默认值：/。

jmix.reports.office-ports

设置 LibreOffice 的可用端口列表，使用逗号或竖直分隔符隔开。

示例：jmix.reports.office-ports = 8100|8101|8102|8103|8104|8105.

默认值：8100, 8101, 8102, 8103。

jmix.reports.pdf-fonts-directory

指定 HTML 转换为 PDF 时使用的字体路径。

示例：jmix.reports.pdf-fonts-directory = C:/Windows/Fonts。

jmix.reports.put-empty-row-if-no-data-selected

设置当报表带区的数据集没有返回记录时是否仍然将带区显示一次。

默认值：true。

jmix.reports.save-output-documents-to-history

如果设置为 true，并且 jmix.reports.history-recording-enabled 属性开启，报表结果文件会保存到 文件存储。参阅 输出文档 了解详情。

默认值：false。

jmix.reports.spreadsheet.output-open-mode

当报表结果显示在 报表电子表格 扩展组件的 电子表格查看器 中时，该属性定义查看器的打开方式。DIALOG 以模态对话框显示，NAVIGATION 通过路由在完整页面打开。

此属性由 Report Spreadsheet 扩展组件提供，仅在安装了该扩展组件时生效。

默认值：DIALOG。

jmix.reports.streaming.cursor-clear-interval

Jmix 3.1+

设置读取 流式 band 的 JPQL 数据集时，报表引擎在多少行之后清除持久化上下文。

该值必须大于 0。否则，应用程序无法启动。

默认值：1000。

jmix.reports.streaming.fetch-size

Jmix 3.1+

设置 流式 band 的 SQL 或 JPQL 查询的 JDBC 一次读取数据的行数。对于 MySQL 和 MariaDB，报表引擎会设置为 Integer.MIN_VALUE，以便驱动程序逐行读取。

该值必须大于 0。否则，应用程序无法启动。

默认值：1000。

jmix.reports.streaming.row-access-window-size

Jmix 3.1+

设置对于有 流式 band 的报表，报表引擎在内存中保留多少已渲染的行。旧的行会写入临时文件。

该值必须大于 0。否则，应用程序无法启动。

默认值：100。

jmix.reports.use-office-for-document-conversion

开启使用 LibreOffice 将含有 DOCX 模板的报表转换为 HTML/PDF 的功能，可以显著提高转换的准确度。

默认值：false。

jmix.reports.view-file-extensions

设置需要在浏览器直接显示而不自动下载的文件类型。对这些文件，浏览器的 URL 包含 VAADIN/dynamic/resource/<random_id> 后缀。

默认值：htm, html, jpg, png, jpeg, pdf

安装和配置 LibreOffice

报表扩展组件使用 LibreOffice 程序包来输出 PDF 和 DOC 格式 的报表。下面我们介绍如何在应用程序服务器上进行安装和配置：

Microsoft Windows

jmix.reports.office-path = C:/Program Files (x86)/LibreOffice 5/program

Ubuntu 服务器

  • 安装 libreoffice，例如，运行下列命令：

    $ sudo apt-get install libreoffice

  • 配置 jmix.reports.office-path 应用程序属性并设置为 LibreOffice 的路径，示例：

    jmix.reports.officePath = /usr/lib/libreoffice/program

  • 如果服务器没有安装窗口界面，LibreOffice 启动时将出现错误，Caused by: java.awt.HeadlessException: No X11 DISPLAY variable was set, but this program performed an operation which requires it，或者只是停止运行而没有错误消息。要解决此问题，请设置 jmix.reports.display-device-available 应用程序属性：

    jmix.reports.display-device-available = false

  • 启动 LibreOffice 时，可以运行以下命令来诊断错误：

    $ strace -e trace=signal /usr/lib/libreoffice/programs/office.bin --headless --accept="socket,host=localhost,port=8100;urp" --nologo --nolockcheck

对于使用 apt 安装 tomcat 的 Ubuntu 用户，需要将 ~/.config/libreoffice 复制到 $CATALINA_HOME。例如，tomcat10 中，这个目录是 /usr/share/tomcat10。

之后，需要更改此文件夹的所有者：

sudo mkdir /usr/share/tomcat10/.config
sudo cp -pr ~/.config/libreoffice /usr/share/tomcat10/.config/
sudo chown -R tomcat10.tomcat10 /usr/share/tomcat10/.config/

macOS

  • 在 www.libreoffice.org 下载软件。

  • 安装软件。

  • 配置 jmix.reports.office-path 应用程序属性，指定 LibreOffice 路径，示例：

    jmix.reports.office-path = /Applications/LibreOffice.app/Contents/MacOS

LibreOffice 公式在加载时自动计算

LibreOffice Calc 设置位于 Tools > Options > LibreOffice Calc > Formula > Recalculation on File Load，可以控制 LibreOffice 在打开电子表格文件（如 XLSX 报表）时处理公式重新计算的方式。

默认情况下，LibreOffice 在打开文件时不自动重新计算公式，以缩短加载时间，尤其是对于大且复杂的电子表格。这可能会导致公式显示过时的结果，直到用户手动触发重新计算（例如，通过按 F9 或编辑单元格内容）。

将 Recalculation on File Load 设置为 Always recalculate 会强制 LibreOffice 在每次打开文件时重新计算所有公式。这可以保证显示的值始终是最新的，但可能会增加文件的打开时间，特别是对于大型或带有许多公式的电子表格。因此，这个设置是在打开速度和数据准确性之间做权衡。虽然在大多数情况下解决了公式结果错误的问题，但也得考虑对大文件打开速度的影响。