Работа с пользовательской разметкой 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 — это перечисление — 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), передав строку id и содержимое XML, либо отдельно создайте CustomXmlPart и передайте его в Add(part).

Что такое пользовательские части пакета и чем они отличаются от пользовательских частей XML?

Document.PackageCustomParts (a CustomPartCollection of CustomPart objects) хранит произвольные части пакета 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