کار با Content Control 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 است. برای مثال، زمانی که color قرمز است، MS Word پس‌زمینه را با رنگ صورتی برجسته می‌کند.
  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")

کار با Repeating Section Content Control

کنترل محتوای بخش تکرار شونده امکان تکرار محتوای موجود در آن را فراهم می کند. با استفاده از 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")