Робота зі структурованими тегами документа (елементи управління вмістом)

Робота зі структуруваними тегами документів (елементи управління вмістом)

Структурований тег документа (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 і діапазонним?

Контроль вмісту, який охоплює більше ніж один розділ документа, представлений як пара StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd, а не як окремий вузол; обидві форми реалізують IStructuredDocumentTag.

API Reference Підсумок

Дивіться також

• Aspose.Words for .NET — Enterprise Documentation