این پست به نحوه انجام عملیات Mail Merge در اسناد MS Word با استفاده از جاوا می پردازد. در پایان این مقاله، نحوه ایجاد قالب های Mail Merge و اجرای Mail Merge را به صورت برنامه ای یاد خواهید گرفت.

درباره Mail Merge

Mail Merge یک روش راحت برای تولید نامه ها، پاکت نامه ها، فاکتورها، گزارش ها و انواع دیگر اسناد به صورت پویا است. با استفاده از Mail Merge، یک فایل قالب حاوی فیلدهای ادغام ایجاد می‌کنید و سپس آن فیلدها را با استفاده از داده‌های موجود در منبع داده پر می‌کنید. فرض کنید باید نامه ای به 20 نفر مختلف ارسال کنید و فقط باید نام و آدرس گیرنده را در هر نسخه تغییر دهید. در این حالت، می توانید یک الگوی Mail Merge برای نامه ایجاد کنید و سپس با پر کردن نام و آدرس به صورت پویا، 20 حرف ایجاد کنید.

Java Mail Merge API - دانلود رایگان

Aspose.Words for Java یک API پردازش کلمه شناخته شده است که به شما امکان می دهد انواع مختلفی از اسناد را از ابتدا ایجاد کنید. API ویژگی های داخلی Mail Merge را ارائه می دهد که به شما امکان می دهد اسناد را با استفاده از الگوها و منابع داده به صورت پویا تولید کنید. Aspose.Words برای جاوا را می توان به صورت JAR دانلود کرد یا در برنامه های مبتنی بر Maven نصب کرد.

<repository>
    <id>AsposeJavaAPI</id>
    <name>Aspose Java API</name>
    <url>https://repository.aspose.com/repo/</url>
</repository>

<dependency>
    <groupId>com.aspose</groupId>
    <artifactId>aspose-words</artifactId>
    <version>20.11</version>
    <classifier>jdk17</classifier>
</dependency>

منابع داده برای ادغام ایمیل

داده‌های موجود در Mail Merge را می‌توان از هر منبع داده‌ای مانند JSON، XML، صفحه‌گسترده یا پایگاه داده دریافت کرد.

ایجاد قالب برای Mail Merge در MS Word

الگویی که در Mail Merge استفاده می‌شود می‌تواند یک سند Word ساده (یعنی DOCX) باشد و نیازی نیست که در قالب قالب باشد. سند الگو حاوی فیلدهای ادغام است که هنگام اجرای Mail Merge با داده ها پر می شود. در ادامه مراحل نحوه تهیه قالب Mail Merge با استفاده از MS Word آورده شده است.

  • یک سند جدید در MS Word ایجاد کنید.
  • مکان نما را در جایی که می خواهید فیلد ادغام اضافه کنید قرار دهید.
  • از منوی Insert گزینه Field را انتخاب کنید.
  • از لیست Field names، MergeField را انتخاب کنید.
  • یک نام برای فیلد ادغام در نام فیلد وارد کنید و OK را فشار دهید.
  • سند را به عنوان DOCX ذخیره کنید.

تصویر زیر اسکرین شات از سند نمونه الگو است.

الگوی کلمه ادغام ایمیل

با استفاده از جاوا قالب Mail Merge ایجاد کنید

همچنین می‌توانید قالب Mail Merge را به صورت برنامه‌نویسی تولید کنید. مراحل زیر برای آن آورده شده است.

نمونه کد زیر نحوه ایجاد یک الگوی Mail Merge را با استفاده از جاوا نشان می دهد.

// ایجاد سند ساز
DocumentBuilder builder = new DocumentBuilder();

// یک فیلد ورودی متن وارد کنید که نام منحصر به فرد این فیلد "Hello" است، سایر پارامترها را تعریف می کند
// نوع FormField چیست، قالب متن، نتیجه فیلد و حداکثر طول متن (0 = بدون محدودیت)
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);

// یک شکست پاراگراف را در سند وارد کنید
builder.insertParagraph();

// درج متن نامه
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();

// درج پایان نامه
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");

// ذخیره سند
builder.getDocument().save("document.docx");

با استفاده از جاوا، Mail Merge را در سند Word انجام دهید

