Trabalhando com Marcação XML Personalizada

Este guia mostra como ler e gerenciar os dados XML personalizados que um documento Word pode conter juntamente com seu conteúdo visível — dados usados para vincular controles de conteúdo, armazenar metadados específicos de aplicativos ou incorporar partes arbitrárias do pacote. Document.CustomXmlParts expõe dados XML personalizados em nível de documento, e Document.PackageCustomParts expõe partes personalizadas em nível de pacote que não são especificamente XML personalizados.

Partes XML Personalizadas

CustomXmlPart representa uma ilha de dados XML personalizada anexada ao documento — o mesmo mecanismo que o Word usa para suportar controles de conteúdo mapeados a XML. Cada parte possui um Id, um array de bytes Data contendo o XML bruto, um DataChecksum e uma propriedade Schemas (um CustomXmlSchemaCollection) que lista os esquemas XML associados a ela. Document.CustomXmlParts devolve um CustomXmlPartCollection: Add(part) anexa um CustomXmlPart existente, Add(id, xml) cria um diretamente a partir de um id e de uma string XML, GetById(id) recupera uma parte específica, e RemoveAt(index)/Clear() removem partes. Tanto CustomXmlPart quanto CustomXmlPartCollection expõem Clone() para duplicar dados XML personalizados, por exemplo ao copiar conteúdo entre documentos.

Esquemas XML Personalizados

CustomXmlSchemaCollection, acessado através de CustomXmlPart.Schemas, lista os URIs de esquema associados a uma parte XML personalizada. Ele suporta Add(value), Remove(name), RemoveAt(index), IndexOf(value), Clear() e Clone(), juntamente com uma propriedade Count — os URIs de esquema são rastreados como strings simples em vez de objetos de esquema analisados.

Propriedades XML Personalizadas

Separadamente de CustomXmlPart, CustomXmlProperty representa uma única propriedade XML de nome/valor, construída com CustomXmlProperty(name, uri, value) e expondo Name, Uri e Value. CustomXmlPropertyCollection gerencia um conjunto desses: Add(property) adiciona um, o indexador (por exemplo properties["MyProp"]) procura um por nome e Contains(name) verifica se está presente, IndexOfKey(name) devolve sua posição, e Remove(name)/RemoveAt(index)/Clear() removem entradas. SmartTag.Properties devolve um CustomXmlPropertyCollection, que é como os dados estruturados de uma smart tag legada são representados (veja abaixo).

Partes Personalizadas ao Nível do Pacote

Document.PackageCustomParts devolve um CustomPartCollection de objetos CustomPart — partes arbitrárias armazenadas no pacote OOXML que não são dados XML personalizados, como partes adicionadas por outras aplicações que modificaram o arquivo. Cada CustomPart possui um Name, ContentType, RelationshipType, um array de bytes Data e um sinalizador IsExternal que indica se a parte é uma referência externa em vez de conteúdo incorporado. A coleção suporta Add(part), RemoveAt(index), Clear() e Clone(), juntamente com Count.

Smart Tags Legadas

SmartTag é um tipo de nó (NodeType.SmartTag) que representa uma smart tag legada do Word envolvida ao texto reconhecido. Um SmartTag é construído com SmartTag(doc) e expõe Element (o nome do elemento reconhecedor) e Uri (o namespace do reconhecedor), juntamente com Properties — um CustomXmlPropertyCollection que contém os dados estruturados que o reconhecedor anexou ao texto marcado. Como SmartTag é um nó, ele também participa da árvore do documento como outros nós, suportando Accept(visitor), AcceptStart(visitor) e AcceptEnd(visitor) para travessia baseada em DocumentVisitor.

MarkupLevel

MarkupLevel é um enum — Unknown, Inline, Block, Row, Cell — que descreve o nível estrutural na árvore do documento onde um elemento de marcação, como uma tag de documento estruturado, pode ocorrer.

Dicas e Melhores Práticas

Use CustomXmlPartCollection.GetById(id) em vez de iterar a coleção manualmente quando você conhece o id da parte que precisa.
Leia CustomXmlPart.DataChecksum para detectar se os dados subjacentes de XML foram alterados sem fazer uma comparação completa de bytes.
Distinga Document.CustomXmlParts (dados personalizados de XML, frequentemente vinculados a controles de conteúdo) de Document.PackageCustomParts (partes de pacote arbitrárias não-XML) — elas servem a propósitos diferentes e são armazenadas separadamente.
Ao trabalhar com documentos legados que utilizam tags inteligentes, verifique SmartTag.Element e Uri juntos para identificar qual reconhecedor criou a tag antes de confiar em seu Properties.
Clone partes personalizadas de XML com CustomXmlPart.Clone() (ou com Clone() da coleção) ao copiar dados entre documentos, em vez de reler e re-adicionar o raw XML.

