كيفية تحميل مستندات Word في .NET
كيفية تحميل مستندات Word في .NET
Aspose.Words FOSS for .NET يقرأ مستندًا إلى الذاكرة بمجرد إنشاء Document كائن — كل مسار تحميل في المكتبة يمر عبر Documentتجاوزات المُنشئ الخاصة به وال LoadOptions الفئة. يوضح هذا الدليل كيفية تحميل مستند من ملف أو من تدفق، وتوفير كلمة مرور أو إعدادات خاصة بالتنسيق، والتحكم فيما يحدث عندما يواجه التحميل موردًا خارجيًا أو مستندًا قد يكون مشوّهًا. Aspose.Words FOSS for .NET يُبنى من المصدر ويُشار إليه مباشرةً في مشروع بدلاً من تثبيته من مصدر حزم — راجع الـ دليل التثبيت لخطوات البناء قبل الانتقال إلى المهام أدناه.
دليل خطوة بخطوة
الخطوة 1: تحميل مستند من ملف أو تدفق
Document يحتوي على خمسة مُنشئين. Document() ينشئ مستندًا جديدًا فارغًا بدلاً من تحميل واحد. Document(fileName) يحمل مباشرةً من مسار على القرص، وDocument(stream) يحمل من أي Stream قابل للقراءة — مفيد عندما لا يكون المصدر ملفًا، مثل محتوى موجود بالفعل في الذاكرة أو تم استلامه عبر اتصال شبكة. كلاهما له تحميل زائد مصاحب يقبل وسيلة ثانية، Document(fileName, loadOptions) وDocument(stream, loadOptions)، والتي تُعد نقطة الدخول لكل مهمة أخرى في هذا الدليل.
الخطوة 2: تحميل مستند محمي بكلمة مرور
قم بإنشاء LoadOptions مع كلمة المرور قبل استدعاء Document(fileName, loadOptions) (أو التحميل الزائد للمجرى). يقوم new LoadOptions(password) بتعيين LoadOptions.Password مباشرة؛ بدلاً من ذلك، عيّن Password على مثال LoadOptions() بدون معاملات قبل تمريره. زوّد كلمة المرور مسبقًا بدلاً من التحميل أولاً والرد على الفشل — يحتاج Aspose.Words FOSS لـ .NET كلمة المرور لتحليل ملف محمي على الإطلاق، لذا لا توجد حالة تحميل جزئية يمكن الاسترداد منها.
الخطوة 3: تطبيق خيارات خاصة بالتنسيق لمصادر النص وMarkdown
تقبل مصادر النص العادي وMarkdown إعدادات لا يُظهرها LoadOptions الأساسي. يضيف TxtLoadOptions AutoNumberingDetection وDetectNumberingWithWhitespaces للتعرف على القوائم المرقمة في النص العادي، وDetectHyperlinks لتحويل الروابط الصريحة إلى روابط تشعبية، وDocumentDirection (LeftToRight، RightToLeft أو Auto) لتحديد اتجاه تدفق النص، وLeadingSpacesOptions/TrailingSpacesOptions منفصلين (من النوع TxtLeadingSpacesOptions/TxtTrailingSpacesOptions) لمعالجة المسافات البيضاء في بداية ونهاية كل سطر. يضيف MarkdownLoadOptions PreserveEmptyLines وImportUnderlineFormatting وSoftLineBreakCharacter للتحكم في كيفية تحويل اتفاقيات فواصل الأسطر في Markdown إلى فقرات وتشغيلات. كلا الفئتين الفرعيتين يشتقان من LoadOptions، لذا كلمة مرور أو رد نداء تحميل المورد المحدد على أي منهما يتصرف بنفس الطريقة كما في الفئة الأساسية — مرّر المثيل الخاص بالتنسيق إلى Document(fileName, loadOptions) تمامًا كما تفعل مع LoadOptions عادي.
الخطوة 4: إعادة توجيه أو اعتراض الموارد الخارجية أثناء التحميل
عيّن LoadOptions.ResourceLoadingCallback إلى تنفيذ لـ IResourceLoadingCallback عندما تحتاج إلى التحكم في كيفية حل مورد خارجي يُشار إليه في المستند أثناء التحميل. تستقبل طريقة ResourceLoading(args) الخاصة به ResourceLoadingArgs تصف ResourceType المورد (Image، Font، CssStyleSheet أو Document) إلى جانب Uri وOriginalUri، وتُعيد ResourceLoadingAction — Default لتحميل المورد بشكل طبيعي، Skip لتجاهله، أو UserProvided لاستبدال البيانات المقدمة عبر ResourceLoadingArgs.SetData(data).
الخطوة 5: تعيين الإعدادات الافتراضية للغة وسلوك الاسترداد
عند عدم وجود بيانات تعريف اللغة في المستند أو كونها غير موثوقة، عيّن LoadOptions.LanguagePreferences.DefaultEditingLanguage إلى قيمة EditingLanguage قبل التحميل، واستخدم AddEditingLanguage(language) أو AddEditingLanguages(languages) على LanguagePreferences لتسجيل لغات إضافية قد يحتويها المستند. بالنسبة للمصادر التي قد تكون مشوهة، عيّن LoadOptions.RecoveryMode إلى قيمة DocumentRecoveryMode — None للتحميل دون أي محاولة استرداد، أو TryRecover لجعل المحمل يتجاوز بعض المشكلات الهيكلية بدلاً من فشل التحميل تمامًا.
المشكلات الشائعة والحلول
لا يزال تحميل مستند محمي بكلمة مرور يطرح استثناءً بعد توفير كلمة المرور. تأكد من أن كلمة المرور تم تعيينها على الـ LoadOptions المثيل الممرَّ إلى Document(fileName, loadOptions) (أو التحميل الزائد للتدفق) — عبر new LoadOptions(password) أو عن طريق الضبط Password بعد ذلك — وأن هذا هو الكائن الذي يتم تمريره فعليًا إلى المُنشئ. A LoadOptions الذي تم إنشاؤه ولكن لم يُسلم أبدًا إلى Document ليس له أي تأثير على التحميل.
يبدو أن إعدادات النص أو الخاصة بـ Markdown لا تُطبَّق. تحقق من أن TxtLoadOptions or MarkdownLoadOptions المثيل — ليس القاعدة LoadOptions — تم تمريره إلى Document المُنشئ. فقط الفئة الفرعية تُظهر الخصائص الخاصة بالتنسيق؛ تمرير الفئة الأساسية يُترجم لكنه يتجاهلها بصمت.
الموارد الخارجية لا يتم اعتراضها أو إعادة توجيهها. ResourceLoadingCallback يجب أن يتم تعيينه على نفس LoadOptions الكائن الممرَّر إلى Document المُنشئ، ويجب تعيينه قبل استدعاء التحميل. تعيينه بعد اكتمال التحميل لا يؤثر.
وثيقة غير صالحة ما زالت تفشل في التحميل بعد تعيين RecoveryMode. DocumentRecoveryMode.TryRecover يسمح للتحميل بالتغلب على بعض المشكلات الهيكلية في الوثيقة، لكن الفساد الأكثر شدة لا يزال يمكن أن يمنع الوثيقة من التحميل بنجاح.
وثيقة تم تحميلها من Stream تتصرف بشكل مختلف عن نفس الملف المحمَّل عبر المسار. تحقق من أن موضع الدفق في البداية قبل تمريره إلى Document(stream) or Document(stream, loadOptions) — تدفق تُرك في منتصف محتواه يتم تحميله فقط البايتات المتبقية.
الأسئلة المتكررة
كيف يمكنني تحميل مستند دون أي خيارات خاصة؟
مرّر مسار ملف أو Stream مباشرةً إلى Document(fileName) أو Document(stream) — LoadOptions لا يُطلب إلا عندما تكون هناك كلمة مرور أو إعدادات خاصة بالتنسيق أو رد نداء مطلوب.
ما الفرق بين LoadOptions وTxtLoadOptions وMarkdownLoadOptions?
TxtLoadOptions وMarkdownLoadOptions كلاهما مشتقان من LoadOptions ويضيفان إعدادات خاصة بمصادر النص العادي وMarkdown على التوالي. كل خاصية عامة لـ LoadOptions — كلمة مرور، ترميز، ردود نداء — تظل متاحة في أي من الفئتين الفرعيتين.
هل يمكنني تحميل مستند مباشرةً من مصفوفة بايت?
غلف البايتات في MemoryStream ومرّر ذلك التدفق إلى Document(stream) أو Document(stream, loadOptions) — لا يوجد مُنشئ يقبل مصفوفة بايت مباشرةً.
كيف يمكنني التحكم في ما يحدث عندما لا يتمكن المحمّل من حل مورد خارجي?
نفّذ IResourceLoadingCallback وعيّنه إلى LoadOptions.ResourceLoadingCallback. أرجع ResourceLoadingAction.Skip من ResourceLoading(args) لتجاهل المورد بدلاً من السماح بحدوث فشل في التحميل.
هل يؤدي ضبط RecoveryMode إلى تغيير طريقة تحميل مستند مُشكَّل بشكل صحيح?
لا. DocumentRecoveryMode يغيّر السلوك فقط عندما يواجه المحمل مشاكل هيكلية — يتم تحميل المستند المُشكل جيدًا بنفس الطريقة بغض النظر عن الإعداد.
