วิธีทำงานกับ Structured Document Tags ใน .NET
คู่มือนี้จะแสดงวิธีการแทรก, กำหนดค่า, ค้นหา, ลบ, และผูกข้อมูลกับแท็กเอกสารที่มีโครงสร้าง (content controls) ใน Aspose.Words FOSS สำหรับ .NET, โดยใช้ StructuredDocumentTag คลาสใน Aspose.Words.Markup เนมสเปซ. ครอบคลุมประเภทของ content-control ที่ DocumentBuilder สามารถแทรก, ตั้งค่าเนื้อหาเฉพาะประเภทเช่น สถานะของเช็คบ็อกซ์หรือ ตัวเลือกในดรอปดาวน์, ค้นหาคอนโทรลโดยแท็กหรือหัวเรื่อง, ลบคอนโทรลพร้อมหรือไม่มีเนื้อหา, และแมปคอนโทรลกับข้อมูล XML แบบกำหนดเอง.
คู่มือแบบขั้นตอนต่อขั้นตอน
ขั้นตอนที่ 1: ติดตั้งแพ็กเกจ
Aspose.Words FOSS for .NET ยังไม่ได้เผยแพร่แพ็กเกจ NuGet – ให้สร้างไลบรารีจากซอร์สโค้ดแทน. คัดลอก https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git, จากนั้นสร้าง Aspose.Words.sln ในคอนฟิกูเรชัน Release ด้วย .NET SDK และอ้างอิงแอสเซมบลี Aspose.Words ที่ได้จากโปรเจกต์ของคุณ. ไลบรารีนี้มุ่งเป้าไปที่ .NET Standard 2.0, ดังนั้นมันทำงานบน .NET Framework 4.6.2+ และ .NET 6/8/10.
ขั้นตอนที่ 2: นำเข้าคลาสที่จำเป็น
เพิ่มคำสั่ง using Aspose.Words; สำหรับ Document และ DocumentBuilder, และเพิ่มคำสั่ง using Aspose.Words.Markup; สำหรับ StructuredDocumentTag, SdtType, SdtListItem, SdtListItemCollection, XmlMapping, และคลาส content-control อื่น ๆ ที่คู่มือนี้ครอบคลุม.
ขั้นตอนที่ 3: ตรวจสอบประเภท Content-Control ที่คุณสามารถแทรกได้
ก่อนทำการแทรก ให้ตรวจสอบว่า SdtType เป้าหมายเป็นหนึ่งในเจ็ดประเภทที่ DocumentBuilder.InsertStructuredDocumentTag(SdtType) ยอมรับหรือไม่: PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture และ Date. RepeatingSection และ RepeatingSectionItem ไม่สามารถแทรกที่เคอร์เซอร์ข้อความด้วยวิธีนี้ – พวกมันจะห่อหุ้มย่อหน้าทั้งหมดหรือแถวตารางแทน. ค่าที่เหลือของ SdtType ที่อาจปรากฏในไฟล์ Word แต่ไม่ได้แสดงใน UI ของ Word เป็นประเภทที่สามารถแทรกได้ – None, Bibliography, Citation, Equation, BuildingBlockGallery, DocPartObj, Group และ EntityPicker – ไม่ได้รับการยอมรับโดยวิธีการแทรกนี้เลย.
ขั้นตอนที่ 4: แทรก Content Control ที่เคอร์เซอร์
เรียก DocumentBuilder.InsertStructuredDocumentTag(SdtType) ด้วยหนึ่งในเจ็ดประเภทที่รองรับเพื่อแทรกคอนโทรลใหม่ที่ตำแหน่งเคอร์เซอร์ปัจจุบันของตัวสร้าง; การเรียกนี้จะคืนค่า StructuredDocumentTag ใหม่. ตั้งค่า Tag และ Title บนคอนโทรลที่คืนค่าเพื่อให้มีสตริงระบุตัวที่ผู้เขียนเห็นใน Word, และตั้งค่า PlaceholderName (ซึ่งรองรับโดย Placeholder BuildingBlock) สำหรับข้อความพรอมท์ที่ Word แสดงเมื่อคอนโทรลว่าง – IsShowingPlaceholderText จะรายงานว่าพรอมท์นั้นกำลังแสดงอยู่หรือไม่.
ขั้นตอนที่ 5: กำหนดค่าข้อมูลตามประเภท
สำหรับคอนโทรลเช็คบ็อกซ์ ให้อ่านหรือกำหนดค่า StructuredDocumentTag.Checked, และเรียก SetCheckedSymbol() / SetUncheckedSymbol() เพื่อปรับแต่ง glyph ที่แสดงสำหรับแต่ละสถานะ. สำหรับคอนโทรลวันที่, ตั้งค่า FullDate, โดยที่ DateDisplayFormat และ DateDisplayLocale ควบคุมวิธีการแสดงผล, DateStorageFormat (SdtDateStorageFormat) ควบคุมวิธีการเก็บเมื่อผูกกับข้อมูล XML, และ CalendarType (SdtCalendarType) เลือกระบบปฏิทิน. สำหรับรายการดรอปดาวน์หรือคอมโบบ็อกซ์, เติมข้อมูล ListItems – ซึ่งเป็น SdtListItemCollection ของ SdtListItem (DisplayText, Value) – ก่อนที่จะตั้งค่า SelectedValue เพื่อเลือกตัวเลือกที่ใช้งาน. สำหรับคอนโทรลข้อความธรรมดา, Multiline คือคุณสมบัติ bool บน StructuredDocumentTag ที่สามารถตั้งค่าเพื่อกำหนดคอนโทรล.
ขั้นตอนที่ 6: การควบคุมลักษณะและการล็อก
ตั้งค่า Appearance (SdtAppearance) เพื่อควบคุมว่าคอนโทรลจะถูกจำกัดรูปแบบอย่างไรใน Word, และตั้งค่า Color เพื่อกำหนดสีไฮไลท์. ContentsFont และ EndCharacterFont ควบคุมฟอนต์ที่ใช้กับเนื้อหาของคอนโทรลและอักขระสิ้นท้ายของมัน. LockContentControl และ LockContents เป็นสวิตช์อิสระ – ตั้งค่า LockContentControl เพื่อบล็อกการลบคอนโทรลเอง, และ LockContents เพื่อบล็อกการแก้ไขสิ่งที่อยู่ภายในโดยไม่กระทบต่ออีกอัน.
ขั้นตอนที่ 7: ค้นหาและลบ Content Controls
อ่าน Range.StructuredDocumentTags – ซึ่งเป็น StructuredDocumentTagCollection ที่มีขอบเขตอยู่ในช่วงนั้น – และเรียก GetById(), GetByTag() หรือ GetByTitle() เพื่อค้นหาคอนโทรลเฉพาะ, หรือใช้ Remove() / RemoveAt() บนคอลเลกชันเพื่อเอาออกโดยอ้างอิงหรือดัชนี. สำหรับคอนโทรลแต่ละตัว, เรียก Remove() เพื่อลบคอนโทรลพร้อมกับเนื้อหาของมัน, RemoveSelfOnly() เพื่อลบเฉพาะตัวหุ้มโดยคงเนื้อหาไว้ในเอกสาร, หรือ Clear() เพื่อล้างเนื้อหาในขณะที่คอนโทรลยังคงอยู่.
ขั้นตอนที่ 8: ผูกคอนโทรลกับข้อมูล XML ที่กำหนดเอง
อ่าน StructuredDocumentTag.XmlMapping – ซึ่งเป็นอินสแตนซ์ของ XmlMapping – และเรียก SetMapping(customXmlPart, xPath, prefixMapping) เพื่อผูกคอนโทรลกับส่วน XML ที่กำหนดเองที่มีอยู่แล้วในที่เก็บข้อมูล XML ที่กำหนดเองของเอกสาร, โดยใช้การแสดง XPath เพื่อเลือกองค์ประกอบที่ผูกไว้. XmlMapping.IsMapped รายงานว่าการผูกกำลังทำงานหรือไม่, CustomXmlPart และ StoreItemId ระบุตำแหน่งข้อมูลที่ผูก, และ Delete() ลบการแมป.
ขั้นตอนที่ 9: จัดการ Content Controls ที่ครอบคลุมหลายส่วน
Content control ที่ครอบคลุมมากกว่าหนึ่งส่วนของเอกสาร – รายงานโดย IsMultiSection – จะไม่ถูกแทนด้วยโหนด StructuredDocumentTag เพียงโหนดเดียว แต่ด้วยคู่ StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd ที่เชื่อมต่อผ่าน StructuredDocumentTagRangeStart.RangeEnd. เขียนโปรแกรมโดยอิงอินเทอร์เฟซร่วม IStructuredDocumentTag (Tag, Title, Placeholder, PlaceholderName, Appearance, IsShowingPlaceholderText, RemoveSelfOnly()) เมื่อโค้ดต้องจัดการรูปแบบโหนดเดียวและรูปแบบช่วงอย่างสอดคล้องกัน, แทนที่จะสาขาตามชนิดที่เป็นจริง.
ปัญหาทั่วไปและการแก้ไข
InsertStructuredDocumentTag โยน NotImplementedException ที่ร้องขอ SdtType – ตัวอย่างเช่น Citation, Equation, หรือ BuildingBlockGallery – ไม่ใช่หนึ่งในเจ็ดประเภทที่สามารถแทรกได้ ใช้ PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture, หรือ Date แทน.
InsertStructuredDocumentTag ทำให้เกิด InvalidOperationException RepeatingSection or RepeatingSectionItem ถูกร้องขอที่เคอร์เซอร์ข้อความ. สองประเภทนี้ห่อหุ้มย่อหน้าทั้งหมดหรือแถวตารางเต็มแทนที่จะถูกแทรกที่ตำแหน่งเคอร์เซอร์.
การลบ content control ยังลบข้อความภายในด้วย Remove() ลบคอนโทรลและเนื้อหาภายในพร้อมกัน. เรียก RemoveSelfOnly() แทนเพื่อเก็บเนื้อหาในเอกสารและลบเฉพาะตัวห่อเท่านั้น.
ช่องทำเครื่องหมายไม่แสดงสัญลักษณ์ที่คาดหวัง อักขระ glyph ที่เลือกและไม่เลือกแบบกำหนดเองไม่เคยถูกตั้งค่า. เรียก SetCheckedSymbol() and SetUncheckedSymbol() บนคอนโทรล.
รายการดรอปดาวน์หรือคอมโบบ็อกซ์แสดงไม่มีตัวเลือก ListItems ไม่เคยถูกเติมข้อมูล. เพิ่ม SdtListItem รายการลงในคอนโทรลของ ListItems คอลเลกชันก่อนคาดว่าจะมีตัวเลือกปรากฏขึ้น, แล้วตั้งค่า SelectedValue เพื่อเลือกอันที่ใช้งานอยู่.
คำถามที่พบบ่อย
ฉันสามารถแทรกประเภทของ content-control ไหนได้โดยตรงด้วย DocumentBuilder?
PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture และ Date. ค่าของ SdtType อื่น ๆ ไม่ได้รับการสนับสนุนโดย InsertStructuredDocumentTag().
ฉันจะหา content controls ทั้งหมดที่มีแท็กเฉพาะได้อย่างไร?
อ่าน Range.StructuredDocumentTags แล้วเรียก GetByTag() หรือ GetByTitle() / GetById() หากจับคู่กับตัวระบุเหล่านั้นแทน.
ฉันจะลบ content control แต่รักษาเนื้อหาของมันในเอกสารไว้ได้อย่างไร?
เรียก StructuredDocumentTag.RemoveSelfOnly() แทน Remove().
ฉันจะผูก content control กับข้อมูล XML แบบกำหนดเองได้อย่างไร?
เรียก XmlMapping.SetMapping() บน XmlMapping ของคอนโทรล โดยชี้ไปที่ส่วน XML แบบกำหนดเองที่มีอยู่และนิพจน์ XPath ภายในนั้น.
content control ที่ข้ามหลายส่วนแตกต่างจากแบบปกติอย่างไร?
มันถูกแทนด้วยคู่ StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd แทนโหนด StructuredDocumentTag เพียงอันเดียว; ทั้งสองรูปแบบทำงานตาม IStructuredDocumentTag ดังนั้น IsMultiSection จะบอกคุณว่าคุณกำลังทำงานกับรูปแบบใด.
