我们很高兴宣布 GroupDocs.Assembly for Java 26.11 已于 2026 年 11 月 发布。此版本将 GroupDocs.Assembly for .NET 26.11 的功能和修复带到了 Java:

  • 模板可以根据 JSON Schema 进行检查;
  • 模板和报告的页面可以 渲染为图像;
  • 外部资源 的加载由应用程序控制;
  • REMOVE_EMPTY_PARAGRAPHS 支持 电子表格和纯文本 模板;
  • <<image>> 标签在 演示文稿的表格单元格 中工作,并且能够相对于模板文件夹解析 相对路径;
  • 颜色标签接受 十六进制字符串。

捆绑的 Aspose 引擎从 2026 年初的版本升级到 26.10,并且多项修复涵盖了授权、报告编码、条形码和 HTML 内容。Java 8 仍为基准。

本次发布的新功能

键 摘要 类别
ASSEMBLYNET-145 JsonDataSource 接受 JSON Schema:即使在数据中为 null、空或缺失,只要在模式中声明的成员也可以引用,且值类型来源于模式 Feature
ASSEMBLYNET-8 DocumentAssembler.generatePreview 将模板、组装报告和其他文档的页面渲染为 PNG、JPEG 或 BMP 图像 Feature
ASSEMBLYNET-36, ASSEMBLYNET-37 DocumentAssemblyOptions.REMOVE_EMPTY_PARAGRAPHS 支持电子表格模板和纯文本文档 Feature
ASSEMBLYNET-140 模板和数据引用的外部资源由应用程序控制;默认跳过来自数据的资源引用 Security
ASSEMBLYJAVA-353 捆绑 Aspose.Words 26.10.1、Aspose.Cells 26.10、Aspose.Slides 26.10、Aspose.Email 26.9 和 Aspose.BarCode 26.10 Update
ASSEMBLYJAVA-353 GS1 条形码(EAN-14、SCC-14、SSCC-18 和 DataBar)在 Aspose.BarCode 26.10 中保持代码文本的自动纠正 Fix
ASSEMBLYNET-52 <<image>> 标签在演示文稿的表格单元格中工作,且组形状中的形状标签也会被处理 Enhancement
ASSEMBLYNET-62 来自数据的相对图像路径相对于模板文件夹解析 Enhancement
ASSEMBLYNET-25 在 backColor 和图表颜色标签中,字符串形式的颜色可以是十六进制值 Enhancement
ASSEMBLYNET-155 缺失的 JSON、XML 或 CSV 布尔值在 ?:、where、count、any、all 和 first 中计为 false,而不是导致错误 Fix
ASSEMBLYNET-157 对嵌套对象的 groupBy 和 distinct 合并相等对象;支持 JSON 数据的 $id/$ref 引用 Fix
ASSEMBLYNET-142 License.setLicense(InputStream) 能读取已经从起始位置读取过的流 Fix
ASSEMBLYNET-143 当操作完成时报告计量授权的消耗 Fix
ASSEMBLYNET-158 ASCII-only 模板的文本和 HTML 报告以 UTF-8 编写,避免拉丁文以外的数据丢失 Fix
ASSEMBLYNET-160 当文本框字体未安装时,条形码不再因 NullPointerException 而失败 Fix
ASSEMBLYNET-159 MSG 模板的会话主题标签与主题标签的处理方式相同 Fix
ASSEMBLYNET-152 在电子表格、演示文稿或文本模板中使用 <<doc>> 标签时会给出明确的错误信息;失败的 assembleDocument 不会留下空的输出文件 Fix
ASSEMBLYJAVA-354 以块元素结束的 -html 表达式标签不再在段落后留下空段落 Fix

升级前需检查的行为更改

  1. 默认跳过来自数据的外部资源。 例如 <<image [item.PhotoUrl]>>,其中 PhotoUrl 为 http 或 https URI 时现在会得到空图像。将主机添加到 LoadSaveOptions.getWhitelistedResources(),或调用 LoadSaveOptions.setSkipExternalResources(false) 以保持之前的行为。模板本身引用的资源和本地文件路径仍然如前工作。
  2. 模糊的 JsonDataSource 调用。 new JsonDataSource(path, null) 带有字面量 null 的第二参数已无法编译。请进行强制转换:new JsonDataSource(path, (JsonDataLoadOptions) null)。已编译的应用程序不受影响。
  3. UTF-8 文本和 HTML 报告。 ASCII-only 文本和 HTML 模板在没有字节顺序标记的情况下现在以 UTF-8 编写,而不是 windows-1252。若需单字节代码页,请在模板中声明(HTML 中的 <meta charset>)。
  4. 对嵌套对象的 groupBy 和 distinct 现在合并相等对象,而不是为每行生成一个组。
  5. HTML 后不再出现额外段落。 以块元素结束的 -html 标签不再在 HTML 之后留下空段落。若需保留空行,请以 <p>&nbsp;</p> 结束 HTML。
  6. DataBar Expanded 条形码。 仅包含数字的 DataBar Expanded 或 DataBar Expanded Stacked 条形码现在使用 (01) 应用标识符编码为 GTIN,行为与其他 DataBar 类型一致。
  7. <<doc>> 标签的异常文本已更改,异常类型保持不变。
  8. 已移除的 API。 ICustomFontsHandler.resetFontSources() 已删除,请改用 FontSettings.resetFontSources()。

