Bekerja dengan Tag Dokumen Terstruktur (Kontrol Konten)

Bekerja dengan Tag Dokumen Terstruktur (Kontrol Konten)

Tag dokumen terstruktur (SDT), yang dikenal di UI Word sebagai kontrol konten, membungkus sepotong konten dokumen dengan perilaku penyuntingan yang bertipe dan terbatas – kotak centang, pemilih tanggal, daftar drop-down, atau placeholder teks biasa atau teks kaya. Aspose.Words FOSS untuk .NET memodelkan ini melalui Aspose.Words.Markup namespace, dipimpin oleh StructuredDocumentTag kelas. Halaman ini mencakup penyisipan kontrol konten, mengonfigurasi setiap tipe, menemukan dan menghapusnya, serta mengaitkannya dengan data XML khusus.

Model Objek Tag Dokumen Terstruktur

StructuredDocumentTag adalah CompositeNode yang juga mengimplementasikan IMarkupNode, ITrackableNode, dan IStructuredDocumentTag. SdtType mengidentifikasi jenis kontrol apa itu. Tag dan Title menyimpan string pengenal yang ditetapkan penulis di Word; Placeholder (sebuah BuildingBlock) dan PlaceholderName menyediakan teks petunjuk yang ditampilkan ketika kontrol kosong, dilaporkan melalui IsShowingPlaceholderText. LockContentControl mencegah kontrol dihapus, dan LockContents mencegah isinya disunting, secara independen satu sama lain.

Menyisipkan Kontrol Konten

DocumentBuilder.InsertStructuredDocumentTag(SdtType) menyisipkan kontrol baru pada kursor, tetapi hanya untuk tujuh nilai SdtType: PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture, dan Date. RepeatingSection dan RepeatingSectionItem tidak dapat disisipkan pada kursor teks dengan cara ini — mereka membungkus seluruh paragraf atau baris tabel sebagai gantinya. Nilai SdtType yang tersisa yang muncul dalam berkas Word tetapi tidak ada di UI Word sebagai tipe yang dapat disisipkan — None, Bibliography, Citation, Equation, BuildingBlockGallery, DocPartObj, Group, dan EntityPicker — tidak didukung oleh metode penyisipan ini.

Konten Spesifik Tipe

Status kontrol kotak centang adalah StructuredDocumentTag.Checked; SetCheckedSymbol() dan SetUncheckedSymbol() mengatur glif yang ditampilkan untuk setiap status. Kontrol tanggal menyimpan nilainya di FullDate, dengan DateDisplayFormat dan DateDisplayLocale mengendalikan cara penampilannya, DateStorageFormat (sebuah SdtDateStorageFormat) mengendalikan cara penyimpanannya ketika terikat pada data XML, dan CalendarType (sebuah SdtCalendarType) memilih sistem kalender. Daftar drop-down atau kotak kombo menampilkan pilihannya melalui ListItems, sebuah SdtListItemCollection dari SdtListItem (DisplayText, Value) dengan SelectedValue. Properti Multiline pada kontrol teks biasa memungkinkan atau melarang jeda baris di dalamnya.

Penampilan dan Penguncian

Appearance (SdtAppearance) mengontrol cara kontrol tersebut dibatasi secara visual di Word. Color menentukan warna sorotannya, dan ContentsFont / EndCharacterFont mengendalikan font yang diterapkan pada isinya serta karakter akhir yang melekat. LockContentControl dan LockContents adalah saklar independen — yang pertama mencegah penghapusan kontrol itu sendiri, yang kedua mencegah penyuntingan isi di dalamnya.

Menemukan dan Menghapus Kontrol Konten

