Travailler avec les balises de document structurées (contrôles de contenu)

Travailler avec les balises de document structuré (contrôles de contenu)

Une balise de document structuré (SDT), connue dans l’interface Word sous le nom de contrôle de contenu, entoure un morceau de contenu du document avec un comportement d’édition typé et contraint – une case à cocher, un sélecteur de date, une liste déroulante ou un espace réservé de texte simple ou enrichi. Aspose.Words FOSS pour .NET modélise ceux-ci à travers le Aspose.Words.Markup espace de noms, intitulé par le StructuredDocumentTag classe. Cette page couvre l’insertion de contrôles de contenu, la configuration de chaque type, leur recherche et suppression, ainsi que leur liaison à des données XML personnalisées.

Le modèle d’objet des balises de document structuré

StructuredDocumentTag est un CompositeNode qui implémente également IMarkupNode, ITrackableNode et IStructuredDocumentTag. SdtType identifie le type de contrôle. Tag et Title contiennent les chaînes d’identification que les auteurs définissent dans Word; Placeholder (un BuildingBlock) et PlaceholderName fournissent le texte d’invite affiché lorsque le contrôle est vide, signalé via IsShowingPlaceholderText. LockContentControl empêche la suppression du contrôle, et LockContents empêche la modification de son contenu, de manière indépendante.

Insertion de contrôles de contenu

DocumentBuilder.InsertStructuredDocumentTag(SdtType) insère un nouveau contrôle à la position du curseur, mais uniquement pour sept des valeurs SdtType: PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture et Date. RepeatingSection et RepeatingSectionItem ne peuvent pas être insérés à un curseur de texte de cette manière — ils entourent plutôt des paragraphes entiers ou des lignes de tableau. Les valeurs SdtType restantes qui apparaissent dans les fichiers Word mais qui ne sont pas présentes dans l’interface Word comme types insérables — None, Bibliography, Citation, Equation, BuildingBlockGallery, DocPartObj, Group et EntityPicker — ne sont pas prises en charge par cette méthode d’insertion.

Contenu spécifique au type

L’état d’un contrôle case à cocher est StructuredDocumentTag.Checked ; SetCheckedSymbol() et SetUncheckedSymbol() définissent les glyphes affichés pour chaque état. Un contrôle de date stocke sa valeur dans FullDate, avec DateDisplayFormat et DateDisplayLocale qui contrôlent son rendu, DateStorageFormat (un SdtDateStorageFormat) qui contrôle la façon dont il est stocké lorsqu’il est lié aux données XML, et CalendarType (un SdtCalendarType) sélectionnant le système de calendrier. Une liste déroulante ou une zone combinée expose ses choix via ListItems, un SdtListItemCollection de SdtListItem (DisplayText, Value) avec un SelectedValue. La propriété Multiline d’un contrôle texte brut autorise ou interdit les sauts de ligne à l’intérieur.

Apparence et verrouillage

Appearance (SdtAppearance) contrôle la façon dont le contrôle est délimité visuellement dans Word. Color définit sa couleur de surbrillance, et ContentsFont / EndCharacterFont contrôlent la police appliquée à son contenu et à son caractère de fin. LockContentControl et LockContents sont des commutateurs indépendants — le premier empêche la suppression du contrôle lui-même, le second empêche la modification de ce qu’il contient.

Recherche et suppression des contrôles de contenu

Range.StructuredDocumentTags renvoie un StructuredDocumentTagCollection limité à cette plage, avec GetById(), GetByTag() et GetByTitle() pour une recherche ciblée ainsi que Remove() et RemoveAt(). Sur un StructuredDocumentTag individuel, Remove() supprime le contrôle et son contenu simultanément, RemoveSelfOnly() supprime uniquement l’enveloppe et conserve son contenu dans le document, et Clear() vide le contenu du contrôle tout en conservant le contrôle lui-même.

XML liaison de données

StructuredDocumentTag.XmlMapping est une instance XmlMapping décrivant une liaison à une partie XML personnalisée dans le document : CustomXmlPart, XPath, PrefixMappings, StoreItemId et IsMapped. SetMapping() établit la liaison à une partie XML personnalisée existante et Delete() la supprime.

Contrôles de contenu multi-section (à portée)

Un contrôle de contenu qui s’étend sur plus d’une section – signalé par IsMultiSection – n’est pas représenté par un seul nœud StructuredDocumentTag mais par une paire de nœuds StructuredDocumentTagRangeStart et StructuredDocumentTagRangeEnd, reliés via StructuredDocumentTagRangeStart.RangeEnd. Les formes à nœud unique et à plage implémentent toutes deux l’interface commune IStructuredDocumentTag, de sorte que le code qui ne nécessite que Tag, Title, SdtType, Placeholder et des propriétés d’identification similaires peut fonctionner uniformément avec l’une ou l’autre forme.

Conseils et bonnes pratiques

• Vérifiez la liste des types pris en charge par DocumentBuilder.InsertStructuredDocumentTag() avant de vous y fier – seuls PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture et Date peuvent être insérés au curseur ; les autres types lèvent une exception.
• Utilisez RemoveSelfOnly() au lieu de Remove() lorsque vous souhaitez « aplatir » un contrôle de contenu – conservez son contenu dans le document mais supprimez l’enveloppe du contrôle.
• Remplissez ListItems avant d’attendre qu’un contrôle DropDownList ou ComboBox affiche des choix, et définissez SelectedValue pour sélectionner celui actif.
• Programmez contre IStructuredDocumentTag plutôt que directement contre StructuredDocumentTag si votre code doit gérer de la même manière les contrôles de contenu ordinaires et ceux à plusieurs sections (à plage).
• XmlMapping.SetMapping() se lie à une partie XML personnalisée qui doit déjà exister dans le magasin de données XML personnalisé du document – ajoutez ou chargez les données XML avant de mapper un contrôle dessus.

Problèmes courants

FAQ

Quels types de contrôles de contenu puis-je insérer directement avec DocumentBuilder?

PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture et Date. Les autres valeurs SdtType ne sont pas prises en charge par InsertStructuredDocumentTag().

Comment trouver tous les contrôles de contenu avec une balise spécifique?

Utilisez Range.StructuredDocumentTags.GetByTag(), ou GetByTitle() / GetById() si vous effectuez la correspondance sur ceux-ci à la place.

Comment supprimer un contrôle de contenu tout en conservant son contenu?

Appelez StructuredDocumentTag.RemoveSelfOnly() plutôt que Remove().

Comment lier un contrôle de contenu à des données personnalisées XML?

Appelez XmlMapping.SetMapping() sur le contrôle, en le pointant vers une partie XML personnalisée existante et une expression XPath à l’intérieur.

Quelle est la différence entre un StructuredDocumentTag simple et un à plage ?

Un contrôle de contenu qui s’étend sur plusieurs sections de document est représenté comme une paire StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd au lieu d’un nœud unique; les deux formes implémentent IStructuredDocumentTag.

Résumé API Reference

Voir aussi

• Aspose.Words for .NET — Enterprise Documentation