郵件合并是一種動態生成信件，信封，發票，報告和其他類型文檔的便捷方法。使用郵件合并，您可以創建一個包含合并字段的模板文件，然后使用數據源中的數據填充這些字段。

假設您必須向20個不同的人發送一封信，并且只需要更改每個副本上收件人的姓名和地址。在這種情況下，您可以為該信件創建一個郵件合并模板，然后通過動態填充名稱和地址字段來生成20個信件。

這篇文章介紹了如何使用Java在MS Word文檔中執行郵件合并操作。同時，將學習如何創建郵件合并模板和以編程方式執行郵件合并。

>>如果想要測試這項新功能，可點擊這里下載最新版試用。

• 使用Java中的密碼保護Word DOCX文件
• 保護具有不同保護類型的DOCX文件
• 使用Java取消保護/解鎖DOCX文件

創建用于MS Word中郵件合并的模板

郵件合并中使用的模板可以是一個簡單的Word文檔（即DOCX），并且不必采用模板格式。模板文檔包含執行“郵件合并”時填充有數據的合并字段。以下是如何使用MS Word準備郵件合并模板的步驟。

• 在MS Word中創建一個新文檔。
• 將光標放在要添加合并字段的位置。
• 從 插入 菜單中選擇字段 選項。
• 從 字段名稱 列表中，選擇 MergeField。
• 在字段名稱中為合并字段輸入名稱 ，然后按 確定。
• 將文檔另存為DOCX。

以下是示例模板 文檔的屏幕截圖 。

使用Java創建郵件合并模板

還可以以編程方式生成郵件合并模板。以下是其步驟。

• 創建DocumentBuilder類的實例。
• 使用DocumentBuilder提供的方法（例如insertTextInput，  insertField，InsertParagraph等）插入合并字段。
• 使用DocumentBuilder.getDocument（）。save（String fileName）方法保存文檔。

下面的代碼示例演示如何使用Java創建郵件合并模板。

// Create document builder
DocumentBuilder builder = new DocumentBuilder();

// Insert a text input field the unique name of this field is "Hello", the other parameters define
// what type of FormField it is, the format of the text, the field result and the maximum text length (0 = no limit)
builder.insertTextInput("TextInput", TextFormFieldType.REGULAR, "", "Hello", 0);
builder.insertField("MERGEFIELD CustomerFirstName \\* MERGEFORMAT");

builder.insertTextInput("TextInput1", TextFormFieldType.REGULAR, "", " ", 0);
builder.insertField("MERGEFIELD CustomerLastName \\* MERGEFORMAT");

builder.insertTextInput("TextInput1", TextFormFieldType.REGULAR, "", " , ", 0);

// Insert a paragraph break into the document
builder.insertParagraph();

// Insert mail body
builder.insertTextInput("TextInput", TextFormFieldType.REGULAR, "", "Thanks for purchasing our ", 0);
builder.insertField("MERGEFIELD ProductName \\* MERGEFORMAT");

builder.insertTextInput("TextInput", TextFormFieldType.REGULAR, "", ", please download your Invoice at ",
	0);
builder.insertField("MERGEFIELD InvoiceURL \\* MERGEFORMAT");

builder.insertTextInput("TextInput", TextFormFieldType.REGULAR, "",
	". If you have any questions please call ", 0);
builder.insertField("MERGEFIELD Supportphone \\* MERGEFORMAT");

builder.insertTextInput("TextInput", TextFormFieldType.REGULAR, "", ", or email us at ", 0);
builder.insertField("MERGEFIELD SupportEmail \\* MERGEFORMAT");

builder.insertTextInput("TextInput", TextFormFieldType.REGULAR, "", ".", 0);

builder.insertParagraph();

// Insert mail ending
builder.insertTextInput("TextInput", TextFormFieldType.REGULAR, "", "Best regards,", 0);
builder.insertBreak(BreakType.LINE_BREAK);
builder.insertField("MERGEFIELD EmployeeFullname \\* MERGEFORMAT");

builder.insertTextInput("TextInput1", TextFormFieldType.REGULAR, "", " ", 0);
builder.insertField("MERGEFIELD EmployeeDepartment \\* MERGEFORMAT");

// Save document
builder.getDocument().save("document.docx");

使用Java在Word文檔中執行郵件合并

模板準備好后，您可以用數據填充合并字段。以下是在Word模板上執行郵件合并的步驟。

• 使用Document 類創建一個新模板 （或加載現有模板）。
• 創建DocumentBuilder類的實例，然后將Document對象傳遞給其構造函數。
• 使用Document.getMailMerge（）。execute（） 方法執行郵件合并 ，并將數據源作為參數傳遞。
• 使用DocumentBuilder.getDocument（）。save（String）方法保存生成的Word文檔 。

