حفظ وتصدير المستندات
حفظ وتصدير المستندات
Document.Save يكتب مستندًا إلى ملف أو تدفق بصيغة هدف. يتم استنتاج الصيغة إما من امتداد الملف، أو تُعطى صراحة كقيمة SaveFormat، أو تُتحكم بها فئة فرعية من SaveOptions — OoxmlSaveOptions، MarkdownSaveOptions، أو TxtSaveOptions — للتحكم الخاص بالصيغ. يغطي هذا الدليل التحميلات Save، تعداد SaveFormat، خيارات حفظ OOXML، تصدير Markdown والنص العادي، واكتشاف الصيغة قبل التحويل.
الحفظ باستخدام Document.Save
أبسط استدعاء، Document.Save(fileName)، يستنتج صيغة الهدف من امتداد الملف. Save(fileName, saveFormat) يجعل الصيغة صريحة بغض النظر عن الامتداد، وSave(fileName, saveOptions) (أو التحميلات المطابقة لـ Stream) تقبل فئة فرعية من SaveOptions لإعدادات خاصة بالصيغ. SaveOptions.CreateSaveOptions(saveFormat) هي مصنع ثابت يُعيد الفئة الفرعية المناسبة للخيارات لِـ SaveFormat المحدد مع القيم الافتراضية مُعينة مسبقًا.
اختيار صيغة باستخدام SaveFormat
تعداد SaveFormat يسرد كل معرف صيغة حفظ تتعرف عليه المكتبة. Document.Save يكتب بالكامل إلى ومن صيغ المستندات الأساسية لهذه النسخة — DOCX، DOCM، DOTX، DOTM، وFlat OPC (بالإضافة إلى المتغيرات الممكّنة للماكرو والقوالب) — وكذلك Markdown والنص العادي. FileFormatUtil.SaveFormatToExtension(saveFormat) وExtensionToSaveFormat(extension) يحولان بين التعداد وسلسلة امتداد الملف.
بعض قيم SaveFormat موجودة في التعداد لإكمال API لكنها تتطابق مع صيغ لا تُنفّذ هذه النسخة المخفّضة المفتوحة المصدر قارئًا أو كاتبًا فعالًا لها — محاولة الحفظ إلى واحدة من تلك الصيغ ينتج مخرجات ليست مكافئة للمستند الأصلي. التزم بالصيغ المذكورة أعلاه لضمان استرجاع موثوق.
خيارات OOXML: DOCX، DOCM، DOTX، DOTM، و Flat OPC
OoxmlSaveOptions يضبط حفظ الملف بأي من تنسيقات Open XML. خاصية SaveFormat تختار أي نسخة محددة للكتابة؛ Password تعيين كلمة مرور مفتوحة للملف المحفوظ (مستقلة عن قيود التحرير الخاصة بـ Document.Protect); Compliance يحدد مستوى صرامة OOXML؛ و CompressionLevel / Zip64Mode يتحكمان في تغليف ZIP الأساسي. أنشئ واحدًا باستخدام new OoxmlSaveOptions(saveFormat) أو عبر SaveOptions.CreateSaveOptions(saveFormat).
التصدير إلى Markdown
MarkdownSaveOptions يتحكم في تصدير Markdown: ListExportMode و LinkExportMode يحددان كيفية عرض القوائم والروابط، ImagesFolder / ImagesFolderAlias يتحكمان في مكان كتابة الصور المستخرجة وكيفية الإشارة إليها، ExportImagesAsBase64 يضمّنها مضمّنًا بدلاً من ذلك، و TableContentAlignment يؤثر على ترميز الجدول المُولد. مرّر نسخة من MarkdownSaveOptions إلى Document.Save(fileName, saveOptions) مع اسم ملف .md، أو عيّن SaveFormat الخاص به صراحةً.
التصدير إلى نص عادي
TxtSaveOptions (من خلال TxtSaveOptionsBase الأساسي، المشترك مع MarkdownSaveOptions) يتحكم في تصدير النص العادي: Encoding يحدد ترميز الأحرف، ParagraphBreak يحدد سلسلة نهاية السطر، MaxCharactersPerLine يلفّ الأسطر الطويلة، SimplifyListLabels يطبع نقاط/أرقام القوائم إلى أحرف عادية، و PreserveTableLayout يحاول الحفاظ على محاذاة أعمدة الجداول باستخدام المسافات.
اكتشاف التنسيق قبل التحويل
قبل تحويل ملف لا تعرف تنسيقه مسبقًا، FileFormatUtil.DetectFileFormat(fileName) يُعيد FileFormatInfo يحتوي على LoadFormat المكتشف. ادمج هذا مع FileFormatUtil.LoadFormatToSaveFormat(loadFormat) لتقرر ما إذا كانت رحلة ذهابًا وإيابًا عبر تنسيقات هذه النسخة المدعومة ممكنة قبل محاولة Document.Save.
نصائح وأفضل الممارسات
- استخدم
Save(fileName, saveOptions)بدلاً من التحميل العاديSave(fileName, saveFormat)كلما احتجت إلى التحكم في سلوك محدد للنسق مثل عرض قوائم Markdown أو ضغط OOXML. - عيّن
OoxmlSaveOptions.Passwordلملف محمي بكلمة مرور مفتوحة؛ هذا مختلف عنDocument.Protect، الذي يقيد التحرير لكنه لا يُشفّر الملف. - اختر
MarkdownSaveOptions.ExportImagesAsBase64لملف Markdown واحد مستقل، أوImagesFolderعندما تريد مجلدًا يحتوي على ملفات الصور المستخرجة جنبًا إلى جنب مع الـ Markdown. - استدعِ
SaveOptions.CreateSaveOptions(saveFormat)بدلاً من اختيار فئة الخيارات المحددة يدويًا عندما يتم تحديد تنسيق الهدف في وقت التشغيل. - تحقق من تنسيق الهدف باستخدام
FileFormatUtilقبل التحويل بدلاً من الاعتماد على امتداد الملف فقط، والذي قد يكون خاطئًا أو مضللًا.
مشكلات شائعة
| المشكلة | السبب | الإصلاح |
|---|---|---|
Save(fileName) يختار الصيغة الخاطئة | امتداد الملف لا يتطابق مع الصيغة المقصودة | استخدم Save(fileName, saveFormat) أو Save(fileName, saveOptions) لجعل الصيغة صريحة |
| ملف OOXML المحفوظ لا يفتح باستخدام كلمة مرور | OoxmlSaveOptions.Password لم يُضبط قبل الحفظ | أنشئ OoxmlSaveOptions، اضبط Password، ومرره إلى Save |
| تصدير Markdown يوزّع ملفات الصور بشكل غير متوقع | السلوك الافتراضي لـ MarkdownSaveOptions يستخرج الصور إلى ملفات | اضبط ExportImagesAsBase64 = true للحصول على ملف واحد مكتمل ذاتيًا، أو اضبط ImagesFolder للتحكم في مكان وضع الصور |
| تصدير النص العادي يفقد محاذاة أعمدة الجدول | يُترك TxtSaveOptions.PreserveTableLayout على قيمته الافتراضية | قم بتعيين PreserveTableLayout = true قبل الحفظ |
FAQ
كيف أحفظ مستندًا بتنسيق محدد بغض النظر عن امتداد ملفه؟
استدعِ Save(fileName, saveFormat) بقيمة SaveFormat صريحة، أو Save(fileName, saveOptions) مع فئة فرعية SaveOptions مطابقة.
ما هي التنسيقات التي يقرأها ويكتبها هذا الإصدار في كلا الاتجاهين؟
DOCX، DOCM، DOTX، DOTM، Flat OPC (بالإضافة إلى إصداراته المدعومة للماكرو والقوالب)، Markdown، والنص العادي.
كيف أحمي ملفًا محفوظًا بكلمة مرور؟
عيّن Password على نسخة OoxmlSaveOptions ومرّرها إلى Document.Save(fileName, saveOptions).
كيف أتحكم في نهايات الأسطر في ملف نصي مُصدَّر؟
عيّن ParagraphBreak على نسخة TxtSaveOptions قبل الحفظ.
كيف يمكنني التحقق من صيغة الملف قبل تحويله؟
استدعِ FileFormatUtil.DetectFileFormat(fileName) واقرأ FileFormatInfo.LoadFormat المُرجع.
API Reference ملخص
| فئة/طريقة | وصف |
|---|---|
Document.Save | يكتب المستند إلى ملف أو تدفق أو هدف إخراج بصيغة مختارة. |
SaveFormat | تعداد يحدد الصيغة المستهدفة لعملية الحفظ. |
SaveOptions | فئة أساسية مجردة لتكوين الحفظ الخاص بالصيغة؛ CreateSaveOptions(saveFormat) تُرجع الفئة الفرعية المطابقة. |
OoxmlSaveOptions | خيارات لـ DOCX، DOCM، DOTX، DOTM، وFlat OPC — كلمة المرور، التوافق، الضغط. |
MarkdownSaveOptions | خيارات تصدير Markdown — عرض القوائم/الروابط، معالجة الصور. |
TxtSaveOptions / TxtSaveOptionsBase | خيارات تصدير النص العادي — الترميز، فواصل الأسطر، تنسيق الجداول. |
FileFormatUtil.DetectFileFormat | يكشف عن تنسيق الملف قبل تحميله أو تحويله. |
FileFormatUtil.SaveFormatToExtension / ExtensionToSaveFormat | تحويل بين قيمة SaveFormat وامتداد الملف. |
