Introducere
Documentele Word plasează imagini, casete de text și alte obiecte libere într-un strat de desen care este separat de fluxul obișnuit al paragrafelor și al tabelelor. Aspose.Words FOSS pentru .NET expune acest strat de desen prin clasele Shape și ShapeBase, oferind acces programatic la același model AutoShape, imagine, casetă de text și obiect OLE pe care Word îl folosește intern. Acest ghid arată cum biblioteca reprezintă și manipulează aceste obiecte de desen — poziționare, format de umplere și contur, imagini încorporate și text așezat în interiorul unei forme — în documentele DOCX, DOCM, DOTX și DOTM.
Acest lucru este util pentru codul care construiește șabloane de rapoarte sau anteturi cu un logo sau grafic poziționat, generează documente cu casete de text și baloane plutitoare, sau inspectează formele deja prezente într-un document încărcat — extragerea byte-urilor unei imagini încorporate, citirea numelui semnatarului dintr-o linie de semnătură sau repoziționarea unei imagini existente.
Aspose.Words FOSS pentru .NET este lansat sub licența MIT și vizează .NET Standard 2.0, astfel încât rulează pe .NET Framework 4.6.2+ și .NET 6, 8 și 10 fără dependențe native. Instalați-l prin NuGet sau construiți-l din sursă (consultați Pornire rapidă de mai jos). Este același motor de documente Aspose.Words utilizat comercial, nu o rescriere sau un wrapper, astfel încât clasele Shape și cele ale stratului de desen descrise aici reprezintă API de producție.
Caracteristici cheie
Modelul de obiecte Shape și ShapeBase
Fiecare AutoShape, casetă de text, imagine încorporată, obiect OLE sau control ActiveX ancorat într-un document Word este reprezentat de clasa Shape — sigilată și construită pe clasa de bază abstractă ShapeBase. Ambele împărtășesc aceeași suprafață de poziționare și formatare: Shape.Left, Shape.Top, Shape.Width, Shape.Height, Shape.Rotation și Shape.ZOrder pentru geometrie, plus steagurile Shape.IsGroup, Shape.IsImage, Shape.IsWordArt și Shape.IsInline care descriu ce tip de obiect deține o anumită instanță. Enumerația ShapeType enumeră tipurile concrete de forme recunoscute de Word — Rectangle, Ellipse, Line, Arrow, o familie de tipuri de baloane și conectori, TextBox, Image și OleObject dintre peste optzeci de valori — astfel încât codul care parcurge formele unui document poate ramifica pe Shape.ShapeType pentru a decide cum să gestioneze fiecare. Mai multe forme pot fi combinate într-un singur GroupShape, care este o subclasă ShapeBase, și păstrează un set de forme poziționate și redimensionate împreună; DocumentBuilder.InsertGroupShape(shapes) creează una dintr-un tablou existent de forme.
Casete de text și WordArt
Orice Shape poate conține propriul său text prin clasa TextBox, expusă ca Shape.TextBox. Proprietățile TextBox controlează modul în care textul este plasat în interiorul formei: TextBox.InternalMarginLeft, TextBox.InternalMarginRight, TextBox.InternalMarginTop și TextBox.InternalMarginBottom pentru spațiere, TextBox.FitShapeToText pentru a permite formei să se mărească odată cu conținutul, LayoutFlow pentru direcția textului, TextBoxWrapMode pentru modul în care textul se înfășoară în interiorul casetei și TextBox.VerticalAnchor — o valoare TextBoxAnchor precum Top, Middle, BottomCentered sau TopBaseline — pentru alinierea verticală. Casetele de text legate, în care textul care depășește continuă într-o a doua casetă, sunt modelate cu TextBox.Next și TextBox.Previous. O clasă înrudită, dar distinctă, TextPath, definește text în stil WordArt care urmează conturul formei în loc să stea în interiorul ei, cu proprietăți cum ar fi TextPath.Text, TextPath.FontFamily, TextPath.Bold și TextPath.RotateLetters, plus un enum TextPathAlignment cu valori precum Stretch, Center și LetterJustify.
Imagini și imagini încorporate
Când o formă conține o imagine, Shape.HasImage este adevărat și Shape.ImageData returnează un obiect ImageData. ImageData expune octeții brute prin ImageData.ImageBytes, formatul detectat prin ImageType (valori incluzând Jpeg, Png, Bmp, Gif, Emf, Wmf, Pict, Eps și WebP), dimensiunile în pixeli și rezoluția prin ImageSize, și decuparea prin ImageData.CropTop, ImageData.CropBottom, ImageData.CropLeft și ImageData.CropRight. Ajustările de culoare — ImageData.Brightness, ImageData.Contrast, ImageData.GrayScale, ImageData.BiLevel și ImageData.ChromaKey — sunt proprietăți ale aceluiași obiect, iar ImageData.IsLink/ImageData.IsLinkOnly diferențiază o imagine încorporată de una care referă doar o cale de fișier externă. DocumentBuilder.InsertImage() are suprasarcini care acceptă o imagine, o cale de fișier, un tablou de octeți sau un flux, inclusiv variante care setează explicit lățimea, înălțimea, poziția orizontală și verticală și WrapType în momentul inserării.
Umplere, Contur și Efecte de formă
Fiecare Shape și GroupShape conține un obiect Fill și un obiect Stroke pentru interior și contur. Fill acceptă șase tipuri de umplere prin FillType, cu valori incluzând Solid, Patterned, Gradient, Textured, Background și Picture, setate cu metode precum Fill.Solid(color), Fill.OneColorGradient(style, variant, degree), Fill.TwoColorGradient(color1, color2, style, variant), Fill.Patterned(patternType) sau Fill.SetImage(fileName). Stroke controlează conturul: Stroke.Weight, DashStyle, JoinStyle, EndCap și Stroke.LineStyle (o valoare ShapeLineStyle) acoperă linia în sine, în timp ce Stroke.StartArrowType și Stroke.EndArrowType, asociate cu enum-urile ArrowWidth și ArrowLength, configurează vârfurile săgeților pe formele de conector și linie. Dincolo de umplere și contur, Shape expune patru obiecte de efect suplimentare — ShadowFormat, ReflectionFormat, GlowFormat și SoftEdgeFormat — fiecare având propriile proprietăți de culoare și transparență pentru efectul vizual corespunzător.
Poziționare și Înfășurare a textului
Formele care plutesc relativ la pagină sau paragraf utilizează RelativeHorizontalPosition și RelativeVerticalPosition pentru a se ancora — la margine, pagină sau coloană, de exemplu — împreună cu RelativeHorizontalSize și RelativeVerticalSize pentru ancorarea dimensiunii, plus HorizontalAlignment și VerticalAlignment pentru plasarea simplă stânga/centru/dreapta sau sus/mijloc/jos. Modul în care textul înconjurător reacționează la o formă este controlat de WrapType, cu valori incluzând Inline, Square, Tight, TopBottom și None; pentru înfășurarea Square și Tight, WrapSide o restrânge și mai mult la Left, Right, Both sau Largest. FlipOrientation oglindește o formă orizontal sau vertical fără a schimba coordonatele, iar steagurile Shape.AllowOverlap/Shape.BehindText controlează cum interacționează forma cu alte conținuturi plutitoare și cu stratul de text de dedesubt.
Linii de semnătură și linii orizontale
Două tipuri de forme specializate suplimentare trăiesc în același model de desen. SignatureLine, configurat la momentul inserării prin SignatureLineOptions (proprietățile includ SignatureLineOptions.Signer, SignatureLineOptions.SignerTitle, SignatureLineOptions.Email, SignatureLineOptions.Instructions, SignatureLineOptions.ShowDate și SignatureLineOptions.AllowComments), redă blocul vizual de semnătură vizibil în documentele tipăribile și expune SignatureLine.IsSigned și SignatureLine.IsValid odată ce o semnătură a fost aplicată — aceasta este distinctă de verificarea criptografică a semnăturii digitale descrisă în altă parte, care lucrează cu părți semnate ale documentului în loc de forma în sine. HorizontalRuleFormat acoperă linia de divizare simplă inserată cu DocumentBuilder.InsertHorizontalRule(), cu proprietățile HorizontalRuleFormat.WidthPercent, HorizontalRuleFormat.Height, HorizontalRuleFormat.NoShade, HorizontalRuleFormat.Color și HorizontalRuleFormat.Alignment (ultima având o valoare HorizontalRuleAlignment).
Pornire rapidă
Aspose.Words FOSS pentru .NET este disponibil prin NuGet:
dotnet add package Aspose.Words.FOSSPentru a construi din sursă în schimb:
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
Adăugați o referință de proiect la Aspose.Words.csproj din aplicația dvs. De acolo, lucrul cu stratul de desen urmează modelul folosit pe tot parcursul acestei postări: încărcați sau creați un Document, parcurgeți formele acestuia cu Document.GetChildNodes(NodeType.Shape, true) sau inserați una nouă cu o metodă DocumentBuilder cum ar fi DocumentBuilder.InsertImage(), DocumentBuilder.InsertGroupShape() sau DocumentBuilder.InsertHorizontalRule(), apoi citiți sau setați proprietăți pe Shape returnat — Shape.ImageData, Shape.TextBox, Shape.Fill, Shape.Stroke, Shape.WrapType și restul — înainte de a apela Document.Save().
Formate suportate
| Format | Extensie | Citește | Scrie |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (toate variantele) | (diverse) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
Această ediție exclude în mod intenționat aranjamentul și redarea paginii — fără export PDF, XPS sau imagine, și fără tipărire — astfel încât Shape.Bounds unei forme și geometria dependentă de aranjament să reflecte valorile stocate în document, nu un aranjament de pagină calculat. Conversoarele de format suplimentare (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3 și WordML) nu sunt citite sau scrise; acestea sunt aceleași subsisteme eliminate din codul comercial pentru a menține această ediție gratuită.
Open Source și Licențiere
Aspose.Words FOSS pentru .NET este lansat sub licența MIT, gratuit pentru utilizare comercială și personală, fără redevențe sau restricții de redistribuire. Codul sursă complet este disponibil pe GitHub în Aspose.Words FOSS pentru depozitul .NET.
