كيفية العمل مع علامات المستند المهيكلة في .NET
يوضح هذا الدليل كيفية إدراج وتكوين وإيجاد وإزالة وربط البيانات بعلامات المستند المهيكلة (عناصر التحكم بالمحتوى) في Aspose.Words FOSS لـ .NET، باستخدام StructuredDocumentTag الفئة في Aspose.Words.Markup المساحة الاسمية. يغطي أي أنواع عناصر التحكم بالمحتوى DocumentBuilder يمكن إدراجها، وتعيين المحتوى الخاص بالنوع مثل حالة خانة الاختيار أو خيارات القائمة المنسدلة، وتحديد عناصر التحكم بواسطة العلامة أو العنوان، وإزالة عنصر تحكم مع أو بدون محتوياته، وربط عنصر التحكم ببيانات XML مخصصة.
دليل خطوة بخطوة
الخطوة 1: تثبيت الحزمة
Aspose.Words FOSS for .NET لا ينشر حزمة NuGet بعد – قم ببناء المكتبة من المصدر بدلاً من ذلك. استنساخ https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git، ثم بناء Aspose.Words.sln في تكوين Release باستخدام مجموعة تطوير .NET SDK والإشارة إلى تجميع Aspose.Words الناتج من مشروعك. تستهدف المكتبة .NET Standard 2.0، لذا تعمل على .NET Framework 4.6.2+ و .NET 6/8/10.
الخطوة 2: استيراد الأصناف المطلوبة
أضف توجيه using Aspose.Words; لـ Document و DocumentBuilder، وتوجيه using Aspose.Words.Markup; لـ StructuredDocumentTag، SdtType، SdtListItem، SdtListItemCollection، XmlMapping، وبقية أصناف عناصر التحكم بالمحتوى التي يغطيها هذا الدليل.
الخطوة 3: تحقق من أنواع عناصر التحكم بالمحتوى التي يمكنك إدراجها
قبل الإدراج، تحقق مما إذا كان الهدف SdtType أحد الأنواع السبعة التي يقبلها DocumentBuilder.InsertStructuredDocumentTag(SdtType): PlainText، RichText، Checkbox، DropDownList، ComboBox، Picture، وDate. لا يمكن إدراج RepeatingSection وRepeatingSectionItem عند مؤشر النص بهذه الطريقة — فهما يغطان فقرات كاملة أو صفوف جدول بدلاً من ذلك. القيم المتبقية من SdtType التي يمكن أن تظهر في ملف Word ولكنها غير موجودة في واجهة Word كأنواع قابلة للإدراج — None، Bibliography، Citation، Equation، BuildingBlockGallery، DocPartObj، Group، وEntityPicker — غير مقبولة على الإطلاق بهذه طريقة الإدراج.
الخطوة 4: إدراج عنصر تحكم بالمحتوى عند المؤشر
استدعِ DocumentBuilder.InsertStructuredDocumentTag(SdtType) بأحد الأنواع السبعة المدعومة لإدراج عنصر تحكم جديد في موضع المؤشر الحالي للمنشئ؛ تُعيد الاستدعاء العنصر الجديد StructuredDocumentTag. عيّن Tag وTitle على العنصر المرجع لإعطائه السلاسل التعريفية التي يراها المؤلفون في Word، وعين PlaceholderName (مدعومة بـ Placeholder BuildingBlock) لنص التلميح الذي يظهره Word عندما يكون العنصر فارغًا — IsShowingPlaceholderText يبلّغ ما إذا كان ذلك التلميح معروضًا حاليًا.
الخطوة 5: تكوين المحتوى حسب النوع
في عنصر تحكم خانة الاختيار، اقرأ أو اضبط StructuredDocumentTag.Checked، واستدعِ SetCheckedSymbol() / SetUncheckedSymbol() لتخصيص الرموز المعروضة لكل حالة. في عنصر تحكم التاريخ، اضبط FullDate، مع DateDisplayFormat وDateDisplayLocale يتحكمان في طريقة عرضه، وDateStorageFormat (SdtDateStorageFormat) يتحكم في طريقة تخزينه عندما يُربط ببيانات XML، وCalendarType (SdtCalendarType) يختار نظام التقويم. بالنسبة لقائمة منسدلة أو مربع combo، املأ ListItems — وهو SdtListItemCollection من SdtListItem (DisplayText، Value) — قبل ضبط SelectedValue لاختيار العنصر النشط. بالنسبة لعنصر تحكم نص عادي، Multiline هو خاصية bool على StructuredDocumentTag يمكن ضبطها لتكوين العنصر.
الخطوة 6: مظهر العنصر والتحكم في القفل
عيّن Appearance (SdtAppearance) للتحكم في كيفية تمييز العنصر بصريًا في Word، وColor لتحديد لون التمييز. ContentsFont وEndCharacterFont يتحكمان في الخط المطبق على محتويات العنصر وحرف النهاية المتتابع. LockContentControl وLockContents هما مفاتيح مستقلة — عيّن LockContentControl لمنع حذف العنصر نفسه، وLockContents لمنع تحرير ما بداخله، دون التأثير على الآخر.
الخطوة 7: العثور على عناصر التحكم بالمحتوى وإزالتها
اقرأ Range.StructuredDocumentTags – StructuredDocumentTagCollection مخصص لذلك النطاق – واستدعِ GetById() أو GetByTag() أو GetByTitle() لتحديد عنصر تحكم معين، أو Remove() / RemoveAt() على المجموعة لإزالة واحد بالمرجع أو الفهرس. بالنسبة لعنصر تحكم فردي، استدعِ Remove() لحذف العنصر مع محتوياته، وRemoveSelfOnly() لحذف الغلاف فقط مع إبقاء المحتويات في المستند، أو Clear() لتفريغ محتوياته مع إبقاء عنصر التحكم في مكانه.
الخطوة 8: ربط عنصر تحكم ببيانات XML مخصصة
اقرأ StructuredDocumentTag.XmlMapping – نسخة من XmlMapping – واستدعِ SetMapping(customXmlPart, xPath, prefixMapping) لربط عنصر التحكم بجزء XML مخصص موجود مسبقًا في مخزن بيانات XML المخصص للمستند، باستخدام تعبير XPath لتحديد العنصر المرتبط. XmlMapping.IsMapped يُبلّغ ما إذا كان الربط نشطًا حاليًا، CustomXmlPart وStoreItemId يحددان جزء البيانات المرتبط، وDelete() يزيل الخريطة.
الخطوة 9: التعامل مع عناصر التحكم بالمحتوى التي تمتد عبر أقسام متعددة
عنصر التحكم بالمحتوى الذي يمتد عبر أكثر من قسم في المستند – يُبلغ عنه بواسطة IsMultiSection – لا يُمثَّل بعقدة StructuredDocumentTag واحدة بل بزوج StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd، متصل عبر StructuredDocumentTagRangeStart.RangeEnd. برمِج ضد الواجهة المشتركة IStructuredDocumentTag (Tag، Title، Placeholder، PlaceholderName، Appearance، IsShowingPlaceholderText، RemoveSelfOnly()) عندما يحتاج الكود إلى التعامل مع الصيغتين (العقدة المفردة والنطاقية) بشكل موحد، بدلاً من التفرع بناءً على النوع المحدد.
المشكلات الشائعة والحلول
InsertStructuredDocumentTag يرمي NotImplementedException المطلوب SdtType – على سبيل المثال Citation, Equation, أو BuildingBlockGallery – ليس أحد الأنواع القابلة للإدراج السبعة. استخدم PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture, أو Date بدلاً من ذلك.
InsertStructuredDocumentTag يرمي InvalidOperationException RepeatingSection or RepeatingSectionItem تم طلبه عند مؤشر النص. هذان النوعان يلتفان حول فقرات أو صفوف جدول كاملة بدلاً من إدراجهما عند موضع المؤشر.
إزالة عنصر التحكم بالمحتوى تحذف أيضًا النص الموجود بداخله Remove() يحذف التحكم ومحتوياته معًا. Call RemoveSelfOnly() بدلاً من ذلك للحفاظ على المحتويات في المستند وإسقاط الغلاف فقط.
صندوق الاختيار لا يُظهر الرمز المتوقع لم يتم أبداً تعيين رموز التحديد وإلغاء التحديد المخصصة. استدعِ SetCheckedSymbol() and SetUncheckedSymbol() على التحكم.
قائمة منسدلة أو صندوق اختيار لا يظهر فيها أي خيارات ListItems لم يتم ملؤها أبداً. أضف SdtListItem عناصر إلى مجموعة التحكم ListItems قبل توقع ظهور الخيارات، ثم عيّن SelectedValue لاختيار العنصر النشط.
الأسئلة المتكررة
ما هي أنواع عناصر تحكم المحتوى التي يمكنني إدراجها مباشرة باستخدام DocumentBuilder؟
PlainText، RichText، Checkbox، DropDownList، ComboBox، Picture، وDate. القيم الأخرى لـ SdtType غير مدعومة من قبل InsertStructuredDocumentTag().
كيف يمكنني العثور على جميع عناصر التحكم بالمحتوى التي تحمل علامة محددة؟
اقرأ Range.StructuredDocumentTags واستدعِ GetByTag()، أو GetByTitle() / GetById() إذا كنت تتطابق مع تلك المعرفات بدلاً من ذلك.
كيف يمكنني إزالة عنصر التحكم بالمحتوى مع الحفاظ على محتواه في المستند؟
استدعِ StructuredDocumentTag.RemoveSelfOnly() بدلاً من Remove().
كيف يمكنني ربط عنصر التحكم بالمحتوى ببيانات XML مخصصة؟
استدعِ XmlMapping.SetMapping() على XmlMapping الخاص بالتحكم، مع توجيهه إلى جزء XML مخصص موجود وتعبير XPath داخله.
كيف يختلف عنصر التحكم بالمحتوى الذي يمتد عبر أقسام متعددة عن العنصر العادي؟
يُمثَّل كزوج StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd بدلاً من عقدة StructuredDocumentTag واحدة؛ كلا الشكلين يطبقان IStructuredDocumentTag، لذا IsMultiSection يخبرك أي شكل تستخدمه.