新功能

对 JsonDataSource 的 JSON Schema 支持

在评估任何 <<if>> 之前,模板会根据其数据结构进行检查。使用 JSON 时,结构通常直接取自数据本身,因此在分支中引用永不渲染的字段会在数据为 null、空数组或缺失时导致错误。

JsonDataSource 现在接受 JSON Schema,方式与 XmlDataSource 接受 XML Schema 相同,模板会根据模式进行检查:

  • 在模式中声明的成员即使在数据中为 null、空或缺失也可以引用;
  • 未在模式中声明的成员仍会导致错误,从而检测拼写错误;
  • 值类型来源于模式,例如布尔值为 Boolean,仅包含数字的字符串仍保持为字符串。

示例客户数据(无支付卡、无忠诚度信息,账户号为数字字符串):

{ "Name": "Quayside Bistro", "Account": "00042", "Cards": [], "Loyalty": null }

对应的 JSON Schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "Name": { "type": "string" },
    "Account": { "type": "string" },
    "Cards": {
      "type": "array",
      "items": { "type": "object", "properties": { "Type": { "type": "string" }, "Last4": { "type": "string" } } }
    },
    "Loyalty": { "type": ["object", "null"], "properties": { "Level": { "type": "string" } } }
  }
}

模板示例:

Customer: <<[customer.Name]>>
Account number: <<[customer.Account]>>
<<if [customer.Cards.count() > 0]>>Payment card: <<[customer.Cards.first().Type]>> ending in <<[customer.Cards.first().Last4]>><<else>>No payment card on file.<</if>>
Loyalty program: <<[customer.Loyalty?.Level]>>

在代码中将模式与数据一起传入:

JsonDataSource dataSource = new JsonDataSource("Customer.json", "Customer.schema.json");

DocumentAssembler assembler = new DocumentAssembler();
assembler.assembleDocument("Json schema.docx", "output.docx", new DataSourceInfo(dataSource, "customer"));

结果为 No payment card on file.,账户号显示为 00042。若不使用模式,同一模板会在 customer.Cards.first().Type 处出错,且账户号会被读取为数字 42。

模式可以是文件路径或 InputStream,可带或不带 JsonDataLoadOptions。支持的关键字包括 type(含可空类型)、properties、items、format(date-time 与 date)、enum、const、allOf 与本地 $ref。不支持 oneOf、anyOf、not、远程或递归 $ref、元组形式的 items 以及数组的数组。

文档预览

DocumentAssembler.generatePreview 将文档页面渲染为 PNG、JPEG 或 BMP 图像:可以是模板、由 GroupDocs.Assembly 组装的文档,或任何受支持格式的其他文档,来源可以是文件或流。支持渲染文字处理、文本和 HTML 文档的页面,电子表格的打印页,演示文稿的幻灯片,以及带有标题的电子邮件。

DocumentAssembler assembler = new DocumentAssembler();

ByteArrayOutputStream report = new ByteArrayOutputStream();
try (InputStream template = new FileInputStream("Customer orders.docx"))
{
    assembler.assembleDocument(template, report,
        new DataSourceInfo(new JsonDataSource("Customers.json"), "customers"));
}

// 为每一页创建流,并在写入后释放。
PreviewOptions options = new PreviewOptions(
    pageNumber -> new FileOutputStream("page" + pageNumber + ".png"),
    (pageNumber, pageStream) -> pageStream.close());
options.setPreviewFormat(PreviewFormats.PNG);
options.setResolution(120);                    // 每英寸点数;默认 96
// options.setPageNumbers(new int[] { 1, 2 }); // 默认全部页面

assembler.generatePreview(new ByteArrayInputStream(report.toByteArray()), options);

当同时设置 setWidth 与 setHeight 时,页面会按保持纵横比的方式缩放至指定尺寸。预览生成过程不加载任何外部资源,生成的图像计入计量授权(如同组装文档)。

