العمل مع التحكم في المحتوى 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)

يوضح مثال التعليمات البرمجية التالي كيفية إنشاء عنصر تحكم المحتوى لمربع النص المنسق للنوع.

# 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")

ربط التحكم في المحتوى بأجزاء 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. عند كتابة النص في عنصر تحكم المحتوى في مستند الإخراج، سيكون للنص المكتوب النمط “اقتباس”.

يوضح مثال التعليمات البرمجية التالي كيفية تعيين نمط التحكم في المحتوى:

# 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")