Einleitung
Word-Dokumente platzieren Bilder, Textfelder und andere frei schwebende Objekte in einer Zeichnungsebene, die vom regulären Fluss der Absätze und Tabellen getrennt ist. Aspose.Words FOSS für .NET stellt diese Zeichnungsebene über die Klassen Shape und ShapeBase bereit und ermöglicht programmgesteuerten Zugriff auf dasselbe AutoShape, Bild-, Textfeld- und OLE-Objektmodell, das Word intern verwendet. Dieser Leitfaden zeigt, wie die Bibliothek diese Zeichenobjekte – Positionierung, Füll- und Konturformatierung, eingebettete Bilder und in einer Form angeordneten Text – in DOCX-, DOCM-, DOTX- und DOTM-Dokumenten darstellt und manipuliert.
Dies ist nützlich für Code, der Berichts- oder Briefkopfvorlagen mit einem positionierten Logo oder einer Grafik erstellt, Dokumente mit schwebenden Textfeldern und Anmerkungen erzeugt oder Formen, die bereits in einem hochgeladenen Dokument vorhanden sind, untersucht – dabei die Bytes eines eingebetteten Bildes extrahiert, den Namen des Unterzeichners einer Signaturzeile ausliest oder ein vorhandenes Bild neu positioniert.
Aspose.Words FOSS für .NET wird unter der MIT-Lizenz veröffentlicht und zielt auf .NET Standard 2.0 ab, sodass es auf .NET Framework 4.6.2+ und .NET 6, 8 und 10 ohne native Abhängigkeiten läuft. Installieren Sie es über NuGet oder bauen Sie es aus dem Quellcode (siehe Schnellstart unten). Es ist dieselbe Aspose.Words Dokumenten-Engine, die kommerziell verwendet wird, kein Neuaufbau oder Wrapper, sodass die hier beschriebenen Shape- und Zeichnungsschichtklassen die Produktions-API darstellen.
Hauptfunktionen
Das Shape- und ShapeBase-Objektmodell
Jedes AutoShape, Textfeld, eingebettete Bild, OLE-Objekt oder ActiveX-Steuerelement, das in einem Word-Dokument verankert ist, wird durch die Klasse Shape repräsentiert – versiegelt und auf der abstrakten Basisklasse ShapeBase aufgebaut. Beide teilen dieselbe Positionierungs- und Formatierungsoberfläche: Shape.Left, Shape.Top, Shape.Width, Shape.Height, Shape.Rotation und Shape.ZOrder für Geometrie, plus die Flags Shape.IsGroup, Shape.IsImage, Shape.IsWordArt und Shape.IsInline, die beschreiben, welche Art von Objekt eine gegebene Instanz enthält. Das Aufzählungs-Enum ShapeType listet die konkreten Formtypen auf, die Word erkennt – Rechteck, Ellipse, Linie, Pfeil, eine Familie von Anmerkungs- und Verbindungstypen, TextBox, Bild und OleObject unter mehr als achtzig Werten – sodass Code, der die Formen eines Dokuments durchläuft, anhand von Shape.ShapeType verzweigen kann, um zu entscheiden, wie jede gehandhabt wird. Mehrere Formen können zu einem einzigen GroupShape kombiniert werden, das selbst eine Unterklasse von ShapeBase ist und ein Set von Formen gemeinsam positioniert und skaliert; DocumentBuilder.InsertGroupShape(shapes) erzeugt eines aus einem bestehenden Array von Formen.
Textfelder und WordArt
Jedes Shape kann eigenen Text über die TextBox Klasse tragen, die als Shape.TextBox bereitgestellt wird. TextBox Eigenschaften steuern, wie dieser Text innerhalb der Form positioniert wird: TextBox.InternalMarginLeft, TextBox.InternalMarginRight, TextBox.InternalMarginTop und TextBox.InternalMarginBottom für den Innenabstand, TextBox.FitShapeToText um die Form mit ihrem Inhalt wachsen zu lassen, LayoutFlow für die Textausrichtung, TextBoxWrapMode dafür, wie Text innerhalb des Feldes umbrochen wird, und TextBox.VerticalAnchor – ein TextBoxAnchor Wert wie Top, Middle, BottomCentered oder TopBaseline – für die vertikale Ausrichtung. Verknüpfte Textfelder, bei denen überlaufender Text in ein zweites Feld weitergeht, werden mit TextBox.Next und TextBox.Previous modelliert. Eine verwandte, aber separate Klasse, TextPath, definiert WordArt-artigen Text, der der Kontur einer Form folgt, anstatt innerhalb zu liegen, mit Eigenschaften wie TextPath.Text, TextPath.FontFamily, TextPath.Bold und TextPath.RotateLetters, plus einem TextPathAlignment Enum mit Werten wie Stretch, Center und LetterJustify.
Bilder und eingebettete Bilder
Wenn eine Form ein Bild enthält, ist Shape.HasImage wahr und Shape.ImageData gibt ein ImageData Objekt zurück. ImageData stellt die Rohbytes über ImageData.ImageBytes bereit, das erkannte Format über ImageType (Werte einschließlich Jpeg, Png, Bmp, Gif, Emf, Wmf, Pict, Eps und WebP), Pixelabmessungen und Auflösung über ImageSize sowie das Zuschneiden über ImageData.CropTop, ImageData.CropBottom, ImageData.CropLeft und ImageData.CropRight. Farbkorrekturen – ImageData.Brightness, ImageData.Contrast, ImageData.GrayScale, ImageData.BiLevel und ImageData.ChromaKey – sind Eigenschaften desselben Objekts, und ImageData.IsLink/ImageData.IsLinkOnly unterscheiden ein eingebettetes Bild von einem, das nur einen externen Dateipfad referenziert. DocumentBuilder.InsertImage() hat Überladungen, die ein Bild, einen Dateipfad, ein Byte-Array oder einen Stream akzeptieren, einschließlich Varianten, die zudem explizite Breite, Höhe, horizontale und vertikale Position sowie WrapType zum Einfügezeitpunkt festlegen.
Füllung, Kontur und Formeffekte
Jedes Shape und GroupShape enthält ein Fill Objekt und ein Stroke Objekt für das Innere bzw. die Kontur. Fill unterstützt sechs Füllungsarten über FillType, mit Werten einschließlich Solid, Patterned, Gradient, Textured, Background und Picture, die mit Methoden wie Fill.Solid(color), Fill.OneColorGradient(style, variant, degree), Fill.TwoColorGradient(color1, color2, style, variant), Fill.Patterned(patternType) oder Fill.SetImage(fileName) festgelegt werden. Stroke steuert die Kontur: Stroke.Weight, DashStyle, JoinStyle, EndCap und Stroke.LineStyle (ein ShapeLineStyle Wert) betreffen die Linie selbst, während Stroke.StartArrowType und Stroke.EndArrowType in Kombination mit den ArrowWidth und ArrowLength Enums Pfeilspitzen bei Verbindungs- und Linienformen konfigurieren. Neben Füllung und Kontur stellt Shape vier weitere Effektobjekte bereit – ShadowFormat, ReflectionFormat, GlowFormat und SoftEdgeFormat – von denen jedes eigene Farb- und Transparenzeigenschaften für den jeweiligen visuellen Effekt besitzt.
Positionierung und Textumbruch
Formen, die relativ zur Seite oder zum Absatz schweben, verwenden RelativeHorizontalPosition und RelativeVerticalPosition, um sich zu verankern – zum Beispiel am Rand, an der Seite oder an der Spalte – zusammen mit RelativeHorizontalSize und RelativeVerticalSize für die Größenverankerung sowie HorizontalAlignment und VerticalAlignment für einfache Links/Mitte/Rechts- oder Oben/Mitte/Unten-Platzierung. Wie der umgebende Text auf eine Form reagiert, wird von WrapType gesteuert, mit Werten einschließlich Inline, Square, Tight, TopBottom und None; für Square- und Tight-Umbruch schränkt WrapSide dies weiter auf Left, Right, Both oder Largest ein. FlipOrientation spiegelt eine Form horizontal oder vertikal, ohne ihre Koordinaten zu ändern, und die Shape.AllowOverlap/Shape.BehindText Flags bestimmen, wie eine Form mit anderem schwebendem Inhalt und der Textebene darunter interagiert.
Signaturzeilen und horizontale Trennlinien
Zwei weitere spezialisierte Formtypen befinden sich im selben Zeichnungsmodell. SignatureLine, zur Einfügezeit über SignatureLineOptions konfiguriert (Eigenschaften umfassen SignatureLineOptions.Signer, SignatureLineOptions.SignerTitle, SignatureLineOptions.Email, SignatureLineOptions.Instructions, SignatureLineOptions.ShowDate und SignatureLineOptions.AllowComments), rendert den visuellen Signaturblock, der in druckbaren Dokumenten zu sehen ist, und stellt SignatureLine.IsSigned und SignatureLine.IsValid bereit, sobald eine Signatur darauf angewendet wurde – dies unterscheidet sich von der kryptografischen digitalen Signaturprüfung, die an anderer Stelle behandelt wird und mit signierten Dokumentteilen statt mit der Form selbst arbeitet. HorizontalRuleFormat deckt die einfache Trennlinie ab, die mit DocumentBuilder.InsertHorizontalRule() eingefügt wird, mit den Eigenschaften HorizontalRuleFormat.WidthPercent, HorizontalRuleFormat.Height, HorizontalRuleFormat.NoShade, HorizontalRuleFormat.Color und HorizontalRuleFormat.Alignment (letztere ein HorizontalRuleAlignment-Wert).
Schnellstart
Aspose.Words FOSS für .NET ist über NuGet verfügbar:
dotnet add package Aspose.Words.FOSSUm stattdessen aus dem Quellcode zu bauen:
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
Fügen Sie Ihrer Anwendung eine Projektverweis auf Aspose.Words.csproj hinzu. Von dort aus folgt die Arbeit mit der Zeichnungsebene dem in diesem Beitrag überall verwendeten Muster: Laden oder erstellen Sie ein Document, durchlaufen Sie seine Formen mit Document.GetChildNodes(NodeType.Shape, true) oder fügen Sie ein neues mit einer DocumentBuilder-Methode wie DocumentBuilder.InsertImage(), DocumentBuilder.InsertGroupShape() oder DocumentBuilder.InsertHorizontalRule() ein, lesen oder setzen Sie dann Eigenschaften des zurückgegebenen Shape – Shape.ImageData, Shape.TextBox, Shape.Fill, Shape.Stroke, Shape.WrapType und weitere – bevor Sie Document.Save() aufrufen.
Unterstützte Formate
| Format | Erweiterung | Lesen | Schreiben |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (alle Varianten) | (verschiedene) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
Diese Ausgabe schließt bewusst Seitenlayout und Rendering aus — kein PDF, XPS oder Bildexport und kein Druck — sodass die Shape.Bounds einer Form und layoutabhängige Geometrie die im Dokument gespeicherten Werte widerspiegeln und nicht ein berechnetes Seitenlayout. Die zusätzlichen Formatkonverter (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3 und WordML) werden nicht gelesen oder geschrieben; dies sind dieselben Subsysteme, die aus dem kommerziellen Codebasis entfernt wurden, um diese Ausgabe kostenlos zu halten.
Open Source & Lizenzierung
Aspose.Words FOSS für .NET wird unter der MIT-Lizenz veröffentlicht, kostenlos für kommerzielle und private Nutzung ohne Lizenzgebühren oder Weiterverbreitungseinschränkungen. Der komplette Quellcode ist auf GitHub im Aspose.Words FOSS für .NET Repository verfügbar.
