مقدمة
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 الواضحة (عدد 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 أبلغ عن طريقة محاذاة المحتوى داخل الإطار.
البحث والاستبدال مع النطاق وIReplacingCallback
Range.Replace — متاح على Document.Range لتمرير على كامل المستند، أو على Range لأي عقدة — يحتوي على إصدارات زائدة لزوج نمط/استبدال بسيط ولزوج نمط/استبدال مُدمج مع كائن FindReplaceOptions، داعمًا للمطابقة القائمة على التعبيرات النمطية. FindReplaceOptions.MatchCase وFindWholeWordsOnly يحدّان ما يُعدّ مطابقة؛ Direction (FindReplaceDirection.Forward أو Backward) يضبط ترتيب الفحص؛ ApplyFont وApplyParagraphFormat يسمحان لتمرير الاستبدال بنقل التنسيق إلى نص الاستبدال؛ ومجموعة من أعلام Ignore* (IgnoreDeleted، IgnoreInserted، IgnoreFields، IgnoreFieldCodes، IgnoreFootnotes، IgnoreStructuredDocumentTags، IgnoreShapes، IgnoreOfficeMath) تستبعد فئات محتوى محددة من المطابقة. لمنطق الاستبدال الذي لا يمكن لسلسلة ثابتة التعبير عنه، نفّذ IReplacingCallback.Replacing(args) وضعه كـ FindReplaceOptions.ReplacingCallback (أو مرره إلى أحد مُنشئي FindReplaceOptions الذين يقبلون رد نداء مباشرة); معلمة args هي ReplacingArgs تُظهر Match، MatchNode، MatchOffset، وسلسلة Replacement قابلة للتعيين حتى يتمكن رد النداء من حساب قيمة لكل مطابقة. تعداد 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. لتنسيق النص أثناء كتابته، قم بتعيين خصائص DocumentBuilder.Font (Bold، Italic، Underline)، خصائص DocumentBuilder.ParagraphFormat (Alignment، المسافات البادئة، التباعد)، وDocumentBuilder.ListFormat (ApplyBulletDefault()، ApplyNumberDefault()) قبل استدعاء Write() أو Writeln() أو InsertParagraph() — يطبق المُنشئ حالته الحالية للتنسيق على كل ما يُكتب حتى تقوم بتغييره مرة أخرى، أو تغلف تغييرًا مؤقتًا داخل 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 المستودع.