پس از آماده شدن الگو، می توانید فیلدهای ادغام را با داده ها پر کنید. در زیر مراحل انجام Mail Merge در قالب Word آمده است.

  • با استفاده از کلاس Document یک الگوی جدید ایجاد کنید (یا قالب موجود را بارگیری کنید).
  • یک نمونه از کلاس DocumentBuilder ایجاد کنید و شی Document را به سازنده آن ارسال کنید.
  • یک Mail Merge را با استفاده از روش Document.getMailMerge().execute() اجرا کنید و منبع داده را به عنوان پارامتر ارسال کنید.
  • سند Word تولید شده را با استفاده از روش DocumentBuilder.getDocument().save(String) ذخیره کنید.

نمونه کد زیر نحوه انجام ادغام نامه را در اسناد Word با استفاده از جاوا نشان می دهد.

// کد قالب ما را وارد کنید
Document doc = new Document();

// سند را به سازنده اسناد منتقل کنید
DocumentBuilder builder = new DocumentBuilder(doc);

// ایجاد فیلدهای ادغام
builder.insertField(" MERGEFIELD CustomerName ");
builder.insertParagraph();
builder.insertField(" MERGEFIELD Item ");
builder.insertParagraph();
builder.insertField(" MERGEFIELD Quantity ");

// قالب را ذخیره کنید
builder.getDocument().save("MailMerge.TestTemplate.docx");

// فیلدهای سند را با اطلاعات کاربر پر کنید
doc.getMailMerge().execute(new String[] { "CustomerName", "Item", "Quantity" },
		new Object[] { "John Doe", "Hawaiian", "2" });

// سند را ذخیره کنید 
builder.getDocument().save("MailMerge.Simple.docx");

قالب

ادغام ایمیل ساده در جاوا

خروجی

ادغام ایمیل ساده

Mail Merge را با استفاده از منبع داده XML انجام دهید

در مثال قبلی، ما Mail Merge را با استفاده از اشیاء جاوا انجام دادیم. با این حال، در بیشتر موارد، یک منبع داده برای پر کردن فیلدهای ادغام استفاده می شود. برای نمایش، بیایید نحوه استفاده از منبع داده XML را در Mail Merge بررسی کنیم. مراحل زیر برای آن آورده شده است.

  • منبع داده XML را با استفاده از کلاس DataSet بارگیری کنید.
  • الگوی Mail Merge را با استفاده از کلاس Document بارگیری کنید.
  • از تابع execute برای پر کردن فیلدهای ادغام با استفاده از جدول داده مورد نظر در منبع داده استفاده کنید.
  • سند Word تولید شده را با استفاده از روش Document.save(String) ذخیره کنید.

در زیر منبع داده XML استفاده شده در این مثال است.

<?xml version="1.0" encoding="utf-8"?>
<customers>
	 <customer Name="John Ben Jan" ID="1" Domain="History" City="Boston"/>
 	<customer Name="Lisa Lane" ID="2" Domain="Chemistry" City="LA"/>
	 <customer Name="Dagomir Zits" ID="3" Domain="Heraldry" City="Milwaukee"/>
 	<customer Name="Sara Careira Santy" ID="4" Domain="IT" City="Miami"/>
</customers>

نمونه کد زیر نحوه پر کردن الگوی Mail Merge را با استفاده از جدول داده‌های مشتری در منبع داده XML نشان می‌دهد.

// Dataset را ایجاد کنید و XML را بخوانید
DataSet customersDs = new DataSet();
customersDs.readXml("Customers.xml");

// یک سند الگو را باز کنید
Document doc = new Document("TestFile XML.docx");

// ادغام نامه را برای پر کردن الگو با داده های XML با استفاده از DataTable اجرا کنید.
// توجه داشته باشید که این کلاس با یک منطقه قابل تکرار (و هر منطقه تودرتو) نیز کار می کند.
// برای ادغام چندین منطقه به طور همزمان از یک منبع داده XML، از کلاس XmlMailMergeDataSet استفاده کنید.
// به عنوان مثال doc.getMailMerge().executeWithRegions(New XmlMailMergeDataSet(xmlData));
doc.getMailMerge().execute(customersDs.getTables().get("Customer"));

