دمج المراسلات في مستندات MS Word باستخدام Java

يغطي هذا المنشور كيفية تنفيذ عمليات دمج المراسلات في مستندات MS Word باستخدام Java. بنهاية هذه المقالة ، ستتعلم كيفية إنشاء قوالب دمج المراسلات وتنفيذ دمج المراسلات برمجيًا.

• حول دمج المراسلات
• Java Mail Merge API
• مصادر البيانات لدمج المراسلات
• قم بإنشاء قالب دمج المراسلات في MS Word
• قم بإنشاء قالب دمج المراسلات باستخدام Java
• قم بإجراء دمج المراسلات في مستند Word باستخدام Java
• دمج المراسلات باستخدام مصدر بيانات XML
• تنفيذ دمج المراسلات مع المناطق
• تكوين مناطق دمج المراسلات المتداخلة
• تنسيق مخصص لحقول الدمج

حول دمج المراسلات

دمج المراسلات هي طريقة ملائمة لإنشاء الرسائل والمغلفات والفواتير والتقارير وأنواع أخرى من المستندات ديناميكيًا. باستخدام دمج المراسلات ، يمكنك إنشاء ملف قالب يحتوي على حقول الدمج ثم ملء تلك الحقول باستخدام البيانات الموجودة في مصدر البيانات. لنفترض أنه يتعين عليك إرسال خطاب إلى 20 شخصًا مختلفًا وتحتاج فقط إلى تغيير اسم وعنوان المستلمين في كل نسخة. في هذه الحالة ، يمكنك إنشاء قالب دمج المراسلات للحرف ثم إنشاء 20 حرفًا عن طريق ملء حقول الاسم والعنوان ديناميكيًا.

Java Mail Merge API - تنزيل مجاني

Aspose.Words for Java هي واجهة برمجة تطبيقات معالجة كلمات مشهورة تتيح لك إنشاء أنواع مختلفة من المستندات من البداية. توفر واجهة برمجة التطبيقات (API) ميزات دمج المراسلات المضمنة التي تتيح لك إنشاء المستندات ديناميكيًا باستخدام القوالب ومصادر البيانات. يمكن تنزيل Aspose.Words for Java كـ 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>

مصادر البيانات لدمج المراسلات

يمكن جلب البيانات الموجودة في دمج المراسلات من أي مصدر بيانات مثل JSON أو XML أو جدول البيانات أو قاعدة بيانات.

إنشاء قالب لدمج المراسلات في MS Word

يمكن أن يكون القالب المستخدم في دمج المراسلات مستند Word بسيطًا (أي DOCX) ولا يلزم أن يكون بتنسيق قالب. يحتوي مستند القالب على حقول الدمج التي يتم ملؤها بالبيانات عند تنفيذ دمج المراسلات. فيما يلي خطوات كيفية تحضير قالب دمج المراسلات باستخدام MS Word.

• قم بإنشاء مستند جديد في MS Word.
• ضع المؤشر حيث تريد إضافة حقل دمج.
• من قائمة “إدراج” ، حدد خيار الحقل.
• من قائمة أسماء الحقول ، حدد MergeField.
• أدخل اسمًا لحقل الدمج في اسم الحقل واضغط على موافق.
• احفظ المستند بتنسيق DOCX.

فيما يلي لقطة شاشة من نموذج نموذج مستند.

قم بإنشاء قالب دمج المراسلات باستخدام Java

يمكنك أيضًا إنشاء قالب دمج المراسلات برمجيًا. فيما يلي الخطوات لذلك.

• قم بإنشاء مثيل لفئة DocumentBuilder.
• أدخل حقول الدمج باستخدام الأساليب التي يوفرها DocumentBuilder مثل insertTextInput و insertField و InsertParagraph وما إلى ذلك.
• احفظ المستند باستخدام طريقة DocumentBuilder.getDocument().save(String fileName).

يوضح نموذج التعليمات البرمجية التالي كيفية إنشاء قالب دمج المراسلات باستخدام Java.

// إنشاء منشئ المستندات
DocumentBuilder builder = new DocumentBuilder();

// أدخل حقل إدخال نص ، الاسم الفريد لهذا الحقل هو "مرحبًا" ، تحدد المعلمات الأخرى
// ما هو نوع 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");

قم بإجراء دمج المراسلات في مستند Word باستخدام Java

بمجرد أن يصبح القالب جاهزًا ، يمكنك ملء حقول الدمج بالبيانات. فيما يلي خطوات تنفيذ دمج المراسلات في قالب Word.

• قم بإنشاء قالب جديد باستخدام فئة مستند(أو قم بتحميل القالب الموجود).
• قم بإنشاء مثيل لفئة DocumentBuilder ومرر كائن المستند إلى المنشئ الخاص به.
• تنفيذ دمج المراسلات باستخدام طريقة Document.getMailMerge().تنفيذ() وتمرير مصدر البيانات كمعامل.
• احفظ مستند Word الذي تم إنشاؤه باستخدام طريقة DocumentBuilder.getDocument().save(String).

يُظهر نموذج التعليمات البرمجية التالي كيفية تنفيذ دمج المراسلات في مستندات Word باستخدام Java.

// قم بتضمين رمز القالب الخاص بنا
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");

قالب

انتاج |

قم بإجراء دمج المراسلات باستخدام مصدر بيانات XML

في المثال السابق ، قمنا بإجراء دمج المراسلات باستخدام كائنات Java. ومع ذلك ، في معظم الحالات ، يتم استخدام مصدر بيانات لملء حقول الدمج. للتوضيح ، دعنا نتحقق من كيفية استخدام مصدر بيانات XML في دمج المراسلات. فيما يلي الخطوات لذلك.

