المقدمة
ينظر هذا الدليل إلى كيفية تمثيل Aspose.Words FOSS لـ .NET مستند Word في الذاكرة، وإلى واجهات برمجة التطبيقات المستخدمة لإنشاء، والتنقل، وتغيير هذا التمثيل: DocumentBuilder للتأليف المتسلسل، وشجرة العقد (Node, CompositeNode, NodeCollection) للوصول الهيكلي المباشر، DocumentVisitor لمعالجة كل نوع من العقد في تمريرة واحدة، البحث والاستبدال عبر Range و FindReplaceOptions، والطرق لدمج واستنساخ المستندات. حيث منشور الإعلان يقدم المكتبة ككل، بينما يظل هذا الدليل مركزًا على نموذج كائن المستند (DOM) — أكبر مجال في سطح API — وكيف تتناسب أجزاؤه معًا.
Aspose.Words FOSS لـ .NET مُصدَر تحت رخصة MIT دون أي تبعيات أصلية؛ يستهدف .NET Standard 2.0، لذا فإن الـ DOM الموصوف هنا متاح على .NET Framework 4.6.2+ و.NET 6، 8، و10، على Windows وLinux وmacOS. قم بتنصيبه عبر NuGet، أو ابنِه من المصدر — راجع دليل البدء السريع أدناه.
كل مهمة موصوفة أدناه — كتابة تقرير من الصفر، إعادة هيكلة ملف .docx موجود، استعراض محتوياته للتحليل، أو تجميع عدة مستندات في واحد — تبدأ من نفس مجموعة الأنواع الأساسية القليلة: Document، DocumentBuilder، وتسلسل Node الهرمي تحتها.
الـ Document Object Model
إنشاء المستندات باستخدام DocumentBuilder
DocumentBuilder هو كاتب يعتمد على المؤشر يجلس فوق Document ويُدرج المحتوى تسلسليًا. Write(text) و Writeln(text) يضيفان نصًا في الموقع الحالي؛ InsertParagraph() و InsertBreak(breakType) يضيفان فقرات وفواصل صفحة/عمود/قسم. التنسيق ذو حالة: خصائص Font، ParagraphFormat، ListFormat، و PageSetup للمنشئ تُطبق على كل ما يُكتب لاحقًا، و PushFont() / PopFont() يحفظان ويستعيدان حالة الخط الحالية بحيث لا يلزم إلغاء تغيير نمط مؤقت يدويًا. طرق التنقل تعيد تموضع المؤشر إلى أي مكان في مستند موجود — MoveToDocumentStart()، MoveToDocumentEnd()، MoveToSection(sectionIndex)، MoveToBookmark(bookmarkName)، MoveToParagraph(paragraphIndex, characterIndex)، والوظيفة العامة MoveTo(node) — و DocumentBuilder.CurrentNode، DocumentBuilder.CurrentParagraph، و DocumentBuilder.CurrentSection تُبلغ عن مكان وجود المنشئ حاليًا. لاستخراج النص للقراءة فقط حيث لا تحتاج إلى DOM كامل، يوفر PlainTextDocument مسارًا أخف: new PlainTextDocument(fileName) يكشف فقط الخاصية PlainTextDocument.Text والخصائص المدمجة والمخصصة للمستند.
شجرة العقد: الأقسام، الفقرات، الجمل، والجداول
Document هو شجرة من كائنات Node متجذرة في المستند نفسه: Section → Body → Paragraph → Run لنص الجسم، مع تفرع Table → Row → Cell حيثما يظهر جدول. CompositeNode، الفئة الأساسية لكل عقدة حاوية، تُظهر CompositeNode.FirstChild، CompositeNode.LastChild، Node.NextSibling، و Node.PreviousSibling للتنقل المباشر، و GetChildNodes(nodeType, isDeep) لجمع كل عقدة من نوع NodeType معين (Paragraph، Run، Table، وما إلى ذلك) على أي عمق، و GetChild(nodeType, index, isDeep) للبحث المفهرس. AppendChild(newChild)، InsertBefore(newChild, refChild)، InsertAfter(newChild, refChild)، و RemoveChild(oldChild) تُغيّر الشجرة مباشرة. CompositeNode.SelectNodes(xpath) و SelectSingleNode(xpath) يختاران العقد باستخدام تعبير شبيه بـ XPath بدلاً من تجوال الشجرة يدويًا، وللمستندات الكبيرة جدًا، Node.NextPreOrder(rootNode) / PreviousPreOrder(rootNode) ينتقلان عبر كل عقدة واحدة تلو الأخرى دون استدعاء متكرر.
DocumentVisitor: معالجة كل نوع عقدة في تمريرة واحدة
إنّ إنشاء فئة فرعية من DocumentVisitor هو الطريقة لمعالجة مستند دون ترميز هيكله يدويًا. تُعرّف طرقًا مزدوجة Visit-Start / Visit-End لكل نوع عقدة مركبة، بما في ذلك DocumentVisitor.VisitSectionStart، DocumentVisitor.VisitParagraphStart، DocumentVisitor.VisitTableStart، DocumentVisitor.VisitRowStart، DocumentVisitor.VisitCellStart، و DocumentVisitor.VisitBookmarkStart — كل منها مع رد نداء End مطابق — بالإضافة إلى DocumentVisitor.VisitFieldStart، DocumentVisitor.VisitFieldSeparator، DocumentVisitor.VisitFieldEnd، و DocumentVisitor.VisitRun لتشغيلات النص الفردية. استدعِ Accept(visitor) على Document أو Section أو أي عقدة أخرى لتشغيل الزائر على تلك العقدة وكل ما تحتها؛ AcceptStart(visitor) و AcceptEnd(visitor) تستدعيان فقط ردود الدخول والخروج لعقدة مركبة واحدة. كل طريقة Visit تُعيد قيمة VisitorAction التي تتحكم في استمرار التجوال — Continue إلى الشجرة الفرعية، SkipThisNode لتجاوزها، أو Stop لإيقاف العملية تمامًا.
العثور على النص واستبداله
Range.Replace(pattern, replacement) يقوم بتنفيذ عملية البحث والاستبدال على الـ Range التي تملكه — مستند Document كامل، أو Section، أو أي خاصية Range خاصة بعقدة — مع قبول نمط البحث إما كسلسلة حرفية أو كتعبير نمطي. التحميل الزائد Range.Replace(pattern, replacement, options) يأخذ مثيل FindReplaceOptions للتحكم في FindReplaceOptions.MatchCase، FindReplaceOptions.FindWholeWordsOnly، اتجاه البحث FindReplaceOptions.Direction (قيمة FindReplaceDirection إما Forward أو Backward)، التنسيق المطبق على نص الاستبدال (FindReplaceOptions.ApplyFont، FindReplaceOptions.ApplyParagraphFormat)، وأي محتوى محيط يجب تركه دون تعديل (FindReplaceOptions.IgnoreFields، FindReplaceOptions.IgnoreFootnotes، FindReplaceOptions.IgnoreFieldCodes، وعلامات Ignore* المرتبطة). للمنطق المتعلق بكل تطابق بخلاف الاستبدال البسيط، نفّذ طريقة Replacing(args) من IReplacingCallback وعيّن التنفيذ إلى FindReplaceOptions.ReplacingCallback؛ كل تطابق يستدعي ردًا مع ReplacingArgs يصف التطابق، وقيمة الإرجاع من الدالة الراجعة — قيمة ReplaceAction إما Replace أو Skip أو Stop — تحدد ما سيحدث معه.
دمج واستنساخ المستندات
Document.AppendDocument(srcDoc, importFormatMode) يضيف المحتوى الكامل لـ Document واحد إلى نهاية آخر. حجّة importFormatMode — قيمة ImportFormatMode من UseDestinationStyles أو KeepSourceFormatting أو KeepDifferentStyles — تقرر كيف يتم حل تعارض الأنماط بين المصدر والوجهة، وتضيف التحميل الزائد Document.AppendDocument(srcDoc, importFormatMode, importFormatOptions) تحكمًا أدق من خلال ImportFormatOptions (ImportFormatOptions.KeepSourceNumbering، ImportFormatOptions.IgnoreHeaderFooter، ImportFormatOptions.MergePastedLists، وعلامات مماثلة). لإدراج محتوى مستند آخر في موضع محدد بدلاً من النهاية، يقوم DocumentBuilder.InsertDocument(srcDoc, importFormatMode, importFormatOptions) بما يعادل ذلك من موضع المؤشر الحالي للمنشئ، و DocumentBuilder.InsertDocumentInline(srcDoc, importFormatMode, importFormatOptions) يُدرج نفس المحتوى دون إضافة فاصل فقرة أو قسم عند نقطة الإدراج. Document.ImportNode(srcNode, isImportChildren) ينسخ عقدة واحدة — اختياريًا مع أطفالها — من مستند مختلف بحيث يمكن إلحاقها بالمستند الحالي، وتُعيد طريقة Node.Clone(isCloneChildren) المتاحة على أي عقدة نسخة مكررة من الهيكل داخل نفس المستند، مثل إعادة استخدام Section كقالب لمحتوى متكرر.
الإشارات المرجعية ومتغيرات المستند
خاصية Range.Bookmarks تكشف عن BookmarkCollection من الروابط المسماة داخل ذلك النطاق. DocumentBuilder.StartBookmark(bookmarkName) و EndBookmark(bookmarkName) يحددان مدى الإشارة أثناء الإنشاء؛ فـ BookmarkCollection الفهرس، bookmarks[name]، يسترجع واحدة لاحقًا لاستخدامها في التنقل عبر DocumentBuilder.MoveToBookmark(bookmarkName) أو لقراءة Bookmark.Text. بشكل منفصل، Document.Variables — وهي VariableCollection — تخزن أزواج سلسلة اسم/قيمة عشوائية مباشرة على المستند نفسه، وهو مفيد لحمل قطع صغيرة من الحالة عبر خط أنابيب توليد المستند دون إضافة محتوى مرئي.
البدء السريع
Aspose.Words FOSS لـ .NET متاح عبر NuGet:
dotnet add package Aspose.Words.FOSSلبناء من المصدر بدلاً من ذلك:
git clone https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git
cd Aspose.Words-FOSS-for-.NET
dotnet build Aspose.Words.sln -c Release
مع وجود إشارة مشروع إلى Aspose.Words.csproj، فإن أقصر مسار إلى المستند يتبع نفس النمط المستخدم طوال هذه المشاركة: إنشاء Document، تغليفه في DocumentBuilder، استدعاء Write() أو Writeln() لإضافة نص — التنسيق المحدد في خصائص Font وParagraphFormat لكائن الـ builder ينتقل إلى كل عملية كتابة لاحقة — ثم استدعاء Document.Save(fileName) لحفظه كـ .docx، .docm، .dotx، .dotm، Flat OPC، Markdown، أو نص عادي. لتحرير ملف موجود بدلاً من البدء من الصفر، قم بتحميله مباشرةً باستخدام new Document(fileName)، وانقل الـ builder إلى موقع محدد باستخدام MoveToBookmark() أو MoveToParagraph() أو MoveTo(node)، ثم استمر في الكتابة من هناك.
الصيغ المدعومة
| التنسيق | الامتداد | قراءة | اكتب |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| OPC مسطح (جميع المتغيّرات) | (متنوعة) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
شجرة العقد الموصوفة أعلاه متاحة بنفس الطريقة بغض النظر عن أيٍ من هذه الصيغ تم تحميل المستند منها أو سيُحفظ إليها — الـ DOM مستقل عن الصيغة داخليًا. ما لا يتضمنه هذا الإصدار هو أي شيء يعتمد على تخطيط الصفحة: لا PDF ولا XPS ولا تصدير صور، ولا طباعة، لذا فإن قيم الحقول المعتمدة على التخطيط مثل أرقام الصفحات تُقَيَّم كعناصر نائبة بدلاً من حسابها. محولات الصيغ الإضافية (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3, and WordML) لا تُقَرَأ ولا تُكتب، ولا تشمل تنفيذ الدمج البريدي، LINQ Reporting، ومقارنة المستندات. يمكن للمطورين الذين يحتاجون إلى هذه القدرات الانتقال إلى النسخة التجارية Aspose.Words لـ .NET دون إعادة كتابة كود DOM المعروض هنا، لأن كلا الإصدارين يشاركان نفس API الأساسي.
المصدر المفتوح والترخيص
Aspose.Words FOSS لـ .NET تم إصداره تحت رخصة MIT، مجاني للاستخدام التجاري والشخصي دون أي إتاوات أو قيود على إعادة التوزيع. المصدر، بما في ذلك الـ Document, DocumentBuilder، وتطبيق شجرة العقد الموصوف أعلاه، متوفر في الـ مستودع Aspose.Words FOSS لـ .NET على GitHub.