对电子表格和纯文本模板的 REMOVE_EMPTY_PARAGRAPHS

DocumentAssemblyOptions.REMOVE_EMPTY_PARAGRAPHS 现同样适用于电子表格模板和纯文本文档。在这些情况下,段落即为一行文本:单元格中的一行文本或文本文件中的一行。模板标签处理后变为空的行会连同换行符一起被删除。单独占一行的 <<if>>、<<foreach>> 等标签不再留下空行。

DocumentAssembler assembler = new DocumentAssembler();
assembler.setOptions(DocumentAssemblyOptions.REMOVE_EMPTY_PARAGRAPHS);
assembler.assembleDocument("Empty paragraph.txt", "result.txt", new DataSourceInfo("dummy", "dummy"));

模板:

Prefix
<<if [false]>>
Text to be removed
<</if>>
Suffix

结果:

Prefix
Suffix

相同的模板文本放在电子表格单元格中会得到相同的结果。HTML 与 XML 文档保持不变。

安全性:外部资源的控制

<<image>> 或 <<doc>> 标签可以评估为来自数据的 URI,之前 GroupDocs.Assembly 会直接请求该资源,无法阻止。若服务器组装来自外部用户的数据,可能被迫请求内部地址。

现在 GroupDocs.Assembly 会标记每个外部资源引用的来源 (ExternalResourceOrigin):

  • TEMPLATE — 模板文档本身引用资源,例如 <<image ["https://example.com/logo.png"]>> 中的字面 URI;
  • DATA — 引用来源于数据,例如标签表达式计算得到的 URI。

默认情况下,模板引用的资源仍会加载,而来源于数据的资源会被跳过。LoadSaveOptions 的四个成员用于控制此行为:

  • setSkipExternalResources(默认 true)— 不加载外部资源;
  • setTrustTemplateResources(默认 true)— 即使跳过也加载模板引用的资源;当模板来自不可信来源时请设为 false;
  • getWhitelistedResources — 即使跳过,也允许的主机名或绝对 URI 前缀;
  • setExternalResourceHandler — 在请求每个外部资源前调用的 ExternalResourceHandler,可决定允许、跳过或提供内容。
final String photoUri = "https://images.example.com/photos/no-photo.jpg";
DocumentAssembler assembler = new DocumentAssembler();

// 默认选项:URI 来自数据,图像被跳过并留下空位。
assembler.assembleDocument("Inserting image.docx", "Skipped.docx", new DataSourceInfo(photoUri, "expression"));

// 允许受信任的主机并查看每个决定。处理器也可以直接提供内容。
LoadSaveOptions options = new LoadSaveOptions();
options.getWhitelistedResources().add("images.example.com");
options.setExternalResourceHandler(new LocalImageHandler("no-photo.jpg"));

assembler.assembleDocument("Inserting image.docx", "Provided.docx", options, new DataSourceInfo(photoUri, "expression"));
public class LocalImageHandler extends ExternalResourceHandler
{
    private final String mImagePath;

    public LocalImageHandler(String imagePath) { mImagePath = imagePath; }

    @Override
    public void onLoading(ExternalResourceLoadingArgs args)
    {
        System.out.println(ExternalResourceOrigin.toString(args.getOrigin()) + " resource " + args.getUri() + ": "
            + (args.isSkipped() ? "skipped" : "allowed"));

        // 提供内容而不是请求它。
        if (!args.isSkipped() && args.getUri().toLowerCase().startsWith("https://images.example.com/"))
        {
            try
            {
                args.setData(Files.readAllBytes(Paths.get(mImagePath)));
            }
            catch (IOException e)
            {
                throw new UncheckedIOException(e);
            }
        }
    }
}

外部资源指的是需要网络访问的资源:http、https、ftp URI、UNC 路径以及带远程主机的 file URI。本地文件路径不受影响。被跳过的文档图像会被替换为透明图像;被跳过的 <<image>> 或 <<doc>> 值会被视为空值。

增强

演示文稿表格单元格和组形状中的图像

在演示文稿模板中,<<image>> 标签过去只能放在文本框内。现在表格单元格也可以作为图像容器:图像会作为单元格的填充图片,包括由 <<foreach>> 重复的行,从而可以构建带图片的项目列表。使用 -fitHeight 时,行会根据图像的纵横比自动增高。组形状(包括嵌套组)中的形状标签现在也会像其他形状一样被处理。

相对图像路径相对于模板文件夹解析

当 <<image>> 标签从数据中获取相对文件路径(如 Images/photo.png)时,首先相对于模板文件夹解析,类似于 Microsoft Office 文档的链接资源。若模板是从流加载的,请使用 LoadSaveOptions.setResourceLoadBaseUri 设置基准文件夹:

