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

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

Структурный тег документа (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