العمل مع علامات المستند المهيكلة (عناصر التحكم في المحتوى)

العمل مع علامات المستند المهيكلة (عناصر التحكم في المحتوى)

علامة مستند مُنظمة (SDT)، المعروفة في واجهة Word باسم عنصر التحكم بالمحتوى، تغلف جزءًا من محتوى المستند بسلوك تحرير محدد ومقيد — خانة اختيار، أداة اختيار التاريخ، قائمة منسدلة، أو عنصر نائب نص عادي أو نص غني. Aspose.Words FOSS لـ .NET يُنمذج هذه من خلال Aspose.Words.Markup المجال، المتصدّر بـ StructuredDocumentTag الفئة. تغطي هذه الصفحة إدراج عناصر التحكم بالمحتوى، تكوين كل نوع، العثور عليها وإزالتها، وربطها ببيانات XML مخصصة.

نموذج كائن علامة المستند المهيكلة

StructuredDocumentTag هو CompositeNode يطبق أيضًا IMarkupNode، ITrackableNode، وIStructuredDocumentTag. SdtType يحدد نوع التحكم. Tag وTitle تحتفظان بالسلاسل التعريفية التي يحددها المؤلفون في Word؛ Placeholder (وهو BuildingBlock) وPlaceholderName يقدمان نص التلميح المعروض عندما يكون التحكم فارغًا، يُبلغ عنه عبر IsShowingPlaceholderText. LockContentControl يمنع حذف التحكم، وLockContents يمنع تعديل محتوياته، بشكل مستقل عن بعضهما.

إدراج عناصر التحكم في المحتوى

DocumentBuilder.InsertStructuredDocumentTag(SdtType) يُدرج تحكمًا جديدًا عند المؤشر، لكن فقط لسبعة من قيم SdtType: PlainText، RichText، Checkbox، DropDownList، ComboBox، Picture، وDate. لا يمكن إدراج RepeatingSection وRepeatingSectionItem عند مؤشر النص بهذه الطريقة — فهما يلتفان حول فقرات كاملة أو صفوف جدول بدلاً من ذلك. القيم المتبقية من SdtType التي تظهر في ملفات Word ولكنها غير موجودة في واجهة Word كأنواع قابلة للإدراج — None، Bibliography، Citation، Equation، BuildingBlockGallery، DocPartObj، Group، وEntityPicker — غير مدعومة بهذه طريقة الإدراج.

محتوى مخصص للنوع

حالة عنصر تحكم خانة الاختيار هي StructuredDocumentTag.Checked؛ SetCheckedSymbol() و SetUncheckedSymbol() يحددان الرموز المعروضة لكل حالة. يخزن عنصر تحكم التاريخ قيمته في FullDate، مع DateDisplayFormat و DateDisplayLocale يتحكمان في طريقة عرضه، DateStorageFormat (وهو SdtDateStorageFormat) يتحكم في طريقة تخزينه عند ربطه ببيانات XML، وCalendarType (وهو SdtCalendarType) يختار نظام التقويم. تعرض قائمة منسدلة أو مربع مركب خياراته عبر ListItems، وهو SdtListItemCollection من SdtListItem (DisplayText، Value) مع SelectedValue. تسمح خاصية Multiline لعنصر تحكم النص العادي أو تمنع فواصل الأسطر داخله.

المظهر والقفل

Appearance (SdtAppearance) يتحكم في كيفية تحديد العنصر بصريًا في Word. Color يحدد لون التظليل، وContentsFont / EndCharacterFont يتحكمان في الخط المطبق على محتوياته وحرف النهاية المتسلسل. LockContentControl وLockContents هما مفاتيح مستقلة – الأول يمنع حذف العنصر نفسه، والثاني يمنع تحرير ما بداخله.

العثور على عناصر التحكم بالمحتوى وإزالتها

Range.StructuredDocumentTags يُعيد StructuredDocumentTagCollection محصورًا على ذلك النطاق، مع GetById() وGetByTag() وGetByTitle() للبحث المستهدف إلى جانب Remove() وRemoveAt(). على StructuredDocumentTag فردي، Remove() يحذف العنصر ومحتوياته معًا، RemoveSelfOnly() يحذف الغلاف فقط ويُبقي محتوياته في المستند، وClear() يفرغ محتويات العنصر مع الإبقاء على العنصر نفسه.

