Як працювати зі структурованими тегами документів у .NET
У цьому посібнику показано, як вставляти, налаштовувати, знаходити, видаляти та прив’язувати дані до структурованих тегів документа (елементи управління вмістом) у Aspose.Words FOSS для .NET, використовуючи StructuredDocumentTag клас у Aspose.Words.Markup просторі імен. Він охоплює, які типи елементів управління вмістом DocumentBuilder можуть вставляти, встановлюючи типо-специфічний вміст, такий як стан прапорця або варіанти випадаючого списку, знаходячи елементи за тегом або назвою, видаляючи елемент разом із його вмістом або без нього, та прив’язуючи елемент до користувацьких даних XML.
Покроковий посібник
Крок 1: Встановити пакет
Aspose.Words FOSS for .NET ще не публікує пакет NuGet — замість цього зберіть бібліотеку з вихідного коду. Клонуйте https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git, потім зберіть Aspose.Words.sln у конфігурації Release з .NET SDK і підключіть отриману збірку 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 – a StructuredDocumentTagCollection scoped to that range – і викличте GetById(), GetByTag() або GetByTitle(), щоб знайти конкретний контроль, або Remove() / RemoveAt() на колекції, щоб видалити його за посиланням або індексом. На окремому контролі викличте Remove(), щоб видалити контроль разом із його вмістом, RemoveSelfOnly(), щоб видалити лише обгортку, залишивши вміст у документі, або Clear(), щоб очистити його вміст, залишивши сам контроль на місці.
Крок 8: Прив’язати контроль до користувацьких XML даних
Прочитайте StructuredDocumentTag.XmlMapping – an XmlMapping instance – і викличте SetMapping(customXmlPart, xPath, prefixMapping), щоб прив’язати контроль до існуючої користувацької частини XML, вже присутньої у сховищі користувацьких XML даних документа, використовуючи вираз XPath для вибору прив’язаного елементу. XmlMapping.IsMapped повідомляє, чи прив’язка зараз активна, CustomXmlPart і StoreItemId ідентифікують прив’язану частину даних, а Delete() видаляє відображення.
Крок 9: Обробка елементів управління вмістом, які охоплюють кілька розділів
Елемент управління вмістом, який охоплює більше одного розділу документа – reported by IsMultiSection – представлений не одним StructuredDocumentTag вузлом, а парою StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd, пов’язаною через StructuredDocumentTagRangeStart.RangeEnd. Програмуйте проти спільного інтерфейсу IStructuredDocumentTag (Tag, Title, Placeholder, PlaceholderName, Appearance, IsShowingPlaceholderText, RemoveSelfOnly()), коли код потребує уніфікованої обробки як одиничних вузлів, так і діапазонних форм, а не розгалуження за конкретним типом.
Типові проблеми та їх вирішення
InsertStructuredDocumentTag викидає NotImplementedException Запитуване SdtType – наприклад Citation, Equation, або BuildingBlockGallery – не є одним із семи типів, які можна вставляти. Використовуйте PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture, або Date замість.
InsertStructuredDocumentTag викидає InvalidOperationException RepeatingSection or RepeatingSectionItem було запрошено в позиції текстового курсору. Ці два типи охоплюють цілі абзаци або рядки таблиці, а не вставляються в позиції курсору.
Видалення елемента керування вмістом також видаляє текст всередині нього Remove() видаляє елемент керування та його вміст разом. Викличте RemoveSelfOnly() замість цього, щоб залишити вміст у документі і видалити лише оболонку.
Прапорець не відображає очікуваний символ Користувацькі гліфи для позначеного та непозначеного стану ніколи не були встановлені. Викличте SetCheckedSymbol() and SetUncheckedSymbol() на елементі керування.
Випадаючий список або комбінований елемент не показує жодних варіантів ListItems ніколи не був заповнений. Додайте SdtListItem записів до елемента керування ListItems колекції перед очікуванням появи варіантів, потім встановіть SelectedValue щоб вибрати активний.
Поширені запитання
Які типи елементів управління вмістом я можу вставляти безпосередньо за допомогою DocumentBuilder?
PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture та Date. Інші значення SdtType не підтримуються InsertStructuredDocumentTag().
Як знайти всі content controls з певним тегом?
Прочитайте Range.StructuredDocumentTags і викличте GetByTag(), або GetByTitle() / GetById(), якщо замість цього порівнювати за цими ідентифікаторами.
Як видалити content control, залишивши його вміст у документі?
Викличте StructuredDocumentTag.RemoveSelfOnly() замість Remove().
Як прив’язати content control до користувацьких даних XML?
Викличте XmlMapping.SetMapping() на XmlMapping елемента керування, вказавши на існуючу користувацьку частину XML та вираз XPath у ній.
Чим відрізняється content control, який охоплює кілька розділів, від звичайного?
Він представлений парою StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd замість одного вузла StructuredDocumentTag; обидві форми реалізують IStructuredDocumentTag, тому IsMultiSection повідомляє, яку форму ви використовуєте.
