Arbeiten mit Content Control SDT

In Microsoft Word können Sie ein Formular erstellen, indem Sie mit einer Vorlage beginnen und Inhaltssteuerelemente hinzufügen, einschließlich Kontrollkästchen, Textfelder, Datumsauswahl und Dropdown-Listen. In Aspose.Words wird ein strukturiertes Dokument-Tag oder Inhaltssteuerelement aus jedem in Aspose.Words geladenen Dokument als StructuredDocumentTag-Knoten importiert. Strukturierte Dokument-Tags (SDT oder Inhaltskontrolle) ermöglichen die Einbettung kundenspezifischer Semantik sowie deren Verhalten und Erscheinungsbild in ein Dokument. StructuredDocumentTag kann in einem Dokument an folgenden Stellen vorkommen:

  • Blockebene – Zwischen Absätzen und Tabellen, als untergeordnetes Element eines Body-, HeaderFooter-, Comment-, Footnote- oder Shape-Knotens
  • Zeilenebene – Zwischen Zeilen in einer Tabelle, als untergeordnetes Element eines Table-Knotens
  • Zellenebene – Zwischen Zellen in einer Tabellenzeile, als untergeordnetes Element eines Row-Knotens
  • Inline-Ebene – Unter Inline-Inhalten im Inneren, als untergeordnetes Element eines Paragraph
  • In einem anderen StructuredDocumentTag verschachtelt

Einfügen von Inhaltssteuerelementen in ein Dokument

In dieser Version von Aspose.Words können die folgenden Arten von SDT oder Inhaltskontrolle erstellt werden:

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

Das folgende Codebeispiel zeigt, wie ein Inhaltssteuerelement vom Typ Kontrollkästchen erstellt wird.

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

Das folgende Codebeispiel zeigt, wie ein Inhaltssteuerelement vom Typ Rich-Text-Feld erstellt wird.

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

Das folgende Codebeispiel zeigt, wie ein Inhaltssteuerelement vom Typ Kombinationsfeld erstellt wird.

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

So aktualisieren Sie Inhaltssteuerelemente

In diesem Abschnitt wird erläutert, wie Sie die Werte von SDT oder Inhaltssteuerung programmgesteuert aktualisieren

Das folgende Codebeispiel zeigt, wie der aktuelle Status des Kontrollkästchens festgelegt wird:

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

Das folgende Codebeispiel zeigt, wie Inhaltssteuerelemente vom Typ “Einfaches Textfeld”, “Dropdown-Liste” und “Bild” geändert werden:

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

Bindung der Inhaltskontrolle an benutzerdefinierte XML-Teile

Sie können Inhaltssteuerelemente mit XML-Daten (benutzerdefinierter XML-Teil) in Word-Dokumenten binden.

Das folgende Codebeispiel zeigt, wie die Inhaltssteuerung an benutzerdefinierte XML-Teile gebunden wird:

# 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 des Tag-Bereichs strukturierter Dokumente

Mithilfe der StructuredDocumentTagRangeStart.xml_mapping-Eigenschaft können Sie die Zuordnung dieses strukturierten Dokument-Tag-Bereichs zu XML-Daten in einem benutzerdefinierten XML-Teil des aktuellen Dokuments abrufen. Allerdings kann die set_mapping-Methode verwendet werden, um einen strukturierten Dokument-Tag-Bereich XML-Daten zuzuordnen.

Das folgende Codebeispiel zeigt, wie die XML-Zuordnung festgelegt wird:

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

Inhalte eines Inhaltssteuerelements löschen

Sie können den Inhalt eines Inhaltssteuerelements löschen, indem Sie einen Platzhalter anzeigen. Die StructuredDocumentTag.clear-Methode löscht den Inhalt dieses strukturierten Dokument-Tags und zeigt einen Platzhalter an, sofern dieser definiert ist. Es ist jedoch nicht möglich, den Inhalt eines Inhaltssteuerelements zu löschen, wenn es Revisionen aufweist. Wenn ein Inhaltssteuerelement keinen Platzhalter hat, werden wie in MS Word fünf Leerzeichen eingefügt (außer sich wiederholende Abschnitte, sich wiederholende Abschnittselemente, Gruppen, Kontrollkästchen, Zitate). Wenn ein Inhaltssteuerelement benutzerdefiniertem XML zugeordnet ist, wird der referenzierte XML-Knoten gelöscht.

Das folgende Codebeispiel zeigt, wie der Inhalt der Inhaltssteuerung gelöscht wird:

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

Ändern Sie die Hintergrund- und Rahmenfarben der Inhaltssteuerung

Mit der StructuredDocumentTag.color-Eigenschaft können Sie die Farbe der Inhaltssteuerung abrufen oder festlegen. Die Farbe beeinflusst die Inhaltssteuerung in zwei Situationen:

  1. MS Word hebt den Hintergrund des Inhaltssteuerelements hervor, wenn die Maus über das Inhaltssteuerelement bewegt wird. Dies hilft, die Inhaltskontrolle zu identifizieren. Die Hervorhebungsfarbe ist etwas “weicher” als beim color. Beispielsweise hebt MS Word den Hintergrund rosa hervor, während color rot ist.
  2. Wenn Sie mit dem Inhaltssteuerelement interagieren (Bearbeiten, Auswählen usw.), wird der Rand des Inhaltssteuerelements mit dem color gefärbt.

Das folgende Codebeispiel zeigt, wie Sie die Farbe des Inhaltssteuerelements ändern:

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

So legen Sie den Stil fest, um in das Inhaltssteuerelement eingegebenen Text zu formatieren

Wenn Sie den Stil der Inhaltssteuerung festlegen möchten, können Sie StructuredDocumentTag.style- oder StructuredDocumentTag.style_name-Eigenschaften verwenden. Wenn Sie den Text in die Inhaltssteuerung im Ausgabedokument eingeben, hat der eingegebene Text den Stil “Zitat”.

Das folgende Codebeispiel zeigt, wie Sie den Stil der Inhaltssteuerung festlegen:

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

Arbeiten mit der Inhaltskontrolle für wiederkehrende Abschnitte

Die Inhaltssteuerung für sich wiederholende Abschnitte ermöglicht die Wiederholung des darin enthaltenen Inhalts. Mithilfe von Aspose.Words können die strukturierten Dokument-Tag-Knoten der Typen “Wiederholungsabschnitt” und “Wiederholungsabschnitt” erstellt werden. Zu diesem Zweck stellt der Aufzählungstyp SdtType eine REPEATING_SECTION_ITEM-Eigenschaft bereit.

Das folgende Codebeispiel zeigt, wie ein sich wiederholendes Abschnittsinhaltssteuerelement an eine Tabelle gebunden wird:

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