مقدمه
این راهنما به بررسی این میپردازد که چگونه Aspose.Words FOSS برای .NET یک سند Word را در حافظه نمایان میکند و به APIهایی که برای ساخت، پیمایش و تغییر این نمایندگی استفاده میشوند: DocumentBuilder برای نوشتن ترتیبی، درخت گره (Node, CompositeNode, NodeCollection) برای دسترسی ساختاری مستقیم، DocumentVisitor برای پردازش همه انواع گرهها در یک عبور، جستجو و جایگزینی از طریق Range و FindReplaceOptions، و متدهایی برای ترکیب و شبیهسازی اسناد. Where پست اعلامیه معرفی میکند کتابخانه را بهصورت کلی، این راهنما بر مدل شیء سند (DOM) متمرکز میماند — بزرگترین بخش سطح API — و اینکه قطعات آن چگونه با هم ترکیب میشوند.
Aspose.Words FOSS برای .NET تحت مجوز MIT منتشر شده است و هیچ وابستگی بومی ندارد؛ هدف آن .NET Standard 2.0 است، بنابراین DOM توصیفشده در اینجا بر روی .NET Framework 4.6.2+ و .NET 6، 8 و 10، در ویندوز، لینوکس و macOS در دسترس است. آن را از طریق NuGet نصب کنید یا از منبع بسازید — بخش Quick Start را در زیر ببینید.
هر کاری که در زیر توصیف میشود — نوشتن گزارش از ابتدا، بازسازی یک فایل .docx موجود، مرور محتویات آن برای تحلیل، یا ترکیب چند سند در یک سند — از همان تعداد محدودی از انواع پایه آغاز میشود: Document، DocumentBuilder و سلسله مراتب Node که زیر آنها قرار دارد.
Document Object Model
ساخت اسناد با DocumentBuilder
DocumentBuilder یک نویسنده مبتنی بر مکاننما است که بر روی یک Document قرار میگیرد و محتوا را بهصورت ترتیبی وارد میکند. Write(text) و Writeln(text) متن را در موقعیت فعلی اضافه میکنند؛ InsertParagraph() و InsertBreak(breakType) پاراگراف و شکستهای صفحه/ستون/بخش را اضافه مینمایند. قالببندی حالتدار است: ویژگیهای Font، ParagraphFormat، ListFormat و PageSetup سازنده بر تمام محتویات نوشتهشده پس از آن اعمال میشوند، و PushFont() / PopFont() وضعیت فعلی قلم را ذخیره و بازیابی میکنند تا نیازی به بازگرداندن دستی تغییر موقت سبک نباشد. متدهای ناوبری مکاننما را به هر نقطهای در یک سند موجود منتقل میکنند — MoveToDocumentStart(), MoveToDocumentEnd(), MoveToSection(sectionIndex), MoveToBookmark(bookmarkName), MoveToParagraph(paragraphIndex, characterIndex), و MoveTo(node) با هدف کلی — و DocumentBuilder.CurrentNode, DocumentBuilder.CurrentParagraph, و DocumentBuilder.CurrentSection نشان میدهند سازنده هماکنون در کجا قرار دارد. برای استخراج متن فقط-خواندنی که در آن نیازی به DOM کامل نیست، PlainTextDocument مسیر سبکتری ارائه میدهد: new PlainTextDocument(fileName) فقط ویژگی PlainTextDocument.Text و ویژگیهای از پیش تعریفشده و سفارشی سند را در دسترس میگذارد.
درخت گره: Sections, Paragraphs, Runs, and Tables
Document یک درخت از اشیاء Node است که ریشه آن خود سند میباشد: Section → Body → Paragraph → Run برای متن بدنه، و با Table → Row → Cell در هر مکانی که جدول ظاهر میشود شاخه میزند. CompositeNode، کلاس پایه برای هر گرهٔ کانتینر، CompositeNode.FirstChild، CompositeNode.LastChild، Node.NextSibling و Node.PreviousSibling را برای پیمایش مستقیم فراهم میکند، GetChildNodes(nodeType, isDeep) برای جمعآوری تمام گرههای یک NodeType معین (Paragraph، Run، Table و غیره) در هر عمقی، و GetChild(nodeType, index, isDeep) برای جستجوهای شاخصی. AppendChild(newChild)، InsertBefore(newChild, refChild)، InsertAfter(newChild, refChild) و RemoveChild(oldChild) درخت را بهصورت مستقیم تغییر میدهند. CompositeNode.SelectNodes(xpath) و SelectSingleNode(xpath) گرهها را با یک عبارت شبیه XPath انتخاب میکنند بهجای پیمایش دستی درخت، و برای اسناد بسیار بزرگ، Node.NextPreOrder(rootNode) / PreviousPreOrder(rootNode) هر گره را یکی یکی بدون بازگشت (recursion) میپیمایند.
DocumentVisitor: پردازش تمام انواع گره در یک عبور
زیرکلاسسازی DocumentVisitor روشی برای پردازش یک سند بدون کدنویسی ثابت ساختار آن است. این کلاس روشهای جفت Visit-Start / Visit-End را برای هر نوع گرهٔ ترکیبی تعریف میکند، شامل DocumentVisitor.VisitSectionStart، DocumentVisitor.VisitParagraphStart، DocumentVisitor.VisitTableStart، DocumentVisitor.VisitRowStart، DocumentVisitor.VisitCellStart و DocumentVisitor.VisitBookmarkStart — هر کدام با یک callback متناظر End — بهعلاوه DocumentVisitor.VisitFieldStart، DocumentVisitor.VisitFieldSeparator، DocumentVisitor.VisitFieldEnd و DocumentVisitor.VisitRun برای رانهای متنی تکتک. Accept(visitor) را بر روی یک Document، Section یا هر گرهٔ دیگری فراخوانی کنید تا بازدیدکننده بر آن گره و همهٔ زیرمجموعههای آن اجرا شود؛ AcceptStart(visitor) و AcceptEnd(visitor) تنها callbackهای ورودی و خروجی برای یک گرهٔ ترکیبی واحد را فرا میخوانند. هر روش Visit یک مقدار VisitorAction برمیگرداند که تعیین میکند پیمایش چگونه ادامه یابد — Continue برای ادامه به زیردرخت، SkipThisNode برای نادیده گرفتن آن، یا Stop برای توقف کامل.
یافتن و جایگزینی متن
Range.Replace(pattern, replacement) یک عملیات پیدا-و-جایگزینی را بر روی Range مالک آن اجرا میکند — که میتواند یک Document کامل، یک Section یا ویژگی Range هر گرهای باشد — و الگوی جستجو میتواند بهصورت رشتهٔ متنی ساده یا عبارت منظم پذیرفته شود. نسخهٔ overload Range.Replace(pattern, replacement, options) یک نمونهٔ FindReplaceOptions میگیرد تا FindReplaceOptions.MatchCase، FindReplaceOptions.FindWholeWordsOnly، جهت جستجو FindReplaceOptions.Direction (مقدار FindReplaceDirection از نوع Forward یا Backward)، قالببندی اعمالشده به متن جایگزین (FindReplaceOptions.ApplyFont، FindReplaceOptions.ApplyParagraphFormat) و اینکه کدام محتوای اطراف بدون تغییر بماند (FindReplaceOptions.IgnoreFields، FindReplaceOptions.IgnoreFootnotes، FindReplaceOptions.IgnoreFieldCodes و پرچمهای مرتبط Ignore*) را کنترل کند. برای منطق در هر تطبیق فراتر از یک جایگزینی ساده، متد Replacing(args) از IReplacingCallback را پیادهسازی کنید و پیادهسازی را به FindReplaceOptions.ReplacingCallback اختصاص دهید؛ هر تطبیق با یک ReplacingArgs توصیف میشود و مقدار بازگشتی callback — یک مقدار ReplaceAction از نوع Replace، Skip یا Stop — تعیین میکند چه اتفاقی برای آن میافتد.
ترکیب و تکثیر اسناد
Document.AppendDocument(srcDoc, importFormatMode) محتواى کامل یک Document را به انتهای سند دیگری اضافه میکند. آرگومان importFormatMode آن — مقداری از ImportFormatMode که میتواند UseDestinationStyles، KeepSourceFormatting یا KeepDifferentStyles باشد — تعیین میکند که تعارضهای استایل بین منبع و مقصد چگونه حل شوند، و overload Document.AppendDocument(srcDoc, importFormatMode, importFormatOptions) کنترل دقیقتری را از طریق ImportFormatOptions (ImportFormatOptions.KeepSourceNumbering، ImportFormatOptions.IgnoreHeaderFooter، ImportFormatOptions.MergePastedLists و پرچمهای مشابه) فراهم میکند. برای درج محتوای سند دیگری در موقعیتی مشخص به جای انتها، DocumentBuilder.InsertDocument(srcDoc, importFormatMode, importFormatOptions) معادل آن را از موقعیت فعلی مکاننما در Builder انجام میدهد، و DocumentBuilder.InsertDocumentInline(srcDoc, importFormatMode, importFormatOptions) همان محتوا را بدون اضافه کردن پاراگراف یا شکست بخش در نقطه درج وارد میکند. Document.ImportNode(srcNode, isImportChildren) یک گره را — بهصورت اختیاری با فرزندانش — از سندی دیگر کپی میکند تا بتوان آن را به سند جاری اضافه کرد، و متد Node.Clone(isCloneChildren) که برای هر گرهای در دسترس است ساختار را درون همان سند تکرار میکند، مانند استفاده مجدد از یک Section به عنوان قالب برای محتوای تکراری.
نشانکها و متغیرهای سند
ویژگی Range.Bookmarks یک BookmarkCollection از انکرهای نامدار درون آن بازه را ارائه میدهد. DocumentBuilder.StartBookmark(bookmarkName) و EndBookmark(bookmarkName) محدوده یک بوکمارک را هنگام ساخت علامتگذاری میکنند؛ ایندکسر BookmarkCollection، bookmarks[name]، بعداً برای ناوبری با DocumentBuilder.MoveToBookmark(bookmarkName) یا برای خواندن Bookmark.Text یک مورد را بازیابی میکند. بهصورت جداگانه، Document.Variables — یک VariableCollection — جفتهای رشتهای نام/مقدار دلخواه را مستقیماً بر روی سند ذخیره میکند که برای حمل قطعات کوچکی از وضعیت در طول یک خط لوله تولید سند بدون افزودن محتوای قابل مشاهده مفید است.
شروع سریع
Aspose.Words FOSS برای .NET از طریق NuGet در دسترس است:
dotnet add package Aspose.Words.FOSSبرای ساخت از منبع بهجای آن:
git clone https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git
cd Aspose.Words-FOSS-for-.NET
dotnet build Aspose.Words.sln -c Release
با داشتن یک ارجاع پروژه به Aspose.Words.csproj، کوتاهترین مسیر برای ایجاد یک سند همان الگوی استفاده شده در سراسر این مقاله را دنبال میکند: یک Document بسازید، آن را در یک DocumentBuilder بپیچید، با فراخوانی Write() یا Writeln() متن اضافه کنید — قالببندی تنظیمشده در ویژگیهای Font و ParagraphFormat سازنده به هر نوشتن بعدی منتقل میشود — و با فراخوانی Document.Save(fileName) آن را به صورت .docx، .docm، .dotx، .dotm، Flat OPC، Markdown یا متن ساده ذخیره کنید. برای ویرایش یک فایل موجود به جای شروع از صفر، آن را مستقیم با new Document(fileName) بارگذاری کنید، سازنده را به موقعیت خاصی با MoveToBookmark()، MoveToParagraph() یا MoveTo(node) منتقل کنید و از آنجا نوشتن را ادامه دهید.
قالبهای پشتیبانیشده
| قالب | پسوند | خواندن | نوشتن |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (تمام انواع) | (متنوع) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
درخت گرهای که در بالا توصیف شد به همان شکل در دسترس است صرفنظر از اینکه سند از کدام یک از این فرمتها بارگذاری شده یا به کدام یک ذخیره خواهد شد — DOM بهصورت داخلی مستقل از فرمت است. چیزی که در این نسخه گنجانده نشده است هر آنچه به چینش صفحه وابسته باشد: هیچ خروجی PDF، XPS یا تصویر، و هیچ چاپی وجود ندارد، بنابراین مقادیر فیلدهای وابسته به چینش مانند شماره صفحه بهعنوان جایگیرها ارزیابی میشوند نه بهصورت محاسبهشده. مبدلهای فرمت اضافی (DOC، RTF، ODT، HTML، EPUB، MHTML، MOBI، AZW3، و WordML) خوانده یا نوشته نمیشوند، و اجرای ادغام نامه، LINQ Reporting، و مقایسه سند نیز شامل نمیشوند. توسعهدهندگانی که به این قابلیتها نیاز دارند میتوانند به نسخه commercial منتقل شوند Aspose.Words برای .NET بدون بازنویسی کد DOM نشان دادهشده در اینجا، زیرا هر دو نسخه همان API زیرساختی را به اشتراک میگذارند.
منبع باز و مجوزدهی
Aspose.Words FOSS برای .NET تحت مجوز MIT منتشر شده است، بهصورت رایگان برای استفاده تجاری و شخصی بدون حق امتیاز یا محدودیتهای توزیع مجدد. منبع، شامل Document, DocumentBuilder، و پیادهسازی درخت گرهای که در بالا توضیح داده شد، در مخزن Aspose.Words FOSS برای .NET در GitHub.
