معرفی
Aspose.Words FOSS برای .NET شامل همان مدل شیء قالببندی متن است که در موتور تجاری Aspose.Words وجود دارد: Font برای ویژگیهای سطح اجرا، ParagraphFormat برای ویژگیهای سطح پاراگراف، ListFormat برای فهرستهای عددی و بولتدار، FrameFormat برای فریمهای متنی موقعیتیابیشده، و Range.Replace برای جستجو و جایگزینی. این راهنما بهطور خاص به این لایه میپردازد — قالببندی و بازنویسی متنی که قبلاً در یک سند وجود دارد — نه به ساختار سند از ابتدا (به پست معرفی برای مرور کلی انتشار مراجعه کنید).
کتابخانه تحت مجوز MIT است، بدون وابستگیهای بومی و هدفگذاری شده برای .NET Standard 2.0، بنابراین بر روی .NET Framework 4.6.2+ و .NET 6، 8 و 10 اجرا میشود. آن را از طریق NuGet نصب کنید، یا از منبع بسازید (به «شروع سریع» زیر مراجعه کنید). همه موارد توضیح داده شده در اینجا با .docx، .docm، .dotx، .dotm و فایلهای Flat OPC بارگذاریشده با new Document(fileName)، یا با اسنادی که در حافظه با DocumentBuilder ساخته شدهاند، کار میکند.
بهدلیل اینکه Aspose.Words FOSS برای .NET کد پایهٔ اصیل Aspose.Words است که بهصورت یک هستهٔ رایگان کاهش یافته و بازنویسی نشده است، مدل شیء Font، ParagraphFormat، ListFormat و FrameFormat بهطور مستقیم به Aspose.Words تجاری برای .NET منتقل میشود، اگر پروژهای بعدها به چیدمان صفحه، رندرینگ یا مبدلهای فرمت اضافی که این نسخه حذف کرده نیاز داشته باشد.
ویژگیهای کلیدی
قالببندی سطح اجرا با قلم
هر Run یک ویژگی Font را ارائه میدهد و DocumentBuilder.Font قلمی را تنظیم میکند که به متنی که بعداً نوشته میشود اعمال خواهد شد. علاوه بر Bold، Italic و Underline واضح، (یک مقدار enum Underline با مقادیری شامل Single، Double، Dotted، Dash، Wavy و انواع *Heavy آن)، Font شامل StrikeThrough، DoubleStrikeThrough، Superscript، Subscript، SmallCaps، AllCaps، Hidden، Shadow، Outline، Emboss، Engrave، Color، HighlightColor، Spacing، Position، Kerning، Scaling و EmphasisMark است. Font.Style، Font.StyleName و Font.StyleIdentifier یک اجرا را به سبک کاراکتری باز میگردانند، و Font.ClearFormatting() قالببندی مستقیم یک اجرا را به پیشفرضهای سبک آن بازنشانی میکند. DocumentBuilder همچنین Bold، Italic و Underline را بهصورت مستقیم بهعنوان میانبرها در دسترس میگذارد، بههمراه PushFont() و PopFont() برای ذخیره و بازیابی وضعیت قلم فعلی سازنده در اطراف یک تغییر قالببندی موقت.
قالببندی پاراگراف با ParagraphFormat
ParagraphFormat (قابل دسترسی از طریق Paragraph.ParagraphFormat یا DocumentBuilder.ParagraphFormat) تراز را از طریق شمارشگر ParagraphAlignment (Left، Center، Right، Justify، Distributed، بهاضافهٔ انواع کشیده عربی و توزیعشدهٔ تایلندی) کنترل میکند، تورفتگی را از طریق LeftIndent، RightIndent و FirstLineIndent (با معادلهای CharacterUnit* برای چیدمانهای آسیای شرقی) و فاصله را از طریق SpaceBefore، SpaceAfter و LineSpacingRule/LineSpacing تنظیم میکند. رفتار صفحهبندی با KeepTogether، KeepWithNext، PageBreakBefore و WidowControl کنترل میشود و Bidi پاراگراف را بهعنوان راست-به-چپ علامتگذاری میکند. ایستهای تب سفارشی در ParagraphFormat.TabStops، یک TabStopCollection از اشیاء TabStop، هر کدام با یک Position، یک TabAlignment (Left، Center، Right، Decimal، Bar) و یک TabLeader (None، Dots، Dashes، Line، Heavy، MiddleDot) وجود دارند. همانند Font، ParagraphFormat.Style و StyleName پاراگراف را به یک Style نامدار پیوند میدهند، و ClearFormatting() قالببندی مستقیم پاراگراف را پاک میکند.
فهرستها با ListFormat
ListFormat (در Paragraph.ListFormat یا DocumentBuilder.ListFormat) قالببندی فهرست را به یک پاراگراف اعمال میکند: ApplyBulletDefault() و ApplyNumberDefault() آن را به فهرست نقطهای یا عددی پیشفرض تغییر میدهند، RemoveNumbers() قالببندی فهرست را کاملاً حذف میکند، و ListIndent()/ListOutdent() آن را بین سطوح فهرست جابهجا میکند. ListFormat.List تعریف List زیرین را برمیگرداند، و ListFormat.ListLevel ListLevel فعال برای آن پاراگراف را برمیگرداند که تنظیمات سطحی مانند NumberStyle، NumberFormat، Alignment (یک ListLevelAlignment از Left، Center یا Right)، StartAt، RestartAfterLevel، یک Font مخصوص سطح، و TrailingCharacter (یک ListTrailingCharacter از Tab، Space یا Nothing) که فاصله بین برچسب فهرست و متن پاراگراف را کنترل میکند. تعاریف جدید فهرست از ListCollection.Add(listTemplate) با استفاده از یکی از پیشتنظیمات داخلی ListTemplate (BulletDefault، NumberArabicDot، NumberUppercaseRomanDot و مشابه) یا AddSingleLevelList برای فهرست تکسطحی میآید؛ فهرستهای یک سند از طریق Document.Lists شمارش میشوند.
قابهای متن با FrameFormat
Paragraph.FrameFormat یک شیء گزارشدهی فقطخواندنی است: هر ویژگی آن بازتابی از یک پاراگراف است فعلی وضعیت فریم را نشان میدهد، نه این که اجازهٔ تنظیم مستقیم آن را بدهد. IsFrame گزارش میدهد که آیا پاراگراف در حال حاضر یک فریم است؛ Width, Height، و HeightRule اندازهٔ آن را گزارش میدهد؛ HorizontalPosition و VerticalPosition، همراه با RelativeHorizontalPosition و RelativeVerticalPosition, گزارش دهید که کجا نسبت به صفحه، حاشیه، ستون یا پاراگراف ثابت شده است؛ و HorizontalDistanceFromText/VerticalDistanceFromText گزارش کنید فاصله بین فریم و متن اصلی اطراف آن. HorizontalAlignment و VerticalAlignment گزارش کنید محتوا چگونه درون فریم تراز میشود.
یافتن و جایگزینی با Range و IReplacingCallback
Range.Replace — در دسترس روی Document.Range برای یک عبور کل-سند، یا روی Range هر گره — دارای بارگذاریهای متعدد برای یک جفت الگو/جایگزین ساده و برای یک جفت الگو/جایگزین که با یک نمونهٔ FindReplaceOptions ترکیب شده است، که جستجوی مبتنی بر regex را پشتیبانی میکند. FindReplaceOptions.MatchCase و FindWholeWordsOnly محدودهٔ مطابقت را محدود میکنند؛ Direction (FindReplaceDirection.Forward یا Backward) ترتیب اسکن را تنظیم میکند؛ ApplyFont و ApplyParagraphFormat اجازه میدهند یک عبور جایگزینی قالببندی را به متن جایگزین منتقل کند؛ و مجموعهای از پرچمهای Ignore* (IgnoreDeleted، IgnoreInserted، IgnoreFields، IgnoreFieldCodes، IgnoreFootnotes، IgnoreStructuredDocumentTags، IgnoreShapes، IgnoreOfficeMath) دستههای محتوا خاصی را از مطابقت حذف میکنند. برای منطق جایگزینی که یک رشته ثابت قادر به بیان آن نیست، IReplacingCallback.Replacing(args) را پیادهسازی کنید و به عنوان FindReplaceOptions.ReplacingCallback تنظیم کنید (یا آن را به یکی از سازندههای FindReplaceOptions که مستقیم یک callback میپذیرند، پاس دهید)؛ پارامتر args یک ReplacingArgs است که Match، MatchNode، MatchOffset را افشا میکند و یک رشتهٔ Replacement قابل تنظیم دارد تا callback بتواند برای هر مطابقت مقداری محاسبه کند. یک شمارندهٔ ReplaceAction مرتبط (Replace، Skip، Stop) نتایج ممکن برای یک مطابقت واحد در طول عملیات را توصیف میکند.
شروع سریع
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 اضافه کنید. برای قالببندی متن هنگام نوشتن، قبل از فراخوانی Write()، Writeln() یا InsertParagraph()، ویژگیهای DocumentBuilder.Font (Bold، Italic، Underline)، ویژگیهای DocumentBuilder.ParagraphFormat (Alignment، تورفتگیها، فاصلهها) و DocumentBuilder.ListFormat (ApplyBulletDefault()، ApplyNumberDefault()) را تنظیم کنید — سازنده وضعیت قالببندی فعلی خود را بر تمام نوشتهها اعمال میکند تا زمانی که دوباره آن را تغییر دهید یا تغییر موقت را در PushFont()/PopFont() بپیچید. برای بازفرمت یا بازنویسی متنی که قبلاً در یک سند وجود دارد، آن را با new Document(fileName) باز کنید و Range.Replace() را روی doc.Range فراخوانی کنید — یا بارگذاری ساده الگو/جایگزینی، یا بارگذاریای که یک FindReplaceOptions با MatchCase، FindWholeWordsOnly یا یک IReplacingCallback سفارشی میگیرد — سپس نتیجه را Save() کنید.
قالبهای پشتیبانیشده
| فرمت | پسوند | خواندن | نوشتن |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (همهٔ انواع) | (متنوع) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
کلاسهای قالببندی فوق بههمین شکل اعمال میشوند، صرفنظر از اینکه سند از کدام یک از این قالبها بارگذاری یا ذخیره شود. این نسخه از DOC، RTF، ODT، HTML، EPUB، MHTML، MOBI، AZW3 یا WordML برای خواندن یا نوشتن پشتیبانی نمیکند و از PDF، XPS یا خروجی تصویر نیز پشتیبانی نمیکند، زیرا چیدمان صفحه و رندرینگ خارج از حوزهٔ آن است.
منبع باز و مجوزدهی
Aspose.Words FOSS برای .NET تحت مجوز MIT منتشر شده است، برای استفاده تجاری و شخصی رایگان است و بدون حق امتیاز یا محدودیتهای بازتوزیع. کد منبع کامل، شامل پیادهسازیهای Font، ParagraphFormat، ListFormat، FrameFormat و Range که در بالا توصیف شدهاند، در GitHub در Aspose.Words FOSS برای مخزن .NET موجود است.
