วิธีทำงานกับ Custom XML Markup ใน .NET
วิธีทำงานกับมาร์กอัป XML แบบกำหนดเองใน .NET
เอกสาร Word สามารถบรรจุข้อมูล XML แบบกำหนดเองควบคู่กับเนื้อหาที่มองเห็นได้ — ข้อมูลที่ใช้ผูกคอนโทรลเนื้อหา, เก็บเมตาดาต้าระดับแอปพลิเคชัน, หรือฝังส่วนที่เพิ่มโดยแอปพลิเคชันอื่น คู่มือฉบับนี้จะแสดงวิธีอ่านข้อมูลนั้น, เพิ่มส่วน XML แบบกำหนดใหม่, และตรวจสอบ smart tags รุ่นเก่าที่เอกสารเก่าอาจยังมีอยู่, โดยใช้ CustomXmlPart, CustomXmlProperty, และ SmartTag ใน Aspose.Words FOSS สำหรับ .NET.
คู่มือแบบขั้นตอนต่อขั้นตอน
ขั้นตอนที่ 1: อ่านข้อมูล XML แบบกำหนดเองจากเอกสาร
Document.CustomXmlParts คืนค่า CustomXmlPartCollection — กลไกเดียวกับที่ Word ใช้เพื่อรองรับคอนโทรลเนื้อหาแบบแมปกับ XML. ทำการวนรอบคอลเลกชัน, หรือเรียก GetById(id) เมื่อคุณทราบแล้วว่าต้องการส่วนใด, เพื่อรับ CustomXmlPart. แต่ละส่วนเปิดเผย Id, ซึ่งเป็นอาร์เรย์ไบต์ Data ที่เก็บ XML ดิบ, DataChecksum สำหรับตรวจจับว่าข้อมูลมีการเปลี่ยนแปลงหรือไม่โดยไม่ต้องเปรียบเทียบไบต์ทั้งหมด, และ Schemas — CustomXmlSchemaCollection ที่แสดงรายการสคีม่า XML ที่เกี่ยวข้องกับมัน.
ขั้นตอนที่ 2: เพิ่มหรืออัปเดตส่วน XML แบบกำหนดเอง
เรียก CustomXmlPartCollection.Add(id, xml) พร้อมสตริง id และเนื้อหา XML เพื่อสร้างส่วนโดยตรง หรือสร้าง CustomXmlPart แยกจากกันแล้วส่งให้ Add(part). เพื่อลบข้อมูล ใช้ RemoveAt(index) ที่ตำแหน่งเฉพาะหรือใช้ Clear() เพื่อลบทุกส่วน. เมื่อคัดลอกข้อมูล XML แบบกำหนดเองระหว่างเอกสาร ใช้ CustomXmlPart.Clone() (หรือ Clone() ของคอลเลกชัน) บนส่วนต้นทางแทนการอ่านใหม่และเพิ่ม XML ดิบ แล้วเพิ่มสำเนาไปยัง Document.CustomXmlParts ของเอกสารเป้าหมาย.
ขั้นตอนที่ 3: จัดการสกีมาที่เชื่อมโยงกับส่วน
CustomXmlPart.Schemas เข้าถึง CustomXmlSchemaCollection ซึ่งติดตาม URI ของสกีมาที่เชื่อมโยงกับส่วนเป็นสตริงธรรมดาแทนวัตถุสกีมาที่แยกวิเคราะห์. ใช้ Add(value) เพื่อลงทะเบียน URI ของสกีมา, Remove(name) หรือ RemoveAt(index) เพื่อลบหนึ่งรายการ, IndexOf(value) เพื่อตำแหน่งหา, และ Clear() เพื่อลบทั้งหมด. Count รายงานจำนวน URI ของสกีมาที่เชื่อมโยงกับส่วนในขณะนี้.
ขั้นตอนที่ 4: ทำงานกับส่วนกำหนดเองระดับแพ็กเกจ
ไม่ใช่ทุกส่วนที่ไม่ปรากฏในแพ็กเกจ OOXML จะเป็น XML ที่กำหนดเอง. Document.PackageCustomParts คืนค่า CustomPartCollection ของวัตถุ CustomPart — ส่วนที่กำหนดเองที่เก็บอยู่ในแพ็กเกจ เช่น ส่วนที่เพิ่มโดยแอปพลิเคชันอื่นที่แก้ไขไฟล์. แต่ละ CustomPart มี Name, ContentType, RelationshipType, อาร์เรย์ไบต์ Data, และแฟล็ก IsExternal ที่บ่งบอกว่ามันเป็นการอ้างอิงภายนอกแทนเนื้อหาแทรก. Add(part), RemoveAt(index), และ Clear() จัดการคอลเลกชันในแบบเดียวกับ CustomXmlPartCollection. ตรวจสอบ PackageCustomParts — ไม่ใช่ CustomXmlParts — เมื่อส่วนที่เอกสารของคุณควรมีไม่ปรากฏในคอลเลกชัน XML ที่กำหนดเอง.
ขั้นตอนที่ 5: ตรวจสอบแท็กอัจฉริยะแบบดั้งเดิมและคุณสมบัติของมัน
SmartTag คือชนิดโหนด (NodeType.SmartTag, สร้างด้วย SmartTag(doc)) ที่แทนแท็กอัจฉริยะ Word แบบดั้งเดิมที่ห่อหุ้มข้อความที่ได้รับการจดจำ. ตรวจสอบ Element และ Uri พร้อมกันเพื่อระบุว่าตัวจดจำใดสร้างแท็กนั้น, จากนั้นอ่าน Properties — ซึ่งเป็น CustomXmlPropertyCollection — สำหรับข้อมูลโครงสร้างที่ตัวจดจำแนบ. ภายใน CustomXmlPropertyCollection, ตัวทำดัชนี (เช่น properties["MyProp"]) หรือ Contains(name) จะค้นหาคุณสมบัติเฉพาะ, IndexOfKey(name) คืนตำแหน่งของมัน, และ Remove(name)/RemoveAt(index)/Clear() ลบรายการ; แต่ละ CustomXmlProperty ถูกสร้างด้วย CustomXmlProperty(name, uri, value) และเปิดเผย Name, Uri, และ Value. เนื่องจาก SmartTag สืบทอดจาก CompositeNode, มันก็มีส่วนร่วมในต้นไม้เอกสารเช่นโหนดอื่น ๆ, รองรับ Accept(visitor), AcceptStart(visitor), และ AcceptEnd(visitor) สำหรับการเดินทางโดยอิง DocumentVisitor.
ปัญหาทั่วไปและวิธีแก้ไข
CustomXmlPartCollection.GetById(id) ไม่คืนค่าใดที่ใช้ได้. รหัสไอดีไม่ตรงกับส่วนใดที่มีอยู่ในขณะนี้ Document.CustomXmlParts. ทำการนับรายการของคอลเลกชันเพื่อยืนยันว่ารหัสไอดีมีอยู่ หรือเพิ่มส่วนนั้นก่อนด้วย Add(id, xml).
ส่วนที่เพิ่มโดยแอปพลิเคชันอื่นจะไม่พบโดยการวนซ้ำ CustomXmlParts. ส่วนของแพ็กเกจที่ไม่ใช่-XML จะถูกเปิดเผยผ่าน Document.PackageCustomParts, ไม่ใช่ CustomXmlParts. ตรวจสอบ PackageCustomParts (a CustomPartCollection) แทน.
SmartTag.Properties ว่างเปล่าแม้ว่าป้ายกำกับจะปรากฏอย่างชัดเจน. ไม่ใช่ทุกตัวตรวจจับแท็กอัจฉริยะที่แนบคุณสมบัติโครงสร้าง ตรวจสอบ SmartTag.Element and Uri เพื่อยืนยันว่าตัวตรวจจับใดสร้างแท็กก่อนที่จะสมมติว่าคุณสมบัติเฉพาะจะปรากฏ.
ข้อมูล XML แบบกำหนดเองดูเหมือนไม่เกี่ยวข้องกับการควบคุมเนื้อหาที่ควรผูกไว้. การควบคุมเนื้อหาจะผูกกับ XML แบบกำหนดเองผ่านการกำหนดค่าการผูกข้อมูลของตนเอง ไม่ได้ผูกโดยอัตโนมัติกับทุก CustomXmlPart in Document.CustomXmlParts. ยืนยันว่าฝ่ายใดของการควบคุมเนื้อหาที่กำหนดเป็นจริงที่ผูกไว้ แทนที่จะสมมติว่ามีความสัมพันธ์แบบหนึ่งต่อหนึ่ง.
คำถามที่พบบ่อย
ฉันจะเพิ่มข้อมูล XML ที่กำหนดเองลงในเอกสารอย่างไร?
เรียก Document.CustomXmlParts.Add(id, xml) พร้อมสตริง id และเนื้อหา XML, หรือสร้าง CustomXmlPart แยกต่างหากแล้วส่งไปยัง Add(part).
ความแตกต่างระหว่าง CustomXmlPart กับ CustomXmlProperty คืออะไร?
CustomXmlPart คือเกาะข้อมูล XML ทั้งหมด — เพย์โหลดแบบอาเรย์ไบต์พร้อมสคีมาที่เกี่ยวข้อง — เข้าถึงได้ผ่าน Document.CustomXmlParts. CustomXmlProperty คือคู่ชื่อ/ค่าเดียว โดยปกติเข้าถึงผ่าน SmartTag.Properties มากกว่าการเข้าถึงโดยตรงจากเอกสาร.
ฉันจะคัดลอกข้อมูล XML แบบกำหนดเองจากเอกสารหนึ่งไปยังอีกเอกสารหนึ่งได้อย่างไร?
เรียก Clone() บน CustomXmlPart แหล่งต้นทาง แล้วเพิ่มคลอนไปยัง Document.CustomXmlParts ของเอกสารเป้าหมายด้วย Add(part).
อะไรคือ SmartTag และฉันจะพบมันเมื่อใด?
SmartTag คือฟีเจอร์ Word รุ่นเก่าที่แสดงถึงข้อความที่ถูกจดจำและห่อหุ้มโดยตัวจดจำ smart-tag — โหนดเอกสาร (NodeType.SmartTag) ที่มี Element และ Uri ระบุตัวจดจำ พร้อมกับคอลเลกชัน Properties ของค่า CustomXmlProperty. มันจะปรากฏในเอกสารที่ถูกสร้างหรือแก้ไขโดยเปิดใช้งาน smart tags ในเวอร์ชัน Word เก่า.
ฉันจะทราบว่ามีส่วน XML แบบกำหนดเองหรือส่วนแพ็คเกจในเอกสารจำนวนเท่าใด?
อ่าน Count บน Document.CustomXmlParts (เป็น CustomXmlPartCollection) หรือ Document.PackageCustomParts (เป็น CustomPartCollection) ตามลำดับ.
