إدراج المستندات وإلحاقها

في بعض الأحيان يكون مطلوبا دمج عدة مستندات في مستند واحد. يمكنك القيام بذلك يدويا أو يمكنك استخدام Aspose.Words إدراج أو إلحاق الميزة.

تتيح لك عملية الإدراج إدراج محتوى المستندات التي تم إنشاؤها مسبقا في مستند جديد أو موجود.

في المقابل، تتيح لك ميزة الإلحاق إضافة مستند فقط في نهاية مستند آخر.

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

أدخل وثيقة

كما ذكر أعلاه، في Aspose.Words يتم تمثيل المستند كشجرة من العقد، وعملية إدراج مستند في آخر هي نسخ العقد من شجرة المستند الأولى إلى الثانية.

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

يمكنك أيضا استخدام طريقة InsertDocument أو InsertDocumentInline، والتي تشبه إدراج مستند في Microsoft Word، لإدراج مستند كامل في موضع المؤشر الحالي دون أي استيراد سابق.

يوضح مثال التعليمات البرمجية التالية كيفية إدراج مستند باستخدام طريقة InsertDocument:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java.git.
Document srcDoc = new Document(getMyDir() + "Document source.docx");
Document dstDoc = new Document(getMyDir() + "Northwind traders.docx");
DocumentBuilder builder = new DocumentBuilder(dstDoc);

builder.moveToDocumentEnd();
builder.insertBreak(BreakType.PAGE_BREAK);

builder.insertDocument(srcDoc, ImportFormatMode.KEEP_SOURCE_FORMATTING);
builder.getDocument().save(getArtifactsDir() + "JoinAndAppendDocuments.insertDocument.docx");

يوضح مثال التعليمات البرمجية التالية كيفية إدراج مستند باستخدام طريقة InsertDocumentInline:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java.git.
DocumentBuilder srcDoc = new DocumentBuilder();
srcDoc.write("[src content]");

// Create destination document.
DocumentBuilder dstDoc = new DocumentBuilder();
dstDoc.write("Before ");
dstDoc.insertNode(new BookmarkStart(dstDoc.getDocument(), "src_place"));
dstDoc.insertNode(new BookmarkEnd(dstDoc.getDocument(), "src_place"));
dstDoc.write(" after");

Assert.assertEquals("Before  after", dstDoc.getDocument().getText().trim());

// Insert source document into destination inline.
dstDoc.moveToBookmark("src_place");
dstDoc.insertDocumentInline(srcDoc.getDocument(), ImportFormatMode.USE_DESTINATION_STYLES, new ImportFormatOptions());

Assert.assertEquals("Before [src content] after", dstDoc.getDocument().getText().trim());

تصف الأقسام الفرعية التالية الخيارات التي يمكنك خلالها إدراج مستند في مستند آخر.

أدخل مستندا أثناء عملية البحث والاستبدال

يمكنك إدراج المستندات أثناء إجراء عمليات البحث والاستبدال. على سبيل المثال، يمكن أن يحتوي المستند على فقرات بالنص [INTRODUCTION] و [CONCLUSION]. لكن في المستند النهائي، تحتاج إلى استبدال تلك الفقرات بالمحتوى الذي تم الحصول عليه من مستند خارجي آخر. لتحقيق ذلك، سوف تحتاج إلى إنشاء معالج للحدث استبدال.

يوضح مثال التعليمات البرمجية التالية كيفية إنشاء معالج للحدث استبدال لاستخدامه لاحقا في عملية الإدراج:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java.git.
private static class InsertDocumentAtReplaceHandler implements IReplacingCallback
{
    public /*ReplaceAction*/int /*IReplacingCallback.*/replacing(ReplacingArgs args) throws Exception
    {
        Document subDoc = new Document(getMyDir() + "Document insertion 2.docx");

        // Insert a document after the paragraph, containing the match text.
        Paragraph para = (Paragraph)args.getMatchNode().getParentNode();
        insertDocument(para, subDoc);
        
        // Remove the paragraph with the match text.
        para.remove();
        return ReplaceAction.SKIP;
    }
}

يوضح مثال الكود التالي كيفية إدراج محتوى مستند إلى آخر أثناء عملية البحث والاستبدال:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java.git.
Document mainDoc = new Document(getMyDir() + "Document insertion 1.docx");

// Set find and replace options.
FindReplaceOptions options = new FindReplaceOptions();
{
    options.setDirection(FindReplaceDirection.BACKWARD); 
    options.setReplacingCallback(new InsertDocumentAtReplaceHandler());
}

// Call the replace method.
mainDoc.getRange().replace(Pattern.compile("\\[MY_DOCUMENT\\]"), "", options);
mainDoc.save(getArtifactsDir() + "CloneAndCombineDocuments.InsertDocumentAtReplace.docx");

أدخل مستندا أثناء عملية Mail Merge

