Bevezetés
A Word-dokumentumok képeket, szövegdobozokat és egyéb szabadon lebegő objektumokat helyeznek el egy rajzrétegben, amely a bekezdések és táblázatok normál folyamától elkülönül. Aspose.Words FOSS a .NET számára a Shape és ShapeBase osztályokon keresztül teszi láthatóvá ezt a rajzréteget, lehetővé téve a programozott hozzáférést ugyanahhoz a AutoShape, kép, szövegdoboz és OLE-objektum modellhez, amelyet a Word belsőleg használ. Ez az útmutató bemutatja, hogyan ábrázolja és kezeli a könyvtár ezeket a rajzobjektumokat – pozicionálás, kitöltés és körvonal formázása, beágyazott képek, valamint egy alakzatba elrendezett szöveg – a DOCX, DOCM, DOTX és DOTM dokumentumokban.
Ez hasznos olyan kódok számára, amelyek jelentés- vagy fejléces sablonokat építenek fel elhelyezett logóval vagy grafikával, lebegő szövegdobozokkal és felhívásokkal ellátott dokumentumokat generálnak, vagy ellenőrzik a feltöltött dokumentumban már meglévő alakzatokat – például egy beágyazott kép bájtjainak kinyerése, aláírási sor aláírójának nevének olvasása, vagy egy meglévő kép újrapozicionálása.
A Aspose.Words FOSS a .NET számára MIT licenc alatt kerül kiadásra, és a .NET Standard 2.0-t célozza, így fut a .NET Framework 4.6.2+ és a .NET 6, 8 és 10 környezeteken, natív függőségek nélkül. Telepíthető a NuGet segítségével, vagy lefordítható forráskódból (lásd alább a Gyors kezdést). Ez ugyanaz a Aspose.Words dokumentummotor, amelyet kereskedelmi célra használnak, nem egy átirat vagy wrapper, ezért a leírt Shape és rajzréteg osztályok a gyártási API.
Főbb jellemzők
Az Alakzat és a ShapeBase objektummodell
Minden AutoShape, szövegdoboz, beágyazott kép, OLE-objektum vagy ActiveX vezérlő, amely egy Word-dokumentumban rögzítve van, a Shape osztály által van reprezentálva – lezárt, és az absztrakt ShapeBase alaposztályra épül. Mindkettő ugyanazt a pozicionálási és formázási felületet használja: Shape.Left, Shape.Top, Shape.Width, Shape.Height, Shape.Rotation és Shape.ZOrder a geometria számára, valamint Shape.IsGroup, Shape.IsImage, Shape.IsWordArt és Shape.IsInline jelzők, amelyek leírják, milyen típusú objektumot tartalmaz egy adott példány. A ShapeType felsoroló (enum) felsorolja a Word által felismert konkrét alakzattípusokat – Téglalap, Ellipszis, Vonal, Nyíl, egy sor felhívás- és összekötő típus, TextBox, Kép és OleObject több mint nyolcvan érték közül – így a dokumentum alakzatait bejáró kód a Shape.ShapeType alapján elágazhat, hogy hogyan kezelje az egyes elemeket. Több alakzat kombinálható egyetlen GroupShape-be, amely maga egy ShapeBase alosztály, és egy alakzathalmazt tart pozícionáltan és méretezve együtt; a DocumentBuilder.InsertGroupShape(shapes) egy meglévő alakzattömbből épít egy ilyenet.
Szövegmezők és WordArt
Bármely Shape saját szöveget hordozhat a TextBox osztályon keresztül, amely Shape.TextBox néven érhető el. A TextBox tulajdonságok szabályozzák, hogyan helyezkedik el ez a szöveg a forma belsejében: TextBox.InternalMarginLeft, TextBox.InternalMarginRight, TextBox.InternalMarginTop és TextBox.InternalMarginBottom a kitöltéshez, TextBox.FitShapeToText a forma tartalommal való növekedéséhez, LayoutFlow a szövegirányhoz, TextBoxWrapMode a szöveg dobozon belüli tördeléséhez, valamint TextBox.VerticalAnchor — egy TextBoxAnchor érték, például Top, Middle, BottomCentered vagy TopBaseline — a függőleges igazításhoz. A kapcsolt szövegmezőket, ahol a túlcsorduló szöveg egy második mezőbe folytatódik, a TextBox.Next és TextBox.Previous modellezi. Egy kapcsolódó, de különálló osztály, a TextPath, WordArt-stílusú szöveget definiál, amely a forma körvonalát követi ahelyett, hogy belül helyezkedne el, olyan tulajdonságokkal, mint TextPath.Text, TextPath.FontFamily, TextPath.Bold és TextPath.RotateLetters, valamint egy TextPathAlignment enumerációval, amelynek értékei például Stretch, Center és LetterJustify.
Képek és beágyazott képek
Amikor egy forma képet tartalmaz, a Shape.HasImage igaz, és a Shape.ImageData egy ImageData objektumot ad vissza. A ImageData a nyers bájtokat a ImageData.ImageBytes segítségével, a felismert formátumot a ImageType (értékek: Jpeg, Png, Bmp, Gif, Emf, Wmf, Pict, Eps és WebP) révén, a képpontméreteket és felbontást a ImageSize segítségével, valamint a vágást a ImageData.CropTop, ImageData.CropBottom, ImageData.CropLeft és ImageData.CropRight által teszi elérhetővé. A színkorrekciók — ImageData.Brightness, ImageData.Contrast, ImageData.GrayScale, ImageData.BiLevel és ImageData.ChromaKey — ugyanazon objektum tulajdonságai, és a ImageData.IsLink/ImageData.IsLinkOnly megkülönböztetik a beágyazott képet azoktól, amelyek csak egy külső fájlútra hivatkoznak. A DocumentBuilder.InsertImage() több overloaddal rendelkezik, amelyek képet, fájlútvonalat, bájt tömböt vagy streamet fogadnak, beleértve olyan változatokat is, amelyek explicit szélességet, magasságot, vízszintes és függőleges pozíciót, valamint a beszúráskor a WrapType értéket is beállítják.
Kitöltés, Körvonal és Alakhatás
Minden Shape és GroupShape egy Fill objektumot és egy Stroke objektumot tartalmaz a belső rész és a körvonal számára. A Fill hat kitöltéstípust támogat a FillType segítségével, amelyek értékei között szerepel a Solid, Patterned, Gradient, Textured, Background és Picture, és beállíthatók olyan módszerekkel, mint a Fill.Solid(color), Fill.OneColorGradient(style, variant, degree), Fill.TwoColorGradient(color1, color2, style, variant), Fill.Patterned(patternType) vagy Fill.SetImage(fileName). A Stroke a körvonalat szabályozza: Stroke.Weight, DashStyle, JoinStyle, EndCap és Stroke.LineStyle (egy ShapeLineStyle érték) a vonalat fedik le, míg a Stroke.StartArrowType és Stroke.EndArrowType, a ArrowWidth és ArrowLength enumokkal párosítva, a nyílhegyeket konfigurálják a csatlakozó és vonal alakzatokon. A kitöltésen és körvonalon túl a Shape négy további hatásobjektust tár fel — ShadowFormat, ReflectionFormat, GlowFormat és SoftEdgeFormat — amelyek mindegyike saját szín- és átlátszósági tulajdonságokkal rendelkezik a megfelelő vizuális hatáshoz.
Pozicionálás és Szövegtördelés
A laphoz vagy bekezdéshez képest lebegő alakzatok a RelativeHorizontalPosition és RelativeVerticalPosition segítségével rögzítik magukat — például a margóhoz, oldalhoz vagy oszlophoz — és a RelativeHorizontalSize és RelativeVerticalSize a méret rögzítésére, plusz a HorizontalAlignment és VerticalAlignment egyszerű bal/közép/jobbra vagy felül/közép/alul elhelyezésre szolgálnak. A környező szöveg alakzatra adott reakcióját a WrapType szabályozza, értékei közé tartozik az Inline, Square, Tight, TopBottom és None; a Square és Tight tördelés esetén a WrapSide tovább szűkíti azt Left, Right, Both vagy Largest értékekre. A FlipOrientation vízszintesen vagy függőlegesen tükrözi az alakzatot anélkül, hogy megváltoztatná a koordinátákat, és a Shape.AllowOverlap/Shape.BehindText jelzők határozzák meg, hogyan lép kölcsönhatásba az alakzat más lebegő tartalmakkal és az alatta lévő szövegréteggel.
Aláírási sorok és vízszintes elválasztók
Két további speciális alakzat típus él a ugyanabban a rajzolási modellben. SignatureLine, amely beillesztéskor SignatureLineOptions segítségével konfigurálható (tulajdonságai között szerepelnek a SignatureLineOptions.Signer, SignatureLineOptions.SignerTitle, SignatureLineOptions.Email, SignatureLineOptions.Instructions, SignatureLineOptions.ShowDate és a SignatureLineOptions.AllowComments), megjeleníti a nyomtatható dokumentumokban látható vizuális aláírásblokkot, és elérhetővé teszi a SignatureLine.IsSigned és SignatureLine.IsValid értékeket, miután aláírás került rá – ez eltér a máshol tárgyalt kriptográfiai digitális aláírás-ellenőrzéstől, amely az aláírt dokumentumrészekkel dolgozik, nem pedig magával az alakzattal. HorizontalRuleFormat a DocumentBuilder.InsertHorizontalRule() segítségével beszúrt egyszerű elválasztó vonalat fedi le, a HorizontalRuleFormat.WidthPercent, HorizontalRuleFormat.Height, HorizontalRuleFormat.NoShade, HorizontalRuleFormat.Color és HorizontalRuleFormat.Alignment tulajdonságokkal (az utolsó egy HorizontalRuleAlignment érték).
Gyors kezdés
Aspose.Words FOSS a .NET számára elérhető a NuGet segítségével:
dotnet add package Aspose.Words.FOSSA forrásból való építéshez:
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
Adjon hozzá egy projektreferenciát a Aspose.Words.csproj komponenshez az alkalmazásából. Ettől kezdve a rajzréteggel való munka a bejegyzésben végighasznált mintát követi: töltse be vagy hozza létre a Document elemet, járja be annak alakzatait a Document.GetChildNodes(NodeType.Shape, true) segítségével, vagy szúrjon be egy újat egy DocumentBuilder módszerrel, például a DocumentBuilder.InsertImage(), DocumentBuilder.InsertGroupShape() vagy DocumentBuilder.InsertHorizontalRule() használatával, majd olvassa vagy állítsa be a visszakapott Shape tulajdonságait – Shape.ImageData, Shape.TextBox, Shape.Fill, Shape.Stroke, Shape.WrapType és a továbbiak – mielőtt meghívná a Document.Save().
Támogatott formátumok
| Formátum | Kiterjesztés | Olvasás | Írás |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (összes változat) | (különböző) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
Ez a kiadás szándékosan kizárja az oldaltervezést és a renderelést — nincs PDF, XPS vagy képexport, és nincs nyomtatás — így egy alakzat Shape.Bounds és az elrendezéstől függő geometria a dokumentumban tárolt értékeket tükrözi, nem egy számított oldaltervet. A további formátumkonverterek (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3 és WordML) nem olvashatók vagy írhatók; ezek ugyanazok a részrendszerek, amelyeket a kereskedelmi kódbázisból eltávolítottak, hogy ez a kiadás ingyenes maradjon.
Nyílt forráskód és licencelés
Aspose.Words FOSS a(z) .NET számára MIT licenc alatt kerül kiadásra, kereskedelmi és személyes használatra egyaránt ingyenes, jogdíj vagy terjesztési korlátozás nélkül. A teljes forrás elérhető a GitHub címen a Aspose.Words FOSS a(z) .NET tárolóban.