Problemas comuns

Problema	Causa	Correção
`CustomXmlPartCollection.GetById(id)` não retorna nada utilizável	O id não corresponde a nenhuma parte atualmente em `Document.CustomXmlParts`	Enumere a coleção para confirmar o id, ou adicione a parte primeiro com `Add(id, xml)`
Os dados personalizados de XML parecem não estar relacionados aos controles de conteúdo visíveis	Os controles de conteúdo vinculam-se ao XML personalizado por meio de sua própria configuração de ligação de dados, não automaticamente a cada `CustomXmlPart`	Confirme a qual parte um determinado controle de conteúdo está vinculado, em vez de assumir uma relação 1:1 com `Document.CustomXmlParts`
Uma parte de pacote adicionada por outra aplicação não é encontrada em `CustomXmlParts`	Partes de pacote não-XML são expostas através de `Document.PackageCustomParts`, não `CustomXmlParts`	Verifique `PackageCustomParts` (um `CustomPartCollection`) em vez disso
`SmartTag.Properties` está vazio	Nem todo reconhecedor de smart tag anexa propriedades estruturadas	Verifique `SmartTag.Element`/`Uri` para confirmar qual reconhecedor criou a tag antes de esperar propriedades específicas

FAQ

Qual é a diferença entre `CustomXmlPart` e `CustomXmlProperty`?

CustomXmlPart é uma ilha de dados XML completa (com um payload de array de bytes e esquemas associados), acessada através de Document.CustomXmlParts. CustomXmlProperty é um par nome/valor único, tipicamente acessado através de SmartTag.Properties ao invés de diretamente do documento.

Como adiciono dados XML personalizados a um documento?

Chame Document.CustomXmlParts.Add(id, xml) com uma string de id e o conteúdo XML, ou construa um CustomXmlPart separadamente e passe-o para Add(part).

O que são partes personalizadas de pacote e como elas diferem das partes personalizadas XML?

Document.PackageCustomParts (um CustomPartCollection de objetos CustomPart) contém partes arbitrárias do pacote OOXML que não são XML personalizadas — cada uma com um ContentType, RelationshipType e Data bruto. Document.CustomXmlParts é especificamente para ilhas de dados XML personalizadas.

O que é um `SmartTag`?

SmartTag é um recurso legado do Word que representa texto reconhecido e envolto por um reconhecedor de smart-tag. É um nó do documento (NodeType.SmartTag) com um Element e Uri que identificam o reconhecedor, e uma coleção Properties de valores CustomXmlProperty que o reconhecedor anexou.

Como copio dados XML personalizados entre documentos?

Use CustomXmlPart.Clone() na parte de origem, depois adicione o clone ao Document.CustomXmlParts do documento de destino com Add(part).

API Reference Resumo

Classe/Método	Descrição
`CustomXmlPart`	Uma única ilha de dados XML personalizada anexada a um documento
`Document.CustomXmlParts`	O `CustomXmlPartCollection` de todas as partes XML personalizadas em um documento
`CustomXmlPartCollection.Add(id, xml)` / `GetById(id)`	Adicionar ou recuperar uma parte XML personalizada por id
`CustomXmlSchemaCollection`	URIs de esquema associados a um `CustomXmlPart`
`CustomXmlProperty`	Uma única propriedade XML de nome/valor
`CustomXmlPropertyCollection`	Uma coleção de valores `CustomXmlProperty`, por exemplo em `SmartTag.Properties`
`Document.PackageCustomParts`	O `CustomPartCollection` de partes arbitrárias de pacote OOXML não-XML
`CustomPart`	Uma parte personalizada ao nível do pacote com `Name`, `ContentType` e `Data` bruto
`SmartTag`	Tipo de nó legado que envolve texto reconhecido por um reconhecedor de smart-tag
`MarkupLevel`	Enum que descreve onde um elemento de marcação pode ocorrer na árvore do documento

Ver também

Aspose.Words for .NET — Enterprise Documentation

Trabalhando com Marcação XML Personalizada