// سند خروجی را ذخیره کنید
doc.save("generated-document.docx");

قالب

نامه با XML ادغام شد

خروجی

ایمیل ادغام xml

ادغام ایمیل با مناطق در جاوا

در موارد خاص، ممکن است لازم باشد منطقه خاصی را در سند تکرار کنید. به عنوان مثال، شما می خواهید سفارش های ارسال شده توسط هر مشتری را در یک جدول جداگانه نمایش دهید. در چنین مواردی، می توانید از مناطق Mail Merge استفاده کنید. برای ایجاد یک منطقه، می توانید شروع و پایان منطقه را مشخص کنید. در نتیجه، منطقه برای هر نمونه از داده ها در طول اجرای Mail Merge تکرار می شود.

اسکرین شات زیر یک الگو را نشان می دهد که در آن منطقه از یک جدول تشکیل شده است. با «TableStart:Customers» شروع می شود و به «TableEnd:Customers» ختم می شود.

الگوی منطقه ادغام ایمیل

نمونه کد زیر نحوه ایجاد یک الگو با مناطق و پر کردن آن با داده ها را نشان می دهد.

// سند ایجاد کنید
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// نقطه شروع نامه با مناطق مجموعه داده ادغام می شود.
builder.insertField(" MERGEFIELD TableStart:Customers");
// داده‌های ردیف‌های ستون «CustomerName» از جدول «Customers» می‌روند
// در این MERGEFIELD.
builder.write("Orders for ");
builder.insertField(" MERGEFIELD CustomerName");
builder.write(":");

// ایجاد هدر ستون
builder.startTable();
builder.insertCell();
builder.write("Item");
builder.insertCell();
builder.write("Quantity");
builder.endRow();

// ما یک جدول داده دوم به نام "Orders" داریم که دارای یک عدد به یک است
// ارتباط با "مشتریان"
// انتخاب ردیف هایی با همان مقدار CustomerID.
builder.insertCell();
builder.insertField(" MERGEFIELD TableStart:Orders");
builder.insertField(" MERGEFIELD ItemName");
builder.insertCell();
builder.insertField(" MERGEFIELD Quantity");
builder.insertField(" MERGEFIELD TableEnd:Orders");
builder.endTable();

// نقطه پایان نامه با مناطق ادغام می شود.
builder.insertField(" MERGEFIELD TableEnd:Customers");

// مجموعه داده ما را برای انجام ادغام نامه با مناطق ارسال کنید.
DataSet customersAndOrders = CreateDataSet();
doc.getMailMerge().executeWithRegions(customersAndOrders);

// نتیجه را ذخیره کنید
doc.save("MailMerge.ExecuteWithRegions.docx");

خروجی

منطقه ادغام ایمیل

مناطق ادغام ایمیل تودرتو با استفاده از جاوا ایجاد کنید

یکی دیگر از سناریوهای محبوب در Mail Merge زمانی است که مناطق تودرتو دارید. به عنوان مثال، هنگامی که باید سفارشات و موارد را در هر ترتیب فهرست کنید، می توانید از مناطق تو در تو استفاده کنید. تصویر زیر تصویر را در مورد مناطق تودرتو واضح تر می کند.

در تصویر بالا، جدول Orders و جدول Items را داریم که در آن هر رکورد در آیتم ها به یک رکورد در Orders پیوند داده شده است. از این رو، یک رابطه یک به چند بین این دو جدول وجود دارد. در چنین مواردی، Aspose.Words با مراقبت از روابط تعریف شده در DataSet، Mail Merge را اجرا می کند. به عنوان مثال، اگر منبع داده XML داشته باشیم، Aspose.Words یا از اطلاعات طرحواره یا ساختار XML برای یافتن روابط استفاده می کند. بنابراین، لازم نیست خودتان آن را به صورت دستی مدیریت کنید و متد Document.getMailMerge().executeWithRegions(DataSet) برای شما کار خواهد کرد (مانند مثال قبلی).

قالب بندی سفارشی را در فیلدهای ادغام اعمال کنید

