配置

应用程序属性

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

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.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.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.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.use-office-for-document-conversion

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

默认值：false。

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