• قم بتحميل مصدر بيانات XML باستخدام فئة DataSet.
• قم بتحميل قالب دمج المراسلات باستخدام فئة مستند.
• استخدم وظيفة التنفيذ لملء حقول الدمج باستخدام جدول البيانات المطلوب في مصدر البيانات.
• احفظ مستند 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> 

يوضح نموذج التعليمات البرمجية التالي كيفية تعبئة قالب دمج المراسلات باستخدام جدول بيانات العميل في مصدر بيانات XML المتوفر.

// أنشئ مجموعة البيانات واقرأ XML
DataSet customersDs = new DataSet();
customersDs.readXml("Customers.xml");

// افتح مستند قالب
Document doc = new Document("TestFile XML.docx");

// تنفيذ دمج المراسلات لملء القالب ببيانات من XML باستخدام DataTable.
// لاحظ أن هذه الفئة تعمل أيضًا مع منطقة واحدة قابلة للتكرار (وأي مناطق متداخلة).
// لدمج مناطق متعددة في نفس الوقت من مصدر بيانات XML واحد ، استخدم فئة XmlMailMergeDataSet.
// على سبيل المثال doc.getMailMerge().executeWithRegions (جديد XmlMailMergeDataSet (xmlData)) ؛
doc.getMailMerge().execute(customersDs.getTables().get("Customer"));

// احفظ المستند الناتج
doc.save("generated-document.docx");

قالب

انتاج |

دمج المراسلات مع المناطق في Java

في بعض الحالات ، قد تحتاج إلى تكرار منطقة معينة في المستند. على سبيل المثال ، تريد عرض الطلبات التي وضعها كل عميل في جدول منفصل. في مثل هذه الحالات ، يمكنك الاستفادة من مناطق دمج المراسلات. لإنشاء منطقة ، يمكنك تحديد بداية المنطقة ونهايتها. نتيجة لذلك ، سيتم تكرار المنطقة لكل مثيل من البيانات أثناء تنفيذ دمج المراسلات.

تُظهر لقطة الشاشة التالية نموذجًا تتكون فيه المنطقة من جدول. يبدأ بـ «TableStart: Customers» وينتهي عند «TableEnd: customers».

يوضح نموذج التعليمات البرمجية التالي كيفية إنشاء قالب بالمناطق وتعبئته بالبيانات.

// إنشاء وثيقة
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// نقطة البداية لدمج المراسلات مع مناطق مجموعة البيانات.
builder.insertField(" MERGEFIELD TableStart:Customers");
// سيتم نقل البيانات من صفوف عمود "CustomerName" في جدول "العملاء"
// في هذا 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();

// لدينا جدول بيانات ثاني يسمى "الطلبات" ، والذي يحتوي على واحد إلى واحد
// العلاقة مع "العملاء"
// التقاط الصفوف بنفس قيمة معرف العميل.
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");

انتاج |

إنشاء مناطق دمج المراسلات المتداخلة باستخدام Java

السيناريو الشائع الآخر في Mail Merge هو عندما يكون لديك مناطق متداخلة. على سبيل المثال ، عندما يتعين عليك سرد الطلبات والعناصر في كل ترتيب ، يمكنك استخدام المناطق المتداخلة. تجعل الصورة التالية الصورة أكثر وضوحًا حول المناطق المتداخلة.

في الصورة أعلاه ، لدينا جدول الطلبات وجدول العناصر حيث يتم ربط كل سجل في العناصر بسجل في الطلبات. وبالتالي ، توجد علاقة رأس بأطراف بين هذين الجدولين. في مثل هذه الحالات ، يقوم Aspose.Words بتنفيذ دمج المراسلات مع مراعاة العلاقات المحددة في DataSet. على سبيل المثال ، إذا كان لدينا مصدر بيانات 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");

        // قم بإضافة معالج للحدث MergeField.
        doc.getMailMerge().setFieldMergingCallback(new HandleMergeFieldAlternatingRows());

        // تنفيذ دمج البريد مع المناطق.
        DataTable dataTable = getSuppliersDataTable();
        doc.getMailMerge().executeWithRegions(dataTable);

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

    /**
     * إرجاع صحيح إذا كانت القيمة فردية ؛ خطأ إذا كانت القيمة زوجية.
     */
    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");
    }

    /**
     * أسلوب مساعد يقوم بإنشاء Java فارغ غير متصل 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;
    }

    /**
     * أسلوب مساعد يضيف صفًا جديدًا بالقيم المحددة إلى ملف
     * 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();

        // هذه "الرقصة" ضرورية لإضافة صفوف إلى نهاية مجموعة النتائج بشكل صحيح.
        // إذا فعلت شيئًا آخر ، فسيتم إضافة الصفوف في المقدمة أو النتيجة
        // تعيين يطرح استثناء حول صف محذوف أثناء دمج المراسلات.
        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;
}

استنتاج

يوفر لك دمج المراسلات مجموعة واسعة من الميزات لإنشاء مستندات MS Word بشكل ديناميكي. يمكنك إنشاء تقارير بسيطة ومعقدة استنادًا إلى البيانات الموجودة في قواعد البيانات أو مصادر البيانات الأخرى. في هذه المقالة ، رأيت كيفية تنفيذ ميزات دمج المراسلات برمجيًا باستخدام Java. يمكنك معرفة المزيد حول Java Mail Merge API باستخدام التوثيق.

أنظر أيضا

• قم بإنشاء مستندات Rich Word برمجيًا في Java