يمكنك إدراج مستند في حقل دمج أثناء عملية Mail Merge. على سبيل المثال، يمكن أن يحتوي قالب Mail Merge على حقل دمج مثل [ملخص]. ولكن في المستند النهائي، تحتاج إلى إدراج محتوى تم الحصول عليه من مستند خارجي آخر في حقل الدمج هذا. لتحقيق ذلك، سوف تحتاج إلى إنشاء معالج لحدث الدمج.

يوضح مثال التعليمات البرمجية التالية كيفية إنشاء معالج لحدث الدمج لاستخدامه لاحقا في عملية الإدراج:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java.git.
private static class InsertDocumentAtMailMergeHandler implements IFieldMergingCallback
{
    // This handler makes special processing for the "Document_1" field.
    // The field value contains the path to load the document. 
    // We load the document and insert it into the current merge field.
    public void /*IFieldMergingCallback.*/fieldMerging(FieldMergingArgs args) throws Exception
    {
        if ("Document_1".equals(args.getDocumentFieldName()))
        {
            // Use document builder to navigate to the merge field with the specified name.
            DocumentBuilder builder = new DocumentBuilder(args.getDocument());
            builder.moveToMergeField(args.getDocumentFieldName());

            // The name of the document to load and insert is stored in the field value.
            Document subDoc = new Document((String)args.getFieldValue());
            
            insertDocument(builder.getCurrentParagraph(), subDoc);

            // The paragraph that contained the merge field might be empty now, and you probably want to delete it.
            if (!builder.getCurrentParagraph().hasChildNodes())
                builder.getCurrentParagraph().remove();

            // Indicate to the mail merge engine that we have inserted what we wanted.
            args.setText(null);
        }
    }

    public void /*IFieldMergingCallback.*/imageFieldMerging(ImageFieldMergingArgs args)
    {
        // Do nothing.
    }
}

يوضح مثال التعليمات البرمجية التالية كيفية إدراج مستند في حقل الدمج باستخدام المعالج الذي تم إنشاؤه:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java.git.
Document mainDoc = new Document(getMyDir() + "Document insertion 1.docx");

mainDoc.getMailMerge().setFieldMergingCallback(new InsertDocumentAtMailMergeHandler());
// The main document has a merge field in it called "Document_1".
// The corresponding data for this field contains a fully qualified path to the document.
// That should be inserted to this field.
mainDoc.getMailMerge().execute(new String[] { "Document_1" }, new Object[] { getMyDir() + "Document insertion 2.docx" });

mainDoc.save(getArtifactsDir() + "CloneAndCombineDocuments.InsertDocumentAtMailMerge.doc");

أدخل مستندا في إشارة مرجعية

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

يوضح مثال الترميز التالي كيفية إدراج محتويات مستند إلى إشارة مرجعية في مستند آخر:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java.git.
Document mainDoc = new Document(getMyDir() + "Document insertion 1.docx");
Document subDoc = new Document(getMyDir() + "Document insertion 2.docx");

Bookmark bookmark = mainDoc.getRange().getBookmarks().get("insertionPlace");
insertDocument(bookmark.getBookmarkStart().getParentNode(), subDoc);
        
mainDoc.save(getArtifactsDir() + "CloneAndCombineDocuments.InsertDocumentAtBookmark.docx");

لاحظ أن الإشارة المرجعية يجب ألا تحتوي على عدة فقرات أو نص تريده أن يظهر في المستند النهائي الناتج.

إلحاق مستند

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

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

يوضح مثال التعليمات البرمجية التالية كيفية إلحاق مستند إلى نهاية مستند آخر:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java.git.
Document dstDoc = new Document();
dstDoc.getFirstSection().getBody().appendParagraph("Destination document text. ");

Document srcDoc = new Document();
srcDoc.getFirstSection().getBody().appendParagraph("Source document text. ");

// Append the source document to the destination document.
// Pass format mode to retain the original formatting of the source document when importing it.
dstDoc.appendDocument(srcDoc, ImportFormatMode.KEEP_SOURCE_FORMATTING);

dstDoc.save(getArtifactsDir() + "JoinAndAppendDocuments.KeepSourceFormatting.docx");

استيراد وإدراج العقد يدويا

Aspose.Words يسمح لك بإدراج وإلحاق المستندات تلقائيا دون أي متطلبات استيراد سابقة. ومع ذلك، إذا كنت بحاجة إلى إدراج أو إلحاق عقدة معينة من المستند، مثل قسم أو فقرة، فأنت بحاجة أولا إلى استيراد هذه العقدة يدويا.

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

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

