Как работать с пользовательской разметкой 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) возвращает ничего пригодного. id не соответствует ни одной части, находящейся в Document.CustomXmlParts. Перечислите коллекцию, чтобы подтвердить наличие id, или сначала добавьте часть с помощью 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 (это CustomXmlPartCollection) или Document.PackageCustomParts (это CustomPartCollection) соответственно.
