ทำงานกับ Custom XML Markup

ทำงานกับ XML Markup ที่กำหนดเอง

คู่มือนี้แสดงวิธีอ่านและจัดการข้อมูล XML ที่กำหนดเองที่เอกสาร Word สามารถบรรจุพร้อมกับเนื้อหาที่มองเห็นได้ — ข้อมูลที่ใช้ผูกกับคอนเทนต์คอนโทรล, เก็บเมทาดาต้าเฉพาะแอปพลิเคชัน, หรือฝังส่วนแพ็กเกจใด ๆ Document.CustomXmlParts เปิดเผยข้อมูล XML ที่กำหนดเองระดับเอกสาร, และ Document.PackageCustomParts เปิดเผยส่วนที่กำหนดเองระดับแพ็กเกจที่ไม่ได้เป็น XML โดยเฉพาะ.

ส่วน XML ที่กำหนดเอง

CustomXmlPart แทนส่วนข้อมูล XML ที่กำหนดเองหนึ่งส่วนที่แนบกับเอกสาร — กลไกเดียวกับที่ Word ใช้เพื่อสนับสนุนคอนเทนต์คอนโทรลที่แมปกับ XML. แต่ละส่วนมี Id, อาร์เรย์ไบต์ Data ที่เก็บ XML ดิบ, DataChecksum, และคุณสมบัติ Schemas (ซึ่งเป็น CustomXmlSchemaCollection) ที่แสดงรายการสคีม่า XML ที่เกี่ยวข้องกับมัน. Document.CustomXmlParts คืนค่า CustomXmlPartCollection: Add(part) ผูก CustomXmlPart ที่มีอยู่แล้ว, Add(id, xml) สร้างใหม่โดยตรงจากไอดีและสตริง XML, GetById(id) ดึงส่วนเฉพาะ, และ RemoveAt(index)/Clear() ลบส่วน. ทั้ง CustomXmlPart และ CustomXmlPartCollection เปิดเผย Clone() สำหรับการทำสำเนาข้อมูล XML ที่กำหนดเอง, ตัวอย่างเช่นเมื่อคัดลอกเนื้อหาระหว่างเอกสาร.

สคีม่า XML ที่กำหนดเอง

CustomXmlSchemaCollection, ที่เข้าถึงผ่าน CustomXmlPart.Schemas, แสดงรายการ URI ของสคีมาที่เชื่อมโยงกับส่วน XML ที่กำหนดเอง. มันรองรับ Add(value), Remove(name), RemoveAt(index), IndexOf(value), Clear(), และ Clone(), พร้อมกับคุณสมบัติ Count — URI ของสคีมาจะถูกติดตามเป็นสตริงธรรมดาแทนที่จะเป็นอ็อบเจกต์สคีมาที่แยกวิเคราะห์.

คุณสมบัติ XML ที่กำหนดเอง

แยกจาก CustomXmlPart แล้ว CustomXmlProperty แสดงถึงคุณสมบัติ XML แบบชื่อ/ค่าเดียวที่สร้างด้วย CustomXmlProperty(name, uri, value) และเปิดเผย Name, Uri, และ Value. CustomXmlPropertyCollection จัดการชุดของสิ่งเหล่านี้: Add(property) เพิ่มหนึ่งรายการ, ตัวดัชนี (เช่น properties["MyProp"]) ค้นหารายการตามชื่อและ Contains(name) ตรวจสอบว่ามีอยู่หรือไม่, IndexOfKey(name) คืนตำแหน่งของมัน, และ Remove(name)/RemoveAt(index)/Clear() ลบรายการ. SmartTag.Properties คืนค่า CustomXmlPropertyCollection, ซึ่งเป็นวิธีที่ข้อมูลโครงสร้างของแท็กอัจฉริยะแบบเก่าถูกแสดง (ดูด้านล่าง).

ส่วนกำหนดเองระดับแพ็คเกจ

Document.PackageCustomParts คืนค่า CustomPartCollection ของวัตถุ CustomPart — ส่วนที่กำหนดเองที่เก็บในแพ็คเกจ OOXML ซึ่งไม่ใช่ข้อมูล XML ที่กำหนดเอง เช่น ส่วนที่เพิ่มโดยแอปพลิเคชันอื่นที่แก้ไขไฟล์นี้. แต่ละ CustomPart มี Name, ContentType, RelationshipType, อาเรย์ไบต์ Data, และแฟล็ก IsExternal ที่บ่งชี้ว่าฝั่งนี้เป็นการอ้างอิงภายนอกแทนที่จะเป็นเนื้อหาที่ฝังอยู่. คอลเลกชันสนับสนุน Add(part), RemoveAt(index), Clear(), และ Clone(), ควบคู่กับ Count.

แท็กอัจฉริยะแบบเก่า

