بارگذاری اسناد با 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 آن (یک مقدار enum EditingLanguage) زبان Aspose.Words که FOSS هنگام عدم تعیین صریح زبان در سند فرض می‌کند، تنظیم می‌کند؛ AddEditingLanguage(language) و AddEditingLanguages(languages) زبان‌های اضافی که سند ممکن است استفاده کند را ثبت می‌کنند. DocumentDirection (که همچنین به‌صورت مستقیم بر روی TxtLoadOptions در دسترس است) یک enum با مقادیر 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 تنظیم کنید) به overload سازنده Document که LoadOptions را می‌پذیرد، پاس بدهید |
| فاصله‌های خالی ابتدای/پایانی در یک فایل متنی بارگذاری‌شده به‌طور مورد انتظار پردازش نمی‌شوند | رفتار پیش‌فرض TxtLeadingSpacesOptions/TxtTrailingSpacesOptions با قراردادهای فاصله‌ای فایل منبع مطابقت ندارد | به‌صورت صریح TxtLoadOptions.LeadingSpacesOptions / TrailingSpacesOptions را تنظیم کنید |
| خطوط شکستهٔ Markdown به ساختار پاراگراف مورد انتظار مطابقت ندارند | MarkdownLoadOptions.PreserveEmptyLines یا SoftLineBreakCharacter با قواعد Markdown منبع مطابقت ندارد | ویژگی MarkdownLoadOptions مربوطه را پیش از بارگذاری تنظیم کنید |
| بارگذاری منابع خارجی قابل مشاهده یا کنترل نیست | هیچ IResourceLoadingCallbackی در LoadOptions.ResourceLoadingCallback ثبت نشده است | IResourceLoadingCallback را پیاده‌سازی کنید و پیش از بارگذاری آن را اختصاص دهید |
FAQ
چگونه می‌توانم یک سند محافظت‌شده با رمز عبور را بارگذاری کنم؟
با رمز عبور — new LoadOptions(password) — LoadOptions را بسازید یا LoadOptions.Password را تنظیم کنید، سپس آن را به new Document(fileName, loadOptions) یا new Document(stream, loadOptions) پاس دهید.
آیا به یک زیرکلاس مخصوص فرمت LoadOptions نیاز دارم، یا کلاس پایه کافی است؟
کلاس پایهٔ LoadOptions تنظیمات مشترک برای همهٔ فرمت‌ها (رمز عبور، رمزگذاری، callbacks) را پوشش می‌دهد. هنگام نیاز به تنظیمات خاص یک فرمت، مانند مدیریت فاصله‌های سفید برای فایل‌های متنی یا قواعد شکست خط برای Markdown، از زیرکلاس مخصوص فرمت مانند TxtLoadOptions یا MarkdownLoadOptions استفاده کنید.
چگونه می‌توانم منابعی که یک سند هنگام بارگذاری به آن‌ها ارجاع می‌دهد را بازدارم یا بازنویسی کنم؟
IResourceLoadingCallback را پیاده‌سازی کنید و قبل از بارگذاری به LoadOptions.ResourceLoadingCallback اختصاص دهید. callback برای هر منبع یک 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 | گزینه‌های بارگذاری مخصوص اسناد مارک‌داون |
IResourceLoadingCallback | رابط callback برای قطع‌واسط حل‌و‌فصل منابع خارجی هنگام بارگذاری |
ResourceLoadingArgs / ResourceLoadingAction | داده‌های رویداد برای هر منبع و عملی که به بارگذار بازگردانده می‌شود |
LanguagePreferences | پیکربندی زبان‌های ویرایشی پیش‌فرض و اضافی که هنگام بارگذاری فرض می‌شوند |
DocumentDirection | Enum کنترل‌کننده جهت جریان متن (LeftToRight, RightToLeft, Auto) |
DocumentRecoveryMode | رفتار لودر را زمانی که سند خراب باشد کنترل می‌کند |