下面的代碼示例演示如何使用Java在Word文檔中執行郵件合并。

// Include the code for our template
Document doc = new Document();

// Pass the document to document builder
DocumentBuilder builder = new DocumentBuilder(doc);

// Create Merge Fields
builder.insertField(" MERGEFIELD CustomerName ");
builder.insertParagraph();
builder.insertField(" MERGEFIELD Item ");
builder.insertParagraph();
builder.insertField(" MERGEFIELD Quantity ");

// Save the template
builder.getDocument().save("MailMerge.TestTemplate.docx");

// Fill the fields in the document with user data
doc.getMailMerge().execute(new String[] { "CustomerName", "Item", "Quantity" },
		new Object[] { "John Doe", "Hawaiian", "2" });

// Save the document 
builder.getDocument().save("MailMerge.Simple.docx");

模板

輸出

使用XML數據源執行郵件合并

在前面的示例中，我們使用Java對象執行了郵件合并。但是，在大多數情況下，數據源用于填充合并字段。為了演示，讓我們檢查一下如何在Mail Merge中使用XML數據源。以下是其步驟。

• 使用DataSet類加載XML數據源。
• 使用文檔類加載郵件合并模板。
• 使用execute函數在數據源中使用所需的數據表填充合并字段。
• 使用Document.save（String）方法保存生成的Word文檔。

以下是此示例中使用的XML數據源。

下面的代碼示例演示如何使用提供的XML數據源中的Customer數據表填充Mail Merge模板。

// Create the Dataset and read the XML
DataSet customersDs = new DataSet();
customersDs.readXml("Customers.xml");

// Open a template document
Document doc = new Document("TestFile XML.docx");

// Execute mail merge to fill the template with data from XML using DataTable.
// Note that this class also works with a single repeatable region (and any nested regions).
// To merge multiple regions at the same time from a single XML data source, use the XmlMailMergeDataSet class.
// e.g doc.getMailMerge().executeWithRegions(new XmlMailMergeDataSet(xmlData));
doc.getMailMerge().execute(customersDs.getTables().get("Customer"));

// Save the output document
doc.save("generated-document.docx");

模板

輸出

Java中的區域合并郵件

在某些情況下，您可能需要重復文檔中的特定區域。例如，您要在單獨的表格中顯示每個客戶下的訂單。在這種情況下，您可以利用郵件合并區域。為了創建區域，您可以指定區域的開始和結束。結果，在郵件合并執行期間，將為數據的每個實例重復該區域。

以下屏幕快照顯示了一個模板，其中區域由一個表組成。它以《 TableStart：Customers》開頭，并以《 TableEnd：Customers》結尾。

以下代碼示例顯示了如何創建具有區域的模板并使用數據填充它。

// Create document
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// The start point of mail merge with regions the dataset.
builder.insertField(" MERGEFIELD TableStart:Customers");
// Data from rows of the "CustomerName" column of the "Customers" table will go
// in this MERGEFIELD.
builder.write("Orders for ");
builder.insertField(" MERGEFIELD CustomerName");
builder.write(":");

// Create column headers
builder.startTable();
builder.insertCell();
builder.write("Item");
builder.insertCell();
builder.write("Quantity");
builder.endRow();

// We have a second data table called "Orders", which has a many-to-one
// relationship with "Customers"
// picking up rows with the same CustomerID value.
builder.insertCell();
builder.insertField(" MERGEFIELD TableStart:Orders");
builder.insertField(" MERGEFIELD ItemName");
builder.insertCell();
builder.insertField(" MERGEFIELD Quantity");
builder.insertField(" MERGEFIELD TableEnd:Orders");
builder.endTable();

// The end point of mail merge with regions.
builder.insertField(" MERGEFIELD TableEnd:Customers");

// Pass our dataset to perform mail merge with regions.
DataSet customersAndOrders = CreateDataSet();
doc.getMailMerge().executeWithRegions(customersAndOrders);

// Save the result
doc.save("MailMerge.ExecuteWithRegions.docx");

輸出

使用Java創建嵌套的郵件合并區域

郵件合并中的另一種流行情況是當您具有嵌套區域時。例如，當您必須列出訂單和每個訂單中的項目時，可以使用嵌套區域。下圖使圖片更清晰地顯示了嵌套區域。

在上圖中，我們有訂單表和項目，其中每個記錄表項目鏈接到創紀錄的訂單。因此，這兩個表之間存在一對多關系。在這種情況下，Aspose.Words將執行Data Merge中定義的關系的郵件合并。例如，如果我們有一個XML數據源，那么Aspose.Words將使用模式信息或XML結構來查找關系。因此，您不必自己手動處理它，而Document.getMailMerge（）。executeWithRegions（DataSet）方法將為您工作（如上例所示）。

