Bekerja dengan Markup XML Kustom

Bekerja dengan Markup XML Kustom

Panduan ini menunjukkan cara membaca dan mengelola data XML kustom yang dapat dibawa oleh dokumen Word bersamaan dengan kontennya yang terlihat — data yang digunakan untuk mengikat kontrol konten, menyimpan metadata spesifik aplikasi, atau menyematkan bagian paket sewenang-wenanya. Document.CustomXmlParts menampilkan data XML kustom tingkat dokumen, dan Document.PackageCustomParts menampilkan bagian paket kustom tingkat paket yang bukan XML kustom secara khusus.

Bagian XML Kustom

CustomXmlPart mewakili satu pulau data XML kustom yang terlampir pada dokumen — mekanisme yang sama yang digunakan Word untuk mendukung kontrol konten yang dipetakan XML. Setiap bagian memiliki Id, sebuah array byte Data yang menyimpan XML mentah, DataChecksum, dan properti Schemas (sebuah CustomXmlSchemaCollection) yang mencantumkan skema XML yang terkait dengannya. Document.CustomXmlParts mengembalikan sebuah CustomXmlPartCollection: Add(part) melampirkan CustomXmlPart yang sudah ada, Add(id, xml) membuat satu secara langsung dari id dan string XML, GetById(id) mengambil bagian tertentu, dan RemoveAt(index)/Clear() menghapus bagian. Baik CustomXmlPart maupun CustomXmlPartCollection menampilkan Clone() untuk menduplikasi data XML kustom, misalnya saat menyalin konten antar dokumen.

Skema XML Kustom

CustomXmlSchemaCollection, yang diakses melalui CustomXmlPart.Schemas, mencantumkan URI skema yang terkait dengan bagian XML kustom. Ini mendukung Add(value), Remove(name), RemoveAt(index), IndexOf(value), Clear(), dan Clone(), bersama dengan properti Count — URI skema dilacak sebagai string biasa bukan sebagai objek skema yang diurai.

Properti XML Kustom

Terpisah dari CustomXmlPart, CustomXmlProperty mewakili properti XML nama/nilai tunggal, dibangun dengan CustomXmlProperty(name, uri, value) dan mengekspos Name, Uri, dan Value. CustomXmlPropertyCollection mengelola sekumpulan ini: Add(property) menambahkan satu, indeks (misalnya properties["MyProp"]) mencari satu berdasarkan nama dan Contains(name) menguji apakah itu ada, IndexOfKey(name) mengembalikan posisinya, dan Remove(name)/RemoveAt(index)/Clear() menghapus entri. SmartTag.Properties mengembalikan sebuah CustomXmlPropertyCollection, yang merupakan cara data terstruktur tag pintar warisan direpresentasikan (lihat di bawah).

Bagian Kustom Tingkat-Paket

Document.PackageCustomParts mengembalikan sebuah CustomPartCollection dari objek CustomPart — bagian arbitrer yang disimpan dalam paket OOXML yang bukan data XML kustom, seperti bagian yang ditambahkan oleh aplikasi lain yang menyentuh file. Setiap CustomPart memiliki Name, ContentType, RelationshipType, sebuah array byte Data, dan sebuah flag IsExternal yang menunjukkan apakah bagian tersebut merupakan referensi eksternal daripada konten tersemat. Koleksi ini mendukung Add(part), RemoveAt(index), Clear(), dan Clone(), bersama dengan Count.

Tag Pintar Warisan

SmartTag adalah tipe node (NodeType.SmartTag) yang mewakili tag pintar Word warisan yang membungkus teks yang dikenali. Sebuah SmartTag dibangun dengan SmartTag(doc), dan mengekspos Element (nama elemen pengenalan) dan Uri (namespace pengenalan), bersama dengan Properties — sebuah CustomXmlPropertyCollection yang menyimpan data terstruktur yang dilampirkan pengenalan ke teks yang ditandai. Karena SmartTag adalah node, ia juga berpartisipasi dalam pohon dokumen seperti node lainnya, mendukung Accept(visitor), AcceptStart(visitor), dan AcceptEnd(visitor) untuk penelusuran berbasis DocumentVisitor.

MarkupLevel

MarkupLevel adalah sebuah enum — Unknown, Inline, Block, Row, Cell — yang menggambarkan level struktural dalam pohon dokumen di mana elemen markup seperti tag dokumen terstruktur dapat muncul.

Tips dan Praktik Terbaik

• Gunakan CustomXmlPartCollection.GetById(id) daripada mengiterasi koleksi secara manual ketika Anda mengetahui id bagian yang Anda butuhkan.
• Baca CustomXmlPart.DataChecksum untuk mendeteksi apakah data XML yang mendasarinya telah berubah tanpa melakukan perbandingan byte secara lengkap.
• Bedakan Document.CustomXmlParts (data XML khusus, sering terikat pada kontrol konten) dari Document.PackageCustomParts (bagian paket non-XML yang sewenang-wang) — mereka melayani tujuan yang berbeda dan disimpan secara terpisah.
• Saat bekerja dengan dokumen warisan yang menggunakan smart tag, periksa SmartTag.Element dan Uri bersama-sama untuk mengidentifikasi pengenal mana yang membuat tag sebelum bergantung pada Properties.
• Klon bagian XML khusus dengan CustomXmlPart.Clone() (atau Clone() koleksi) saat menyalin data antar dokumen daripada membaca ulang dan menambahkan kembali XML mentah.

Masalah Umum

FAQ

Apa perbedaan antara CustomXmlPart dan CustomXmlProperty?

CustomXmlPart adalah sebuah pulau data XML seluruh (dengan muatan byte-array dan skema terkait), dapat diakses melalui Document.CustomXmlParts. CustomXmlProperty adalah pasangan nama/nilai tunggal, biasanya diakses melalui SmartTag.Properties alih-alih langsung dari dokumen.

Bagaimana cara menambahkan data XML khusus 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 itu bagian khusus paket, dan bagaimana mereka berbeda dari bagian khusus XML?

Document.PackageCustomParts (sebuah CustomPartCollection dari objek CustomPart) menyimpan bagian paket OOXML arbitrer yang bukan XML khusus — masing-masing dengan ContentType, RelationshipType, dan Data mentah. Document.CustomXmlParts khusus untuk pulau data XML khusus.

Apa itu SmartTag?

SmartTag adalah fitur Word lama yang mewakili teks yang dikenali dan dibungkus oleh pengenal smart-tag. Itu adalah node dokumen (NodeType.SmartTag) dengan Element dan Uri yang mengidentifikasi pengenal, serta kumpulan Properties nilai CustomXmlProperty yang dilampirkan oleh pengenal.

Bagaimana cara menyalin data XML khusus antara dokumen?

Gunakan CustomXmlPart.Clone() pada bagian sumber, lalu tambahkan klon ke Document.CustomXmlParts dokumen target dengan Add(part).

Ringkasan API Reference

Lihat Juga

• Aspose.Words for .NET — Enterprise Documentation