การทำงานกับ SDT การควบคุมเนื้อหา

ใน Microsoft Word คุณสามารถสร้างแบบฟอร์มได้โดยเริ่มต้นด้วยเทมเพลตและเพิ่มการควบคุมเนื้อหา รวมถึงช่องทำเครื่องหมาย กล่องข้อความ ตัวเลือกวันที่ และรายการแบบเลื่อนลง ใน Aspose.Words แท็กเอกสารที่มีโครงสร้างหรือการควบคุมเนื้อหาจากเอกสารใดๆ ที่โหลดลงใน Aspose.Words จะถูกนำเข้าเป็นโหนด StructuredDocumentTag แท็กเอกสารที่มีโครงสร้าง (SDT หรือการควบคุมเนื้อหา) ช่วยให้สามารถฝังความหมายที่ลูกค้ากำหนด รวมถึงลักษณะการทำงานและรูปลักษณ์ลงในเอกสารได้ StructuredDocumentTag สามารถเกิดขึ้นในเอกสารในตำแหน่งต่อไปนี้:

• ระดับบล็อก - ระหว่างย่อหน้าและตารางในฐานะลูกของ Body, HeaderFooter, Comment, Footnote หรือโหนด Shape
• ระดับแถว - ท่ามกลางแถวในตารางในฐานะลูกของโหนด Table
• ระดับเซลล์ - ในกลุ่มเซลล์ในแถวของตาราง เป็นรายการย่อยของโหนด Row
• ระดับอินไลน์ - ท่ามกลางเนื้อหาอินไลน์ภายในในฐานะลูกของ Paragraph
• ซ้อนอยู่ใน StructuredDocumentTag อื่น

การแทรกการควบคุมเนื้อหาลงในเอกสาร

ใน Aspose.Words เวอร์ชันนี้ คุณจะสร้าง SDT หรือการควบคุมเนื้อหาประเภทต่อไปนี้ได้

• Checkbox
• DropDownList
• ComboBox
• Date
• BuildingBlockGallery
• Group
• Picture
• RichText
• PlainText

ตัวอย่างรหัสต่อไปนี้สาธิตวิธีการสร้างการควบคุมเนื้อหาประเภทช่องทำเครื่องหมาย

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document()
builder = aw.DocumentBuilder(doc)

sdtCheckBox = aw.markup.StructuredDocumentTag(doc, aw.markup.SdtType.CHECKBOX, aw.markup.MarkupLevel.INLINE)
builder.insert_node(sdtCheckBox)
            
doc.save(docs_base.artifacts_dir + "WorkingWithSdt.check_box_type_content_control.docx", aw.SaveFormat.DOCX)

ตัวอย่างโค้ดต่อไปนี้สาธิตวิธีการสร้างการควบคุมเนื้อหาของกล่องข้อความ rich text ชนิด

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document()

sdtRichText = aw.markup.StructuredDocumentTag(doc, aw.markup.SdtType.RICH_TEXT, aw.markup.MarkupLevel.BLOCK)

para = aw.Paragraph(doc)
run = aw.Run(doc)
run.text = "Hello World"
run.font.color = drawing.Color.green
para.runs.add(run)
sdtRichText.child_nodes.add(para)
doc.first_section.body.append_child(sdtRichText)

doc.save(docs_base.artifacts_dir + "WorkingWithSdt.rich_text_box_content_control.docx")

ตัวอย่างโค้ดต่อไปนี้สาธิตวิธีการสร้างการควบคุมเนื้อหาของกล่องคำสั่งผสมชนิด

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document()

sdt = aw.markup.StructuredDocumentTag(doc, aw.markup.SdtType.COMBO_BOX, aw.markup.MarkupLevel.BLOCK)
sdt.list_items.add(aw.markup.SdtListItem("Choose an item", "-1"))
sdt.list_items.add(aw.markup.SdtListItem("Item 1", "1"))
sdt.list_items.add(aw.markup.SdtListItem("Item 2", "2"))
doc.first_section.body.append_child(sdt)

doc.save(docs_base.artifacts_dir + "WorkingWithSdt.combo_box_content_control.docx")

