کار با برچسب‌های سند ساختاری (کنترل‌های محتوا)

کار با برچسب‌های سند ساختاری (کنترل‌های محتوا)

یک برچسب سند ساختاری (SDT)، که در Word UI به عنوان کنترل محتوا شناخته می‌شود، یک بخش از محتوای سند را با رفتار ویرایشی نوعی و محدود شده می‌پیچاند — یک چک‌باکس، یک انتخابگر تاریخ، یک فهرست کشویی، یا یک جای‌دار متن ساده یا غنی. 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” کنید – محتویات آن را در سند نگه دارید اما پوشش کنترل را حذف کنید.
• قبل از این که انتظار داشته باشید یک کنترل DropDownList یا ComboBox گزینه‌ها را نشان دهد، ListItems را پر کنید و برای انتخاب فعال، SelectedValue را تنظیم کنید.
• اگر کد شما نیاز دارد هر دو کنترل محتوا عادی و چندبخشی (بازه‌ای) را به‌صورت یکسان مدیریت کند، به‌جای استفاده مستقیم از StructuredDocumentTag، در برابر IStructuredDocumentTag برنامه‌نویسی کنید.
• XmlMapping.SetMapping() به یک بخش سفارشی XML متصل می‌شود که باید از پیش در مخزن داده‌های سفارشی XML سند موجود باشد – قبل از نگاشت یک کنترل به آن، داده‌های XML را اضافه یا بارگذاری کنید.

مشکلات رایج

FAQ

کدام انواع کنترل محتوا را می‌توانم مستقیماً با DocumentBuilder وارد کنم؟

PlainText، RichText، Checkbox، DropDownList، ComboBox، Picture و Date. مقادیر دیگر SdtType توسط InsertStructuredDocumentTag() پشتیبانی نمی‌شوند.

چگونه می‌توانم تمام کنترل‌های محتوا را که دارای برچسب خاصی هستند پیدا کنم؟

از Range.StructuredDocumentTags.GetByTag() استفاده کنید، یا GetByTitle() / GetById() اگر به جای آن‌ها مطابقت می‌دهید.

چگونه یک کنترل محتوا را حذف کنم اما محتوای آن را نگه دارم؟

به جای Remove()، StructuredDocumentTag.RemoveSelfOnly() را فراخوانی کنید.

چگونه یک کنترل محتوا را به داده‌های سفارشی XML متصل کنم؟

متد XmlMapping.SetMapping() را روی کنترل فراخوانی کنید و آن را به یک بخش سفارشی XML موجود و یک عبارت XPath درون آن اشاره دهید.

تفاوت بین یک StructuredDocumentTag ساده و یک StructuredDocumentTag محدوده‌ای چیست؟

یک کنترل محتوا که بیش از یک بخش سند را پوشش می‌دهد به‌صورت یک جفت StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd نمایش داده می‌شود نه به‌عنوان یک گرهٔ منفرد؛ هر دو شکل IStructuredDocumentTag را پیاده‌سازی می‌کنند.

API Reference خلاصه

همچنین ببینید:

• Aspose.Words for .NET — Enterprise Documentation