کار با اسناد
کار با اسناد
Aspose.Words FOSS برای .NET هر فایل Word را به‌عنوان یک مدل شیء در حافظه که ریشه آن کلاس Document است، نمایش می‌دهد، به‌طوری که DocumentBuilder یک API سطح بالا و مبتنی بر مکان‌نما برای نوشتن محتوا فراهم می‌کند. این راهنما شامل ایجاد و بارگذاری اسناد، نوشتن با DocumentBuilder، ساختار بخش/بدنه، پیمایش درخت گره‌ها، ترکیب اسناد و حفاظت از آن‌ها است.
ایجاد و بارگذاری اسناد
یک سند خالی را با new Document() ایجاد کنید، یا با ارسال مسیر یا Stream به سازندهٔ Document(fileName) یا Document(stream) یک فایل موجود را باز کنید. نسخه‌های بارگذاری‌شده که آرگومان LoadOptions را می‌پذیرند، به شما امکان کنترل رفتار بارگذاری را می‌دهند، مانند ارائهٔ رمز عبور برای یک فایل رمزگذاری‌شده.
قبل از بارگذاری فایلی از منبع ناشناخته یا نامطمئن، FileFormatUtil.DetectFileFormat(fileName) (یا نسخهٔ بارگذاری Stream) یک FileFormatInfo برمی‌گرداند که LoadFormat شناسایی‌شده را توصیف می‌کند و اینکه آیا فایل IsEncrypted، HasDigitalSignature یا HasMacros است.
نوشتن با DocumentBuilder
DocumentBuilder یک Document را می‌پیچاند و یک مکان‌نما را نمایان می‌کند که هنگام درج محتوا، آن را در سند جابه‌جا می‌کنید. Write(text) و Writeln(text) متن را در مکان‌نما وارد می‌کنند؛ InsertParagraph() یک پاراگراف جدید را آغاز می‌کند. ویژگی‌های فرمت‌بندی در سازنده — Font، ParagraphFormat، ListFormat، PageSetup — بر روی هر چه بعداً نوشته می‌شود اعمال می‌شوند.
موقعیت‌نمای (cursor) را با MoveToDocumentStart()، MoveToDocumentEnd()، MoveToSection(sectionIndex)، MoveToBookmark(bookmarkName) یا MoveToParagraph(paragraphIndex, characterIndex) حرکت دهید. ویژگی‌های CurrentNode، CurrentParagraph و CurrentSection سازنده موقعیت فعلی آن را در درخت گزارش می‌دهند.
ساختار سند: بخش‌ها و بدنه
یک Document شامل یک SectionCollection (Document.Sections، به‌اضافه FirstSection / LastSection) است؛ هر Section یک Body دارد، یک مجموعه اختیاری سرصفحه/پاصفحه، و PageSetup خود را دارد. Section.AppendContent(sourceSection) و PrependContent(sourceSection) محتوا را بین بخش‌ها کپی می‌کنند، و ClearContent() یک بخش را بدون حذف آن از سند بازنشانی می‌کند.
در داخل یک Body، محتوا از طریق Body.Paragraphs (یک ParagraphCollection) و Body.Tables در دسترس است. یک Range — که از Document، Section، Paragraph و گره‌های دیگر قابل دسترسی است — نمایانگر یک ناحیه پیوسته از درخت است؛ Range.Text متن ساده آن را می‌خواند و Range.Replace(pattern, replacement) جستجو و جایگزینی را فقط بر روی آن ناحیه انجام می‌دهد.
پیمایش درخت گره‌ها با DocumentVisitor
هر بخش از یک سند — بخش‌ها، پاراگراف‌ها، runها، جدول‌ها، فیلدها، شکل‌ها، نظرات، پانوشت‌ها — یک Node در یک درخت ترکیبی است که ریشه‌اش Document است. برای پردازش هر گره‌ای از نوع مشخص بدون نیاز به بازگشت دستی، کلاس فرزند از DocumentVisitor انتزاعی بسازید و فراخوانی‌های Visit*Start / Visit*End مورد نیاز خود را، مانند VisitParagraphStart(paragraph) یا VisitRun(run)، بازنویسی کنید، سپس document.Accept(visitor) را فراخوانی کنید. هر فراخوانی می‌تواند یک VisitorAction (Continue، SkipThisNode یا Stop) برگرداند تا نحوهٔ پیشرفت پیمایش را کنترل کند.
کلون‌سازی، وارد کردن و افزودن محتوا
Document.Clone() یک نسخهٔ عمیق از تمام سند تولید می‌کند. برای جابجایی محتوا بین دو نمونهٔ متفاوت Document، ImportNode(srcNode, isImportChildren) را روی سند مقصد فراخوانی کنید تا گره‌ای از درخت خارجی وارد شود، یا Document.AppendDocument(srcDoc, importFormatMode) را فراخوانی کنید تا بخش‌های یک سند را با استفاده از یک ImportFormatMode انتخابی — KeepSourceFormatting، UseDestinationStyles یا KeepDifferentStyles — به سند دیگری الحاق کنید. DocumentBuilder.InsertDocument(srcDoc, importFormatMode) محتویات سند منبع را در موقعیت‌نمای سازنده به‌جای انتهای مقصد وارد می‌کند.
محافظت از اسناد
Document.Protect(type, password) ویرایش را بر اساس مقدار ProtectionType محدود می‌کند — ReadOnly، AllowOnlyComments، AllowOnlyRevisions، AllowOnlyFormFields یا NoProtection برای حذف حفاظت. Unprotect() (با یا بدون رمز عبور) آن را معکوس می‌کند. این یک محدودیت ویرایشی است که توسط Word اعمال می‌شود و جدا از رمزنگاری رمز عبوری OOXML که OoxmlSaveOptions.Password هنگام ذخیره‌سازی فایل اعمال می‌کند.
نکات و بهترین شیوه‌ها
- برای ساخت محتوای جدید، از
DocumentBuilderاستفاده کنید؛ وقتی به کنترل دقیق بر روی درخت موجود نیاز دارید، به دست‌کاری مستقیم گره‌ها (AppendChild،InsertAfter،Clone) روی آورید. - قبل از بارگذاری فایلی از منبع نامطمئن یا کاربر،
FileFormatUtil.DetectFileFormatرا فراخوانی کنید تا بتوانیدLoadFormatرا بررسی کرده و ورودی‌های پشتیبانی‌نشده یا رمزنگاری‌شده را زودتر رد کنید. - هنگام ترکیب اسناد با
AppendDocumentیاInsertDocument،ImportFormatModeرا به‌صورت عمدی انتخاب کنید —KeepSourceFormattingظاهر منبع را حفظ می‌کند،UseDestinationStylesسبک مجموعه سند هدف را منطبق می‌سازد. - به جای پیمایش دستی بازگشتی درخت، وقتی نیاز به پردازش مستمر تمام نمونه‌های یک نوع گره دارید، از زیرکلاس
DocumentVisitorاستفاده کنید. Document.Protectیک محدودیت ویرایشی است، نه رمزنگاری — اگر فایل ذخیره‌شده نیاز به رمز عبور برای باز شدن داشته باشد، آن را باOoxmlSaveOptions.Passwordترکیب کنید.
مشکلات رایج
| مشکل | دلیل | راه‌حل |
|---|---|---|
Document(fileName) برای فایلی که در Word به‌درستی باز می‌شود استثنا می‌اندازد | قالب فایل یکی از قالب‌هایی که این نسخه برای بارگذاری پشتیبانی می‌کند نیست | ابتدا FileFormatUtil.DetectFileFormat را فراخوانی کنید و قبل از بارگذاری، مقدار بازگشتی LoadFormat را بررسی کنید |
| محتوای اضافه‌شده قلم‌ها یا سبک‌های نادرست را برمی‌گیرد | ImportFormatMode عدم تطابق بین مجموعه‌های سبک منبع و مقصد | به‌جای تکیه بر مقدار پیش‌فرض، KeepSourceFormatting یا UseDestinationStyles را به‌صورت صریح پاس دهید |
گردش DocumentVisitor زود متوقف می‌شود یا محتوا را نادیده می‌گیرد | یک بازنویسی Visit*Start / Visit*End به‌صورت ناخواسته SkipThisNode یا Stop را برمی‌گرداند | از هر بازنویسی، VisitorAction.Continue را برگردانید مگر اینکه به‌طور خاص قصد عبور یا توقف داشته باشید |
Unprotect() تأثیری ندارد | سند با رمز عبور محافظت نشده بود، یا رمز عبور نادرستی ارائه شد | اگر Protect بدون رمز عبور فراخوانی شده باشد، Unprotect() را بدون آرگومان صدا بزنید؛ در غیر این صورت، رمز عبور منطبق را پاس دهید |
FAQ
تفاوت Document.Clone() و ImportNode چیست؟
Clone() یک سند کامل را به یک نمونه جدید از Document کپی می‌کند. ImportNode(srcNode, isImportChildren) یک گرهٔ واحد (به‌طور اختیاری همراه فرزندانش) را از درخت یک سند به سند دیگری می‌آورد، که هنگام ترکیب محتوای خاص به‌جای سندهای کامل از آن استفاده می‌کنید.
Document(fileName) می‌تواند کدام فرمت‌های فایل را بارگذاری کند؟
Document(fileName) فرمت‌های DOCX، DOCM، DOTX، DOTM، Flat OPC (به‌همراه انواع ماکرو فعال و قالب آن)، Markdown و متن ساده را بارگذاری می‌کند. فرمت‌های قدیمی پردازش کلمه و وب در بارگذارهای این نسخه گنجانده نشده‌اند.
چگونه می‌توانم مکان فعلی یک DocumentBuilder را پیدا کنم؟
در نمونهٔ سازنده، CurrentNode، CurrentParagraph یا CurrentSection را بخوانید.
آیا Document.Protect فایل ذخیره‌شده را رمزنگاری می‌کند؟
نه — این یک محدودیت ویرایشی است که توسط Word هنگام باز کردن فایل اعمال می‌شود. برای اینکه فقط برای باز کردن فایل نیاز به رمز عبور باشد، هنگام ذخیره‌سازی OoxmlSaveOptions.Password را تنظیم کنید.
چگونه فقط پاراگراف‌های موجود در بدنه سند را بخوانم؟
از مجموعه Body.Paragraphs استفاده کنید، یا برای انواع دیگر گره‌ها Body.GetChildNodes(nodeType, isDeep) را به کار ببرید.
API Reference خلاصه
| کلاس/متد | توضیح |
|---|---|
Document | ریشهٔ مدل شیء سند؛ سازنده‌ها از یک فایل یا جریان بارگذاری می‌کنند یا یک سند خالی ایجاد می‌نمایند. |
Document.Save | سند را در یک فایل، جریان، یا پاسخ HTTP به فرمت انتخابی می‌نویسد. |
Document.Clone() | یک کپی عمیق از کل سند تولید می‌کند. |
Document.Protect(type, password) / Unprotect() | یک محدودیت ویرایشی را اعمال یا حذف می‌کند. |
Document.AppendDocument(srcDoc, importFormatMode) | بخش‌های سند دیگری را به این سند اضافه می‌کند. |
DocumentBuilder | مبنی بر مکان‌نما API برای نوشتن متن و وارد کردن محتوا به یک سند. |
DocumentBuilder.InsertDocument(srcDoc, importFormatMode) | محتوای سند منبع را در مکان‌نما وارد می‌کند. |
Section / SectionCollection | یک بخش منفرد از سند، و مجموعهٔ همه بخش‌ها. |
Body | محفظه‌ای برای متن اصلی (پاراگراف‌ها و جداول) یک بخش. |
Range | یک ناحیهٔ پیوسته از درخت سند؛ از Text و Replace پشتیبانی می‌کند. |
DocumentVisitor | کلاس پایهٔ انتزاعی برای پیمایش هر گره در درخت سند. |
ProtectionType | Enum محدودیت‌های ویرایشی در سطح سند. |
FileFormatUtil.DetectFileFormat | فرمت یک فایل یا جریان را پیش از بارگذاری شناسایی می‌کند. |
