نحوه کار با برچسب‌های سند ساختاریافته در .NET

گام ۱: نصب بسته

Aspose.Words FOSS for .NET هنوز بسته NuGet را منتشر نکرده است – به‌جای آن کتابخانه را از منبع بسازید. https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git را کلون کنید، سپس Aspose.Words.sln را در پیکربندی Release با SDK .NET بسازید و اسمبلی Aspose.Words حاصل را در پروژه خود ارجاع دهید. این کتابخانه هدف .NET Standard 2.0 را دارد، بنابراین بر روی .NET Framework 4.6.2+ و .NET 6/8/10 اجرا می‌شود.

گام ۲: وارد کردن کلاس‌های مورد نیاز

یک دستور using Aspose.Words; برای Document و DocumentBuilder اضافه کنید، و یک دستور using Aspose.Words.Markup; برای StructuredDocumentTag، SdtType، SdtListItem، SdtListItemCollection، XmlMapping و سایر کلاس‌های کنترل محتوا که این راهنما پوشش می‌دهد، اضافه کنید.

مرحله 3: بررسی کنید کدام انواع Content-Control را می‌توانید وارد کنید

قبل از وارد کردن، بررسی کنید که هدف 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: درج یک Content Control در مکان‌نما

با فراخوانی 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) سیستم تقویم را انتخاب می‌کند. برای یک فهرست کشویی یا جعبه ترکیبی، قبل از تنظیم SelectedValue برای انتخاب گزینه فعال، ListItems را پر کنید — یک SdtListItemCollection از SdtListItem (DisplayText، Value) —. برای یک کنترل متن ساده، Multiline یک ویژگی bool بر روی StructuredDocumentTag است که می‌تواند برای پیکربندی کنترل تنظیم شود.

مرحله 6: کنترل ظاهر و قفل‌گذاری

با تنظیم Appearance (SdtAppearance) نحوهٔ مرزبندی بصری کنترل در Word را کنترل کنید و با تنظیم Color رنگ برجسته‌سازی آن را تعیین کنید. ContentsFont و EndCharacterFont فونتی را که بر محتوای کنترل و کاراکتر انتهایی آن اعمال می‌شود، کنترل می‌کنند. LockContentControl و LockContents سوئیچ‌های مستقل هستند — LockContentControl را تنظیم کنید تا حذف خود کنترل مسدود شود، و LockContents را تنظیم کنید تا ویرایش محتوای داخل آن مسدود شود، بدون اینکه دیگری تحت تأثیر قرار گیرد.

مرحله ۷: یافتن و حذف کنترل‌های محتوا

دریافت Range.StructuredDocumentTags – یک StructuredDocumentTagCollection محدوده‌شده به آن بازه – و فراخوانی GetById()، GetByTag() یا GetByTitle() برای پیدا کردن یک کنترل خاص، یا Remove() / RemoveAt() روی مجموعه برای حذف یکی به‌صورت ارجاع یا اندیس. برای یک کنترل منفرد، فراخوانی Remove() برای حذف کنترل همراه با محتویات آن، RemoveSelfOnly() برای حذف تنها بسته‌بندی در حالی که محتویات در سند باقی می‌ماند، یا Clear() برای خالی کردن محتویات در حالی که خود کنترل در جای خود می‌ماند.

مرحله ۸: اتصال یک کنترل به داده‌های سفارشی XML

دریافت StructuredDocumentTag.XmlMapping – یک نمونه XmlMapping – و فراخوانی SetMapping(customXmlPart, xPath, prefixMapping) برای اتصال کنترل به یک بخش سفارشی XML موجود که پیشاپیش در ذخیره‌ساز داده‌های سفارشی XML سند حضور دارد، با استفاده از یک عبارت XPath برای انتخاب عنصر متصل. XmlMapping.IsMapped گزارش می‌دهد که آیا اتصال در حال حاضر فعال است، CustomXmlPart و StoreItemId بخش داده متصل را شناسایی می‌کنند، و Delete() نگاشت را حذف می‌کند.

مرحله ۹: مدیریت کنترل‌های محتوا که چندین بخش را پوشش می‌دهند

یک کنترل محتوا که بیش از یک بخش سند را پوشش می‌دهد – گزارش‌شده توسط IsMultiSection – نه با یک گره StructuredDocumentTag منفرد بلکه با یک جفت StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd که از طریق StructuredDocumentTagRangeStart.RangeEnd به هم متصل هستند، نمایش داده می‌شود. هنگام برنامه‌نویسی، برای کدی که نیاز به مدیریت یکنواخت هر دو شکل تک‌گره و بازه‌ای دارد، به جای انشعاب بر پایه نوع خاص، از رابط مشترک IStructuredDocumentTag (Tag، Title، Placeholder، PlaceholderName، Appearance، IsShowingPlaceholderText، RemoveSelfOnly()) استفاده کنید.