چگونه اسناد Word را در .NET بارگذاری کنیم
نحوه بارگذاری اسناد Word در .NET
Aspose.Words FOSS برای .NET یک سند را به محض ساختن یک Document شیء — هر مسیر بارگذاری در کتابخانه از طریق Documentبارگذاری‌های سازندهٔ آن و LoadOptions کلاس. این راهنما نشان می‌دهد چگونه یک سند را از فایل یا جریان بارگذاری کنید، رمز عبور یا تنظیمات مخصوص فرمت را فراهم کنید، و کنترل کنید چه اتفاقی می‌افتد وقتی بارگذاری با منبع خارجی یا سندی که ممکن است خراب باشد، مواجه می‌شود. Aspose.Words FOSS برای .NET از منبع ساخته می‌شود و به‌صورت مستقیم در یک پروژه ارجاع داده می‌شود نه اینکه از یک فید بسته نصب شود — ببینید راهنمای نصب برای مراحل ساخت قبل از انجام کارهای زیر.
راهنمای گام‌به‌گام
مرحله 1: بارگذاری سند از فایل یا جریان
Document دارای پنج سازنده است. Document() یک سند جدید و خالی ایجاد می‌کند به‌جای اینکه یک سند را بارگذاری کند. Document(fileName) مستقیماً از مسیری روی دیسک بارگذاری می‌کند، و Document(stream) از هر Stream قابل خواندن بارگذاری می‌کند — که زمانی مفید است که منبع فایل نیست، مانند محتوایی که قبلاً در حافظه است یا از طریق اتصال شبکه دریافت شده است. هر دو یک overload همراه دارند که آرگومان دوم، Document(fileName, loadOptions) و Document(stream, loadOptions)، را می‌پذیرند، که نقطهٔ ورود برای تمام کارهای دیگر در این راهنما است.
مرحله 2: بارگذاری سند با رمز عبور
یک LoadOptions را با گذرواژه پیش از فراخوانی Document(fileName, loadOptions) (یا نسخهٔ overload جریان) ایجاد کنید. new LoadOptions(password) مستقیماً LoadOptions.Password را تنظیم می‌کند؛ به‌جای آن، Password را روی یک نمونهٔ LoadOptions() بدون پارامتر قبل از انتقال تنظیم کنید. گذرواژه را از ابتدا فراهم کنید به جای بارگذاری ابتدا و واکنش به خطا — Aspose.Words FOSS برای .NET برای تجزیهٔ یک فایل محافظت‌شده به گذرواژه نیاز دارد، بنابراین هیچ وضعیت بارگذاری جزئی برای بازیابی وجود ندارد.
مرحله ۳: اعمال گزینه‌های مخصوص فرمت برای منابع متنی و Markdown
منابع متن ساده و Markdown تنظیماتی را می‌پذیرند که پایهٔ LoadOptions آن‌ها را نمایش نمی‌دهد. TxtLoadOptions AutoNumberingDetection و DetectNumberingWithWhitespaces را برای شناسایی فهرست‌های شماره‌دار در متن ساده اضافه می‌کند، DetectHyperlinks برای تبدیل URLهای ساده به ابرپیوندها، DocumentDirection (LeftToRight، RightToLeft یا Auto) برای جهت جریان متن، و LeadingSpacesOptions/TrailingSpacesOptions جداگانه (از نوع TxtLeadingSpacesOptions/TxtTrailingSpacesOptions) برای مدیریت فاصله‌های سفید در ابتدای و انتهای هر خط. MarkdownLoadOptions PreserveEmptyLines، ImportUnderlineFormatting و SoftLineBreakCharacter را برای کنترل نحوهٔ نگاشت قواعد شکست خط Markdown به پاراگراف‌ها و بخش‌ها اضافه می‌کند. هر دو زیرکلاس از LoadOptions ارث می‌برند، بنابراین یک گذرواژه یا callback بارگذاری منبع که بر روی هرکدام تنظیم شود، همانند پایهٔ کلاس رفتار می‌کند — نمونهٔ مخصوص فرمت را به Document(fileName, loadOptions) همان‌طور که یک LoadOptions ساده می‌فرستید، پاس کنید.
مرحله ۴: تغییر مسیر یا رهگیری منابع خارجی هنگام بارگذاری
LoadOptions.ResourceLoadingCallback را به پیاده‌سازی IResourceLoadingCallback تنظیم کنید وقتی نیاز دارید نحوهٔ حل یک منبع خارجی که توسط سند ارجاع شده است را در حین بارگذاری کنترل کنید. متد ResourceLoading(args) آن یک ResourceLoadingArgs دریافت می‌کند که ResourceType منبع را توصیف می‌کند (Image، Font، CssStyleSheet یا Document) به‌همراه Uri و OriginalUri، و یک ResourceLoadingAction برمی‌گرداند — Default برای بارگذاری معمولی منبع، Skip برای حذف آن، یا UserProvided برای جایگزینی داده‌های تأمین‌شده از طریق ResourceLoadingArgs.SetData(data).
مرحله ۵: تنظیم پیش‌فرض‌های زبان و رفتار بازیابی
وقتی فرادادهٔ زبان یک سند گمشده یا نامطمئن باشد، پیش از بارگذاری LoadOptions.LanguagePreferences.DefaultEditingLanguage را به مقدار EditingLanguage تنظیم کنید، و از AddEditingLanguage(language) یا AddEditingLanguages(languages) بر روی LanguagePreferences برای ثبت زبان‌های افزایشی که سند ممکن است شامل آن‌ها باشد، استفاده کنید. برای منابعی که ممکن است خراب باشند، LoadOptions.RecoveryMode را به مقدار DocumentRecoveryMode تنظیم کنید — None برای بارگذاری بدون هیچ تلاش بازیابی، یا TryRecover برای اینکه بارگذار برخی مشکلات ساختاری را دور بزند به‌جای اینکه بارگذاری را به‌طور کامل متوقف کند.
مشکلات رایج و راه‌حل‌ها
بارگذاری یک سند محافظت‌شده با رمز عبور هنوز پس از ارائهٔ رمز عبور یک استثنا پرتاب می‌کند. تأیید کنید که رمز عبور دقیقاً روی LoadOptions نمونه‌ای که به Document(fileName, loadOptions) (یا overload جریان) — از طریق new LoadOptions(password) یا با تنظیم Password afterward — و اینکه این همان شیئی است که واقعاً به سازنده پاس داده می‌شود. یک LoadOptions که ایجاد شد اما هرگز به Document تأثیری بر بارگذاری ندارد.
به‌نظر می‌رسد تنظیمات خاص متن یا Markdown اعمال نمی‌شوند. بررسی کنید که یک TxtLoadOptions or MarkdownLoadOptions نمونه — نه پایه LoadOptions — به Document سازنده. فقط زیرکلاس ویژگی‌های خاص قالب را در دسترس می‌گذارد؛ عبور از کلاس پایه کامپایل می‌شود اما به‌صورت خاموش آن‌ها را حذف می‌کند.
منابع خارجی بازدارده یا هدایت نمی‌شوند. ResourceLoadingCallback باید بر روی همان LoadOptions شیء ارسال شده به Document سازنده، و باید قبل از فراخوانی load اختصاص داده شود. اختصاص آن پس از این که بارگذاری قبلاً تکمیل شده باشد، هیچ تأثیری ندارد.
یک سند خراب همچنان پس از تنظیم، بارگذاری نمی‌شود RecoveryMode. DocumentRecoveryMode.TryRecover به بارگذار اجازه می‌دهد تا برخی مشکلات ساختاری در یک سند را دور بزند، اما خراب‌سازی شدیدتر همچنان می‌تواند مانع از بارگذاری موفقیت‌آمیز سند شود.
سندی که از یک Stream رفتار متفاوتی نسبت به همان فایلی که از مسیر بارگذاری می‌شود دارد. مطمئن شوید موقعیت جریان در ابتدای خود است قبل از اینکه آن را به Document(stream) or Document(stream, loadOptions) — یک جریان که در میانهٔ محتوای خود قطع شده است، فقط بایت‌های باقی‌مانده را بارگذاری می‌کند.
سوالات متداول
چگونه می‌توانم سندی را بدون هیچ گزینهٔ خاصی بارگذاری کنم؟
یک مسیر فایل یا یک Stream را مستقیماً به Document(fileName) یا Document(stream) پاس بدهید — LoadOptions فقط زمانی لازم است که نیاز به رمز عبور، تنظیمات خاص فرمت، یا یک callback باشد.
تفاوت بین LoadOptions، TxtLoadOptions و MarkdownLoadOptions چیست؟
TxtLoadOptions و MarkdownLoadOptions هر دو از LoadOptions ارث می‌برند و تنظیمات خاصی برای منابع متن‌ساده و Markdown به ترتیب اضافه می‌کنند. هر ویژگی عمومی LoadOptions — رمز عبور، رمزگذاری، callbacks — برای هر یک از زیرکلاس‌ها در دسترس باقی می‌ماند.
آیا می‌توانم یک سند را مستقیماً از یک آرایه بایت بارگذاری کنم؟
بایت‌ها را در یک MemoryStream بپیچید و آن استریم را به Document(stream) یا Document(stream, loadOptions) پاس دهید — سازنده‌ای وجود ندارد که آرایه بایت را به‌طور مستقیم بپذیرد.
چگونه می‌توانم کنترل کنم که وقتی لودر نتواند یک منبع خارجی را حل کند، چه اتفاقی می‌افتد؟
یک IResourceLoadingCallback پیاده‌سازی کنید و آن را به LoadOptions.ResourceLoadingCallback اختصاص دهید. ResourceLoadingAction.Skip را از ResourceLoading(args) برگردانید تا به‌جای اینکه بارگذاری شکست بخورد، منبع حذف شود.
آیا تنظیم RecoveryMode نحوه بارگذاری یک سند به‌درست‌ساختار را تغییر می‌دهد؟
نه. DocumentRecoveryMode فقط زمانی رفتار را تغییر می‌دهد که بارگذار واقعاً با مشکلات ساختاری مواجه شود — یک سند به‌خوبی‌ساختار شده به همان شکل بارگذاری می‌شود، صرف‌نظر از تنظیمات.
