Pendahuluan
Dokumen Word menempatkan gambar, kotak teks, dan objek mengambang lainnya dalam lapisan gambar yang terpisah dari alur reguler paragraf dan tabel. Aspose.Words FOSS untuk .NET mengekspos lapisan gambar ini melalui kelas Shape dan ShapeBase, memberikan akses programatik ke AutoShape, gambar, kotak teks, dan model objek OLE yang sama yang digunakan Word secara internal. Panduan ini menunjukkan bagaimana perpustakaan merepresentasikan dan memanipulasi objek gambar ini — penempatan, format isian dan garis tepi, gambar tersemat, serta teks yang ditata di dalam bentuk — pada dokumen DOCX, DOCM, DOTX, dan DOTM.
Ini berguna untuk kode yang membuat templat laporan atau kop surat dengan logo atau grafik yang diposisikan, menghasilkan dokumen dengan kotak teks mengambang dan callout, atau memeriksa bentuk yang sudah ada dalam dokumen yang diunggah — mengekstrak byte gambar tersemat, membaca nama penandatangan pada baris tanda tangan, atau memindahkan posisi gambar yang ada.
Aspose.Words FOSS untuk .NET dirilis di bawah lisensi MIT dan menargetkan .NET Standard 2.0, sehingga dapat berjalan pada .NET Framework 4.6.2+ dan .NET 6, 8, dan 10 tanpa ketergantungan native. Instal melalui NuGet, atau bangun dari sumber (lihat Panduan Cepat di bawah). Ini adalah mesin dokumen Aspose.Words yang sama yang digunakan secara komersial, bukan penulisan ulang atau pembungkus, sehingga kelas Shape dan lapisan gambar yang dijelaskan di sini adalah API produksi.
Fitur Utama
Model Objek Bentuk dan ShapeBase
Setiap AutoShape, kotak teks, gambar tersemat, objek OLE, atau kontrol ActiveX yang dijajarkan dalam dokumen Word direpresentasikan oleh kelas Shape — sealed, dan dibangun di atas kelas dasar abstrak ShapeBase. Keduanya berbagi permukaan penempatan dan format yang sama: Shape.Left, Shape.Top, Shape.Width, Shape.Height, Shape.Rotation, dan Shape.ZOrder untuk geometri, serta flag Shape.IsGroup, Shape.IsImage, Shape.IsWordArt, dan Shape.IsInline yang menjelaskan jenis objek yang dimiliki suatu instance. Enum ShapeType mencantumkan jenis bentuk konkret yang dikenali Word — Persegi Panjang, Elips, Garis, Panah, keluarga tipe callout dan connector, TextBox, Gambar, dan OleObject di antara lebih dari delapan puluh nilai — sehingga kode yang menelusuri bentuk dokumen dapat bercabang pada Shape.ShapeType untuk memutuskan cara menangani masing-masing. Beberapa bentuk dapat digabung menjadi satu GroupShape, yang sendiri merupakan subclass ShapeBase, yang menjaga sekumpulan bentuk diposisikan dan diubah ukuran secara bersamaan; DocumentBuilder.InsertGroupShape(shapes) membangun satu dari array bentuk yang ada.
Kotak Teks dan WordArt
Setiap Shape dapat membawa teksnya sendiri melalui kelas TextBox, yang diekspos sebagai Shape.TextBox. Properti TextBox mengontrol bagaimana teks tersebut duduk di dalam bentuk: TextBox.InternalMarginLeft, TextBox.InternalMarginRight, TextBox.InternalMarginTop, dan TextBox.InternalMarginBottom untuk padding, TextBox.FitShapeToText untuk membiarkan bentuk tumbuh dengan kontennya, LayoutFlow untuk arah teks, TextBoxWrapMode untuk cara teks melilit di dalam kotak, dan TextBox.VerticalAnchor — nilai TextBoxAnchor seperti Top, Middle, BottomCentered, atau TopBaseline — untuk perataan vertikal. Kotak teks yang terhubung, di mana teks berlebih berlanjut ke kotak kedua, dimodelkan dengan TextBox.Next dan TextBox.Previous. Kelas terkait namun berbeda, TextPath, mendefinisikan teks gaya WordArt yang mengikuti kontur bentuk alih-alih berada di dalamnya, dengan properti seperti TextPath.Text, TextPath.FontFamily, TextPath.Bold, dan TextPath.RotateLetters, serta enum TextPathAlignment dengan nilai seperti Stretch, Center, dan LetterJustify.
Gambar dan Gambar Tersemat
Ketika sebuah bentuk memuat gambar, Shape.HasImage bernilai true dan Shape.ImageData mengembalikan objek ImageData. ImageData mengekspos byte mentah melalui ImageData.ImageBytes, format yang terdeteksi melalui ImageType (nilai termasuk Jpeg, Png, Bmp, Gif, Emf, Wmf, Pict, Eps, dan WebP), dimensi piksel dan resolusi melalui ImageSize, serta pemotongan melalui ImageData.CropTop, ImageData.CropBottom, ImageData.CropLeft, dan ImageData.CropRight. Penyesuaian warna — ImageData.Brightness, ImageData.Contrast, ImageData.GrayScale, ImageData.BiLevel, dan ImageData.ChromaKey — adalah properti pada objek yang sama, dan ImageData.IsLink/ImageData.IsLinkOnly membedakan gambar tersemat dari yang hanya merujuk ke jalur file eksternal. DocumentBuilder.InsertImage() memiliki overload yang menerima gambar, jalur file, array byte, atau stream, termasuk varian yang juga menetapkan lebar, tinggi, posisi horizontal dan vertikal secara eksplisit, serta WrapType pada saat penyisipan.
Isian, Garis, dan Efek Bentuk
Setiap Shape dan GroupShape memiliki objek Fill dan objek Stroke untuk interior dan kontur. Fill mendukung enam jenis isian melalui FillType, dengan nilai termasuk Solid, Patterned, Gradient, Textured, Background, dan Picture, yang diatur dengan metode seperti Fill.Solid(color), Fill.OneColorGradient(style, variant, degree), Fill.TwoColorGradient(color1, color2, style, variant), Fill.Patterned(patternType), atau Fill.SetImage(fileName). Stroke mengontrol kontur: Stroke.Weight, DashStyle, JoinStyle, EndCap, dan Stroke.LineStyle (nilai ShapeLineStyle) mencakup garis itu sendiri, sementara Stroke.StartArrowType dan Stroke.EndArrowType, dipasangkan dengan enum ArrowWidth dan ArrowLength, mengonfigurasi kepala panah pada bentuk penghubung dan garis. Selain isian dan kontur, Shape mengekspos empat objek efek tambahan — ShadowFormat, ReflectionFormat, GlowFormat, dan SoftEdgeFormat — masing-masing membawa properti warna dan transparansi sendiri untuk efek visual yang bersangkutan.
Posisi dan Pembungkus Teks
Bentuk yang mengambang relatif terhadap halaman atau paragraf menggunakan RelativeHorizontalPosition dan RelativeVerticalPosition untuk menambatkannya — ke margin, halaman, atau kolom, misalnya — dipasangkan dengan RelativeHorizontalSize dan RelativeVerticalSize untuk penambatan ukuran, serta HorizontalAlignment dan VerticalAlignment untuk penempatan sederhana kiri/tengah/kanan atau atas/tengah/bawah. Cara teks di sekitarnya bereaksi terhadap sebuah bentuk dikendalikan oleh WrapType, dengan nilai termasuk Inline, Square, Tight, TopBottom, dan None; untuk pembungkus Square dan Tight, WrapSide mempersempitnya lebih jauh menjadi Left, Right, Both, atau Largest. FlipOrientation mencerminkan bentuk secara horizontal atau vertikal tanpa mengubah koordinatnya, dan flag Shape.AllowOverlap/Shape.BehindText mengontrol bagaimana sebuah bentuk berinteraksi dengan konten mengambang lainnya serta lapisan teks di bawahnya.
Garis Tanda Tangan dan Garis Horizontal
Dua jenis bentuk khusus lainnya berada dalam model gambar yang sama. SignatureLine, yang dikonfigurasi pada saat penyisipan melalui SignatureLineOptions (properti termasuk SignatureLineOptions.Signer, SignatureLineOptions.SignerTitle, SignatureLineOptions.Email, SignatureLineOptions.Instructions, SignatureLineOptions.ShowDate, dan SignatureLineOptions.AllowComments), menampilkan blok tanda tangan visual yang terlihat di dokumen yang dapat dicetak dan mengekspos SignatureLine.IsSigned serta SignatureLine.IsValid setelah tanda tangan diterapkan padanya — ini berbeda dari verifikasi tanda tangan digital kriptografis yang dibahas di tempat lain, yang bekerja dengan bagian dokumen yang ditandatangani bukan bentuk itu sendiri. HorizontalRuleFormat mencakup garis pemisah polos yang disisipkan dengan DocumentBuilder.InsertHorizontalRule(), dengan properti HorizontalRuleFormat.WidthPercent, HorizontalRuleFormat.Height, HorizontalRuleFormat.NoShade, HorizontalRuleFormat.Color, dan HorizontalRuleFormat.Alignment (yang terakhir adalah nilai HorizontalRuleAlignment).
Panduan Cepat
Aspose.Words FOSS untuk .NET tersedia melalui NuGet:
dotnet add package Aspose.Words.FOSSUntuk membangun dari sumber sebagai gantinya:
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
Tambahkan referensi proyek ke Aspose.Words.csproj dari aplikasi Anda. Dari sana, bekerja dengan lapisan gambar mengikuti pola yang digunakan sepanjang posting ini: muat atau buat Document, telusuri bentuk-bentuknya dengan Document.GetChildNodes(NodeType.Shape, true) atau sisipkan yang baru dengan metode DocumentBuilder seperti DocumentBuilder.InsertImage(), DocumentBuilder.InsertGroupShape(), atau DocumentBuilder.InsertHorizontalRule(), kemudian baca atau atur properti pada Shape yang dikembalikan — Shape.ImageData, Shape.TextBox, Shape.Fill, Shape.Stroke, Shape.WrapType, dan lainnya — sebelum memanggil Document.Save().
Format yang Didukung
| Format | Ekstensi | Baca | Tulis |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (semua varian) | (berbagai) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
Edisi ini sengaja mengecualikan tata letak halaman dan rendering — tidak ada PDF, XPS, atau ekspor gambar, dan tidak ada pencetakan — sehingga Shape.Bounds bentuk dan geometri yang bergantung pada tata letak mencerminkan nilai yang disimpan dalam dokumen daripada tata letak halaman yang dihitung. Konverter format tambahan (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3, dan WordML) tidak dibaca atau ditulis; ini adalah subsistem yang sama yang dihapus dari basis kode komersial untuk menjaga edisi ini gratis.
Sumber Terbuka & Lisensi
Aspose.Words FOSS untuk .NET dirilis di bawah lisensi MIT, gratis untuk penggunaan komersial maupun pribadi tanpa royalti atau pembatasan redistribusi. Sumber lengkap tersedia di GitHub dalam Aspose.Words FOSS untuk repositori .NET.