SmartTag เป็นประเภทโหนด (NodeType.SmartTag) ที่แทนแท็กอัจฉริยะ Word รุ่นเก่าซึ่งหุ้มข้อความที่ถูกจดจำ. SmartTag ถูกสร้างด้วย SmartTag(doc), และเปิดเผย Element (ชื่อองค์ประกอบของตัวจดจำ) และ Uri (เนมสเปซของตัวจดจำ), พร้อมกับ Properties — CustomXmlPropertyCollection ที่เก็บข้อมูลโครงสร้างที่ตัวจดจำแนบกับข้อความที่ถูกแท็ก. เนื่องจาก SmartTag เป็นโหนด, มันจึงมีส่วนร่วมในต้นไม้เอกสารเช่นโหนดอื่น ๆ, สนับสนุน Accept(visitor), AcceptStart(visitor), และ AcceptEnd(visitor) สำหรับการเดินทางแบบอิง DocumentVisitor.

MarkupLevel

MarkupLevel เป็น enum — Unknown, Inline, Block, Row, Cell — ที่อธิบายระดับโครงสร้างในต้นไม้เอกสารที่องค์ประกอบการทำเครื่องหมาย เช่น แท็กเอกสารโครงสร้าง สามารถเกิดขึ้นได้.

เคล็ดลับและแนวทางปฏิบัติที่ดีที่สุด

• ใช้ CustomXmlPartCollection.GetById(id) แทนการวนลูปคอลเลกชันด้วยตนเองเมื่อคุณทราบ id ของส่วนที่ต้องการ.
• อ่าน CustomXmlPart.DataChecksum เพื่อกำหนดว่าข้อมูล XML ด้านล่างได้เปลี่ยนแปลงหรือไม่โดยไม่ต้องทำการเปรียบเทียบไบต์ทั้งหมด.
• แยกแยะ Document.CustomXmlParts (ข้อมูล XML แบบกำหนดเอง ซึ่งมักผูกกับคอนโทรลเนื้อหา) จาก Document.PackageCustomParts (ส่วนของแพคเกจที่ไม่เป็น XML ใด ๆ) — พวกมันทำหน้าที่ต่างกันและถูกเก็บแยกจากกัน.
• เมื่อทำงานกับเอกสารเก่าที่ใช้ smart tags ให้ตรวจสอบ SmartTag.Element และ Uri พร้อมกันเพื่อระบุว่า recognizer ตัวใดสร้างแท็กนั้นก่อนที่จะพึ่งพา Properties ของมัน.
• คัดลอกส่วน XML แบบกำหนดเองด้วย CustomXmlPart.Clone() (หรือ Clone() ของคอลเลกชัน) เมื่อคัดลอกข้อมูลระหว่างเอกสารแทนการอ่านซ้ำและเพิ่ม XML ดิบใหม่.

ปัญหาทั่วไป

FAQ

ความแตกต่างระหว่าง CustomXmlPart และ CustomXmlProperty คืออะไร?

CustomXmlPart เป็นเกาะข้อมูล XML ทั้งหมด (มี payload เป็นอาเรย์ไบต์และสคีมาที่เชื่อมโยง) ที่เข้าถึงได้ผ่าน Document.CustomXmlParts. CustomXmlProperty เป็นคู่ชื่อ/ค่าเดียว โดยทั่วไปเข้าถึงผ่าน SmartTag.Properties แทนที่จะเข้าถึงโดยตรงจากเอกสาร.

ฉันจะเพิ่มข้อมูล XML ที่กำหนดเองลงในเอกสารได้อย่างไร?

เรียก Document.CustomXmlParts.Add(id, xml) พร้อมสตริงไอดีและเนื้อหา XML, หรือสร้าง CustomXmlPart แยกต่างหากแล้วส่งให้ Add(part).

ส่วนกำหนดเองของแพ็คเกจคืออะไร และแตกต่างจากส่วนกำหนดเองของ XML อย่างไร?

Document.PackageCustomParts (เป็น CustomPartCollection ของอ็อบเจกต์ CustomPart) เก็บส่วนของแพ็คเกจ OOXML ใด ๆ ที่ไม่ใช่ XML ที่กำหนดเอง — แต่ละส่วนมี ContentType, RelationshipType, และ Data ดิบ. Document.CustomXmlParts ใช้สำหรับเกาะข้อมูล XML ที่กำหนดเองโดยเฉพาะ.

SmartTag คืออะไร?

SmartTag เป็นฟีเจอร์ Word รุ่นเก่าที่แสดงข้อความที่ถูกจำแนกและห่อหุ้มโดยตัวตรวจจับ smart-tag. มันเป็นโหนดของเอกสาร (NodeType.SmartTag) ที่มี Element และ Uri ระบุตัวตรวจจับ, และคอลเลกชัน Properties ของค่า CustomXmlProperty ที่ตัวตรวจจับแนบไว้.

ฉันจะคัดลอกข้อมูล XML ที่กำหนดเองระหว่างเอกสารได้อย่างไร?

ใช้ CustomXmlPart.Clone() บนส่วนต้นฉบับ แล้วเพิ่มสำเนาไปยัง Document.CustomXmlParts ของเอกสารเป้าหมายด้วย Add(part).

API Reference สรุป

ดูเพิ่มเติม

• Aspose.Words for .NET — Enterprise Documentation