تحميل المستندات باستخدام LoadOptions
تحميل المستندات باستخدام LoadOptions
يوضح هذا الدليل كيفية التحكم في تحميل المستندات بما يتجاوز مسار الملف أو الدفق البسيط، باستخدام الفئة LoadOptions. يحتوي Document على تحميلات مفرطة للمُنشئ تقبل كائن LoadOptions — Document(fileName, loadOptions) وDocument(stream, loadOptions) — بحيث تُطبق أي من الإعدادات الموضحة هنا عند وقت التحميل، قبل إرجاع كائن المستند إلى الكود الخاص بك.
الفئة LoadOptions
LoadOptions يحمل الإعدادات Aspose.Words التي يحتاجها FOSS أثناء تحميل مستند إلى كائن Document. تشمل مُنشئاته LoadOptions() بدون معاملات، وLoadOptions(password) لفتح ملف محمي بكلمة مرور مباشرة، وLoadOptions(loadFormat, password, baseUri) لتحديد الصيغة صراحة. إلى جانب Password وBaseUri (المستخدمة لحل المراجع النسبية مثل الموارد المرتبطة)، يُظهر LoadOptions Encoding للصيغات القائمة على النص، وTempFolder لمعالجة المستندات الكبيرة، وMswVersion لتحديد أي إصدار من Word تُطبق قواعد صياغته، وUpdateDirtyFields وIgnoreOleData وUseSystemLcid للتحكم الدقيق في سلوك التحميل. يتيح لك LoadOptions.FontSettings توفير FontSettings عند وقت التحميل بدلاً من تكوين الخطوط فقط بعد تحميل المستند.
خيارات التحميل الخاصة بالتنسيق
بعض الصيغ لها الفئة الفرعية الخاصة بها LoadOptions التي تكشف عن إعدادات خاصة بذلك الصيغة. يضيف TxtLoadOptions (للنص العادي) AutoNumberingDetection وDetectNumberingWithWhitespaces وDetectHyperlinks وDocumentDirection، بالإضافة إلى LeadingSpacesOptions/TrailingSpacesOptions منفصلين من النوع TxtLeadingSpacesOptions/TxtTrailingSpacesOptions للتحكم في كيفية معالجة الفراغات البادئة واللاحقة في كل سطر. يضيف MarkdownLoadOptions PreserveEmptyLines وImportUnderlineFormatting وSoftLineBreakCharacter للتحكم في كيفية تحويل اتفاقيات فواصل الأسطر في Markdown إلى فقرات وتشغيلات المستند. كلا الفئتين الفرعيتين ترثان كل خاصية عامة LoadOptions، لذلك كلمة المرور أو استدعاء التحميل للموارد المحدد على كائن TxtLoadOptions أو MarkdownLoadOptions يعمل بنفس الطريقة كما في الفئة الأساسية.
استدعاءات تحميل الموارد
LoadOptions.ResourceLoadingCallback تقبل تنفيذًا لـ IResourceLoadingCallback، والذي يتم إخطاره عندما يقوم المُحمِّل بحل الموارد الخارجية المشار إليها في المستند الجاري تحميله. يتلقى رد النداء ResourceLoadingArgs يصف ResourceType للموارد التي يتم تحميلها، ويعيد ResourceLoadingAction لإخبار المُحمِّل ما إذا كان يجب تحميل المورد بشكل عادي، أو تخطيه، أو استبداله ببيانات مخصصة. هذه هي نقطة الامتداد للتحكم أو اعتراض حل الموارد أثناء التحميل، بغض النظر عن التنسيق المقروء.
إعدادات اللغة والاتجاه والاستعادة
LoadOptions.LanguagePreferences هو كائن LanguagePreferences يحدد DefaultEditingLanguage (قيمة تعداد EditingLanguage) اللغة Aspose.Words التي يفترضها FOSS عندما لا يحدد المستند لغة صراحةً؛ AddEditingLanguage(language) وAddEditingLanguages(languages) تسجلان لغات إضافية قد يستخدمها المستند. DocumentDirection (المعروض أيضًا مباشرةً على TxtLoadOptions) هو تعداد يحتوي على قيم LeftToRight وRightToLeft وAuto للتحكم في اتجاه تدفق النص عند التحميل. LoadOptions.RecoveryMode يأخذ قيمة DocumentRecoveryMode، والتي تتحكم في كيفية استجابة المُحمِّل عندما يصادف مستندًا غير صالح أو تالف جزئيًا.
نداءات التقدم والتحذير
بعيدًا عن تحميل الموارد، LoadOptions.WarningCallback وLoadOptions.ProgressCallback تقبلان تنفيذات نداء استرجاع يتم إخطارهما بالمشكلات غير القاتلة التي تم مواجهتها أثناء التحميل وبالتقدم في التحميل، على التوالي — وهذا مفيد لعرض المشكلات القابلة للاسترداد على الكود المستدعي أو للإبلاغ عن التقدم في المستندات الكبيرة دون الحاجة إلى الاستطلاع.
نصائح وأفضل الممارسات
- مرّر
LoadOptions(password)(أو اضبطLoadOptions.Password) بدلاً من التقاط استثناء التحميل وإعادة المحاولة — Aspose.Words يحتاج FOSS إلى كلمة المرور قبل أن يتمكن من تحليل المستند على الإطلاق. - قم بتعيين
LanguagePreferences.DefaultEditingLanguageعند تحميل المستندات التي تكون بيانات تعريف اللغة مفقودة أو غير موثوقة، حتى يتصرف المعالجة اللاحقة المعتمدة على اللغة بشكل متوقع. - يفضَّل استخدام فئة الخيارات الخاصة بالتنسيق (
TxtLoadOptions,MarkdownLoadOptions) على الفئة الأساسيةLoadOptionsعند تحميل تلك التنسيقات، لأن الفئة الفرعية المحددة تكشف عن إعدادات ذات صلة بالتنسيق لا توفرها الفئة الأساسية. - طبّق
IResourceLoadingCallbackعندما تحتاج إلى إعادة توجيه أو تخزين مؤقت أو حظر حل الموارد الخارجية أثناء التحميل بدلاً من بعد أن يصبح المستند موجودًا في الذاكرة. - قم بتعيين
LoadOptions.RecoveryModeعن قصد للأنابيب التي تعالج مستندات من مصادر غير موثوقة أو من أطراف ثالثة، بدلاً من الاعتماد على سلوك الاستعادة الافتراضي.
المشكلات الشائعة
| المشكلة | السبب | الإصلاح |
|---|---|---|
| تحميل مستند محمي بكلمة مرور يطرح استثناءً | لم يتم توفير كلمة مرور، أو تم توفيرها بعد أن بدأ التحميل بالفعل | مرّر LoadOptions(password) (أو اضبط Password على كائن LoadOptions) إلى نسخة مُنشيء Document التي تقبل LoadOptions |
| المسافات البيضاء في بداية/نهاية ملف نصي محمّل لا تُعامل كما هو متوقع | السلوك الافتراضي لـ TxtLeadingSpacesOptions/TxtTrailingSpacesOptions لا يتطابق مع قواعد المسافات البيضاء في ملف المصدر | تعيين TxtLoadOptions.LeadingSpacesOptions / TrailingSpacesOptions صراحةً |
| لا تتطابق فواصل أسطر Markdown مع بنية الفقرة المتوقعة | MarkdownLoadOptions.PreserveEmptyLines أو SoftLineBreakCharacter لا تتطابق مع قواعد Markdown المصدر | قم بتعديل خاصية MarkdownLoadOptions ذات الصلة قبل التحميل |
| تحميل الموارد الخارجية غير ملحوظ أو غير قابل للتحكم | لم يتم تسجيل أي IResourceLoadingCallback على LoadOptions.ResourceLoadingCallback | نفّذ IResourceLoadingCallback وعيّنها قبل التحميل |
FAQ
كيف يمكنني تحميل مستند محمي بكلمة مرور؟
أنشئ LoadOptions باستخدام كلمة المرور — new LoadOptions(password) — أو عيّن LoadOptions.Password، ثم مرّرها إلى new Document(fileName, loadOptions) أو new Document(stream, loadOptions).
هل أحتاج إلى فئة فرعية خاصة بالتنسيق LoadOptions، أم أن الفئة الأساسية كافية؟
الفئة الأساسية LoadOptions تغطي الإعدادات المشتركة لكل تنسيق (كلمة المرور، الترميز، الاستدعاءات). استخدم فئة فرعية خاصة بالتنسيق مثل TxtLoadOptions أو MarkdownLoadOptions عندما تحتاج إلى إعدادات مخصصة لذلك التنسيق، مثل معالجة المسافات البيضاء لملفات النص أو قواعد فواصل الأسطر للـMarkdown.
كيف يمكنني اعتراض أو إعادة توجيه الموارد التي يشير إليها المستند أثناء التحميل؟
نفّذ IResourceLoadingCallback وعيّنها إلى LoadOptions.ResourceLoadingCallback قبل التحميل. تستقبل دالة الاستدعاء ResourceLoadingArgs لكل مورد وتُعيد ResourceLoadingAction يحدد كيفية متابعة المُحمِّل.
كيف أتحكم في اللغة التي يفترضها Aspose.Words FOSS للمستند المحمَّل؟
عيّن LoadOptions.LanguagePreferences.DefaultEditingLanguage إلى قيمة EditingLanguage قبل التحميل؛ استخدم AddEditingLanguage/AddEditingLanguages لتسجيل لغات إضافية قد يحتويها المستند.
ماذا يحدث إذا صادف المُحمِّل مستندًا غير مُشكل بشكل صحيح؟
السلوك يُتحكم فيه بواسطة LoadOptions.RecoveryMode، وهي قيمة DocumentRecoveryMode تحدد كيفية استجابة المُحمِّل للمشكلات الهيكلية في مستند المصدر.
API Reference ملخص
| فئة/طريقة | وصف |
|---|---|
LoadOptions | كائن الخيارات الأساسي الذي يتحكم في طريقة تحميل المستند |
Document(fileName, loadOptions) / Document(stream, loadOptions) | تجاوزات المُنشئ التي تُطبق LoadOptions أثناء التحميل |
TxtLoadOptions | خيارات التحميل الخاصة بالمستندات النصية العادية |
MarkdownLoadOptions | خيارات التحميل الخاصة بمستندات Markdown |
IResourceLoadingCallback | واجهة رد النداء لاعتراض حل الموارد الخارجية أثناء التحميل |
ResourceLoadingArgs / ResourceLoadingAction | بيانات الحدث لكل مورد والإجراء الذي يُرجع إلى أداة التحميل |
LanguagePreferences | يكوّن اللغات التحريرية الافتراضية والإضافية المفترضة عند التحميل |
DocumentDirection | Enum يتحكم في اتجاه تدفق النص (LeftToRight, RightToLeft, Auto) |
DocumentRecoveryMode | يتحكم في سلوك أداة التحميل عندما يكون المستند معطوبًا |