วิธีอัปเดตการควบคุมเนื้อหา

ส่วนนี้อธิบายวิธีอัปเดตค่า SDT หรือการควบคุมเนื้อหาโดยทางโปรแกรม

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีการตั้งค่าสถานะปัจจุบันของช่องทำเครื่องหมาย:

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document(docs_base.my_dir + "Structured document tags.docx")
            
# Get the first content control from the document.
sdtCheckBox = doc.get_child(aw.NodeType.STRUCTURED_DOCUMENT_TAG, 0, True).as_structured_document_tag()

if (sdtCheckBox.sdt_type == aw.markup.SdtType.CHECKBOX) :
    sdtCheckBox.checked = True

doc.save(docs_base.artifacts_dir + "WorkingWithSdt.current_state_of_check_box.docx")

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีการปรับเปลี่ยนการควบคุมเนื้อหาของประเภทกล่องข้อความธรรมดา รายการแบบหล่นลง และรูปภาพ:

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document(docs_base.my_dir + "Structured document tags.docx")

for sdt in doc.get_child_nodes(aw.NodeType.STRUCTURED_DOCUMENT_TAG, True) :
    sdt = sdt.as_structured_document_tag()

    if (sdt.sdt_type == aw.markup.SdtType.PLAIN_TEXT) :
        
        sdt.remove_all_children()
        para = sdt.append_child(aw.Paragraph(doc)).as_paragraph()
        run = aw.Run(doc, "new text goes here")
        para.append_child(run)
        
    elif (sdt.sdt_type == aw.markup.SdtType.DROP_DOWN_LIST) :
        
        secondItem = sdt.list_items[2]
        sdt.list_items.selected_value = secondItem
        
    elif (sdt.sdt_type == aw.markup.SdtType.PICTURE) :
        
        shape = sdt.get_child(NodeType.shape, 0, True).as_shape()
        if (shape.has_image) :
            shape.image_data.set_image(docs_base.images_dir + "Watermark.png")
            
doc.save(docs_base.artifacts_dir + "WorkingWithSdt.modify_content_controls.docx")

คุณสามารถดาวน์โหลดไฟล์ตัวอย่างของตัวอย่างเหล่านี้ได้จาก Aspose.Words GitHub

การเชื่อมโยงการควบคุมเนื้อหาเข้ากับส่วน XML ที่กำหนดเอง

คุณสามารถผูกตัวควบคุมเนื้อหากับข้อมูล XML (ส่วน XML แบบกำหนดเอง) ในเอกสาร Word ได้

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีการผูกการควบคุมเนื้อหากับส่วน XML แบบกำหนดเอง:

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document()
xmlPart = doc.custom_xml_parts.add(str(uuid.uuid4()), "<root><text>Hello, World!</text></root>")

sdt = aw.markup.StructuredDocumentTag(doc, aw.markup.SdtType.PLAIN_TEXT, aw.markup.MarkupLevel.BLOCK)
doc.first_section.body.append_child(sdt)

sdt.xml_mapping.set_mapping(xmlPart, "/root[1]/text[1]", "")

doc.save(docs_base.artifacts_dir + "WorkingWithSdt.bind_sd_tto_custom_xml_part.doc")

XMLMapping ของช่วงแท็กเอกสารที่มีโครงสร้าง

คุณสามารถรับการแมปช่วงแท็กเอกสารที่มีโครงสร้างนี้กับข้อมูล XML ในส่วน XML ที่กำหนดเองของเอกสารปัจจุบันได้โดยใช้คุณสมบัติ StructuredDocumentTagRangeStart.xml_mapping อย่างไรก็ตาม สามารถใช้วิธี set_mapping เพื่อแมปช่วงแท็กเอกสารที่มีโครงสร้างกับข้อมูล XML

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีการตั้งค่าการแมป XML:

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document(docs_base.my_dir + "Multi-section structured document tags.docx")

# Construct an XML part that contains data and add it to the document's CustomXmlPart collection.
xmlPartId = str(uuid.uuid4())
xmlPartContent = "<root><text>Text element #1</text><text>Text element #2</text></root>"
xmlPart = doc.custom_xml_parts.add(xmlPartId, xmlPartContent)
print(xmlPart.data.decode("utf-8"))