برای اینکه کنترل بیشتری روی Mail Merge به شما بدهد، Aspose.Words برای جاوا به شما اجازه می دهد تا فیلدهای ادغام را در طول اجرای Mail Merge سفارشی کنید. متد setFieldMergingCallback(IFieldMergingCallback) کلاسی را می‌پذیرد که روش‌های fieldMerging(FieldMergingArgs) و imageFieldMerging(ImageFieldMergingArgs) را برای کنترل سفارشی روی فرآیند Mail Merge پیاده‌سازی می‌کند. رویداد fieldMerging(FieldMergingArgs) زمانی اتفاق می‌افتد که در طول اجرای Mail Merge با یک فیلد ادغام مواجه می‌شوید.

در زیر نمونه کد کاملی از نحوه سفارشی سازی عملیات Mail Merge و اعمال قالب بندی در سلول ها آمده است.

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");

        // یک کنترل کننده برای رویداد MergeField اضافه کنید.
        doc.getMailMerge().setFieldMergingCallback(new HandleMergeFieldAlternatingRows());

        // ادغام نامه با مناطق را اجرا کنید.
        DataTable dataTable = getSuppliersDataTable();
        doc.getMailMerge().executeWithRegions(dataTable);

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

    /**
     * اگر مقدار فرد باشد، true را برمی‌گرداند. false اگر مقدار زوج باشد.
     */
    public static boolean isOdd(int value) throws Exception {
        return (value % 2 != 0);
    }

    /**
     * DataTable را ایجاد کنید و آن را با داده پر کنید. در زندگی واقعی این DataTable
     * باید از پایگاه داده پر شود.
     */
    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");
    }

    /**
     * یک روش کمکی که یک ResultSet خالی جاوا را ایجاد می کند
     * ستون های مشخص شده
     */
    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 اضافه می کند
     * 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();

        // این "رقص" برای اضافه کردن ردیف ها به انتهای مجموعه نتیجه به درستی مورد نیاز است.
        // اگر کار دیگری انجام دهم، ردیف ها یا در جلو اضافه می شوند یا در نتیجه
        // set یک استثنا در مورد یک ردیف حذف شده در طول ادغام ایمیل ایجاد می کند.
        resultSet.moveToCurrentRow();
        resultSet.last();
    }
}

class HandleMergeFieldAlternatingRows implements IFieldMergingCallback {
    /**
     * برای هر فیلد ادغامی که در سند مواجه می شود فراخوانی می شود. ما هم می توانیم
     * برخی از داده ها را به موتور ادغام نامه برگردانید یا کار دیگری با آن انجام دهید
     * سند در این مورد ما قالب بندی سلول را تغییر می دهیم.
     */
    public void fieldMerging(FieldMergingArgs e) throws Exception {
        if (mBuilder == null)
            mBuilder = new DocumentBuilder(e.getDocument());

        // به این ترتیب شروع یک ردیف جدید را می گیریم.
        if (e.getFieldName().equals("CompanyName")) {
            // بسته به زوج یا فرد بودن شماره ردیف، رنگ را انتخاب کنید.
            Color rowColor;
            if (ApplyCustomFormattingDuringMailMerge.isOdd(mRowIdx))
                rowColor = new Color(213, 227, 235);
            else
                rowColor = new Color(242, 242, 242);

            // هیچ راهی برای تنظیم خصوصیات سلول برای کل ردیف در حال حاضر وجود ندارد،
            // بنابراین باید روی تمام سلول های ردیف تکرار کنیم.
           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 {
        // هیچ کاری نکن
    }

    private DocumentBuilder mBuilder;
    private int mRowIdx;
}

نتیجه

Mail Merge طیف گسترده ای از ویژگی ها را برای تولید اسناد MS Word به صورت پویا در اختیار شما قرار می دهد. شما می توانید گزارش های ساده و همچنین پیچیده را بر اساس داده های موجود در پایگاه های داده یا سایر منابع داده ایجاد کنید. در این مقاله نحوه پیاده سازی ویژگی های Mail Merge را به صورت برنامه نویسی با استفاده از جاوا مشاهده کرده اید. می‌توانید با استفاده از مستندات درباره Java Mail Merge API اطلاعات بیشتری کسب کنید.

همچنین ببینید