Inleiding
Word-documenten plaatsen afbeeldingen, tekstvakken en andere vrij zwevende objecten in een tekenlaag die gescheiden is van de reguliere stroom van alinea’s en tabellen. Aspose.Words FOSS voor .NET maakt deze tekenlaag toegankelijk via de Shape en ShapeBase klassen, waardoor programmatisch toegang wordt verkregen tot hetzelfde AutoShape, afbeelding, tekstvak en OLE-objectmodel dat Word zelf intern gebruikt. Deze gids laat zien hoe de bibliotheek deze tekenobjecten weergeeft en bewerkt — positionering, opvul- en contouropmaak, ingebedde afbeeldingen en tekst die binnen een vorm is geplaatst — in DOCX-, DOCM-, DOTX- en DOTM-documenten.
Dit is nuttig voor code die rapport- of briefhoofd-sjablonen maakt met een gepositioneerd logo of afbeelding, documenten genereert met zwevende tekstvakken en bijschriften, of vormen inspecteert die al aanwezig zijn in een geüpload document — het extraheren van de bytes van een ingebedde afbeelding, het lezen van de ondertekenaarnaam van een handtekeningregel, of het verplaatsen van een bestaande afbeelding.
Aspose.Words FOSS voor .NET wordt uitgebracht onder de MIT-licentie en richt zich op .NET Standard 2.0, zodat het draait op .NET Framework 4.6.2+ en .NET 6, 8 en 10 zonder native afhankelijkheden. Installeer het via NuGet, of bouw het vanaf de bron (zie Snelstart hieronder). Het is dezelfde Aspose.Words documentengine die commercieel wordt gebruikt, geen herschrijving of wrapper, zodat de hier beschreven Shape en tekenlaag-klassen de productie-API zijn.
Belangrijkste functies
Het vorm- en ShapeBase objectmodel
Elke AutoShape, tekstvak, ingebedde afbeelding, OLE-object of ActiveX-besturingselement dat verankerd is in een Word-document wordt vertegenwoordigd door de Shape-klasse — sealed en gebouwd op de abstracte ShapeBase-basisklasse. Beide delen hetzelfde positionerings- en opmaakoppervlak: Shape.Left, Shape.Top, Shape.Width, Shape.Height, Shape.Rotation en Shape.ZOrder voor geometrie, plus Shape.IsGroup, Shape.IsImage, Shape.IsWordArt en Shape.IsInline-vlaggen die beschrijven welk type object een gegeven instantie bevat. De ShapeType-enum somt de concrete vormsoorten op die Word herkent — Rechthoek, Ellips, Lijn, Pijl, een familie van bijschrift- en connector-typen, TextBox, Afbeelding en OleObject onder meer dan tachtig waarden — zodat code die de vormen van een document doorloopt, kan vertakken op Shape.ShapeType om te bepalen hoe elke vorm te behandelen. Meerdere vormen kunnen worden gecombineerd in één enkele GroupShape, zelf een ShapeBase-subklasse, die een set vormen samen gepositioneerd en geschaald houdt; DocumentBuilder.InsertGroupShape(shapes) bouwt er een vanuit een bestaande array van vormen.
Tekstvakken en WordArt
Elke Shape kan zijn eigen tekst dragen via de TextBox klasse, beschikbaar als Shape.TextBox. TextBox eigenschappen bepalen hoe die tekst zich binnen de vorm bevindt: TextBox.InternalMarginLeft, TextBox.InternalMarginRight, TextBox.InternalMarginTop en TextBox.InternalMarginBottom voor padding, TextBox.FitShapeToText om de vorm te laten groeien met zijn inhoud, LayoutFlow voor tekstrichting, TextBoxWrapMode voor hoe tekst in de doos wordt omgebroken, en TextBox.VerticalAnchor — een TextBoxAnchor waarde zoals Top, Middle, BottomCentered of TopBaseline — voor verticale uitlijning. Gekoppelde tekstvakken, waarbij overlopende tekst doorgaat naar een tweede vak, worden gemodelleerd met TextBox.Next en TextBox.Previous. Een verwante maar aparte klasse, TextPath, definieert WordArt-stijl tekst die de omtrek van een vorm volgt in plaats van erin te zitten, met eigenschappen zoals TextPath.Text, TextPath.FontFamily, TextPath.Bold en TextPath.RotateLetters, plus een TextPathAlignment enum met waarden zoals Stretch, Center en LetterJustify.
Afbeeldingen en Ingesloten Afbeeldingen
Wanneer een vorm een afbeelding bevat, is Shape.HasImage waar en retourneert Shape.ImageData een ImageData object. ImageData maakt de ruwe bytes beschikbaar via ImageData.ImageBytes, het gedetecteerde formaat via ImageType (waarden inclusief Jpeg, Png, Bmp, Gif, Emf, Wmf, Pict, Eps en WebP), pixelafmetingen en resolutie via ImageSize, en bijsnijden via ImageData.CropTop, ImageData.CropBottom, ImageData.CropLeft en ImageData.CropRight. Kleurcorrecties — ImageData.Brightness, ImageData.Contrast, ImageData.GrayScale, ImageData.BiLevel en ImageData.ChromaKey — zijn eigenschappen van hetzelfde object, en ImageData.IsLink/ImageData.IsLinkOnly onderscheiden een ingesloten afbeelding van een afbeelding die alleen naar een extern bestandspad verwijst. DocumentBuilder.InsertImage() heeft overloads die een afbeelding, een bestandspad, een byte-array of een stream accepteren, inclusief varianten die ook een expliciete breedte, hoogte, horizontale en verticale positie, en WrapType bij het invoegen instellen.
Vulling, Lijn en Vormeffecten
Elke Shape en GroupShape bevat een Fill object en een Stroke object voor respectievelijk het interieur en de omtrek. Fill ondersteunt zes vulsoorten via FillType, met waarden inclusief Solid, Patterned, Gradient, Textured, Background en Picture, ingesteld met methoden zoals Fill.Solid(color), Fill.OneColorGradient(style, variant, degree), Fill.TwoColorGradient(color1, color2, style, variant), Fill.Patterned(patternType) of Fill.SetImage(fileName). Stroke regelt de omtrek: Stroke.Weight, DashStyle, JoinStyle, EndCap en Stroke.LineStyle (een ShapeLineStyle waarde) bestrijken de lijn zelf, terwijl Stroke.StartArrowType en Stroke.EndArrowType, gecombineerd met de ArrowWidth en ArrowLength enums, pijlpuntinstellingen voor connector- en lijngesneden configureren. Naast vulling en lijn, maakt Shape vier extra effectobjecten zichtbaar — ShadowFormat, ReflectionFormat, GlowFormat en SoftEdgeFormat — elk met eigen kleur- en transparantie-eigenschappen voor het betreffende visuele effect.
Positionering en Tekstomloop
Vormen die zweven ten opzichte van de pagina of alinea gebruiken RelativeHorizontalPosition en RelativeVerticalPosition om zich te verankeren — bijvoorbeeld aan de marge, pagina of kolom — in combinatie met RelativeHorizontalSize en RelativeVerticalSize voor grootteverankering, plus HorizontalAlignment en VerticalAlignment voor eenvoudige links/midden/rechts of boven/midden/onder plaatsing. Hoe omringende tekst reageert op een vorm wordt bepaald door WrapType, met waarden waaronder Inline, Square, Tight, TopBottom en None; voor Square- en Tight-omloop beperkt WrapSide dit verder tot Left, Right, Both of Largest. FlipOrientation spiegelt een vorm horizontaal of verticaal zonder de coördinaten te wijzigen, en de Shape.AllowOverlap/Shape.BehindText vlaggen regelen hoe een vorm interageert met andere zwevende inhoud en de tekstlaag eronder.
Handtekeningregels en horizontale regels
Twee andere gespecialiseerde vormtypen bevinden zich in hetzelfde tekenmodel. SignatureLine, geconfigureerd op het moment van invoegen via SignatureLineOptions (eigenschappen omvatten SignatureLineOptions.Signer, SignatureLineOptions.SignerTitle, SignatureLineOptions.Email, SignatureLineOptions.Instructions, SignatureLineOptions.ShowDate en SignatureLineOptions.AllowComments), rendert het visuele handtekeningsblok dat in afdrukbare documenten wordt gezien en maakt SignatureLine.IsSigned en SignatureLine.IsValid bloot zodra een handtekening erop is toegepast — dit verschilt van de cryptografische digitale-handtekeningverificatie die elders wordt behandeld, en werkt met ondertekende documentonderdelen in plaats van de vorm zelf. HorizontalRuleFormat behandelt de gewone scheidingslijn die wordt ingevoegd met DocumentBuilder.InsertHorizontalRule(), met HorizontalRuleFormat.WidthPercent, HorizontalRuleFormat.Height, HorizontalRuleFormat.NoShade, HorizontalRuleFormat.Color en HorizontalRuleFormat.Alignment eigenschappen (de laatste een HorizontalRuleAlignment waarde).
Snelstart
Aspose.Words FOSS voor .NET is beschikbaar via NuGet:
dotnet add package Aspose.Words.FOSSOm in plaats daarvan vanuit de bron te bouwen:
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
Voeg een projectreferentie naar Aspose.Words.csproj toe vanuit uw applicatie. Vanaf daar volgt het werken met de tekenlaag het patroon dat in dit bericht wordt gebruikt: laad of maak een Document, doorloop de vormen met Document.GetChildNodes(NodeType.Shape, true) of voeg een nieuwe toe met een DocumentBuilder methode zoals DocumentBuilder.InsertImage(), DocumentBuilder.InsertGroupShape() of DocumentBuilder.InsertHorizontalRule(), lees vervolgens eigenschappen van of stel ze in op de geretourneerde Shape — Shape.ImageData, Shape.TextBox, Shape.Fill, Shape.Stroke, Shape.WrapType en de rest — voordat u Document.Save() aanroept.
Ondersteunde formaten
| Formaat | Extensie | Lezen | Schrijven |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (alle varianten) | (diverse) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
Deze editie sluit opzettelijk paginalay-out en rendering uit — geen PDF, XPS of afbeeldingsexport, en geen afdrukken — zodat de Shape.Bounds van een vorm en lay-outafhankelijke geometrie de waarden weergeven die in het document zijn opgeslagen in plaats van een berekende paginalay-out. De extra formaatconverters (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3, en WordML) worden niet gelezen of geschreven; dit zijn dezelfde subsystemen die uit de commerciële codebase zijn verwijderd om deze editie gratis te houden.
Open source & licenties
Aspose.Words FOSS voor .NET wordt uitgebracht onder de MIT-licentie, gratis voor zowel commercieel als persoonlijk gebruik zonder royalty’s of beperkingen op herdistributie. De volledige broncode is beschikbaar op GitHub in de Aspose.Words FOSS voor .NET repository.
