我們很高興宣布 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、空或缺失,只要在 schema 中聲明即可引用,且值類型來自 schema |
功能 |
| ASSEMBLYNET-8 | DocumentAssembler.generatePreview 將模板、組合報告及其他文件的頁面渲染為 PNG、JPEG 或 BMP 圖像 |
功能 |
| ASSEMBLYNET-36, ASSEMBLYNET-37 | DocumentAssemblyOptions.REMOVE_EMPTY_PARAGRAPHS 可用於試算表模板和純文字文件 |
功能 |
| ASSEMBLYNET-140 | 模板和資料引用的外部資源由應用程式控制;預設會跳過來源於資料的資源 | 安全 |
| ASSEMBLYJAVA-353 | 捆綁了 Aspose.Words 26.10.1、Aspose.Cells 26.10、Aspose.Slides 26.10、Aspose.Email 26.9 與 Aspose.BarCode 26.10 | 更新 |
| ASSEMBLYJAVA-353 | GS1 條碼(EAN-14、SCC-14、SSCC-18 與 DataBar)在 Aspose.BarCode 26.10 中保留其代碼文字的自動校正 | 修復 |
| ASSEMBLYNET-52 | <<image>> 標籤可在簡報的表格儲存格中使用,且群組形狀中的形狀標籤也會被處理 |
增強 |
| ASSEMBLYNET-62 | 來自資料的相對圖像路徑會相對於模板資料夾解析 | 增強 |
| ASSEMBLYNET-25 | 以字串給予的顏色可在 backColor 與圖表顏色標籤中使用十六進位值 |
增強 |
| ASSEMBLYNET-155 | JSON、XML 或 CSV 資料中缺失的布林值在 ?: 以及 where、count、any、all、first 中視為 false,而不會因 NullPointerException 而失敗 |
修復 |
| ASSEMBLYNET-157 | groupBy 與 distinct 在巢狀物件上會合併相等的物件;支援 JSON 資料的 $id/$ref 參照 |
修復 |
| ASSEMBLYNET-142 | License.setLicense(InputStream) 會從流的起始位置重新讀取已讀過的流 |
修復 |
| ASSEMBLYNET-143 | 計量授權的消耗會在操作完成時回報 | 修復 |
| ASSEMBLYNET-158 | 僅含 ASCII 的模板的文字與 HTML 報告會以 UTF-8 編寫,因而不會遺失非拉丁字元資料 | 修復 |
| ASSEMBLYNET-160 | 當條碼文字框的字體未安裝時,條碼不再因 NullPointerException 而失敗 |
修復 |
| ASSEMBLYNET-159 | MSG 模板的對話主題中的標籤會像主旨的標籤一樣被組合 | 修復 |
| ASSEMBLYNET-152 | 在試算表、簡報或文字模板中的 <<doc>> 標籤會以清晰訊息失敗;失敗的 assembleDocument 不會留下空的輸出檔案 |
修復 |
| ASSEMBLYJAVA-354 | -html 表達式標籤結束其段落時,不會在以區塊元素結尾的 HTML 後留下空段落 |
修復 |
升級前需檢查的行為變更
-
預設會跳過來自資料的外部資源。 例如,
<<image [item.PhotoUrl]>>,其中PhotoUrl為 http 或 https URI 時,現在會產生空圖像。將主機加入LoadSaveOptions.getWhitelistedResources(),或呼叫LoadSaveOptions.setSkipExternalResources(false)以保留先前行為。模板本身引用的資源與本機檔案路徑仍如往常工作。 -
JsonDataSource呼叫不明確。 使用文字null作為第二參數的new JsonDataSource(path, null)已無法編譯。請將參數轉型:new JsonDataSource(path, (JsonDataLoadOptions) null)。已編譯的應用程式不受影響。 -
UTF-8 文字與 HTML 報告。 僅含 ASCII 的文字與 HTML 模板(未含 BOM)的報告現在以 UTF-8 編寫,而非 windows-1252。若需保留單位元組編碼頁,請在模板中宣告(HTML 中的
<meta charset>)。 -
groupBy與distinct在巢狀物件(JSON、XML 與 DataSet 資料)現在會合併相等的物件,而非為每列產生一個群組。 -
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 的方式相同,且模板會根據 schema 進行檢查:
- 在 schema 中聲明的成員即使在資料中為 null、空或缺失,也可被參照;
- 未在 schema 中聲明的成員仍會失敗,因而可偵測拼寫錯誤的名稱;
- 值類型來源於 schema,因此布林值為
Boolean,而包含數字的字串仍保持為字串。
假設有一位客戶沒有付款卡與忠誠度資料,且帳號為數字字串:
{ "Name": "Quayside Bistro", "Account": "00042", "Cards": [], "Loyalty": null }
{
"$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]>>
將 schema 與資料一起傳入:
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。若未使用 schema,同樣的模板會在 customer.Cards.first().Type 處失敗,且帳號會被讀為數字 42。
schema 可以以檔案路徑或 InputStream 形式提供,並可搭配或不搭配 JsonDataLoadOptions。支援的關鍵字包括 type(含可為 null 的類型)、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"));
}
// A stream is created for every page and released when the page is written.
PreviewOptions options = new PreviewOptions(
pageNumber -> new FileOutputStream("page" + pageNumber + ".png"),
(pageNumber, pageStream) -> pageStream.close());
options.setPreviewFormat(PreviewFormats.PNG);
options.setResolution(120); // dots per inch; 96 by default
// options.setPageNumbers(new int[] { 1, 2 }); // all pages by default
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();
// Default options: the URI comes from data, so the image is skipped and left empty.
assembler.assembleDocument("Inserting image.docx", "Skipped.docx", new DataSourceInfo(photoUri, "expression"));
// Allow a trusted host and see every decision. The handler can also provide the content itself.
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"));
// Provide the content instead of requesting it.
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 時,列會依圖像的長寬比增高。群組形狀中的形狀標籤(含巢狀群組)現在會像其他形狀一樣被處理。
相對圖像路徑相對於模板資料夾解析
從資料取得相對檔案路徑(例如 Images/photo.png)的 <<image>> 標籤,現在會先相對於模板資料夾解析,類似 Microsoft Office 文件的連結資源。若模板是從串流載入,請使用 LoadSaveOptions.setResourceLoadBaseUri 設定資料夾:
DocumentAssembler assembler = new DocumentAssembler();
// A template loaded from a stream has no folder: set it with 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"));
}
如果該處不存在檔案,則會如同以前使用當前目錄。
十六進位顏色字串
以字串給予的顏色現在除了顏色名稱與 ARGB 整數外,還可以是十六進位值 — "#RRGGBB"、"#RGB" 或 "#AARRGGBB" —,適用於 backColor 與圖表顏色標籤。例如,<<backColor [item.Color]>> 若資料傳入 "#FF0000",則會套用紅色。
修復
- JSON、XML 與 CSV 資料中缺失的布林值 現在在條件運算子
?:以及where、count、any、all、first的謂詞中視為false,而不會因NullPointerException而失敗。 groupBy與distinct在巢狀物件上(JSON 與 XML 資料)會依值比較物件,因而相同的客戶會合併為一個群組。現在支援保留參照的 JSON($id/$ref)。License.setLicense(InputStream)會從其標記位置讀取ByteArrayInputStream,從位置 0 讀取FileInputStream,因此已用於授權其他 GroupDocs 產品的串流不再因「Unexpected EOF in prolog」失敗。- 計量消耗 會在組合文件或產生預覽完成時回報,而不是稍後由背景執行緒回報。
- 僅含 ASCII 的模板的文字與 HTML 報告 會以 UTF-8 編寫,因而不會因 windows-1252 而遺失如
Café或Привет等資料。 - 條碼(其代碼文字由引擎繪製,如 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 使用者的說明
- JSON 或 CSV 資料中帶有
Z或時區偏移的日期 會是該瞬間的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。