Utilisation de SDT de contrôle de contenu

Dans Microsoft Word, vous pouvez créer un formulaire en commençant par un modèle et en ajoutant des contrôles de contenu, notamment des cases à cocher, des zones de texte, des sélecteurs de date et des listes déroulantes. Dans Aspose.Words, une balise de document structuré ou un contrôle de contenu de tout document chargé dans Aspose.Words est importé en tant que nœud StructuredDocumentTag. Les balises de document structurées (SDT ou contrôle de contenu) permettent d’intégrer la sémantique définie par le client ainsi que son comportement et son apparence dans un document. StructuredDocumentTag peut apparaître dans un document aux endroits suivants:

• Au niveau bloc - Parmi les paragraphes et les tableaux, en tant qu’enfant d’un nœud Body, HeaderFooter, Comment, Footnote ou Shape
• Au niveau des lignes - Parmi les lignes d’une table, en tant qu’enfant d’un nœud Table
• Au niveau des cellules: parmi les cellules d’une ligne de tableau, en tant qu’enfant d’un nœud Row
• Niveau en ligne - Parmi le contenu en ligne à l’intérieur, en tant qu’enfant d’un Paragraph
• Niché dans un autre StructuredDocumentTag

Insertion de contrôles de contenu dans un document

Dans cette version de Aspose.Words, les types suivants de SDT ou de contrôle de contenu peuvent être créés:

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

L’exemple de code suivant montre comment créer un contrôle de contenu de type case à cocher.

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

L’exemple de code suivant montre comment créer un contrôle de contenu de type zone de texte enrichi.

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

L’exemple de code suivant montre comment créer un contrôle de contenu de type zone de liste déroulante.

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

Comment mettre à jour les contrôles de contenu

Cette section explique comment mettre à jour les valeurs de SDT ou de contrôle de contenu par programmation

L’exemple de code suivant montre comment définir l’état actuel de la case à cocher:

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

L’exemple de code suivant montre comment modifier les contrôles de contenu de type zone de texte brut, liste déroulante et image:

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

Vous pouvez télécharger le fichier exemple de ces exemples à partir de Aspose.Words GitHub.

Liaison du contrôle de contenu à des parties XML personnalisées

Vous pouvez lier des contrôles de contenu avec des données XML (partie XML personnalisée) dans des documents Word.

L’exemple de code suivant montre comment lier le contrôle de contenu à des parties XML personnalisées:

# 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 de la plage de balises de documents structurés

Vous pouvez obtenir le mappage de cette plage de balises de document structuré avec des données XML dans une partie XML personnalisée du document actuel à l’aide de la propriété StructuredDocumentTagRangeStart.xml_mapping. Cependant, la méthode set_mapping peut être utilisée pour mapper une plage de balises de document structuré à des données XML.

L’exemple de code suivant montre comment définir le mappage 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")

Effacer le contenu d’un contrôle de contenu

Vous pouvez effacer le contenu d’un contrôle de contenu en affichant un espace réservé. La méthode StructuredDocumentTag.clear efface le contenu de cette balise de document structuré et affiche un espace réservé s’il est défini. Cependant, il n’est pas possible d’effacer le contenu d’un contrôle de contenu s’il comporte des révisions. Si un contrôle de contenu n’a pas d’espace réservé, cinq espaces sont insérés comme dans MS Word (sauf les sections répétitives, les éléments de section répétitifs, les groupes, les cases à cocher, les citations). Si un contrôle de contenu est mappé à du XML personnalisé, le nœud XML référencé est effacé.

L’exemple de code suivant montre comment effacer le contenu du contrôle de contenu:

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

Modifier les couleurs d’arrière-plan et de bordure du contrôle de contenu

La propriété StructuredDocumentTag.color vous permet d’obtenir ou de définir la couleur du contrôle de contenu. La couleur affecte le contrôle du contenu dans deux situations:

1. MS Word met en évidence l’arrière-plan du contrôle de contenu lorsque la souris se déplace sur le contrôle de contenu. Cela permet d’identifier le contrôle de contenu. La couleur de surbrillance est un peu plus “douce” que celle du color. Par exemple, MS Word met en évidence l’arrière-plan avec la couleur rose, alors que color est rouge.
2. Lorsque vous interagissez (édition, sélection, etc.) avec le contrôle de contenu, la bordure du contrôle de contenu est colorée avec le color.

L’exemple de code suivant montre comment modifier la couleur du contrôle de contenu:

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

Comment définir le style pour formater le texte saisi dans le contrôle de contenu

Si vous souhaitez définir le style de contrôle de contenu, vous pouvez utiliser les propriétés StructuredDocumentTag.style ou StructuredDocumentTag.style_name. Lorsque vous tapez le texte dans le contrôle de contenu dans le document de sortie, le texte saisi aura le style “Citation”.

Notez que seuls les styles Lié et Caractère peuvent être appliqués au contrôle de contenu. Une exception (“Impossible d’appliquer ce style au SDT”) est levée lorsqu’un style qui existe mais qui n’est pas lié ou un style de caractère est appliqué.

L’exemple de code suivant montre comment définir le style du contrôle de contenu:

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

Utilisation du contrôle de contenu de section répétitive

Le contrôle du contenu de la section répétitive permet de répéter le contenu qu’elle contient. À l’aide de Aspose.Words, les nœuds de balises de document structurés des types d’éléments de section répétitive et de section répétitive peuvent être créés et à cet effet, le type d’énumération SdtType fournit une propriété REPEATING_SECTION_ITEM.

L’exemple de code suivant montre comment lier un contrôle de contenu de section répétitive à une table:

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