我們很高興宣布 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 後留下空段落 修復

升級前需檢查的行為變更

  1. 預設會跳過來自資料的外部資源。 例如,<<image [item.PhotoUrl]>>,其中 PhotoUrl 為 http 或 https URI 時,現在會產生空圖像。將主機加入 LoadSaveOptions.getWhitelistedResources(),或呼叫 LoadSaveOptions.setSkipExternalResources(false) 以保留先前行為。模板本身引用的資源與本機檔案路徑仍如往常工作。

  2. JsonDataSource 呼叫不明確。 使用文字 null 作為第二參數的 new JsonDataSource(path, null) 已無法編譯。請將參數轉型:new JsonDataSource(path, (JsonDataLoadOptions) null)。已編譯的應用程式不受影響。

  3. UTF-8 文字與 HTML 報告。 僅含 ASCII 的文字與 HTML 模板(未含 BOM)的報告現在以 UTF-8 編寫,而非 windows-1252。若需保留單位元組編碼頁,請在模板中宣告(HTML 中的 <meta charset>)。

  4. groupBy 與 distinct 在巢狀物件(JSON、XML 與 DataSet 資料)現在會合併相等的物件,而非為每列產生一個群組。

  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 的方式相同,且模板會根據 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。

資源