# Create a StructuredDocumentTag that will display the contents of our CustomXmlPart in the document.
sdtRangeStart = doc.get_child(aw.NodeType.STRUCTURED_DOCUMENT_TAG_RANGE_START, 0, True).as_structured_document_tag_range_start()

# If we set a mapping for our StructuredDocumentTag,
# it will only display a part of the CustomXmlPart that the XPath points to.
# This XPath will point to the contents second "<text>" element of the first "<root>" element of our CustomXmlPart.
sdtRangeStart.xml_mapping.set_mapping(xmlPart, "/root[1]/text[2]", None)

doc.save(docs_base.artifacts_dir + "WorkingWithSdt.structured_document_tag_range_start_xml_mapping.docx")

ล้างเนื้อหาของการควบคุมเนื้อหา

คุณสามารถล้างเนื้อหาของตัวควบคุมเนื้อหาด้วยการแสดงพื้นที่ที่สำรองไว้ วิธี StructuredDocumentTag.clear จะล้างเนื้อหาของแท็กเอกสารที่มีโครงสร้างนี้ และแสดงตัวยึดตำแหน่งหากมีการกำหนดไว้ อย่างไรก็ตาม ไม่สามารถล้างเนื้อหาของตัวควบคุมเนื้อหาได้หากมีการแก้ไข ถ้าตัวควบคุมเนื้อหาไม่มีพื้นที่ที่สำรองไว้ ระบบจะแทรกช่องว่างห้าช่องเหมือนกับใน MS Word (ยกเว้นส่วนที่ทำซ้ำ รายการส่วนที่ซ้ำ กลุ่ม กล่องกาเครื่องหมาย ข้อมูลอ้างอิง) ถ้าตัวควบคุมเนื้อหาถูกแมปกับ XML แบบกำหนดเอง โหนด XML ที่อ้างอิงจะถูกล้าง

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีการล้างเนื้อหาของการควบคุมเนื้อหา:

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document(docs_base.my_dir + "Structured document tags.docx")

sdt = doc.get_child(aw.NodeType.STRUCTURED_DOCUMENT_TAG, 0, True).as_structured_document_tag()
sdt.clear()

doc.save(docs_base.artifacts_dir + "WorkingWithSdt.clear_contents_control.doc")

เปลี่ยนพื้นหลังการควบคุมเนื้อหาและสีเส้นขอบ

คุณสมบัติ StructuredDocumentTag.color ช่วยให้คุณสามารถรับหรือตั้งค่าสีของการควบคุมเนื้อหาได้ สีส่งผลต่อการควบคุมเนื้อหาในสองสถานการณ์:

1. MS Word เน้นพื้นหลังของตัวควบคุมเนื้อหาเมื่อเลื่อนเมาส์ไปเหนือตัวควบคุมเนื้อหา ซึ่งช่วยในการระบุการควบคุมเนื้อหา สีไฮไลต์จะ “อ่อนกว่า” เล็กน้อยกว่า color ตัวอย่างเช่น MS Word เน้นพื้นหลังด้วยสีชมพู เมื่อ color เป็นสีแดง
2. เมื่อคุณโต้ตอบ (แก้ไข การเลือก ฯลฯ) กับตัวควบคุมเนื้อหา เส้นขอบของตัวควบคุมเนื้อหาจะมีสีด้วย color

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีการเปลี่ยนสีของการควบคุมเนื้อหา:

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document(docs_base.my_dir + "Structured document tags.docx")

sdt = doc.get_child(aw.NodeType.STRUCTURED_DOCUMENT_TAG, 0, True).as_structured_document_tag()
sdt.color = drawing.Color.red

doc.save(docs_base.artifacts_dir + "WorkingWithSdt.set_content_control_color.docx")

วิธีการตั้งค่าสไตล์เพื่อจัดรูปแบบข้อความที่พิมพ์ลงในตัวควบคุมเนื้อหา

