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