在合并字段上應用自定義格式

為了使您能夠更好地控制郵件合并，Aspose.Words for Java允許您在郵件合并執行期間自定義合并字段。所述 setFieldMergingCallback（IFieldMergingCallback） 方法接受了一類工具fieldMerging（FieldMergingArgs） 和 imageFieldMerging（ImageFieldMergingArgs）用于在郵件合并過程定制的控制方法。該 fieldMerging（FieldMergingArgs） 當郵件合并執行過程中遇到合并域發生的事件。

以下是有關如何自定義郵件合并操作以及將格式應用于單元格的完整代碼示例。

public class ApplyCustomFormattingDuringMailMerge {

    private static final String dataDir = Utils.getSharedDataDir(ApplyCustomFormattingDuringMailMerge.class) + "MailMerge/";

    public static void main(String[] args) throws Exception {
        Document doc = new Document(dataDir + "MailMerge.AlternatingRows.doc");

        // Add a handler for the MergeField event.
        doc.getMailMerge().setFieldMergingCallback(new HandleMergeFieldAlternatingRows());

        // Execute mail merge with regions.
        DataTable dataTable = getSuppliersDataTable();
        doc.getMailMerge().executeWithRegions(dataTable);

        doc.save(dataDir + "MailMerge.AlternatingRows Out.doc");
    }

    /**
     * Returns true if the value is odd; false if the value is even.
     */
    public static boolean isOdd(int value) throws Exception {
        return (value % 2 != 0);
    }

    /**
     * Create DataTable and fill it with data. In real life this DataTable
     * should be filled from a database.
     */
    private static DataTable getSuppliersDataTable() throws Exception {
        java.sql.ResultSet resultSet = createCachedRowSet(new String[]{"CompanyName", "ContactName"});

        for (int i = 0; i < 10; i++)
            addRow(resultSet, new String[]{"Company " + Integer.toString(i), "Contact " + Integer.toString(i)});

        return new DataTable(resultSet, "Suppliers");
    }

    /**
     * A helper method that creates an empty Java disconnected ResultSet with
     * the specified columns.
     */
    private static ResultSet createCachedRowSet(String[] columnNames) throws Exception {
        RowSetMetaDataImpl metaData = new RowSetMetaDataImpl();
        metaData.setColumnCount(columnNames.length);
        for (int i = 0; i < columnNames.length; i++) {
            metaData.setColumnName(i + 1, columnNames[i]);
            metaData.setColumnType(i + 1, java.sql.Types.VARCHAR);
        }

        CachedRowSet rowSet = RowSetProvider.newFactory().createCachedRowSet();
        ;
        rowSet.setMetaData(metaData);

        return rowSet;
    }

    /**
     * A helper method that adds a new row with the specified values to a
     * disconnected ResultSet.
     */
    private static void addRow(ResultSet resultSet, String[] values) throws Exception {
        resultSet.moveToInsertRow();

        for (int i = 0; i < values.length; i++)
            resultSet.updateString(i + 1, values[i]);

        resultSet.insertRow();

        // This "dance" is needed to add rows to the end of the result set properly.
        // If I do something else then rows are either added at the front or the result
        // set throws an exception about a deleted row during mail merge.
        resultSet.moveToCurrentRow();
        resultSet.last();
    }
}

class HandleMergeFieldAlternatingRows implements IFieldMergingCallback {
    /**
     * Called for every merge field encountered in the document. We can either
     * return some data to the mail merge engine or do something else with the
     * document. In this case we modify cell formatting.
     */
    public void fieldMerging(FieldMergingArgs e) throws Exception {
        if (mBuilder == null)
            mBuilder = new DocumentBuilder(e.getDocument());

        // This way we catch the beginning of a new row.
        if (e.getFieldName().equals("CompanyName")) {
            // Select the color depending on whether the row number is even or odd.
            Color rowColor;
            if (ApplyCustomFormattingDuringMailMerge.isOdd(mRowIdx))
                rowColor = new Color(213, 227, 235);
            else
                rowColor = new Color(242, 242, 242);

            // There is no way to set cell properties for the whole row at the moment,
            // so we have to iterate over all cells in the row.
            for (int colIdx = 0; colIdx < 4; colIdx++) {
                mBuilder.moveToCell(0, mRowIdx, colIdx, 0);
                mBuilder.getCellFormat().getShading().setBackgroundPatternColor(rowColor);
            }

            mRowIdx++;
        }
    }

    public void imageFieldMerging(ImageFieldMergingArgs args) throws Exception {
        // Do nothing.
    }

    private DocumentBuilder mBuilder;
    private int mRowIdx;
}