ถ้าคุณต้องการตั้งค่าสไตล์ของการควบคุมเนื้อหา คุณสามารถใช้คุณสมบัติ StructuredDocumentTag.style หรือ StructuredDocumentTag.style_name ได้ เมื่อคุณพิมพ์ข้อความลงในตัวควบคุมเนื้อหาในเอกสารผลลัพธ์ ข้อความที่พิมพ์จะมีลักษณะเป็น “เครื่องหมายคำพูด”

โปรดทราบว่าเฉพาะลักษณะที่เชื่อมโยงและอักขระเท่านั้นที่สามารถนำไปใช้กับการควบคุมเนื้อหาได้ ข้อยกเว้น (“ไม่สามารถใช้สไตล์นี้กับ SDT”) เกิดขึ้นเมื่อมีการใช้สไตล์ที่มีอยู่แต่ไม่ได้เชื่อมโยงหรือลักษณะอักขระ

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีการตั้งค่ารูปแบบของการควบคุมเนื้อหา:

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document(docs_base.my_dir + "Structured document tags.docx")

sdt = doc.get_child(aw.NodeType.STRUCTURED_DOCUMENT_TAG, 0, True).as_structured_document_tag()
style = doc.styles.get_by_style_identifier(aw.StyleIdentifier.QUOTE)
sdt.style = style

doc.save(docs_base.artifacts_dir + "WorkingWithSdt.set_content_control_style.docx")

การทำงานกับการควบคุมเนื้อหาส่วนการทำซ้ำ

การควบคุมเนื้อหาส่วนที่ทำซ้ำช่วยให้สามารถทำซ้ำเนื้อหาที่มีอยู่ภายในได้ เมื่อใช้ Aspose.Words คุณสามารถสร้างโหนดแท็กเอกสารที่มีโครงสร้างของส่วนการทำซ้ำและประเภทรายการส่วนที่ทำซ้ำได้ และเพื่อจุดประสงค์นี้ ประเภทการแจงนับ SdtType จะจัดเตรียมคุณสมบัติ REPEATING_SECTION_ITEM

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีการผูกตัวควบคุมเนื้อหาส่วนที่ทำซ้ำกับตาราง:

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document()
builder = aw.DocumentBuilder(doc)

xmlPart = doc.custom_xml_parts.add("Books",
    "<books><book><title>Everyday Italian</title><author>Giada De Laurentiis</author></book>" +
    "<book><title>Harry Potter</title><author>J K. Rowling</author></book>" +
    "<book><title>Learning XML</title><author>Erik T. Ray</author></book></books>")

table = builder.start_table()

builder.insert_cell()
builder.write("Title")

builder.insert_cell()
builder.write("Author")

builder.end_row()
builder.end_table()

repeatingSectionSdt =aw.markup.StructuredDocumentTag(doc, aw.markup.SdtType.REPEATING_SECTION, aw.markup.MarkupLevel.ROW)
repeatingSectionSdt.xml_mapping.set_mapping(xmlPart, "/books[1]/book", "")
table.append_child(repeatingSectionSdt)

repeatingSectionItemSdt = aw.markup.StructuredDocumentTag(doc, aw.markup.SdtType.REPEATING_SECTION_ITEM, aw.markup.MarkupLevel.ROW)
repeatingSectionSdt.append_child(repeatingSectionItemSdt)

row = aw.tables.Row(doc)
repeatingSectionItemSdt.append_child(row)

titleSdt = aw.markup.StructuredDocumentTag(doc, aw.markup.SdtType.PLAIN_TEXT, aw.markup.MarkupLevel.CELL)
titleSdt.xml_mapping.set_mapping(xmlPart, "/books[1]/book[1]/title[1]", "")
row.append_child(titleSdt)

authorSdt = aw.markup.StructuredDocumentTag(doc, aw.markup.SdtType.PLAIN_TEXT, aw.markup.MarkupLevel.CELL)
authorSdt.xml_mapping.set_mapping(xmlPart, "/books[1]/book[1]/author[1]", "")
row.append_child(authorSdt)

doc.save(docs_base.artifacts_dir + "WorkingWithSdt.creating_table_repeating_section_mapped_to_custom_xml_part.docx")