Lavorare con Content Control SDT

In Microsoft Word, puoi creare un modulo iniziando con un modello e aggiungendo controlli del contenuto, tra cui caselle di controllo, caselle di testo, selettori di data ed elenchi a discesa. In Aspose.Words, un tag di documento strutturato o un controllo del contenuto da qualsiasi documento caricato in Aspose.Words viene importato come nodo StructuredDocumentTag. I tag di documenti strutturati (SDT o controllo del contenuto) consentono di incorporare in un documento la semantica definita dal cliente, nonché il suo comportamento e il suo aspetto. StructuredDocumentTag può verificarsi in un documento nei seguenti luoghi:

• A livello di blocco - Tra paragrafi e tabelle, come figlio di un nodo Body, HeaderFooter, Comment, Footnote o Shape
• A livello di riga: tra le righe di una tabella, come figlio di un nodo Table
• A livello di cella: tra le celle in una riga di tabella, come figlio di un nodo Row
• Livello in linea: tra i contenuti in linea all’interno, come figlio di un Paragraph
• Nidificato all’interno di un altro StructuredDocumentTag

Inserimento di controlli contenuto in un documento

In questa versione di Aspose.Words è possibile creare i seguenti tipi di SDT o controllo del contenuto:

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

Nell’esempio di codice seguente viene illustrato come creare un controllo contenuto di tipo casella di controllo.

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

Nell’esempio di codice seguente viene illustrato come creare un controllo contenuto di tipo casella di testo RTF.

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

Nell’esempio di codice seguente viene illustrato come creare il controllo contenuto della casella combinata tipo.

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

Come aggiornare i controlli del contenuto

Questa sezione spiega come aggiornare i valori di SDT o il controllo del contenuto a livello di codice

L’esempio di codice seguente mostra come impostare lo stato corrente della casella di controllo:

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

Il seguente esempio di codice mostra come modificare i controlli del contenuto di tipo casella di testo semplice, elenco a discesa e immagine:

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

È possibile scaricare il file di esempio di questi esempi da Aspose.Words GitHub.

Associazione del controllo del contenuto a parti XML personalizzate

È possibile associare i controlli del contenuto ai dati XML (parte XML personalizzata) nei documenti di Word.

L’esempio di codice seguente mostra come associare il controllo del contenuto a parti XML personalizzate:

# 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 dell’intervallo di tag del documento strutturato

Puoi ottenere la mappatura di questo intervallo di tag del documento strutturato sui dati XML in una parte XML personalizzata del documento corrente utilizzando la proprietà StructuredDocumentTagRangeStart.xml_mapping. Tuttavia, il metodo set_mapping può essere utilizzato per mappare un intervallo di tag di documento strutturato su dati XML.

L’esempio di codice seguente mostra come impostare la mappatura 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")

Cancella contenuto di un controllo contenuto

È possibile cancellare il contenuto di un controllo contenuto visualizzando un segnaposto. Il metodo StructuredDocumentTag.clear cancella il contenuto di questo tag di documento strutturato e visualizza un segnaposto se è definito. Tuttavia, non è possibile cancellare il contenuto di un controllo contenuto se presenta revisioni. Se un controllo del contenuto non ha segnaposto, vengono inseriti cinque spazi come in MS Word (eccetto sezioni ripetute, elementi di sezione ripetuti, gruppi, caselle di controllo, citazioni). Se un controllo contenuto viene mappato a un codice XML personalizzato, il nodo XML a cui si fa riferimento viene cancellato.

L’esempio di codice seguente mostra come cancellare il contenuto del controllo contenuto:

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

Modificare i colori dello sfondo e del bordo del controllo contenuto

La proprietà StructuredDocumentTag.color consente di ottenere o impostare il colore del controllo del contenuto. Il colore influisce sul controllo del contenuto in due situazioni:

1. MS Word evidenzia lo sfondo del controllo del contenuto quando il mouse si sposta sul controllo del contenuto. Ciò aiuta a identificare il controllo del contenuto. Il colore dell’evidenziazione è un po' più “morbido” rispetto al color. Ad esempio, MS Word evidenzia lo sfondo con il colore rosa, quando color è rosso.
2. Quando interagisci (modifica, selezione, ecc.) con il controllo del contenuto, il bordo del controllo del contenuto è colorato con il color.

L’esempio di codice seguente mostra come modificare il colore del controllo contenuto:

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

Come impostare lo stile per formattare il testo digitato nel controllo contenuto

Se desideri impostare lo stile del controllo del contenuto, puoi utilizzare le proprietà StructuredDocumentTag.style o StructuredDocumentTag.style_name. Quando digiti il testo nel controllo del contenuto nel documento di output, il testo digitato avrà lo stile “Citazione”.

Tieni presente che solo gli stili Collegato e Carattere possono essere applicati al controllo del contenuto. Viene generata un’eccezione (“Impossibile applicare questo stile all’SDT”) quando viene applicato uno stile che esiste ma non è collegato o uno stile di carattere.

L’esempio di codice seguente mostra come impostare lo stile del controllo del contenuto:

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

Lavorare con il controllo del contenuto della sezione ripetuta

Il controllo del contenuto della sezione ripetuta consente di ripetere il contenuto in essa contenuto. Utilizzando Aspose.Words, è possibile creare i nodi dei tag del documento strutturato della sezione ripetuta e dei tipi di elementi della sezione ripetuta e, a questo scopo, il tipo di enumerazione SdtType fornisce la proprietà REPEATING_SECTION_ITEM.

L’esempio di codice seguente mostra come associare un controllo del contenuto della sezione ripetuta a una tabella:

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