Travailler avec le XML Markup personnalisé

Travailler avec le balisage personnalisé XML

Ce guide montre comment lire et gérer les données personnalisées XML qu’un document Word peut contenir en plus de son contenu visible — des données utilisées pour lier des contrôles de contenu, stocker des métadonnées spécifiques à l’application ou incorporer des parties de paquet arbitraires. Document.CustomXmlParts expose les données personnalisées XML au niveau du document, et Document.PackageCustomParts expose les parties personnalisées au niveau du paquet qui ne sont pas spécifiquement des XML personnalisés.

Parties personnalisées XML

CustomXmlPart représente une île de données personnalisées XML attachée au document — le même mécanisme que Word utilise pour prendre en charge les contrôles de contenu mappés XML. Chaque partie possède un Id, un tableau d’octets Data contenant le XML brut, un DataChecksum, et une propriété Schemas (un CustomXmlSchemaCollection) répertoriant les schémas XML qui lui sont associés. Document.CustomXmlParts renvoie un CustomXmlPartCollection : Add(part) attache un CustomXmlPart existant, Add(id, xml) crée un directement à partir d’un identifiant et d’une chaîne XML, GetById(id) récupère une partie spécifique, et RemoveAt(index)/Clear() suppriment des parties. Les CustomXmlPart et CustomXmlPartCollection exposent Clone() pour dupliquer les données personnalisées XML, par exemple lors de la copie de contenu entre documents.

Schémas personnalisés XML

CustomXmlSchemaCollection, accessible via CustomXmlPart.Schemas, répertorie les URI de schéma associés à une partie personnalisée XML. Il prend en charge Add(value), Remove(name), RemoveAt(index), IndexOf(value), Clear() et Clone(), ainsi qu’une propriété Count — les URI de schéma sont suivis comme des chaînes simples plutôt que comme des objets de schéma analysés.

Propriétés personnalisées XML

Séparément de CustomXmlPart, CustomXmlProperty représente une propriété XML nom/valeur unique, construite avec CustomXmlProperty(name, uri, value) et exposant Name, Uri et Value. CustomXmlPropertyCollection gère un ensemble de celles-ci: Add(property) en ajoute une, l’indexeur (par ex. properties["MyProp"]) en recherche une par son nom et Contains(name) vérifie si elle est présente, IndexOfKey(name) renvoie sa position, et Remove(name)/RemoveAt(index)/Clear() suppriment des entrées. SmartTag.Properties renvoie un CustomXmlPropertyCollection, qui est la façon dont les données structurées d’un smart tag hérité sont représentées (voir ci-dessous).

Éléments personnalisés au niveau du package

Document.PackageCustomParts renvoie un CustomPartCollection d’objets CustomPart — des parties arbitraires stockées dans le package OOXML qui ne sont pas des données XML personnalisées, telles que des parties ajoutées par d’autres applications ayant manipulé le fichier. Chaque CustomPart possède un Name, un ContentType, un RelationshipType, un tableau d’octets Data, et un drapeau IsExternal indiquant si la partie est une référence externe plutôt qu’un contenu intégré. La collection prend en charge Add(part), RemoveAt(index), Clear() et Clone(), ainsi que Count.

Smart tags hérités

SmartTag est un type de nœud (NodeType.SmartTag) représentant un smart tag Word hérité enveloppant du texte reconnu. Un SmartTag est construit avec SmartTag(doc), et expose Element (le nom de l’élément du reconnaisseur) et Uri (l’espace de noms du reconnaisseur), ainsi que Properties — un CustomXmlPropertyCollection contenant les données structurées que le reconnaisseur a attachées au texte balisé. Parce que SmartTag est un nœud, il participe également à l’arbre du document comme les autres nœuds, prenant en charge Accept(visitor), AcceptStart(visitor) et AcceptEnd(visitor) pour la traversée basée sur DocumentVisitor.

MarkupLevel

MarkupLevel est une énumération — Unknown, Inline, Block, Row, Cell — décrivant le niveau structurel dans l’arbre du document où un élément de balisage tel qu’une balise de document structuré peut se produire.

Conseils et bonnes pratiques

• Utilisez CustomXmlPartCollection.GetById(id) plutôt que d’itérer manuellement la collection lorsque vous connaissez l’ID de la partie dont vous avez besoin.
• Lisez CustomXmlPart.DataChecksum pour détecter si les données XML sous-jacentes ont changé sans effectuer une comparaison complète d’octets.
• Distinguez Document.CustomXmlParts (données XML personnalisées, souvent liées aux contrôles de contenu) de Document.PackageCustomParts (parties de package arbitraires non-XML) — elles remplissent des fonctions différentes et sont stockées séparément.
• Lorsque vous travaillez avec des documents hérités qui utilisent des balises intelligentes, vérifiez SmartTag.Element et Uri ensemble pour identifier quel reconnaisseur a créé la balise avant de vous fier à son Properties.
• Clonez les parties XML personnalisées avec CustomXmlPart.Clone() (ou le Clone() de la collection) lors de la copie de données entre documents plutôt que de relire et de réajouter le XML brut.

Problèmes courants

FAQ

Quelle est la différence entre CustomXmlPart et CustomXmlProperty?

CustomXmlPart est une île de données XML complète (avec une charge utile sous forme de tableau d’octets et des schémas associés), accessible via Document.CustomXmlParts. CustomXmlProperty est une paire nom/valeur unique, généralement atteinte via SmartTag.Properties plutôt que directement depuis le document.

Comment ajouter des données XML personnalisées à un document?

Appelez Document.CustomXmlParts.Add(id, xml) avec une chaîne d’identifiant et le contenu XML, ou construisez un CustomXmlPart séparément et transmettez-le à Add(part).

Quelles sont les parties personnalisées du package, et comment diffèrent-elles des parties personnalisées XML?

Document.PackageCustomParts (un CustomPartCollection de CustomPart objets) contient des parties de package OOXML arbitraires qui ne sont pas des XML personnalisées — chacune avec un ContentType, un RelationshipType et un Data brut. Document.CustomXmlParts est spécifiquement destiné aux îles de données XML personnalisées.

Qu’est-ce qu’un SmartTag?

SmartTag est une fonctionnalité héritée de Word représentant du texte reconnu et enveloppé par un reconnaisseur de smart-tag. C’est un nœud de document (NodeType.SmartTag) avec un Element et un Uri identifiant le reconnaisseur, ainsi qu’une collection Properties de valeurs CustomXmlProperty attachées par le reconnaisseur.

Comment copier des données XML personnalisées entre des documents?

Utilisez CustomXmlPart.Clone() sur la partie source, puis ajoutez le clone au Document.CustomXmlParts du document cible avec Add(part).

API Reference Résumé

Voir aussi

• Aspose.Words for .NET — Enterprise Documentation