Introduktion
Word-dokument placerar bilder, textrutor och andra fristående objekt i ett ritlager som ligger åtskilt från den vanliga flödet av stycken och tabeller. Aspose.Words FOSS för .NET exponerar detta ritlager via klasserna Shape och ShapeBase, vilket ger programmatisk åtkomst till samma AutoShape, bild-, textrute- och OLE-objektmodell som Word själv använder internt. Denna guide visar hur biblioteket representerar och manipulerar dessa ritobjekt — positionering, fyllnings- och konturformatering, inbäddade bilder och text som placeras inuti en form — i DOCX-, DOCM-, DOTX- och DOTM-dokument.
Detta är användbart för kod som bygger rapport- eller brevhuvudsmallar med en placerad logotyp eller grafik, genererar dokument med flytande textrutor och anmärkningar, eller inspekterar former som redan finns i ett uppladdat dokument — extrahera en inbäddad bilds byte, läsa namnet på undertecknaren i en signaturlinje, eller omplacera en befintlig bild.
Aspose.Words FOSS för .NET släpps under MIT-licensen och riktar sig mot .NET Standard 2.0, så den körs på .NET Framework 4.6.2+ och .NET 6, 8 och 10 utan inhemska beroenden. Installera den via NuGet, eller bygg den från källkod (se Snabbstart nedan). Det är samma Aspose.Words dokumentmotor som används kommersiellt, inte en omskrivning eller ett omslag, så de Shape och ritlagerklasser som beskrivs här är produktions-API.
Nyckelfunktioner
Form- och ShapeBase objektmodell
Varje AutoShape, textruta, inbäddad bild, OLE-objekt eller ActiveX-kontroll förankrad i ett Word-dokument representeras av klassen Shape — förseglad och byggd på den abstrakta basklassen ShapeBase. Båda delar samma positionerings- och formateringsyta: Shape.Left, Shape.Top, Shape.Width, Shape.Height, Shape.Rotation och Shape.ZOrder för geometri, samt Shape.IsGroup, Shape.IsImage, Shape.IsWordArt och Shape.IsInline flaggor som beskriver vilken typ av objekt en given instans innehåller. ShapeType-enumet listar de konkreta formtyperna som Word känner igen — Rektangel, Ellips, Linje, Pil, en familj av anmärkning- och anslutningstyper, TextBox, Bild och OleObject bland mer än åttio värden — så kod som går igenom ett dokuments former kan grena på Shape.ShapeType för att avgöra hur varje ska hanteras. Flera former kan kombineras till en enda GroupShape, som själv är en ShapeBase-subklass, vilket behåller en uppsättning former som positioneras och skalas tillsammans; DocumentBuilder.InsertGroupShape(shapes) bygger en från en befintlig matris av former.
Textrutor och WordArt
Alla Shape kan bära sin egen text via TextBox-klassen, som exponeras som Shape.TextBox. TextBox-egenskaper styr hur den texten placeras inuti formen: TextBox.InternalMarginLeft, TextBox.InternalMarginRight, TextBox.InternalMarginTop och TextBox.InternalMarginBottom för utfyllnad, TextBox.FitShapeToText för att låta formen växa med sitt innehåll, LayoutFlow för textriktning, TextBoxWrapMode för hur texten radbryts i rutan, och TextBox.VerticalAnchor – ett TextBoxAnchor-värde såsom Top, Middle, BottomCentered eller TopBaseline – för vertikal justering. Länkade textrutor, där överskjutande text fortsätter i en andra ruta, modelleras med TextBox.Next och TextBox.Previous. En närliggande men separat klass, TextPath, definierar WordArt-stiltext som följer formens kontur istället för att sitta inuti den, med egenskaper såsom TextPath.Text, TextPath.FontFamily, TextPath.Bold och TextPath.RotateLetters, samt en TextPathAlignment-enum med värden såsom Stretch, Center och LetterJustify.
Bilder och inbäddade bilder
När en form innehåller en bild är Shape.HasImage sant och Shape.ImageData returnerar ett ImageData-objekt. ImageData exponerar de råa bytena via ImageData.ImageBytes, det upptäckta formatet via ImageType (värden inklusive Jpeg, Png, Bmp, Gif, Emf, Wmf, Pict, Eps och WebP), pixelmått och upplösning via ImageSize, samt beskärning via ImageData.CropTop, ImageData.CropBottom, ImageData.CropLeft och ImageData.CropRight. Färgjusteringar — ImageData.Brightness, ImageData.Contrast, ImageData.GrayScale, ImageData.BiLevel och ImageData.ChromaKey — är egenskaper på samma objekt, och ImageData.IsLink/ImageData.IsLinkOnly skiljer en inbäddad bild från en som bara refererar till en extern filsökväg. DocumentBuilder.InsertImage() har överlagringar som accepterar en bild, en filsökväg, en byte-array eller en ström, inklusive varianter som också sätter explicit bredd, höjd, horisontell och vertikal position samt WrapType vid infogningstillfället.
Fyllning, linje och formeffekter
Varje Shape och GroupShape har ett Fill-objekt och ett Stroke-objekt för respektive inre och kontur. Fill stödjer sex fyllningstyper via FillType, med värden inklusive Solid, Patterned, Gradient, Textured, Background och Picture, som sätts med metoder såsom Fill.Solid(color), Fill.OneColorGradient(style, variant, degree), Fill.TwoColorGradient(color1, color2, style, variant), Fill.Patterned(patternType) eller Fill.SetImage(fileName). Stroke styr konturen: Stroke.Weight, DashStyle, JoinStyle, EndCap och Stroke.LineStyle (ett ShapeLineStyle-värde) täcker själva linjen, medan Stroke.StartArrowType och Stroke.EndArrowType, i kombination med ArrowWidth och ArrowLength-enums, konfigurerar pilspetsar på kopplings- och linjeformer. Utöver fyllning och kontur exponeras Shape fyra ytterligare effektobjekt — ShadowFormat, ReflectionFormat, GlowFormat och SoftEdgeFormat — som var och en har sina egna färg- och transparensegenskaper för den motsvarande visuella effekten.
Positionering och textomslag
Former som flyter i förhållande till sidan eller stycket använder RelativeHorizontalPosition och RelativeVerticalPosition för att förankra sig — till marginalen, sidan eller kolumnen, till exempel — i kombination med RelativeHorizontalSize och RelativeVerticalSize för storleksförankring, samt HorizontalAlignment och VerticalAlignment för enkel vänster/centrerad/höger eller topp/mitten/botten-placering. Hur omgivande text reagerar på en form styrs av WrapType, med värden inklusive Inline, Square, Tight, TopBottom och None; för Square och Tight-omslag begränsar WrapSide detta ytterligare till Left, Right, Both eller Largest. FlipOrientation speglar en form horisontellt eller vertikalt utan att ändra dess koordinater, och flaggorna Shape.AllowOverlap/Shape.BehindText styr hur en form interagerar med annat flytande innehåll och textlagret under den.
Signaturlinjer och horisontella linjer
Två ytterligare specialiserade formtyper finns i samma ritmodell. SignatureLine, konfigurerad vid infogningstid genom SignatureLineOptions (egenskaper inkluderar SignatureLineOptions.Signer, SignatureLineOptions.SignerTitle, SignatureLineOptions.Email, SignatureLineOptions.Instructions, SignatureLineOptions.ShowDate och SignatureLineOptions.AllowComments), renderar det visuella signaturblocket som ses i utskrivbara dokument och exponerar SignatureLine.IsSigned och SignatureLine.IsValid när en signatur har applicerats på den — detta är skilt från den kryptografiska digitala signaturverifieringen som behandlas på annat håll, vilken arbetar med signerade dokumentdelar snarare än själva formen. HorizontalRuleFormat omfattar den enkla avdelningslinjen som infogas med DocumentBuilder.InsertHorizontalRule(), med HorizontalRuleFormat.WidthPercent, HorizontalRuleFormat.Height, HorizontalRuleFormat.NoShade, HorizontalRuleFormat.Color och HorizontalRuleFormat.Alignment egenskaper (den sista ett HorizontalRuleAlignment värde).
Snabbstart
Aspose.Words FOSS för .NET är tillgänglig via NuGet:
dotnet add package Aspose.Words.FOSSFör att bygga från källkoden istället:
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
Lägg till en projektreferens till Aspose.Words.csproj från din applikation. Därifrån följer arbete med ritlagret mönstret som används i hela detta inlägg: läs in eller skapa en Document, gå igenom dess former med Document.GetChildNodes(NodeType.Shape, true) eller infoga en ny med en DocumentBuilder metod såsom DocumentBuilder.InsertImage(), DocumentBuilder.InsertGroupShape() eller DocumentBuilder.InsertHorizontalRule(), läs sedan eller sätt egenskaper på det returnerade Shape — Shape.ImageData, Shape.TextBox, Shape.Fill, Shape.Stroke, Shape.WrapType och resten — innan du anropar Document.Save().
Stödda format
| Format | Filändelse | Läs | Skriv |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (alla varianter) | (olika) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
Denna utgåva utesluter medvetet sidlayout och rendering — ingen PDF, XPS eller bildexport, och ingen utskrift — så en forms Shape.Bounds och layoutberoende geometri återspeglar de värden som lagras i dokumentet snarare än en beräknad sidlayout. De ytterligare formatkonverterarna (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3, och WordML) läses inte av eller skrivs; dessa är samma delsystem som togs bort från den kommersiella kodbasen för att hålla denna utgåva gratis.
Öppen källkod & licensiering
Aspose.Words FOSS för .NET släpps under MIT-licensen, gratis för både kommersiell och personlig användning utan royaltyavgifter eller restriktioner för vidaredistribution. Den fullständiga källkoden finns tillgänglig på GitHub i Aspose.Words FOSS för .NET repository.
