Як працювати з користувацькою розміткою XML у .NET
Як працювати з користувацькою розміткою XML у .NET
Документ Word може містити користувацькі дані XML поряд зі своїм видимим вмістом — дані, що використовуються для прив’язки елементів управління вмістом, зберігання метаданих, специфічних для застосунку, або вбудовування частин, доданих іншим застосунком. Цей посібник показує, як читати ці дані, додавати нові користувацькі частини XML і перевіряти застарілі смарт-теги, які старі документи все ще можуть містити, використовуючи CustomXmlPart, CustomXmlProperty та SmartTag у Aspose.Words FOSS для .NET.
Покроковий посібник
Крок 1: Читання користувацьких даних XML з документа
Document.CustomXmlParts повертає CustomXmlPartCollection — той самий механізм, який Word використовує для підтримки елементів управління вмістом, прив’язаних до XML. Перебирайте колекцію або викличте GetById(id), якщо ви вже знаєте, яку частину потрібно отримати, щоб отримати CustomXmlPart. Кожна частина відкриває Id, Data масив байтів, що містить необроблені XML, DataChecksum для визначення, чи змінилися дані без повного порівняння байтів, та Schemas — CustomXmlSchemaCollection, що перераховує схеми XML, пов’язані з нею.
Крок 2: Додати або оновити користувацьку частину XML
Викличте CustomXmlPartCollection.Add(id, xml) з рядком ідентифікатора та вмістом XML, щоб створити частину безпосередньо, або окремо створіть CustomXmlPart і передайте його до Add(part). Щоб видалити дані, використайте RemoveAt(index) у конкретній позиції або Clear(), щоб видалити кожну частину. При копіюванні користувацьких даних XML між документами використовуйте CustomXmlPart.Clone() (або Clone() колекції) у вихідній частині замість повторного читання та повторного додавання необроблених XML, потім додайте клон до Document.CustomXmlParts цільового документа.
Крок 3: Керування схемами, пов’язаними з частиною
CustomXmlPart.Schemas досягає CustomXmlSchemaCollection, який відстежує URI схем, пов’язаних з частиною, як прості рядки, а не як розібрані об’єкти схеми. Використайте Add(value) для реєстрації URI схеми, Remove(name) або RemoveAt(index) для видалення одного, IndexOf(value) для пошуку, і Clear() для видалення всіх. Count повідомляє, скільки URI схем наразі пов’язані з частиною.
Крок 4: Робота з користувацькими частинами рівня пакету
Не кожна невидима частина в пакеті OOXML є користувацьким XML. Document.PackageCustomParts повертає CustomPartCollection CustomPart об’єктів — довільних частин, збережених у пакеті, наприклад частин, доданих іншим застосунком, який змінював файл. Кожен CustomPart має Name, ContentType, RelationshipType, масив байтів Data і прапорець IsExternal, який вказує, чи це зовнішнє посилання, а не вбудований вміст. Add(part), RemoveAt(index) та Clear() керують колекцією так само, як CustomXmlPartCollection. Перевірте PackageCustomParts — а не CustomXmlParts — коли частина, яку ваш документ має містити, не з’являється у користувацькій колекції XML.
Крок 5: Перевірка застарілих смарт-тегів і їх властивостей
SmartTag — це тип вузла (NodeType.SmartTag, створений за допомогою SmartTag(doc)), який представляє застарілий смарт-тег Word, обгорнутий навколо розпізнаного тексту. Перевірте Element і Uri разом, щоб визначити, який розпізнавач створив тег, потім прочитайте Properties — CustomXmlPropertyCollection — для структурованих даних, які розпізнавач прикріпив. Усередині CustomXmlPropertyCollection індексатор (наприклад, properties["MyProp"]) або Contains(name) шукає конкретну властивість, IndexOfKey(name) повертає її позицію, а Remove(name)/RemoveAt(index)/Clear() видаляють записи; кожен CustomXmlProperty створений за допомогою CustomXmlProperty(name, uri, value) і надає Name, Uri та Value. Оскільки SmartTag успадковується від CompositeNode, він також бере участь у дереві документа як інші вузли, підтримуючи Accept(visitor), AcceptStart(visitor) і AcceptEnd(visitor) для обходу на основі DocumentVisitor.
Типові проблеми та виправлення
CustomXmlPartCollection.GetById(id) повертає нічого придатного. Ідентифікатор не відповідає жодній частині, що наразі є в Document.CustomXmlParts. Перерахуйте колекцію, щоб підтвердити, що ідентифікатор присутній, або спочатку додайте частину за допомогою Add(id, xml).
Частина, додана іншим застосунком, не знаходиться при ітерації CustomXmlParts. Частини пакету, що не є XML, доступні через Document.PackageCustomParts, а не CustomXmlParts. Перевірте PackageCustomParts (a CustomPartCollection) замість.
SmartTag.Properties порожній, хоча тег явно присутній. Не кожен розпізнавач смарт-тегів додає структуровані властивості. Перевірте SmartTag.Element and Uri щоб підтвердити, який розпізнавач створив тег, перш ніж припускати, що певні властивості будуть присутні.
Користувацькі дані XML здається, не пов’язані з елементом управління вмістом, до якого вони мають бути прив’язані. Елементи управління вмістом прив’язуються до користувацького XML через їх власну конфігурацію прив’язки даних, а не автоматично до кожного CustomXmlPart in Document.CustomXmlParts. Підтвердіть, до якої частини даного елемента управління вмістом фактично прив’язано, а не припускаючи одне-до-одного взаємозв’язок.
Поширені запитання
Як додати користувацькі дані XML до документа?
Викличте Document.CustomXmlParts.Add(id, xml) з рядком ідентифікатора та вмістом XML, або створіть окремо CustomXmlPart і передайте його до Add(part).
У чому різниця між CustomXmlPart та CustomXmlProperty?
CustomXmlPart — це повний острів даних XML — корисне навантаження у вигляді масиву байтів плюс пов’язані схеми — до якого доступно через Document.CustomXmlParts. CustomXmlProperty — це окрема пара ім’я/значення, зазвичай доступна через SmartTag.Properties, а не безпосередньо з документа.
Як скопіювати користувацькі дані XML з одного документа в інший?
Викличте Clone() на вихідному CustomXmlPart, а потім додайте клон до Document.CustomXmlParts цільового документа за допомогою Add(part).
Що таке SmartTag і коли я можу його зустріти?
SmartTag — це застаріла функція Word, що представляє текст, розпізнаний і обгорнутий розпізнавачем смарт-тегів — вузол документа (NodeType.SmartTag) з Element та Uri, що ідентифікують розпізнавач, плюс колекція Properties значень CustomXmlProperty. Вона з’являється в документах, створених або відредагованих зі ввімкненими смарт-тегами в старіших версіях Word.
Як дізнатися, скільки користувацьких частин XML або пакетних частин має документ?
Прочитайте Count у Document.CustomXmlParts (a CustomXmlPartCollection) або Document.PackageCustomParts (a CustomPartCollection) відповідно.
