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

في بعض الأحيان يكون من الضروري دمج عدة مستندات في وثيقة واحدة. يمكنك القيام بذلك يدويًا أو يمكنك استخدام ميزة إدراج أو إلحاق 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-.NET.git.
Document srcDoc = new Document(MyDir + "Document source.docx");
Document dstDoc = new Document(MyDir + "Northwind traders.docx");
DocumentBuilder builder = new DocumentBuilder(dstDoc);

builder.MoveToDocumentEnd();
builder.InsertBreak(BreakType.PageBreak);

builder.InsertDocument(srcDoc, ImportFormatMode.KeepSourceFormatting);
builder.Document.Save(ArtifactsDir + "JoinAndAppendDocuments.InsertDocument.docx");

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

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

// Create destination document.
DocumentBuilder dstDoc = new DocumentBuilder();
dstDoc.Write("Before ");
dstDoc.InsertNode(new BookmarkStart(dstDoc.Document, "src_place"));
dstDoc.InsertNode(new BookmarkEnd(dstDoc.Document, "src_place"));
dstDoc.Write(" after");

Assert.AreEqual("Before  after", dstDoc.Document.GetText().TrimEnd());

// Insert source document into destination inline.
dstDoc.MoveToBookmark("src_place");
dstDoc.InsertDocumentInline(srcDoc.Document, ImportFormatMode.UseDestinationStyles, new ImportFormatOptions());

Assert.AreEqual("Before [src content] after", dstDoc.Document.GetText().TrimEnd());

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

قم بإدراج مستند أثناء عملية البحث والاستبدال

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

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

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET.git.
private class InsertDocumentAtReplaceHandler : IReplacingCallback
{
    ReplaceAction IReplacingCallback.Replacing(ReplacingArgs args)
    {
        Document subDoc = new Document(MyDir + "Document insertion 2.docx");

        // Insert a document after the paragraph, containing the match text.
        Paragraph para = (Paragraph)args.MatchNode.ParentNode;
        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-.NET.git.
Document mainDoc = new Document(MyDir + "Document insertion 1.docx");
            
FindReplaceOptions options = new FindReplaceOptions
{
    Direction = FindReplaceDirection.Backward, 
    ReplacingCallback = new InsertDocumentAtReplaceHandler()
};

mainDoc.Range.Replace(new Regex("\\[MY_DOCUMENT\\]"), "", options);
mainDoc.Save(ArtifactsDir + "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-.NET.git.
private class InsertDocumentAtMailMergeHandler : 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.
    void IFieldMergingCallback.FieldMerging(FieldMergingArgs args)
    {
        if (args.DocumentFieldName == "Document_1")
        {
            // Use document builder to navigate to the merge field with the specified name.
            DocumentBuilder builder = new DocumentBuilder(args.Document);
            builder.MoveToMergeField(args.DocumentFieldName);

            // The name of the document to load and insert is stored in the field value.
            Document subDoc = new Document((string)args.FieldValue);
            
            InsertDocument(builder.CurrentParagraph, subDoc);

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

            // Indicate to the mail merge engine that we have inserted what we wanted.
            args.Text = null;
        }
    }

    void IFieldMergingCallback.ImageFieldMerging(ImageFieldMergingArgs args)
    {
        // Do nothing.
    }
}

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

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

mainDoc.MailMerge.FieldMergingCallback = 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.MailMerge.Execute(new[] { "Document_1" }, new object[] { MyDir + "Document insertion 2.docx" });

mainDoc.Save(ArtifactsDir + "CloneAndCombineDocuments.InsertDocumentAtMailMerge.doc");

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

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

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

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

Bookmark bookmark = mainDoc.Range.Bookmarks["insertionPlace"];
InsertDocument(bookmark.BookmarkStart.ParentNode, subDoc);
            
mainDoc.Save(ArtifactsDir + "CloneAndCombineDocuments.InsertDocumentAtBookmark.docx");

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

إلحاق مستند

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

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

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

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

Document srcDoc = new Document();
srcDoc.FirstSection.Body.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.KeepSourceFormatting);

dstDoc.Save(ArtifactsDir + "JoinAndAppendDocuments.KeepSourceFormatting.docx");

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

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

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

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

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

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET.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.NodeType == NodeType.Paragraph || insertionDestination.NodeType == NodeType.Table)
    {
        CompositeNode destinationParent = insertionDestination.ParentNode;

        NodeImporter importer =
            new NodeImporter(docToInsert, insertionDestination.Document, ImportFormatMode.KeepSourceFormatting);

        // 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.
        foreach (Section srcSection in docToInsert.Sections.OfType<Section>())
        foreach (Node srcNode in srcSection.Body)
        {
            if (srcNode.NodeType == 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 ArgumentException("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-.NET.git.
Document srcDoc = new Document(MyDir + "Document source.docx");
Document dstDoc = new Document(MyDir + "Northwind traders.docx");

// Set the source document to continue straight after the end of the destination document.
srcDoc.FirstSection.PageSetup.SectionStart = SectionStart.Continuous;

// Restart the page numbering on the start of the source document.
srcDoc.FirstSection.PageSetup.RestartPageNumbering = true;
srcDoc.FirstSection.PageSetup.PageStartingNumber = 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.FirstSection.PageSetup.PageWidth = dstDoc.LastSection.PageSetup.PageWidth;
srcDoc.FirstSection.PageSetup.PageHeight = dstDoc.LastSection.PageSetup.PageHeight;
srcDoc.FirstSection.PageSetup.Orientation = dstDoc.LastSection.PageSetup.Orientation;

// Iterate through all sections in the source document.
foreach (Paragraph para in srcDoc.GetChildNodes(NodeType.Paragraph, true))
{
    para.ParagraphFormat.KeepWithNext = true;
}

dstDoc.AppendDocument(srcDoc, ImportFormatMode.KeepSourceFormatting);
            
dstDoc.Save(ArtifactsDir + "JoinAndAppendDocuments.DifferentPageSetup.docx");