ربط بيانات XML

StructuredDocumentTag.XmlMapping هو مثال XmlMapping يصف ربطًا إلى جزء XML مخصص في المستند: CustomXmlPart، XPath، PrefixMappings، StoreItemId، وIsMapped. SetMapping() يُنشئ الربط إلى جزء XML مخصص موجود وDelete() يزيله.

عناصر التحكم بالمحتوى متعددة الأقسام (نطاقية)

عن عنصر التحكم بالمحتوى الذي يمتد على أكثر من قسم – تم الإبلاغ عنه بواسطة IsMultiSection – لا يُمثَّل بعقدة StructuredDocumentTag واحدة بل بزوج من عقد StructuredDocumentTagRangeStart وStructuredDocumentTagRangeEnd، متصلة عبر StructuredDocumentTagRangeStart.RangeEnd. كل من الشكل ذات العقدة الواحدة والشكل المتعدد الأقسام يطبقان الواجهة المشتركة IStructuredDocumentTag، لذا يمكن للكود الذي يحتاج فقط إلى Tag، Title، SdtType، Placeholder، وغيرها من الخصائص التعريفية المشابهة أن يعمل مع أيٍ من الشكلين بشكل موحد.

نصائح وأفضل الممارسات

• تحقّق من قائمة الأنواع المدعومة في DocumentBuilder.InsertStructuredDocumentTag() قبل الاعتماد عليها – فقط PlainText، RichText، Checkbox، DropDownList، ComboBox، Picture، وDate يمكن إدراجها عند المؤشر؛ الأنواع الأخرى تُسبب استثناءً.
• استخدم RemoveSelfOnly() بدلاً من Remove() عندما تريد “flatten” عنصر التحكم بالمحتوى – احتفظ بمحتوياته في المستند لكن احذف غلاف التحكم.
• املأ ListItems قبل أن تتوقع ظهور خيارات في عنصر تحكم DropDownList أو ComboBox، واضبط SelectedValue لاختيار العنصر النشط.
• برمج ضد IStructuredDocumentTag بدلاً من StructuredDocumentTag مباشرةً إذا كان الكود الخاص بك يحتاج إلى معالجة كل من عناصر التحكم بالمحتوى العادية ومتعددة الأقسام (المحددة) بنفس الطريقة.
• XmlMapping.SetMapping() يرتبط بجزء XML مخصص يجب أن يكون موجودًا بالفعل في مخزن بيانات XML المخصص للمستند – أضف أو حمّل بيانات XML قبل ربط عنصر تحكم بها.

المشكلات الشائعة

FAQ

ما أنواع التحكم بالمحتوى التي يمكنني إدراجها مباشرة باستخدام DocumentBuilder؟

PlainText، RichText، Checkbox، DropDownList، ComboBox، Picture، و Date. القيم الأخرى لـ SdtType غير مدعومة من قبل InsertStructuredDocumentTag().

كيف يمكنني العثور على جميع عناصر التحكم بالمحتوى التي تحمل علامة محددة؟

استخدم Range.StructuredDocumentTags.GetByTag()، أو GetByTitle() / GetById() إذا كنت تطابق عليها بدلاً من ذلك.

كيف يمكنني إزالة عنصر التحكم بالمحتوى مع الحفاظ على محتواه؟

استدعِ StructuredDocumentTag.RemoveSelfOnly() بدلاً من Remove().

كيف يمكنني ربط عنصر التحكم بالمحتوى ببيانات XML مخصصة؟

استدعِ XmlMapping.SetMapping() على عنصر التحكم، موجهًا إياه إلى جزء XML مخصص موجود وتعبير XPath داخله.

ما الفرق بين StructuredDocumentTag العادي وStructuredDocumentTag النطاقي؟

يتم تمثيل عنصر التحكم في المحتوى الذي يمتد عبر أكثر من قسم في المستند كزوج StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd بدلاً من عقدة واحدة؛ كلا الشكلين ينفّذان IStructuredDocumentTag.

ملخص API Reference

انظر أيضاً

• Aspose.Words for .NET — Enterprise Documentation