چگونه با اسناد در .NET کار کنیم
این راهنما نشان می‌دهد چگونه با مدل شیء Document در Aspose.Words FOSS برای .NET کار کنید: ایجاد یک سند خالی، بارگذاری ایمن یک سند موجود، پیمایش ساختار بخش/بدنه آن، ترکیب اسناد، و اعمال محدودیت ویرایش. Aspose.Words FOSS برای .NET از طریق NuGet یا با ساخت از منبع در دسترس است.
راهنمای گام به گام
گام ۱: دریافت کتابخانه
مخزن را کلون کنید و بسازید Aspose.Words.sln در پیکربندی Release، سپس یک ارجاع پروژه به Aspose.Words.csproj از پروژه .NET خودتان. دستورات کامل کلون و ساخت در راهنمای نصب. پس از ارجاع، اضافه کنید using Aspose.Words; در بالای هر فایلی که با اسناد کار می‌کند.
گام ۲: ایجاد یا بارگذاری یک سند
برای یک سند خالی، new Document() را فراخوانی کنید، یا مسیر فایل یا Stream را به سازنده Document(fileName) / Document(stream) پاس دهید تا یک سند موجود را باز کنید. یک overload که یک آرگومان LoadOptions می‌گیرد، به شما امکان می‌دهد رمز عبور برای یک فایل رمزگذاری‌شده فراهم کنید. پیش از بارگذاری فایلی که قالب آن را هنوز اعتماد ندارید، FileFormatUtil.DetectFileFormat(fileName) را صدا بزنید — این متد یک FileFormatInfo برمی‌گرداند که LoadFormat شناسایی‌شده و اینکه فایل IsEncrypted، HasDigitalSignature یا HasMacros است را گزارش می‌کند، تا بتوانید ورودی غیرمنتظره را قبل از اینکه Document سعی در تجزیه آن داشته باشد، رد کنید.
مرحله 3: نوشتن محتوا با DocumentBuilder
DocumentBuilder یک Document را با یک مکان‌نما می‌پیچد که شما هنگام وارد کردن محتوا آن را در درخت حرکت می‌دهید. Write(text) و Writeln(text) متن را در مکان‌نما وارد می‌کنند، و InsertParagraph() یک پاراگراف جدید را آغاز می‌کند. قالب‌بندی تنظیم‌شده بر روی ویژگی‌های Font، ParagraphFormat، ListFormat و PageSetup سازنده بر هر چیزی که بعداً می‌نویسید اعمال می‌شود. مکان‌نما را با MoveToDocumentStart()، MoveToDocumentEnd()، MoveToSection(sectionIndex)، MoveToBookmark(bookmarkName) یا MoveToParagraph(paragraphIndex, characterIndex) جابجا کنید، و CurrentNode / CurrentParagraph / CurrentSection را بخوانید تا تأیید کنید سازنده در کجا قرار دارد.
مرحله 4: بررسی ساختار بخش و بدنه
یک Document یک SectionCollection را از طریق Document.Sections (به‌علاوه FirstSection / LastSection) نمایش می‌دهد. هر Section دقیقاً یک Body دارد که محتوای اصلی آن از طریق Body.Paragraphs (یک ParagraphCollection) و Body.Tables قابل دسترسی است. برای خواندن یا جستجوی متن بدون پیمایش دستی گره‌ها، از Range موجود بر روی Document، Section، Paragraph و گره‌های دیگر استفاده کنید — Range.Text متن ساده آن را برمی‌گرداند، و Range.Replace(pattern, replacement) جستجو و جایگزینی‌ای را که فقط به آن بازه محدود است انجام می‌دهد.
مرحله 5: ترکیب دو سند
برای کپی کردن یک سند کامل، Document.Clone() را فراخوانی کنید. برای آوردن محتوای خاص از یک نمونه Document به نمونه دیگر، ImportNode(srcNode, isImportChildren) را بر روی سند مقصد فراخوانی کنید، یا Document.AppendDocument(srcDoc, importFormatMode) را برای افزودن هر بخش از سند منبع به انتهای سند جاری فراخوانی کنید. DocumentBuilder.InsertDocument(srcDoc, importFormatMode) همین کار را انجام می‌دهد اما به‌جای انتها در مکان‌نمای سازنده درج می‌کند. در هر سه حالت، مقدار ImportFormatMode — KeepSourceFormatting، UseDestinationStyles یا KeepDifferentStyles — را با دقت انتخاب کنید، زیرا تعیین می‌کند کدام استایل‌های سند در مواجهه دو سند برتری داشته باشند.
مرحله 6: اعمال محدودیت ویرایشی
Document.Protect(type, password) را با مقدار ProtectionType — ReadOnly، AllowOnlyComments، AllowOnlyRevisions یا AllowOnlyFormFields — فراخوانی کنید تا ویرایش‌هایی که Word برای سند می‌پذیرد محدود شوند. Unprotect() (با یا بدون رمز عبور مطابق) محدودیت را حذف می‌کند. این فقط بر ویرایش داخل Word تأثیر می‌گذارد؛ فایل ذخیره‌شده را رمزگذاری نمی‌کند. برای اینکه فقط با وارد کردن رمز عبور بتوان فایل را باز کرد، هنگام ذخیره OoxmlSaveOptions.Password را تنظیم کنید.
مشکلات رایج و راه‌حل‌ها
Document(fileName) یک استثنا برای فایلی که در Word به‌خوبی باز می‌شود، پرتاب می‌کند. قالب فایل یکی از قالب‌هایی نیست که بارگذارهای این نسخه پشتیبانی می‌کنند. فراخوانی کنید FileFormatUtil.DetectFileFormat(fileName) ابتدا و خروجی بازگشتی را بررسی کنید LoadFormat قبل از تلاش برای بارگذاری.
محتوایی که بین اسناد کپی می‌شود، قلم‌ها یا سبک‌های نادرستی می‌گیرد. این ImportFormatMode به‌ارسال شده به AppendDocument or InsertDocument با آنچه انتظار داشتید مطابقت ندارد. ارسال کنید KeepSourceFormatting or UseDestinationStyles به‌صورت صریح به‌جای تکیه بر پیش‌فرض.
Unprotect() به نظر می‌رسد هیچ اثری نداشته باشد. یا سند با رمز عبور محافظت نشده بود (call Unprotect() بدون آرگومان)، یا رمز عبور ارائه‌شده با آن مطابقت ندارد Protect() با آن فراخوانی شده است.
قالب‌بندی اعمال‌شده از طریق DocumentBuilder در جایی که انتظار می‌رود نمایش داده نمی‌شود. قالب‌بندی در سطح Builder (Font, ParagraphFormat) فقط بر محتوای نوشته‌شده اعمال می‌شود after تنظیم شده است. مکان‌نما را جابجا کنید و قبل از فراخوانی قالب‌بندی را تنظیم کنید Write/Writeln, نه پس از آن.
سوالات متداول
چگونه یک سند ورد جدید و خالی ایجاد کنم؟
متد new Document() را فراخوانی کنید. آن را با یک DocumentBuilder بپیچید تا فوراً شروع به وارد کردن محتوا کنید.
تفاوت بین Document.Clone() و ImportNode چیست؟
متد Clone() یک سند کامل را به یک نمونه جدید از Document کپی می‌کند. ImportNode(srcNode, isImportChildren) یک گره تک را — به‌طور اختیاری همراه با فرزندانش — از درخت یک سند به سند دیگر منتقل می‌کند، که برای ترکیب محتوای خاص به جای اسناد کامل استفاده می‌شود.
چگونه می‌توانم قبل از بارگذاری، فرمت یک فایل را به‌صورت ایمن بررسی کنم؟
متد FileFormatUtil.DetectFileFormat(fileName) را فراخوانی کنید (یا نسخهٔ overload Stream) و پیش از ارسال فایل به Document، ویژگی‌های LoadFormat، IsEncrypted، HasDigitalSignature و HasMacros شیء بازگشتی FileFormatInfo را بررسی کنید.
چگونه می‌توانم فقط پاراگراف‌های داخل بدنهٔ یک سند را بخوانم؟
از مجموعهٔ Body.Paragraphs در Body بخش استفاده کنید، یا برای انواع دیگر گره‌ها Body.GetChildNodes(nodeType, isDeep) را به کار ببرید.
آیا Document.Protect فایل ذخیره‌شده را رمزگذاری می‌کند؟
خیر — این یک محدودیت ویرایشی است که Word هنگام باز شدن فایل اعمال می‌کند. برای الزام داشتن رمز عبور برای باز کردن خود فایل، هنگام فراخوانی Document.Save، OoxmlSaveOptions.Password را تنظیم کنید.
