Как работать со Structured Document Tags в .NET

Шаг 1: Установить пакет

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.

Шаг 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) выбирает календарную систему. Для раскрывающегося списка или комбобокса заполните 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()), когда коду необходимо единообразно обрабатывать как одиночные узлы, так и диапазонные формы, вместо ветвления по конкретному типу.