Робота з власною розміткою XML

Робота з користувацькою XML розміткою

У цьому посібнику показано, як читати та керувати користувацькими даними XML, які документ Word може нести поряд зі своїм видимим вмістом — даними, які використовуються для прив’язки елементів управління вмістом, зберігання метаданих, специфічних для застосунку, або вбудовування довільних частин пакету. Document.CustomXmlParts відкриває дані користувацького XML на рівні документа, а Document.PackageCustomParts відкриває користувацькі частини на рівні пакету, які не є спеціальними XML.

Користувацькі частини XML

CustomXmlPart представляє один користувацький острів даних XML, прикріплений до документа — той самий механізм, який Word використовує для підтримки елементів управління вмістом, прив’язаних до XML. Кожна частина має Id, масив байтів Data, що містить необроблені XML, DataChecksum та властивість Schemas ( CustomXmlSchemaCollection), у якій перераховані схеми XML, пов’язані з нею. Document.CustomXmlParts повертає CustomXmlPartCollection: Add(part) приєднує існуючий CustomXmlPart, Add(id, xml) створює його безпосередньо з ідентифікатора та рядка XML, GetById(id) отримує конкретну частину, а RemoveAt(index)/Clear() видаляють частини. Як CustomXmlPart, так і CustomXmlPartCollection відкривають Clone() для дублювання користувацьких даних XML, наприклад при копіюванні вмісту між документами.

Користувацькі схеми XML

CustomXmlSchemaCollection, доступний через CustomXmlPart.Schemas, перераховує URI схем, пов’язані з користувацькою частиною XML. Він підтримує Add(value), Remove(name), RemoveAt(index), IndexOf(value), Clear() та Clone(), разом з властивістю Count — URI схем відстежуються як прості рядки, а не як розпарсені об’єкти схеми.

Користувацькі властивості XML

Окремо від CustomXmlPart, CustomXmlProperty представляє одиничну властивість XML у вигляді пари ім’я/значення, створену за допомогою CustomXmlProperty(name, uri, value) і що надає Name, Uri та Value. CustomXmlPropertyCollection керує набором таких елементів: Add(property) додає один, індексатор (наприклад, properties["MyProp"]) шукає його за ім’ям і Contains(name) перевіряє, чи він присутній, IndexOfKey(name) повертає його позицію, а Remove(name)/RemoveAt(index)/Clear() видаляють записи. SmartTag.Properties повертає CustomXmlPropertyCollection, що є способом представлення структурованих даних застарілого смарт-тегу (див. нижче).

Користувацькі частини рівня пакету

Document.PackageCustomParts повертає CustomPartCollection з об’єктів CustomPart — довільних частин, що зберігаються у пакеті OOXML і не є кастомними даними XML, наприклад частини, додані іншими застосунками, які модифікували файл. Кожен CustomPart має Name, ContentType, RelationshipType, масив байтів Data та прапорець IsExternal, що вказує, чи є частина зовнішнім посиланням, а не вбудованим вмістом. Колекція підтримує Add(part), RemoveAt(index), Clear() і Clone(), разом з Count.

Застарілі смарт-теги

SmartTag — це тип вузла (NodeType.SmartTag), що представляє застарілий смарт-тег Word, обгорнутий навколо розпізнаного тексту. SmartTag створюється за допомогою SmartTag(doc) і надає Element (назву елемента розпізнавальника) та Uri (простір імен розпізнавальника), разом з Properties — CustomXmlPropertyCollection, що містить структуровані дані, які розпізнавальник прикріпив до позначеного тексту. Оскільки SmartTag є вузлом, він також бере участь у дереві документа як інші вузли, підтримуючи Accept(visitor), AcceptStart(visitor) та AcceptEnd(visitor) для обходу на основі DocumentVisitor.

MarkupLevel

MarkupLevel — це перелік (enum) — Unknown, Inline, Block, Row, Cell — який описує структурний рівень у дереві документа, на якому може розташовуватись елемент розмітки, такий як структурний тег документа.

Поради та кращі практики

• Використовуйте CustomXmlPartCollection.GetById(id) замість ручного перебору колекції, коли ви знаєте ідентифікатор потрібної частини.
• Прочитайте CustomXmlPart.DataChecksum, щоб виявити, чи змінилися базові дані XML, без повного порівняння байтів.
• Розрізняйте Document.CustomXmlParts (користувацькі дані XML, часто прив’язані до елементів управління вмістом) від Document.PackageCustomParts (довільні частини пакету, які не є XML) — вони виконують різні функції та зберігаються окремо.
• Працюючи зі старими документами, які використовують смарт-теґи, перевіряйте SmartTag.Element і Uri разом, щоб визначити, який розпізнавач створив теґ, перед тим як покладатися на його Properties.
• Клонувати користувацькі частини XML за допомогою CustomXmlPart.Clone() (або Clone() колекції) під час копіювання даних між документами, а не перечитувати та повторно додавати необроблені XML.

Поширені проблеми

FAQ

У чому різниця між CustomXmlPart і CustomXmlProperty?

CustomXmlPart — це весь XML острів даних (з корисним навантаженням у вигляді масиву байтів і пов’язаними схемами), доступний через Document.CustomXmlParts. CustomXmlProperty — це окрема пара ім’я/значення, зазвичай доступна через SmartTag.Properties, а не безпосередньо з документа.

Як додати користувацькі дані XML до документа?

Викличте Document.CustomXmlParts.Add(id, xml) з рядком ідентифікатора та вмістом XML, або окремо створіть CustomXmlPart і передайте її до Add(part).

Що таке користувацькі частини пакету і чим вони відрізняються від користувацьких частин XML?

Document.PackageCustomParts (це CustomPartCollection з CustomPart об’єктів) містить довільні частини пакету OOXML, які не є користувацькими XML — кожна має ContentType, RelationshipType та необроблений Data. Document.CustomXmlParts призначений спеціально для користувацьких островів даних XML.

Що таке SmartTag?

SmartTag — це застаріла функція Word, що представляє текст, розпізнаний і обгорнутий розпізнавачем смарт-тегів. Це вузол документа (NodeType.SmartTag) з Element і Uri, що ідентифікують розпізнавач, і колекцією Properties значень CustomXmlProperty, які розпізнавач додав.

Як скопіювати користувацькі дані XML між документами?

Використайте CustomXmlPart.Clone() у вихідній частині, потім додайте клон до Document.CustomXmlParts цільового документа за допомогою Add(part).

Підсумок API Reference

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

• Aspose.Words for .NET — Enterprise Documentation