Cara Bekerja dengan Markup XML Kustom di .NET
Cara Bekerja dengan Markup XML Kustom di .NET
Dokumen Word dapat membawa data XML kustom bersamaan dengan konten yang terlihat — data yang digunakan untuk mengikat kontrol konten, menyimpan metadata spesifik aplikasi, atau menyematkan bagian yang ditambahkan oleh aplikasi lain. Panduan ini menunjukkan cara membaca data tersebut, menambahkan bagian XML kustom baru, dan memeriksa smart tag warisan yang mungkin masih ada di dokumen lama, menggunakan CustomXmlPart, CustomXmlProperty, dan SmartTag dalam Aspose.Words FOSS untuk .NET.
Panduan Langkah demi Langkah
Langkah 1: Baca Data XML Kustom dari Dokumen
Document.CustomXmlParts mengembalikan sebuah CustomXmlPartCollection — mekanisme yang sama yang digunakan Word untuk mendukung kontrol konten yang dipetakan ke XML. Iterasi koleksi, atau panggil GetById(id) ketika Anda sudah mengetahui bagian mana yang dibutuhkan, untuk mendapatkan sebuah CustomXmlPart. Setiap bagian mengekspos Id, sebuah array byte Data yang menyimpan XML mentah, sebuah DataChecksum untuk mendeteksi apakah data telah berubah tanpa perbandingan byte penuh, dan Schemas — sebuah CustomXmlSchemaCollection yang mencantumkan skema XML yang terkait dengannya.
Langkah 2: Tambahkan atau Perbarui Bagian XML Kustom
Panggil CustomXmlPartCollection.Add(id, xml) dengan string id dan konten XML untuk membuat bagian secara langsung, atau buat CustomXmlPart secara terpisah dan berikan ke Add(part). Untuk menghapus data, gunakan RemoveAt(index) pada posisi tertentu atau Clear() untuk menghapus semua bagian. Saat menyalin data XML khusus antara dokumen, gunakan CustomXmlPart.Clone() (atau Clone() koleksi) pada bagian sumber alih-alih membaca ulang dan menambahkan kembali XML mentah, kemudian tambahkan klon ke Document.CustomXmlParts dokumen target.
Langkah 3: Kelola Skema yang Terkait dengan Bagian
CustomXmlPart.Schemas mencapai CustomXmlSchemaCollection, yang melacak URI skema yang terkait dengan bagian sebagai string biasa bukan objek skema yang diurai. Gunakan Add(value) untuk mendaftarkan URI skema, Remove(name) atau RemoveAt(index) untuk menghapus satu, IndexOf(value) untuk menemukan satu, dan Clear() untuk menghapus semuanya. Count melaporkan berapa banyak URI skema yang saat ini terkait dengan bagian.
Langkah 4: Bekerja dengan Bagian Kustom Tingkat Paket
Tidak setiap bagian yang tidak terlihat dalam paket OOXML adalah XML kustom. Document.PackageCustomParts mengembalikan CustomPartCollection dari objek CustomPart — bagian arbitrer yang disimpan dalam paket, seperti bagian yang ditambahkan oleh aplikasi lain yang menyentuh file. Setiap CustomPart memiliki Name, ContentType, RelationshipType, array byte Data, dan flag IsExternal yang menunjukkan apakah itu referensi eksternal bukan konten tersemat. Add(part), RemoveAt(index), dan Clear() mengelola koleksi dengan cara yang sama seperti CustomXmlPartCollection. Periksa PackageCustomParts — bukan CustomXmlParts — ketika bagian yang seharusnya dimiliki dokumen Anda tidak muncul di koleksi XML kustom.
Langkah 5: Periksa Tag Pintar Warisan dan Propertinya
SmartTag adalah tipe node (NodeType.SmartTag, dibangun dengan SmartTag(doc)) yang mewakili tag pintar Word warisan yang membungkus teks yang dikenali. Periksa Element dan Uri bersama-sama untuk mengidentifikasi pengenal mana yang membuat tag, lalu baca Properties — sebuah CustomXmlPropertyCollection — untuk data terstruktur yang dilampirkan oleh pengenal. Dalam sebuah CustomXmlPropertyCollection, pengindeks (mis. properties["MyProp"]) atau Contains(name) mencari properti spesifik, IndexOfKey(name) mengembalikan posisinya, dan Remove(name)/RemoveAt(index)/Clear() menghapus entri; setiap CustomXmlProperty dibangun dengan CustomXmlProperty(name, uri, value) dan mengekspos Name, Uri, dan Value. Karena SmartTag diturunkan dari CompositeNode, ia juga berpartisipasi dalam pohon dokumen seperti node lainnya, mendukung Accept(visitor), AcceptStart(visitor), dan AcceptEnd(visitor) untuk penelusuran berbasis DocumentVisitor.
Masalah Umum dan Solusi
CustomXmlPartCollection.GetById(id) tidak mengembalikan apa pun yang dapat digunakan. ID tidak cocok dengan bagian apa pun yang saat ini ada di Document.CustomXmlParts. Enumerasikan koleksi untuk memastikan ID ada, atau tambahkan bagian terlebih dahulu dengan Add(id, xml).
Bagian yang ditambahkan oleh aplikasi lain tidak ditemukan dengan iterasi CustomXmlParts. Bagian paket Non-XML diekspos melalui Document.PackageCustomParts, bukan CustomXmlParts. Periksa PackageCustomParts (a CustomPartCollection) sebagai gantinya.
SmartTag.Properties kosong meskipun tag tersebut jelas ada. Tidak setiap pengenal smart tag menambahkan properti terstruktur. Periksa SmartTag.Element and Uri untuk memastikan pengenal mana yang membuat tag sebelum mengasumsikan properti tertentu akan ada.
Data XML khusus tampaknya tidak terkait dengan kontrol konten yang seharusnya terikat padanya. Kontrol konten terikat ke XML khusus melalui konfigurasi pengikatan data mereka sendiri, bukan secara otomatis ke setiap CustomXmlPart in Document.CustomXmlParts. Pastikan bagian mana dari kontrol konten yang sebenarnya terikat daripada mengasumsikan hubungan satu-ke-satu.
Pertanyaan yang Sering Diajukan
Bagaimana cara menambahkan data XML kustom ke dokumen?
Panggil Document.CustomXmlParts.Add(id, xml) dengan string id dan konten XML, atau buat CustomXmlPart secara terpisah dan berikan ke Add(part).
Apa perbedaannya antara CustomXmlPart dan CustomXmlProperty?
CustomXmlPart adalah sebuah pulau data XML lengkap — payload berupa array byte ditambah skema terkait — yang diakses melalui Document.CustomXmlParts. CustomXmlProperty adalah pasangan nama/nilai tunggal, biasanya diakses melalui SmartTag.Properties daripada secara langsung dari dokumen.
Bagaimana cara menyalin data XML khusus dari satu dokumen ke dokumen lain?
Panggil Clone() pada CustomXmlPart sumber, lalu tambahkan klon ke Document.CustomXmlParts dokumen target dengan Add(part).
Apa itu SmartTag, dan kapan saya akan menemukannya?
SmartTag adalah fitur Word warisan yang mewakili teks yang dikenali dan dibungkus oleh pengenalan smart-tag — sebuah node dokumen (NodeType.SmartTag) dengan Element dan Uri yang mengidentifikasi pengenalan, plus koleksi Properties nilai CustomXmlProperty. Ia muncul dalam dokumen yang dibuat atau diedit dengan smart tag diaktifkan pada versi Word yang lebih lama.
Bagaimana saya mengetahui berapa banyak bagian XML khusus atau bagian paket yang dimiliki sebuah dokumen?
Baca Count pada Document.CustomXmlParts (sebuah CustomXmlPartCollection) atau Document.PackageCustomParts (sebuah CustomPartCollection) masing-masing.
