Introduction
Les documents Word placent des images, des zones de texte et d’autres objets flottants dans un calque de dessin qui se situe en dehors du flux normal des paragraphes et des tableaux. Aspose.Words FOSS pour .NET expose ce calque de dessin via les classes Shape et ShapeBase, offrant un accès programmatique au même modèle AutoShape, image, zone de texte et objet OLE que Word utilise en interne. Ce guide montre comment la bibliothèque représente et manipule ces objets de dessin — positionnement, remplissage et format de contour, images incorporées, et texte disposé à l’intérieur d’une forme — à travers les documents DOCX, DOCM, DOTX et DOTM.
Cela est utile pour le code qui crée des modèles de rapports ou d’en-têtes avec un logo ou un graphique positionné, génère des documents avec des zones de texte flottantes et des annotations, ou inspecte les formes déjà présentes dans un document téléchargé — extraire les octets d’une image incorporée, lire le nom du signataire d’une ligne de signature, ou repositionner une image existante.
Aspose.Words FOSS pour .NET est publié sous la licence MIT et cible .NET Standard 2.0, il fonctionne donc sur le Framework .NET 4.6.2+ et .NET 6, 8 et 10 sans dépendances natives. Installez-le via NuGet, ou compilez-le à partir des sources (voir le Démarrage rapide ci-dessous). C’est le même moteur de documents Aspose.Words utilisé commercialement, pas une réécriture ou un wrapper, de sorte que les classes Shape et du calque de dessin décrites ici sont la version de production API.
Fonctionnalités clés
Le modèle d’objet Shape et ShapeBase
Chaque AutoShape, zone de texte, image incorporée, objet OLE ou contrôle ActiveX ancré dans un document Word est représenté par la classe Shape — scellée et construite sur la classe de base abstraite ShapeBase. Les deux partagent la même surface de positionnement et de formatage : Shape.Left, Shape.Top, Shape.Width, Shape.Height, Shape.Rotation et Shape.ZOrder pour la géométrie, plus les indicateurs Shape.IsGroup, Shape.IsImage, Shape.IsWordArt et Shape.IsInline décrivant le type d’objet qu’une instance donnée contient. L’énumération ShapeType répertorie les types concrets de formes reconnus par Word — Rectangle, Ellipse, Ligne, Flèche, une famille de types d’annotation et de connecteur, TextBox, Image et OleObject parmi plus de quatre-vingts valeurs — ainsi le code parcourant les formes d’un document peut se ramifier sur Shape.ShapeType pour décider comment gérer chacune d’elles. Plusieurs formes peuvent être combinées en un seul GroupShape, lui-même une sous-classe de ShapeBase, qui conserve un ensemble de formes positionnées et redimensionnées ensemble ; DocumentBuilder.InsertGroupShape(shapes) en crée une à partir d’un tableau existant de formes.
Zones de texte et WordArt
Tout Shape peut contenir son propre texte via la classe TextBox, exposée sous le nom Shape.TextBox. Les propriétés TextBox contrôlent la façon dont ce texte se place à l’intérieur de la forme: TextBox.InternalMarginLeft, TextBox.InternalMarginRight, TextBox.InternalMarginTop et TextBox.InternalMarginBottom pour le remplissage, TextBox.FitShapeToText pour permettre à la forme de s’agrandir avec son contenu, LayoutFlow pour la direction du texte, TextBoxWrapMode pour la façon dont le texte s’enroule à l’intérieur de la boîte, et TextBox.VerticalAnchor — une valeur TextBoxAnchor telle que Top, Middle, BottomCentered ou TopBaseline — pour l’alignement vertical. Les boîtes de texte liées, où le texte débordant continue dans une seconde boîte, sont modélisées avec TextBox.Next et TextBox.Previous. Une classe apparentée mais distincte, TextPath, définit le texte de style WordArt qui suit le contour d’une forme au lieu de se placer à l’intérieur, avec des propriétés telles que TextPath.Text, TextPath.FontFamily, TextPath.Bold et TextPath.RotateLetters, ainsi qu’une énumération TextPathAlignment avec des valeurs comme Stretch, Center et LetterJustify.
Images et images incorporées
Lorsque une forme contient une image, Shape.HasImage est vrai et Shape.ImageData renvoie un objet ImageData. ImageData expose les octets bruts via ImageData.ImageBytes, le format détecté via ImageType (valeurs incluant Jpeg, Png, Bmp, Gif, Emf, Wmf, Pict, Eps et WebP), les dimensions en pixels et la résolution via ImageSize, et le recadrage via ImageData.CropTop, ImageData.CropBottom, ImageData.CropLeft et ImageData.CropRight. Les ajustements de couleur — ImageData.Brightness, ImageData.Contrast, ImageData.GrayScale, ImageData.BiLevel et ImageData.ChromaKey — sont des propriétés du même objet, et ImageData.IsLink/ImageData.IsLinkOnly distinguent une image incorporée d’une image qui ne fait qu’une référence à un chemin de fichier externe. DocumentBuilder.InsertImage() propose des surcharges qui acceptent une image, un chemin de fichier, un tableau d’octets ou un flux, incluant des variantes qui définissent également la largeur, la hauteur, la position horizontale et verticale, et WrapType au moment de l’insertion.
Remplissage, contour et effets de forme
Chaque Shape et GroupShape possède un objet Fill et un objet Stroke pour son intérieur et son contour. Fill prend en charge six types de remplissage via FillType, avec des valeurs incluant Solid, Patterned, Gradient, Textured, Background et Picture, définies avec des méthodes telles que Fill.Solid(color), Fill.OneColorGradient(style, variant, degree), Fill.TwoColorGradient(color1, color2, style, variant), Fill.Patterned(patternType) ou Fill.SetImage(fileName). Stroke contrôle le contour : Stroke.Weight, DashStyle, JoinStyle, EndCap et Stroke.LineStyle (une valeur ShapeLineStyle) couvrent la ligne elle-même, tandis que Stroke.StartArrowType et Stroke.EndArrowType, associés aux énumérations ArrowWidth et ArrowLength, configurent les pointes de flèche sur les formes de connexion et de ligne. Au-delà du remplissage et du contour, Shape expose quatre objets d’effet supplémentaires — ShadowFormat, ReflectionFormat, GlowFormat et SoftEdgeFormat — chacun portant ses propres propriétés de couleur et de transparence pour l’effet visuel correspondant.
Positionnement et habillage du texte
Les formes qui flottent par rapport à la page ou au paragraphe utilisent RelativeHorizontalPosition et RelativeVerticalPosition pour s’ancrer — à la marge, à la page ou à la colonne, par exemple — associées à RelativeHorizontalSize et RelativeVerticalSize pour l’ancrage de la taille, plus HorizontalAlignment et VerticalAlignment pour un placement simple gauche/centre/droite ou haut/milieu/bas. La façon dont le texte environnant réagit à une forme est contrôlée par WrapType, avec des valeurs incluant Inline, Square, Tight, TopBottom et None; pour les habillages Square et Tight, WrapSide le restreint davantage à Left, Right, Both ou Largest. FlipOrientation reflète une forme horizontalement ou verticalement sans modifier ses coordonnées, et les indicateurs Shape.AllowOverlap/Shape.BehindText contrôlent la façon dont une forme interagit avec d’autres contenus flottants et la couche de texte en dessous.
Lignes de signature et traits horizontaux
Deux types de formes spécialisées supplémentaires résident dans le même modèle de dessin. SignatureLine, configuré au moment de l’insertion via SignatureLineOptions (les propriétés incluent SignatureLineOptions.Signer, SignatureLineOptions.SignerTitle, SignatureLineOptions.Email, SignatureLineOptions.Instructions, SignatureLineOptions.ShowDate et SignatureLineOptions.AllowComments), rend le bloc de signature visuel visible dans les documents imprimables et expose SignatureLine.IsSigned et SignatureLine.IsValid une fois qu’une signature a été appliquée — cela diffère de la vérification cryptographique de signature numérique couverte ailleurs, qui fonctionne avec des parties de document signées plutôt qu’avec la forme elle-même. HorizontalRuleFormat couvre la simple ligne de séparation insérée avec DocumentBuilder.InsertHorizontalRule(), avec les propriétés HorizontalRuleFormat.WidthPercent, HorizontalRuleFormat.Height, HorizontalRuleFormat.NoShade, HorizontalRuleFormat.Color et HorizontalRuleFormat.Alignment (la dernière une valeur HorizontalRuleAlignment).
Démarrage rapide
Aspose.Words FOSS pour .NET est disponible via NuGet:
dotnet add package Aspose.Words.FOSSPour construire à partir du code source à la place:
git clone https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git
cd Aspose.Words-FOSS-for-.NET
dotnet build Aspose.Words.sln -c Release
Ajoutez une référence de projet à Aspose.Words.csproj depuis votre application. À partir de là, travailler avec la couche de dessin suit le schéma utilisé tout au long de cet article: chargez ou créez un Document, parcourez ses formes avec Document.GetChildNodes(NodeType.Shape, true) ou insérez-en une nouvelle à l’aide d’une méthode DocumentBuilder telle que DocumentBuilder.InsertImage(), DocumentBuilder.InsertGroupShape() ou DocumentBuilder.InsertHorizontalRule(), puis lisez ou définissez les propriétés sur le Shape retourné — Shape.ImageData, Shape.TextBox, Shape.Fill, Shape.Stroke, Shape.WrapType et les suivantes — avant d’appeler Document.Save().
Formats pris en charge
| Format | Extension | Lire | Écrire |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (toutes les variantes) | (divers) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
Cette édition exclut intentionnellement la mise en page et le rendu — pas de PDF, XPS, ou export d’image, et pas d’impression — de sorte que le Shape.Bounds d’une forme et la géométrie dépendante de la mise en page reflètent les valeurs stockées dans le document plutôt qu’une mise en page calculée. Les convertisseurs de formats supplémentaires (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3, et WordML) ne sont pas lus ni écrits; ce sont les mêmes sous-systèmes retirés du code commercial pour garder cette édition gratuite.
Open Source & Licence
Aspose.Words FOSS pour .NET est publié sous licence MIT, gratuit pour une utilisation commerciale et personnelle sans redevances ni restrictions de redistribution. Le code source complet est disponible sur GitHub dans le Aspose.Words FOSS pour le dépôt .NET.