DocumentAssembler assembler = new DocumentAssembler();

// 从流加载的模板没有文件夹:使用 setResourceLoadBaseUri 设置。
LoadSaveOptions options = new LoadSaveOptions();
options.setResourceLoadBaseUri("C:\\Reports\\Templates");

try (InputStream template = new FileInputStream("C:\\Reports\\Templates\\Inserting image.docx");
     OutputStream report = new FileOutputStream("output-from-stream.docx"))
{
    assembler.assembleDocument(template, report, options, new DataSourceInfo("../Images/no-photo.jpg", "expression"));
}

如果该位置不存在文件,则仍使用当前目录。

十六进制颜色字符串

颜色字符串现在可以是十六进制值 — "#RRGGBB"、"#RGB" 或 "#AARRGGBB" — 除了颜色名称和 ARGB 整数外,可用于 backColor 和图表颜色标签。例如,<<backColor [item.Color]>> 若数据提供 "#FF0000",则会应用红色。

修复

  • JSON、XML 和 CSV 数据中缺失的布尔值 现在在条件运算符 ?: 以及 where、count、any、all、first 的谓词中计为 false,而不是抛出 NullPointerException。
  • 对嵌套对象的 groupBy 和 distinct 在 JSON 与 XML 数据中按值比较对象,等价的客户会被归为同一组。现在支持带有 $id/$ref 的 JSON 引用。
  • License.setLicense(InputStream) 能从 ByteArrayInputStream 的标记位置以及 FileInputStream 的起始位置读取,因此已用于其他 GroupDocs 产品的流不再因 “Unexpected EOF in prolog” 而失败。
  • 计量消耗 在文档组装或预览生成完成时报告,而不是稍后由后台线程报告。
  • ASCII-only 模板的文本和 HTML 报告 以 UTF-8 编写,避免 Café、Привет 等数据因 windows-1252 丢失。
  • 条形码(QR、DataMatrix、Aztec 等)在文本框字体未安装时不再失败——例如 Linux 上缺少 Calibri 时会使用回退字体。
  • MSG 模板:会话主题中的标签与主题标签的处理方式相同,Outlook 能正确串联消息。
  • 在电子表格、演示文稿和文本模板中使用 <<doc>> 时会给出不支持该格式的明确错误信息,且失败的 assembleDocument 不会留下空的输出文件。
  • HTML 内容:以块元素结束的 -html 表达式标签不再在 HTML 后留下额外的空段落(ASSEMBLYJAVA-354)。
  • GS1 条形码:GroupDocs.Assembly 现在自行纠正仅数字的 EAN-14、SCC-14、SSCC-18 和 DataBar 条形码的代码文本,因为 Aspose.BarCode 26.10 已不再执行此操作,条形码行为保持与 26.10.1 相同。

Aspose 引擎升级至 26.10

GroupDocs.Assembly for Java 26.10.1 捆绑了 2026 年初的 Aspose 库,随后安全扫描器报告了自那以后修复的漏洞。现在的捆绑引擎为:

引擎 26.10.1 26.11
Aspose.Words for Java 26.3 26.10.1
Aspose.Cells for Java 26.3 26.10
Aspose.Slides for Java 26.2 26.10
Aspose.Email for Java 26.1 26.9
Aspose.BarCode for Java 26.6 26.10

已发布的 POM 仍未声明任何依赖。由于引擎已刷新,重新生成的文档在字节层面可能会有所不同,但在视觉和功能上保持等价。如果在升级后进行字节比较,请刷新基准文件。

Java 用户注意事项

  • 带有 Z 或时区偏移的日期 在 JSON 或 CSV 数据中会被解析为 java.util.Date 的精确瞬间,并按照 JVM 默认时区格式化。若希望输出不随服务器时区变化,请使用固定时区启动 JVM,例如 -Duser.timezone=UTC。
  • ExternalResourceOrigin 与 PreviewFormats 是 int 常量类,类似于 Java API 中的其他枚举。CreatePageStream 与 ReleasePageStream 为函数式接口,可直接使用 lambda 表达式。

如何获取更新

Maven

在 pom.xml 中添加 GroupDocs 仓库和依赖:

<repositories>
    <repository>
        <id>groupdocs-artifacts-repository</id>
        <name>GroupDocs Artifacts Repository</name>
        <url>https://releases.groupdocs.com/java/repo/</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.groupdocs</groupId>
        <artifactId>groupdocs-assembly</artifactId>
        <version>26.11</version>
    </dependency>
</dependencies>

直接下载

从 GroupDocs.Assembly for Java 26.11 下载页面 下载 JAR 包。

资源