يوضح مثال الكود التالي كيفية استيراد العقد يدويا وإدراجها بعد عقدة معينة باستخدام طريقة InsertAfter:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java.git.
/// <summary>
/// Inserts content of the external document after the specified node.
/// Section breaks and section formatting of the inserted document are ignored.
/// </summary>
/// <param name="insertionDestination">Node in the destination document after which the content
/// Should be inserted. This node should be a block level node (paragraph or table).</param>
/// <param name="docToInsert">The document to insert.</param>
private static void insertDocument(Node insertionDestination, Document docToInsert)
{
    if (insertionDestination.getNodeType() == NodeType.PARAGRAPH || insertionDestination.getNodeType() == NodeType.TABLE)
    {
        CompositeNode destinationParent = insertionDestination.getParentNode();

        NodeImporter importer =
            new NodeImporter(docToInsert, insertionDestination.getDocument(), ImportFormatMode.KEEP_SOURCE_FORMATTING);

        // Loop through all block-level nodes in the section's body,
        // then clone and insert every node that is not the last empty paragraph of a section.
        for (Section srcSection : docToInsert.getSections())
        for (Node srcNode : srcSection.getBody())
        {
            if (srcNode.getNodeType() == NodeType.PARAGRAPH)
            {
                Paragraph para = (Paragraph)srcNode;
                if (para.isEndOfSection() && !para.hasChildNodes())
                    continue;
            }

            Node newNode = importer.importNode(srcNode, true);

            destinationParent.insertAfter(newNode, insertionDestination);
            insertionDestination = newNode;
        }
    }
    else
    {
        throw new IllegalArgumentException("The destination node should be either a paragraph or table.");
    }
}

يقوم الاستيراد بإنشاء عقدة جديدة هي نسخة من العقدة الأصلية ومناسبة للإدراج في المستند الوجهة.

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

الخصائص الشائعة لإدراج وإلحاق المستندات

تقبل كل من الطريقتين InsertDocument و AppendDocument ImportFormatMode و ImportFormatOptions كمعلمات إدخال. يسمح لك ImportFormatMode بالتحكم في كيفية دمج تنسيق المستند عند استيراد محتوى من مستند إلى آخر عن طريق تحديد أوضاع تنسيق مختلفة مثل UseDestinationStyles و KeepSourceFormatting و KeepDifferentStyles. ال ImportFormatOptions يسمح لك بتحديد خيارات استيراد مختلفة مثل IgnoreHeaderFooter, IgnoreTextBoxes, KeepSourceNumbering, MergePastedLists, و SmartStyleBehavior.

Aspose.Words يسمح لك بضبط التصور للمستند الناتج عند إضافة وثيقتين معا في عملية إدراج أو إلحاق باستخدام خصائص Section و PageSetup. تحتوي الخاصية PageSetup على جميع سمات قسم مثل SectionStart, RestartPageNumbering, PageStartingNumber, Orientation, وغيرها. حالة الاستخدام الأكثر شيوعا هي تعيين خاصية SectionStart لتحديد ما إذا كان المحتوى المضاف سيظهر على نفس الصفحة أو ينقسم إلى صفحة جديدة.

لاحظ أن الخصائص Section و PageSetup لا تتحكم في كيفية إدراج/إلحاق مستندين معا. إنها تسمح لك فقط بتغيير مظهر مستند النتائج الخاص بك.

يوضح مثال الكود التالي كيفية إلحاق مستند بآخر مع الحفاظ على المحتوى من الانقسام عبر صفحتين:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java.git.
Document srcDoc = new Document(getMyDir() + "Document source.docx");
Document dstDoc = new Document(getMyDir() + "Northwind traders.docx");

// Set the source document to continue straight after the end of the destination document.
srcDoc.getFirstSection().getPageSetup().setSectionStart(SectionStart.CONTINUOUS);

// Restart the page numbering on the start of the source document.
srcDoc.getFirstSection().getPageSetup().setRestartPageNumbering(true);
srcDoc.getFirstSection().getPageSetup().setPageStartingNumber(1);

// To ensure this does not happen when the source document has different page setup settings, make sure the
// settings are identical between the last section of the destination document.
// If there are further continuous sections that follow on in the source document,
// this will need to be repeated for those sections.
srcDoc.getFirstSection().getPageSetup().setPageWidth(dstDoc.getLastSection().getPageSetup().getPageWidth());
srcDoc.getFirstSection().getPageSetup().setPageHeight(dstDoc.getLastSection().getPageSetup().getPageHeight());
srcDoc.getFirstSection().getPageSetup().setOrientation(dstDoc.getLastSection().getPageSetup().getOrientation());

// Iterate through all sections in the source document.
for (Paragraph para : (Iterable<Paragraph>) srcDoc.getChildNodes(NodeType.PARAGRAPH, true))
{
    para.getParagraphFormat().setKeepWithNext(true);
}

dstDoc.appendDocument(srcDoc, ImportFormatMode.KEEP_SOURCE_FORMATTING);
        
dstDoc.save(getArtifactsDir() + "JoinAndAppendDocuments.DifferentPageSetup.docx");