Comment travailler avec les balises de document structurées dans .NET

Étape 1 : Installer le package

Aspose.Words FOSS pour .NET ne publie pas encore de package NuGet — construisez la bibliothèque à partir du code source à la place. Clonez https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git, puis compilez Aspose.Words.sln en configuration Release avec le SDK .NET et référencez l’assembly Aspose.Words résultant depuis votre projet. La bibliothèque cible .NET Standard 2.0, elle s’exécute donc sur le Framework .NET 4.6.2+ et .NET 6/8/10.

Étape 2 : Importer les classes requises

Ajoutez une directive using Aspose.Words; pour Document et DocumentBuilder, ainsi qu’une directive using Aspose.Words.Markup; pour StructuredDocumentTag, SdtType, SdtListItem, SdtListItemCollection, XmlMapping, et les autres classes de contrôles de contenu couvertes par ce guide.

Étape 3: Vérifiez quels types de contrôle de contenu vous pouvez insérer

Avant d’insérer, vérifiez si la cible SdtType fait partie des sept types acceptés par DocumentBuilder.InsertStructuredDocumentTag(SdtType): PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture et Date. RepeatingSection et RepeatingSectionItem ne peuvent pas être insérés à un curseur de texte avec cette méthode — ils enveloppent plutôt des paragraphes entiers ou des lignes de tableau. Les valeurs SdtType restantes qui peuvent apparaître dans un fichier 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 du tout acceptées par cette méthode d’insertion.

Étape 4: Insérer un contrôle de contenu au curseur

Appelez DocumentBuilder.InsertStructuredDocumentTag(SdtType) avec l’un des sept types pris en charge pour insérer un nouveau contrôle à la position actuelle du curseur du constructeur; l’appel renvoie le nouveau StructuredDocumentTag. Définissez Tag et Title sur le contrôle renvoyé pour lui attribuer les chaînes d’identification que les auteurs voient dans Word, et définissez PlaceholderName (soutenu par un Placeholder BuildingBlock) pour le texte d’invite que Word affiche lorsque le contrôle est vide — IsShowingPlaceholderText indique si cette invite est actuellement affichée.

Étape 5: Configurer le contenu spécifique au type

Pour un contrôle case à cocher, lisez ou définissez StructuredDocumentTag.Checked, et appelez SetCheckedSymbol() / SetUncheckedSymbol() pour personnaliser les glyphes affichés pour chaque état. Pour un contrôle de date, définissez FullDate, avec DateDisplayFormat et DateDisplayLocale qui contrôlent son rendu, DateStorageFormat (SdtDateStorageFormat) qui contrôle la façon dont il est stocké lorsqu’il est lié aux données XML, et CalendarType (SdtCalendarType) qui sélectionne le système de calendrier. Pour une liste déroulante ou une zone combinée, remplissez ListItems — un SdtListItemCollection de SdtListItem (DisplayText, Value) — avant de définir SelectedValue pour choisir l’option active. Pour un contrôle de texte brut, Multiline est une propriété bool sur StructuredDocumentTag qui peut être définie pour configurer le contrôle.

Étape 6: Apparence du contrôle et verrouillage

Définissez Appearance (SdtAppearance) pour contrôler la façon dont le contrôle est délimité visuellement dans Word, et Color pour définir sa couleur de surbrillance. ContentsFont et EndCharacterFont contrôlent la police appliquée au contenu du contrôle et son caractère de fin. LockContentControl et LockContents sont des commutateurs indépendants — définissez LockContentControl pour empêcher la suppression du contrôle lui-même, et LockContents pour empêcher la modification de ce qu’il contient, sans affecter l’autre.

Étape 7: Trouver et supprimer les contrôles de contenu

Lisez Range.StructuredDocumentTags — un StructuredDocumentTagCollection limité à cette plage — et appelez GetById(), GetByTag() ou GetByTitle() pour localiser un contrôle spécifique, ou Remove() / RemoveAt() sur la collection pour en supprimer un par référence ou par indice. Sur un contrôle individuel, appelez Remove() pour supprimer le contrôle ainsi que son contenu, RemoveSelfOnly() pour supprimer uniquement l’enveloppe tout en conservant son contenu dans le document, ou Clear() pour vider son contenu tout en laissant le contrôle en place.

Étape 8: Lier un contrôle à des données XML personnalisées

Lisez StructuredDocumentTag.XmlMapping — une instance XmlMapping — et appelez SetMapping(customXmlPart, xPath, prefixMapping) pour lier le contrôle à une partie XML personnalisée existante déjà présente dans le magasin de données XML du document, en utilisant une expression XPath pour sélectionner l’élément lié. XmlMapping.IsMapped indique si une liaison est actuellement active, CustomXmlPart et StoreItemId identifient la partie de données liée, et Delete() supprime le mappage.

Étape 9: Gérer les contrôles de contenu qui s’étendent sur plusieurs sections

Un contrôle de contenu s’étendant sur plus d’une section du document — signalé par IsMultiSection — n’est pas représenté par un seul nœud StructuredDocumentTag mais par une paire StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd, reliée via StructuredDocumentTagRangeStart.RangeEnd. Programmez contre l’interface partagée IStructuredDocumentTag (Tag, Title, Placeholder, PlaceholderName, Appearance, IsShowingPlaceholderText, RemoveSelfOnly()) lorsque le code doit gérer uniformément les formes à nœud unique et à plage, plutôt que de bifurquer selon le type concret.