Cara Bekerja dengan Structured Document Tags di .NET

Langkah 1: Instal Paket

Aspose.Words FOSS untuk .NET belum mempublikasikan paket NuGet – bangun perpustakaan dari sumbernya. Klon https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git, lalu bangun Aspose.Words.sln dalam konfigurasi Release dengan SDK .NET dan referensikan assembly Aspose.Words yang dihasilkan dari proyek Anda. Perpustakaan menargetkan .NET Standard 2.0, sehingga dapat dijalankan pada .NET Framework 4.6.2+ dan .NET 6/8/10.

Langkah 2: Impor Kelas yang Diperlukan

Tambahkan direktif using Aspose.Words; untuk Document dan DocumentBuilder, serta direktif using Aspose.Words.Markup; untuk StructuredDocumentTag, SdtType, SdtListItem, SdtListItemCollection, XmlMapping, dan kelas content-control lainnya yang dibahas dalam panduan ini.

Langkah 3: Periksa Jenis Kontrol-Konten yang Dapat Anda Sisipkan

Sebelum menyisipkan, periksa apakah target SdtType merupakan salah satu dari tujuh jenis yang diterima oleh DocumentBuilder.InsertStructuredDocumentTag(SdtType): PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture, dan Date. RepeatingSection dan RepeatingSectionItem tidak dapat disisipkan pada kursor teks dengan metode ini — mereka membungkus seluruh paragraf atau baris tabel sebagai gantinya. Nilai SdtType yang tersisa yang dapat muncul dalam file Word tetapi tidak ada di UI Word sebagai jenis yang dapat disisipkan — None, Bibliography, Citation, Equation, BuildingBlockGallery, DocPartObj, Group, dan EntityPicker — tidak diterima oleh metode penyisipan ini sama sekali.

Langkah 4: Sisipkan Kontrol Konten pada Kursor

Panggil DocumentBuilder.InsertStructuredDocumentTag(SdtType) dengan salah satu dari tujuh jenis yang didukung untuk menyisipkan kontrol baru pada posisi kursor saat ini milik pembangun; panggilan tersebut mengembalikan StructuredDocumentTag yang baru. Atur Tag dan Title pada kontrol yang dikembalikan untuk memberikan string identifikasi yang dilihat penulis di Word, dan atur PlaceholderName (didukung oleh Placeholder BuildingBlock) untuk teks petunjuk yang ditampilkan Word saat kontrol kosong — IsShowingPlaceholderText melaporkan apakah petunjuk tersebut sedang ditampilkan.

Langkah 5: Konfigurasikan Konten Spesifik Tipe

Untuk kontrol kotak centang, baca atau atur StructuredDocumentTag.Checked, dan panggil SetCheckedSymbol() / SetUncheckedSymbol() untuk menyesuaikan glif yang ditampilkan untuk setiap status. Untuk kontrol tanggal, atur FullDate, dengan DateDisplayFormat dan DateDisplayLocale mengendalikan cara tampilannya, DateStorageFormat (SdtDateStorageFormat) mengendalikan cara penyimpanannya ketika terikat pada data XML, dan CalendarType (SdtCalendarType) memilih sistem kalender. Untuk daftar drop-down atau kotak kombo, isi ListItems — sebuah SdtListItemCollection dari SdtListItem (DisplayText, Value) — sebelum mengatur SelectedValue untuk memilih pilihan aktif. Untuk kontrol teks polos, Multiline adalah properti bool pada StructuredDocumentTag yang dapat diatur untuk mengkonfigurasi kontrol.

Langkah 6: Penampilan dan Penguncian Kontrol

Atur Appearance (SdtAppearance) untuk mengendalikan bagaimana kontrol dibatasi secara visual di Word, dan Color untuk mengatur warna sorotnya. ContentsFont dan EndCharacterFont mengendalikan font yang diterapkan pada isi kontrol dan karakter akhir yang menempel. LockContentControl dan LockContents adalah saklar independen — atur LockContentControl untuk memblokir penghapusan kontrol itu sendiri, dan LockContents untuk memblokir penyuntingan isi di dalamnya, tanpa memengaruhi yang lain.

Langkah 7: Temukan dan Hapus Kontrol Konten

Baca Range.StructuredDocumentTags – sebuah StructuredDocumentTagCollection yang berskala pada rentang tersebut – dan panggil GetById(), GetByTag(), atau GetByTitle() untuk menemukan kontrol tertentu, atau Remove() / RemoveAt() pada koleksi untuk menghapus satu berdasarkan referensi atau indeks. Pada kontrol individual, panggil Remove() untuk menghapus kontrol beserta isinya, RemoveSelfOnly() untuk menghapus hanya pembungkus sambil mempertahankan isinya di dokumen, atau Clear() untuk mengosongkan isinya sambil mempertahankan kontrol itu sendiri di tempat.

Langkah 8: Kaitkan Kontrol ke Data XML Kustom

Baca StructuredDocumentTag.XmlMapping – sebuah instance XmlMapping – dan panggil SetMapping(customXmlPart, xPath, prefixMapping) untuk mengaitkan kontrol ke bagian XML kustom yang sudah ada di penyimpanan data XML kustom dokumen, menggunakan ekspresi XPath untuk memilih elemen yang terikat. XmlMapping.IsMapped melaporkan apakah sebuah pengikatan saat ini aktif, CustomXmlPart dan StoreItemId mengidentifikasi bagian data yang terikat, dan Delete() menghapus pemetaan.

Langkah 9: Tangani Kontrol Konten yang Melintasi Beberapa Seksi

Sebuah kontrol konten yang melintasi lebih dari satu seksi dokumen – dilaporkan oleh IsMultiSection – tidak direpresentasikan oleh satu node StructuredDocumentTag melainkan oleh pasangan StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd, yang terhubung melalui StructuredDocumentTagRangeStart.RangeEnd. Programkan terhadap antarmuka IStructuredDocumentTag bersama (Tag, Title, Placeholder, PlaceholderName, Appearance, IsShowingPlaceholderText, RemoveSelfOnly()) ketika kode perlu menangani kedua bentuk node tunggal dan rentang secara seragam, alih-alih bercabang berdasarkan tipe konkret.