Trabajando con Marcado XML Personalizado

Trabajando con Marcado Personalizado XML

Esta guía muestra cómo leer y gestionar los datos personalizados XML que un documento de Word puede llevar junto a su contenido visible — datos utilizados para vincular controles de contenido, almacenar metadatos específicos de la aplicación o incrustar partes arbitrarias del paquete. Document.CustomXmlParts expone los datos personalizados XML a nivel de documento, y Document.PackageCustomParts expone partes personalizadas a nivel de paquete que no son XML personalizados específicamente.

Partes Personalizadas XML

CustomXmlPart representa una isla de datos personalizada XML adjunta al documento — el mismo mecanismo que Word usa para respaldar los controles de contenido mapeados XML. Cada parte tiene un Id, una matriz de bytes Data que contiene el XML sin procesar, un DataChecksum, y una propiedad Schemas (un CustomXmlSchemaCollection) que enumera los esquemas XML asociados. Document.CustomXmlParts devuelve un CustomXmlPartCollection: Add(part) adjunta un CustomXmlPart existente, Add(id, xml) crea uno directamente a partir de un id y una cadena XML, GetById(id) recupera una parte específica, y RemoveAt(index)/Clear() eliminan partes. Tanto CustomXmlPart como CustomXmlPartCollection exponen Clone() para duplicar datos personalizados XML, por ejemplo al copiar contenido entre documentos.

Esquemas Personalizados XML

CustomXmlSchemaCollection, accesible a través de CustomXmlPart.Schemas, enumera los URI de esquema asociados a una parte personalizada XML. Soporta Add(value), Remove(name), RemoveAt(index), IndexOf(value), Clear() y Clone(), junto con una propiedad Count — los URI de esquema se rastrean como cadenas simples en lugar de objetos de esquema analizados.

Propiedades Personalizadas XML

Separadamente de CustomXmlPart, CustomXmlProperty representa una única propiedad XML de nombre/valor, construida con CustomXmlProperty(name, uri, value) y exponiendo Name, Uri y Value. CustomXmlPropertyCollection gestiona un conjunto de estas: Add(property) agrega una, el indexador (p. ej. properties["MyProp"]) busca una por nombre y Contains(name) comprueba si está presente, IndexOfKey(name) devuelve su posición, y Remove(name)/RemoveAt(index)/Clear() eliminan entradas. SmartTag.Properties devuelve un CustomXmlPropertyCollection, que es cómo se representa los datos estructurados de una etiqueta inteligente heredada (ver abajo).

Partes Personalizadas a Nivel de Paquete

Document.PackageCustomParts devuelve un CustomPartCollection de objetos CustomPart — partes arbitrarias almacenadas en el paquete OOXML que no son datos XML personalizados, como partes añadidas por otras aplicaciones que modificaron el archivo. Cada CustomPart tiene un Name, ContentType, RelationshipType, un Data array de bytes y una bandera IsExternal que indica si la parte es una referencia externa en lugar de contenido incrustado. La colección admite Add(part), RemoveAt(index), Clear() y Clone(), junto con Count.

Etiquetas Inteligentes Legadas

SmartTag es un tipo de nodo (NodeType.SmartTag) que representa una etiqueta inteligente heredada de Word envuelta alrededor del texto reconocido. Un SmartTag se construye con SmartTag(doc), y expone Element (el nombre del elemento del reconocedor) y Uri (el espacio de nombres del reconocedor), junto con Properties — un CustomXmlPropertyCollection que contiene los datos estructurados que el reconocedor adjuntó al texto etiquetado. Debido a que SmartTag es un nodo, también participa en el árbol del documento como otros nodos, soportando Accept(visitor), AcceptStart(visitor) y AcceptEnd(visitor) para el recorrido basado en DocumentVisitor.

MarkupLevel

MarkupLevel es una enumeración — Unknown, Inline, Block, Row, Cell — que describe el nivel estructural en el árbol del documento donde puede aparecer un elemento de marcado, como una etiqueta de documento estructurado.

Consejos y Buenas Prácticas

• Utilice CustomXmlPartCollection.GetById(id) en lugar de iterar la colección manualmente cuando conozca el id de la parte que necesita.
• Lea CustomXmlPart.DataChecksum para detectar si los datos subyacentes de XML han cambiado sin realizar una comparación completa de bytes.
• Distinga Document.CustomXmlParts (datos XML personalizados, a menudo vinculados a controles de contenido) de Document.PackageCustomParts (partes de paquete arbitrarias que no son XML) — cumplen propósitos diferentes y se almacenan por separado.
• Al trabajar con documentos heredados que usan etiquetas inteligentes, verifique SmartTag.Element y Uri juntos para identificar qué reconocedor creó la etiqueta antes de confiar en su Properties.
• Clone partes XML personalizadas con CustomXmlPart.Clone() (o con el Clone() de la colección) al copiar datos entre documentos en lugar de volver a leer y volver a añadir el XML sin procesar.

Problemas comunes

FAQ

¿Cuál es la diferencia entre CustomXmlPart y CustomXmlProperty?

CustomXmlPart es una isla de datos completa de XML (con una carga útil de matriz de bytes y esquemas asociados), a la que se accede a través de Document.CustomXmlParts. CustomXmlProperty es un par nombre/valor único, típicamente accedido a través de SmartTag.Properties en lugar de directamente desde el documento.

¿Cómo añado datos personalizados de XML a un documento?

Llame a Document.CustomXmlParts.Add(id, xml) con una cadena de id y el contenido de XML, o construya un CustomXmlPart por separado y páselo a Add(part).

¿Qué son las partes personalizadas del paquete y cómo difieren de las partes personalizadas de XML?

Document.PackageCustomParts (un CustomPartCollection de objetos CustomPart) contiene partes arbitrarias del paquete OOXML que no son XML personalizadas — cada una con un ContentType, RelationshipType y raw Data. Document.CustomXmlParts es específicamente para islas de datos personalizadas de XML.

¿Qué es un SmartTag?

SmartTag es una característica heredada de Word que representa texto reconocido y envuelto por un reconocedor de etiquetas inteligentes. Es un nodo del documento (NodeType.SmartTag) con un Element y Uri que identifican al reconocedor, y una Properties de valores CustomXmlProperty que el reconocedor adjuntó.

¿Cómo copio datos personalizados de XML entre documentos?

Utilice CustomXmlPart.Clone() en la parte de origen, luego añada el clon al Document.CustomXmlParts del documento de destino con Add(part).

Resumen de API Reference

Ver también

• Aspose.Words for .NET — Enterprise Documentation