العمل مع المستندات
العمل مع المستندات
Aspose.Words FOSS لـ .NET يمثل كل ملف Word كنموذج كائنات في الذاكرة يبدأ من الفئة Document، مع DocumentBuilder التي توفر API عالي المستوى قائم على المؤشر لتأليف المحتوى. يغطي هذا الدليل إنشاء وتحميل المستندات، التأليف باستخدام DocumentBuilder، بنية القسم/المحتوى، تجوال شجرة العقد، دمج المستندات، وحمايتها.
إنشاء وتحميل المستندات
أنشئ مستندًا فارغًا باستخدام new Document()، أو افتح ملفًا موجودًا بتمرير مسار أو Stream إلى المُنشئ Document(fileName) أو Document(stream). التحميلات الزائدة التي تقبل معامل LoadOptions تسمح لك بالتحكم في سلوك التحميل، مثل توفير كلمة مرور لملف مشفر.
قبل تحميل ملف من مصدر غير معروف أو غير موثوق، يقوم FileFormatUtil.DetectFileFormat(fileName) (أو التحميل Stream) بإرجاع FileFormatInfo يصف LoadFormat المكتشف، وما إذا كان الملف IsEncrypted، HasDigitalSignature، أو HasMacros.
التأليف باستخدام DocumentBuilder
DocumentBuilder يغلف Document ويكشف عن مؤشر يمكنك تحريكه عبر المستند أثناء إدراج المحتوى. Write(text) وWriteln(text) يدرجان نصًا عند المؤشر؛ InsertParagraph() يبدأ فقرة جديدة. خصائص التنسيق على المُنشئ — Font، ParagraphFormat، ListFormat، PageSetup — تُطبق على ما يُكتب بعد ذلك.
حرك المؤشر باستخدام MoveToDocumentStart()، MoveToDocumentEnd()، MoveToSection(sectionIndex)، MoveToBookmark(bookmarkName) أو MoveToParagraph(paragraphIndex, characterIndex). خصائص CurrentNode وCurrentParagraph وCurrentSection الخاصة بالباني تُبلغ عن موقعه الحالي في الشجرة.
بنية المستند: الأقسام والجسم
يحتوي Document على SectionCollection (Document.Sections، بالإضافة إلى FirstSection / LastSection)؛ كل Section لديه Body واحد، ومجموعة رؤوس/تذييلات اختيارية، وPageSetup الخاص به. يقوم Section.AppendContent(sourceSection) وPrependContent(sourceSection) بنسخ المحتوى بين الأقسام، وClearContent() يعيد ضبط قسم دون إزالته من المستند.
داخل Body، يُعرَض المحتوى عبر Body.Paragraphs (وهو ParagraphCollection) وBody.Tables. الـRange — المتاح من Document وSection وParagraph وعُقَد أخرى — يمثل مساحة متصلة من الشجرة؛ Range.Text يقرأ نصه الصريح وRange.Replace(pattern, replacement) يُجري عملية بحث-استبدال على تلك المنطقة فقط.
التجول في شجرة العقد باستخدام DocumentVisitor
كل جزء من المستند — الأقسام، الفقرات، السلاسل، الجداول، الحقول، الأشكال، التعليقات، الحواشي — هو Node في شجرة مركبة جذورها Document. لمعالجة كل عقدة من نوع معين دون الحاجة إلى الاستدعاء المتكرر يدويًا، قم بإنشاء فئة فرعية من DocumentVisitor المجردة وتجاوز استدعاءات Visit*Start / Visit*End التي تحتاجها، مثل VisitParagraphStart(paragraph) أو VisitRun(run)، ثم استدعِ document.Accept(visitor). يمكن لكل استدعاء إرجاع VisitorAction (Continue، SkipThisNode أو Stop) للتحكم في طريقة سير التجوال.
استنساخ، استيراد، وإلحاق المحتوى
Document.Clone() ينتج نسخة عميقة من مستند كامل. لنقل المحتوى بين مثيلتين مختلفتين من Document، استدعِ ImportNode(srcNode, isImportChildren) على المستند الوجهة لجلب عقدة من شجرة خارجية، أو استدعِ Document.AppendDocument(srcDoc, importFormatMode) لإلحاق أقسام مستند بآخر باستخدام ImportFormatMode مختار — KeepSourceFormatting أو UseDestinationStyles أو KeepDifferentStyles. DocumentBuilder.InsertDocument(srcDoc, importFormatMode) يدرج محتوى المستند المصدر عند مؤشر الباني بدلاً من نهايته في الوجهة.
حماية المستندات
Document.Protect(type, password) يقيّد التحرير وفقًا لقيمة ProtectionType — ReadOnly، AllowOnlyComments، AllowOnlyRevisions، AllowOnlyFormFields أو NoProtection لإزالة الحماية. Unprotect() (مع أو بدون كلمة مرور) يعكس ذلك. هذا تقييد تحرير يفرضه Word، منفصل عن تشفير كلمة المرور في OOXML الذي يطبّقه OoxmlSaveOptions.Password عند حفظ الملف.
نصائح وأفضل الممارسات
- يفضَّل استخدام
DocumentBuilderلإنشاء محتوى جديد؛ انتقل إلى التلاعب المباشر بالعقد (AppendChild،InsertAfter،Clone) عندما تحتاج إلى سيطرة دقيقة على شجرة موجودة. - استدعِ
FileFormatUtil.DetectFileFormatقبل تحميل ملف من مصدر غير موثوق أو مقدم من المستخدم حتى تتمكن من فحصLoadFormatورفض الإدخال غير المدعوم أو المشفر مبكرًا. - عند دمج المستندات باستخدام
AppendDocumentأوInsertDocument، اخترImportFormatModeبعناية —KeepSourceFormattingيحافظ على مظهر المصدر،UseDestinationStylesيتطابق مع مجموعة أنماط المستند الهدف. - استخدم فئة فرعية من
DocumentVisitorبدلاً من التجوال اليدوي المتكرر في الشجرة عندما تحتاج إلى معالجة كل مثال من نوع العقدة بشكل ثابت. Document.Protectهو تقييد تحرير، ليس تشفيرًا — اربطه بـOoxmlSaveOptions.Passwordإذا كان يجب على الملف المحفوظ نفسه طلب كلمة مرور للفتح.
المشكلات الشائعة
| المشكلة | السبب | الإصلاح |
|---|---|---|
Document(fileName) يرمي استثناءً لملف يفتح بشكل صحيح في Word | تنسيق الملف ليس من التنسيقات التي يدعمها هذا الإصدار للتحميل | استدعِ FileFormatUtil.DetectFileFormat أولاً وتحقق من LoadFormat المُرجع قبل التحميل |
| المحتوى المضاف يلتقط الخطوط أو الأنماط غير الصحيحة | ImportFormatMode عدم تطابق بين مجموعات الأنماط المصدر والوجهة | قم بتمرير KeepSourceFormatting أو UseDestinationStyles صراحةً بدلاً من الاعتماد على القيمة الافتراضية |
يتوقف تجول DocumentVisitor مبكرًا أو يتخطى المحتوى | تجاوز Visit*Start / Visit*End يُعيد SkipThisNode أو Stop عن غير قصد | أرجع VisitorAction.Continue من كل عملية تجاوز ما لم تكن تقصد تحديدًا التخطي أو الإيقاف |
Unprotect() لا يُحدث أي تأثير | لم يتم حماية المستند بكلمة مرور، أو تم توفير كلمة مرور خاطئة | استدعِ Unprotect() بدون أي معطيات إذا تم استدعاء Protect بدون كلمة مرور، وإلا مرّر كلمة المرور المطابقة |
FAQ
ما الفرق بين Document.Clone() و ImportNode؟
Clone() ينسخ مستندًا كاملاً إلى نسخة Document جديدة. ImportNode(srcNode, isImportChildren) يجلب عقدة واحدة (وبشكل اختياري أبناءها) من شجرة مستند إلى آخر، وهو ما تستخدمه عند دمج محتوى محدد بدلًا من مستندات كاملة.
ما صيغ الملفات التي يمكن لـ Document(fileName) تحميلها؟
Document(fileName) يحمل DOCX, DOCM, DOTX, DOTM, Flat OPC (بالإضافة إلى المتغيرات الممكنة للماكرو والقوالب)، Markdown، والنص العادي. تم استبعاد صيغ المعالجة النصية والويب القديمة من محملات هذا الإصدار.
كيف يمكنني معرفة مكان تموضع DocumentBuilder حاليًا؟
اقرأ CurrentNode أو CurrentParagraph أو CurrentSection على نسخة المُنشئ.
هل يقوم Document.Protect بتشفير الملف المحفوظ؟
لا — إنها قيد تحرير يفرضه Word عند فتح الملف. لطلب كلمة مرور لفتح الملف فقط، اضبط OoxmlSaveOptions.Password عند الحفظ.
كيف يمكنني قراءة الفقرات فقط في جسم المستند؟
استخدم مجموعة Body.Paragraphs، أو Body.GetChildNodes(nodeType, isDeep) لأنواع العقد الأخرى.
API Reference ملخص
| فئة/طريقة | وصف |
|---|---|
Document | جذر نموذج كائن المستند؛ تقوم المُنشئات بالتحميل من ملف أو تدفق، أو إنشاء مستند فارغ. |
Document.Save | يكتب المستند إلى ملف أو تدفق أو استجابة HTTP بتنسيق مختار. |
Document.Clone() | ينتج نسخة عميقة من المستند بأكمله. |
Document.Protect(type, password) / Unprotect() | يطبق أو يزيل قيد التحرير. |
Document.AppendDocument(srcDoc, importFormatMode) | يضيف أقسام مستند آخر إلى هذا المستند. |
DocumentBuilder | أداة API قائمة على المؤشر لكتابة النص وإدراج المحتوى في مستند. |
DocumentBuilder.InsertDocument(srcDoc, importFormatMode) | يدرج محتوى مستند المصدر عند المؤشر. |
Section / SectionCollection | قسم واحد من مستند، ومجموعة جميع الأقسام. |
Body | حاوية للنص الرئيسي (الفقرات والجداول) لقسم. |
Range | منطقة متصلة من شجرة المستند؛ تدعم Text و Replace. |
DocumentVisitor | فئة أساسية مجردة للتنقل عبر كل عقدة في شجرة المستند. |
ProtectionType | تعداد لقيود التحرير على مستوى المستند. |
FileFormatUtil.DetectFileFormat | يتعرف على تنسيق ملف أو تدفق قبل تحميله. |
