Wprowadzenie
Dokumenty Word umieszczają obrazy, pola tekstowe i inne swobodnie unoszące się obiekty w warstwie rysunku, która znajduje się poza regularnym przepływem akapitów i tabel. Aspose.Words FOSS dla .NET udostępnia tę warstwę rysunku poprzez klasy Shape i ShapeBase, zapewniając programowy dostęp do tego samego modelu AutoShape, obrazu, pola tekstowego i obiektu OLE, którego Word używa wewnętrznie. Ten przewodnik pokazuje, jak biblioteka reprezentuje i manipuluje tymi obiektami rysunkowymi — pozycjonowanie, formatowanie wypełnienia i konturu, osadzone obrazy oraz tekst rozmieszczony wewnątrz kształtu — w dokumentach DOCX, DOCM, DOTX i DOTM.
Jest to przydatne dla kodu, który tworzy szablony raportów lub papeterii firmowej z umieszczonym logo lub grafiką, generuje dokumenty z unoszącymi się polami tekstowymi i adnotacjami, lub analizuje kształty już obecne w przesłanym dokumencie — wyodrębniając bajty osadzonego obrazu, odczytując nazwisko podpisującego w linii podpisu lub zmieniając pozycję istniejącego obrazu.
Aspose.Words FOSS dla .NET jest wydany na licencji MIT i celuje w .NET Standard 2.0, więc działa na .NET Framework 4.6.2+ oraz .NET 6, 8 i 10 bez natywnych zależności. Zainstaluj go za pomocą NuGet lub zbuduj ze źródeł (zobacz szybki start poniżej). To ten sam silnik dokumentów Aspose.Words używany komercyjnie, nie przepisana wersja ani wrapper, więc klasy Shape i warstwy rysunku opisane tutaj są produkcyjnym API.
Kluczowe funkcje
Model obiektów Shape i ShapeBase
Każdy AutoShape, pole tekstowe, osadzony obraz, obiekt OLE lub kontrolka ActiveX zakotwiona w dokumencie Word jest reprezentowana przez klasę Shape — zamkniętą i opartą na abstrakcyjnej klasie bazowej ShapeBase. Obie dzielą tę samą powierzchnię pozycjonowania i formatowania: Shape.Left, Shape.Top, Shape.Width, Shape.Height, Shape.Rotation i Shape.ZOrder dla geometrii, oraz flagi Shape.IsGroup, Shape.IsImage, Shape.IsWordArt i Shape.IsInline opisujące, jakiego rodzaju obiekt zawiera dana instancja. Enum ShapeType wylicza konkretne typy kształtów rozpoznawane przez Word — Prostokąt, Elipsa, Linia, Strzałka, rodzina typów adnotacji i łączników, TextBox, Obraz i OleObject spośród ponad osiemdziesięciu wartości — dzięki czemu kod przeglądający kształty dokumentu może rozgałęziać się na podstawie Shape.ShapeType, aby zdecydować, jak obsłużyć każdy z nich. Wiele kształtów może być połączonych w pojedynczy GroupShape, który sam jest podklasą ShapeBase, utrzymując zestaw kształtów pozycjonowanych i skalowanych razem; DocumentBuilder.InsertGroupShape(shapes) tworzy taki zestaw z istniejącej tablicy kształtów.
Pola tekstowe i WordArt
Dowolny Shape może zawierać własny tekst za pośrednictwem klasy TextBox, udostępnionej jako Shape.TextBox. Właściwości TextBox kontrolują, jak ten tekst znajduje się wewnątrz kształtu: TextBox.InternalMarginLeft, TextBox.InternalMarginRight, TextBox.InternalMarginTop i TextBox.InternalMarginBottom dla odstępów, TextBox.FitShapeToText aby pozwolić kształtowi rosnąć wraz z zawartością, LayoutFlow dla kierunku tekstu, TextBoxWrapMode dla sposobu zawijania tekstu w ramce oraz TextBox.VerticalAnchor — wartość TextBoxAnchor taką jak Top, Middle, BottomCentered lub TopBaseline — dla wyrównania pionowego. Połączone pola tekstowe, w których nadmiarowy tekst przechodzi do drugiego pola, są modelowane za pomocą TextBox.Next i TextBox.Previous. Powiązana, ale odrębna klasa, TextPath, definiuje tekst w stylu WordArt, który podąża za konturem kształtu zamiast znajdować się wewnątrz niego, z właściwościami takimi jak TextPath.Text, TextPath.FontFamily, TextPath.Bold i TextPath.RotateLetters, plus wyliczenie TextPathAlignment z wartościami takimi jak Stretch, Center i LetterJustify.
Obrazy i osadzone obrazy
Gdy kształt zawiera obraz, Shape.HasImage jest prawdziwe, a Shape.ImageData zwraca obiekt ImageData. ImageData udostępnia surowe bajty poprzez ImageData.ImageBytes, wykryty format poprzez ImageType (wartości obejmujące Jpeg, Png, Bmp, Gif, Emf, Wmf, Pict, Eps oraz WebP), wymiary pikseli i rozdzielczość poprzez ImageSize, oraz przycinanie za pomocą ImageData.CropTop, ImageData.CropBottom, ImageData.CropLeft i ImageData.CropRight. Regulacje koloru — ImageData.Brightness, ImageData.Contrast, ImageData.GrayScale, ImageData.BiLevel i ImageData.ChromaKey — są właściwościami tego samego obiektu, a ImageData.IsLink/ImageData.IsLinkOnly rozróżniają osadzony obraz od tego, który jedynie odwołuje się do zewnętrznej ścieżki pliku. DocumentBuilder.InsertImage() posiada przeciążenia akceptujące obraz, ścieżkę pliku, tablicę bajtów lub strumień, w tym warianty, które dodatkowo ustawiają explicite szerokość, wysokość, pozycję poziomą i pionową oraz WrapType w momencie wstawiania.
Wypełnienie, obrys i efekty kształtu
Każdy Shape i GroupShape zawiera obiekt Fill oraz obiekt Stroke dla wnętrza i obrysu. Fill obsługuje sześć rodzajów wypełnień poprzez FillType, z wartościami takimi jak Solid, Patterned, Gradient, Textured, Background i Picture, ustawianymi metodami takimi jak Fill.Solid(color), Fill.OneColorGradient(style, variant, degree), Fill.TwoColorGradient(color1, color2, style, variant), Fill.Patterned(patternType) lub Fill.SetImage(fileName). Stroke kontroluje obrys: Stroke.Weight, DashStyle, JoinStyle, EndCap i Stroke.LineStyle (wartość ShapeLineStyle) obejmują samą linię, podczas gdy Stroke.StartArrowType i Stroke.EndArrowType, w połączeniu z wyliczeniami ArrowWidth i ArrowLength, konfigurują groty strzałek na kształtach łączników i linii. Poza wypełnieniem i obrysem, Shape udostępnia cztery dodatkowe obiekty efektów — ShadowFormat, ReflectionFormat, GlowFormat i SoftEdgeFormat — z własnymi właściwościami koloru i przezroczystości dla odpowiadającego efektu wizualnego.
Pozycjonowanie i zawijanie tekstu
Kształty, które unoszą się względem strony lub akapitu, używają RelativeHorizontalPosition i RelativeVerticalPosition do zakotwiczenia się — na przykład do marginesu, strony lub kolumny — w połączeniu z RelativeHorizontalSize i RelativeVerticalSize dla zakotwiczenia rozmiaru, oraz HorizontalAlignment i VerticalAlignment dla prostej pozycjonowania lewo/środek/prawo lub góra/środek/dół. To, jak otaczający tekst reaguje na kształt, jest kontrolowane przez WrapType, z wartościami takimi jak Inline, Square, Tight, TopBottom i None; dla zawijania Square i Tight, WrapSide ogranicza je dodatkowo do Left, Right, Both lub Largest. FlipOrientation odbija kształt w poziomie lub pionie bez zmiany jego współrzędnych, a flagi Shape.AllowOverlap/Shape.BehindText kontrolują, jak kształt współdziała z inną unoszącą się treścią i warstwą tekstu pod nim.
Linia podpisów i linie poziome
Dwa kolejne specjalistyczne rodzaje kształtów żyją w tym samym modelu rysowania. SignatureLine, konfigurowany w momencie wstawiania poprzez SignatureLineOptions (właściwości obejmują SignatureLineOptions.Signer, SignatureLineOptions.SignerTitle, SignatureLineOptions.Email, SignatureLineOptions.Instructions, SignatureLineOptions.ShowDate i SignatureLineOptions.AllowComments), renderuje wizualny blok podpisu widoczny w dokumentach do druku i udostępnia SignatureLine.IsSigned oraz SignatureLine.IsValid po zastosowaniu podpisu — jest to odrębne od kryptograficznej weryfikacji podpisu cyfrowego omawianej gdzie indziej, która działa na podpisanych częściach dokumentu, a nie na samym kształcie. HorizontalRuleFormat obejmuje zwykłą linię podziału wstawianą za pomocą DocumentBuilder.InsertHorizontalRule(), z właściwościami HorizontalRuleFormat.WidthPercent, HorizontalRuleFormat.Height, HorizontalRuleFormat.NoShade, HorizontalRuleFormat.Color i HorizontalRuleFormat.Alignment (ostatnia to wartość HorizontalRuleAlignment).
Szybki start
Aspose.Words FOSS dla .NET jest dostępny poprzez NuGet:
dotnet add package Aspose.Words.FOSSAby zamiast tego zbudować ze źródeł:
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
Dodaj odwołanie do projektu Aspose.Words.csproj z poziomu swojej aplikacji. Stamtąd praca z warstwą rysowania podąża za wzorcem używanym w całym tym poście: wczytaj lub utwórz Document, przejdź po jego kształtach za pomocą Document.GetChildNodes(NodeType.Shape, true) lub wstaw nowy przy użyciu metody DocumentBuilder, takiej jak DocumentBuilder.InsertImage(), DocumentBuilder.InsertGroupShape() lub DocumentBuilder.InsertHorizontalRule(), a następnie odczytaj lub ustaw właściwości zwróconego Shape — Shape.ImageData, Shape.TextBox, Shape.Fill, Shape.Stroke, Shape.WrapType i pozostałe — przed wywołaniem Document.Save().
Obsługiwane formaty
| Format | Rozszerzenie | Odczyt | Zapis |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (wszystkie warianty) | (różne) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
Ta edycja celowo pomija układ strony i renderowanie — brak eksportu do PDF, XPS ani obrazów oraz brak drukowania — tak więc Shape.Bounds kształtu i geometria zależna od układu odzwierciedlają wartości zapisane w dokumencie, a nie obliczony układ strony. Dodatkowe konwertery formatów (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3 i WordML) nie są odczytywane ani zapisywane; są to te same podsystemy usunięte z komercyjnej bazy kodu, aby utrzymać tę edycję darmową.
Open Source i licencjonowanie
Aspose.Words FOSS dla .NET jest udostępniony na licencji MIT, bezpłatny zarówno do użytku komercyjnego, jak i osobistego, bez opłat licencyjnych ani ograniczeń w redystrybucji. Pełne źródło jest dostępne na GitHub w Aspose.Words FOSS dla .NET repository.