Range.StructuredDocumentTags mengembalikan sebuah StructuredDocumentTagCollection yang cakupannya terbatas pada rentang tersebut, dengan GetById(), GetByTag(), dan GetByTitle() untuk pencarian terarah bersama Remove() dan RemoveAt(). Pada StructuredDocumentTag individu, Remove() menghapus kontrol beserta isinya, RemoveSelfOnly() hanya menghapus pembungkus dan mempertahankan isinya dalam dokumen, dan Clear() mengosongkan isi kontrol sambil mempertahankan kontrol itu sendiri.

Pengikatan Data XML

StructuredDocumentTag.XmlMapping adalah sebuah instance XmlMapping yang menggambarkan pengikatan ke bagian XML khusus dalam dokumen: CustomXmlPart, XPath, PrefixMappings, StoreItemId, dan IsMapped. SetMapping() menetapkan pengikatan ke bagian XML khusus yang sudah ada dan Delete() menghapusnya.

Kontrol Konten Multi-Bagian (Berjangkauan)

Kontrol konten yang melintasi lebih dari satu bagian – dilaporkan oleh IsMultiSection – tidak direpresentasikan oleh satu node StructuredDocumentTag melainkan oleh sepasang node StructuredDocumentTagRangeStart dan StructuredDocumentTagRangeEnd, yang terhubung melalui StructuredDocumentTagRangeStart.RangeEnd. Baik bentuk satu-node maupun bentuk rentang mengimplementasikan antarmuka umum IStructuredDocumentTag, sehingga kode yang hanya membutuhkan Tag, Title, SdtType, Placeholder, dan properti identifikasi serupa dapat bekerja dengan kedua bentuk secara seragam.

Tips dan Praktik Terbaik

• Periksa daftar tipe yang didukung oleh DocumentBuilder.InsertStructuredDocumentTag() sebelum mengandalkannya – hanya PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture, dan Date yang dapat disisipkan pada kursor; tipe lain akan melempar pengecualian.
• Gunakan RemoveSelfOnly() alih-alih Remove() ketika Anda ingin “meratakan” sebuah kontrol konten – pertahankan isinya di dalam dokumen tetapi hilangkan pembungkus kontrol.
• Isi ListItems sebelum Anda mengharapkan kontrol DropDownList atau ComboBox menampilkan pilihan, dan atur SelectedValue untuk memilih yang aktif.
• Program terhadap IStructuredDocumentTag alih-alih langsung ke StructuredDocumentTag jika kode Anda perlu menangani baik kontrol konten biasa maupun multi-bagian (rentang) dengan cara yang sama.
• XmlMapping.SetMapping() terikat pada bagian XML khusus yang harus sudah ada di penyimpanan data XML khusus dokumen — tambahkan atau muat data XML sebelum memetakan kontrol ke sana.

Masalah Umum

FAQ

Jenis kontrol konten apa yang dapat saya sisipkan secara langsung dengan DocumentBuilder?

PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture, dan Date. Nilai SdtType lainnya tidak didukung oleh InsertStructuredDocumentTag().

Bagaimana cara menemukan semua kontrol konten dengan tag tertentu?

Gunakan Range.StructuredDocumentTags.GetByTag(), atau GetByTitle() / GetById() jika Anda mencocokkan pada mereka saja.

Bagaimana cara menghapus kontrol konten tetapi mempertahankan isinya?

Panggil StructuredDocumentTag.RemoveSelfOnly() daripada Remove().

Bagaimana cara mengaitkan kontrol konten dengan data XML khusus?

Panggil XmlMapping.SetMapping() pada kontrol, mengarahkannya ke bagian XML khusus yang ada dan ekspresi XPath di dalamnya.

Apa perbedaan antara StructuredDocumentTag biasa dan yang memiliki rentang?

Kontrol konten yang melintasi lebih dari satu bagian dokumen direpresentasikan sebagai pasangan StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd alih-alih satu node tunggal; kedua bentuk tersebut mengimplementasikan IStructuredDocumentTag.

Ringkasan API Reference

Lihat Juga

• Aspose.Words for .NET — Enterprise Documentation