وحدات البناء
كتل البناء
يوضح هذا الدليل كيفية قراءة وتعديل كتل المحتوى القابلة لإعادة الاستخدام المخزنة في وثيقة مسرد الوثيقة باستخدام Aspose.Words FOSS لـ .NET. تعرض المكتبة AutoText إدخالات، صفحات الغلاف، رؤوس، تذييلات، ومحتوى مسبق التعريف مشابه عبر Document.GlossaryDocument ونموذج الكائن BuildingBlock/BuildingBlockCollection.
وثيقة القاموس
كل Document يحمل GlossaryDocument — يمكن الوصول إليه عبر Document.GlossaryDocument — وهو نفسه فئة فرعية من DocumentBase تحتفظ بكتل البناء. تُعيد خاصية BuildingBlocks الخاصة به BuildingBlockCollection، مع FirstBuildingBlock/LastBuildingBlock توفر وصولًا سريعًا إلى نهايات القائمة. ابحث عن كتلة بناء محددة باستخدام GetBuildingBlock(gallery, category, name)، مطابقةً BuildingBlockGallery، وسلسلة الفئة، والاسم معًا.
بنية كتلة البناء
BuildingBlock هو CompositeNode، لذا فهو يحتفظ بشجرة محتوى خاصة به — Sections (وهو SectionCollection)، FirstSection، وLastSection — بنفس الطريقة التي يحتفظ بها Document بالأقسام. تحدد خصائص التعريف الوصفي الخاصة به وتصنّفه: Name، Guid، Description، Category، Gallery (وهو BuildingBlockGallery — AutoText، CoverPage، Headers، Footers، Tables، Watermarks، والعديد من المعارض المعرفة مسبقًا)، Type (وهو BuildingBlockType)، وBehavior (وهو BuildingBlockBehavior من Content، Paragraph، أو Page) الذي يتحكم في كيفية دمج محتوياته في وثيقة عند الإدراج.
إدارة مجموعة كتل البناء
BuildingBlockCollection يدعم تحرير المجموعة بالكامل: Add(node)، Insert(index, node)، Remove(node)، RemoveAt(index)، Clear()، Contains(node)، وIndexOf(node)، بالإضافة إلى ToArray() وGetEnumerator() للقراءة. لأنّه NodeCollection، يمكن إنشاء كتل البناء، استنساخها، ونقلها باستخدام نفس واجهات برمجة العقد (node APIs) كما هو الحال مع أي جزء آخر من شجرة المستند.
كتل بناء النص النائب
يمكن لعلامات المستند المهيكلة الإشارة إلى كتلة بناء كالمحتوى النائب لها: StructuredDocumentTag.Placeholder وStructuredDocumentTagRangeStart.Placeholder كلاهما يُعيد BuildingBlock المعروضة عندما تكون العلامة فارغة، عبر الخاصية المشتركة IStructuredDocumentTag.Placeholder.
نصائح وأفضل الممارسات
- طابق المعاملات الثلاث لـ
GetBuildingBlock(gallery, category, name)بعناية — قد يوجد نفس الاسم في معارض أو فئات مختلفة. - استخدم
BuildingBlockGalleryلتصفية نوع المحتوى القابل لإعادة الاستخدام الذي تبحث عنه (AutoText،CoverPage،Tables،Watermarks، إلخ) بدلاً من فحص كل كتلة بناء حسب الاسم فقط. - يحدد
BuildingBlockBehaviorكيفية دمج المحتوى المُدرج مع المستند المحيط (Content،Paragraph، أوPage) — تحقق منه قبل افتراض أن كتلة البناء ستُدرج بالطريقة التي تتوقعها. - نظرًا لأن
BuildingBlockهوCompositeNode، فعامله كأي شجرة فرعية لعقدة أخرى عند بناء أو تحرير محتوياته —AppendChild،InsertAfter، وغيرها من طرق العقد المماثلة تنطبق جميعًا.
المشكلات الشائعة
| المشكلة | السبب | الإصلاح |
|---|---|---|
GetBuildingBlock() لا يُعيد أي شيء | المعرض أو الفئة أو الاسم لا يتطابق تمامًا مع building block موجود | عدّ GlossaryDocument.BuildingBlocks للعثور على تركيبة Gallery/Category/Name الدقيقة |
| محتوى building block المُدرج يندمج بشكل غير متوقع | Behavior (Content/Paragraph/Page) غير مُؤخذ في الاعتبار | تحقق من BuildingBlock.Behavior قبل الإدراج لفهم كيفية دمجه |
| عنصر نائب لعلامة المستند المُنظم لا يعرض المحتوى المتوقع | Placeholder يشير إلى BuildingBlock مختلف عما كان مفترضًا | اقرأ StructuredDocumentTag.Placeholder لتأكيد أي كتلة بناء يتم الإشارة إليها فعليًا |
FAQ
أين يتم تخزين كتل البناء في المستند؟
في GlossaryDocument الخاص بالمستند، يمكن الوصول إليه عبر Document.GlossaryDocument، حيث إن خاصية BuildingBlocks هي BuildingBlockCollection.
كيف يمكنني العثور على كتلة بناء محددة، مثل إدخال AutoText؟
استدعِ GlossaryDocument.GetBuildingBlock(gallery, category, name) مع BuildingBlockGallery المطابقة، والفئة، والاسم.
هل يمكنني إضافة كتل بناء جديدة برمجيًا؟
نعم — يدعم BuildingBlockCollection Add(node) وInsert(index, node) لأنه NodeCollection.
ما الذي يتحكم فيه BuildingBlockBehavior؟
كيف يندمج محتوى كتلة البناء في المستند عند إدراجه — كـ Content، أو كـ Paragraph كامل، أو كـ Page كامل.
كيف ترتبط كتلة البناء بنص العنصر النائب لعلامة المستند المنظم؟
StructuredDocumentTag.Placeholder (و StructuredDocumentTagRangeStart.Placeholder) تُعيد الـ BuildingBlock الذي يزود محتوى العنصر النائب لـ SDT عندما يكون فارغًا.
API Reference ملخص
| فئة / طريقة | وصف |
|---|---|
Document.GlossaryDocument | الGlossaryDocument الخاص بالمستند، الذي يحتوي على جميع كتل البناء |
GlossaryDocument.BuildingBlocks | BuildingBlockCollection من كل كتلة بناء |
GlossaryDocument.GetBuildingBlock() | يبحث عن وحدة بناء حسب المعرض، الفئة، والاسم |
BuildingBlock | CompositeNode مع Name، Gallery، Category، Behavior، Type، Sections |
BuildingBlockCollection | Add()، Insert()، Remove()، Clear()، Contains()، IndexOf() |
BuildingBlockGallery / BuildingBlockType / BuildingBlockBehavior | Enums تصنف وحدة بناء |
StructuredDocumentTag.Placeholder | يُستخدم BuildingBlock كمحتوى نائب لعنصر SDT |
