Trabalhando com SDT de controle de conteúdo

No Microsoft Word, você pode criar um formulário começando com um modelo e adicionando controles de conteúdo, incluindo caixas de seleção, caixas de texto, seletores de data e listas suspensas. No Aspose.Words, uma tag de documento estruturado ou controle de conteúdo de qualquer documento carregado no Aspose.Words é importado como um nó StructuredDocumentTag. Tags estruturadas de documentos (SDT ou controle de conteúdo) permitem incorporar a semântica definida pelo cliente, bem como seu comportamento e aparência em um documento. StructuredDocumentTag pode ocorrer em um documento nos seguintes locais:

  • Nível de bloco - Entre parágrafos e tabelas, como filho de um nó Body, HeaderFooter, Comment, Footnote ou Shape
  • Nível de linha - Entre as linhas de uma tabela, como filho de um nó Table
  • Nível de célula - Entre células em uma linha da tabela, como filho de um nó Row
  • Nível inline - Entre o conteúdo inline interno, como filho de um Paragraph
  • Aninhado dentro de outro StructuredDocumentTag

Inserindo controles de conteúdo em um documento

Nesta versão do Aspose.Words, os seguintes tipos de SDT ou controle de conteúdo podem ser criados:

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

O exemplo de código a seguir demonstra como criar um controle de conteúdo do tipo checkbox.

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

O exemplo de código a seguir demonstra como criar controle de conteúdo do tipo caixa de rich text.

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

O exemplo de código a seguir demonstra como criar controle de conteúdo da caixa de combinação de 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")

Como atualizar os controles de conteúdo

Esta seção explica como atualizar os valores de SDT ou controle de conteúdo de forma programática

O exemplo de código a seguir mostra como definir o estado atual da caixa de seleção:

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

O exemplo de código a seguir mostra como modificar controles de conteúdo do tipo caixa de texto simples, lista suspensa e imagem:

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

Vinculando controle de conteúdo a partes XML personalizadas

Você pode vincular controles de conteúdo a dados XML (parte XML personalizada) em documentos do Word.

O exemplo de código a seguir mostra como vincular o controle de conteúdo a partes XML personalizadas:

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

Mapeamento XML do intervalo de tags de documentos estruturados

Você pode obter o mapeamento desse intervalo de tags de documento estruturado para dados XML em uma parte XML personalizada do documento atual usando a propriedade StructuredDocumentTagRangeStart.xml_mapping. No entanto, o método set_mapping pode ser usado para mapear um intervalo de tags de documento estruturado para dados XML.

O exemplo de código a seguir mostra como definir o mapeamento 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")

Limpar conteúdo de um controle de conteúdo

Você pode limpar o conteúdo de um controle de conteúdo exibindo um espaço reservado. O método StructuredDocumentTag.clear limpa o conteúdo desta tag de documento estruturado e exibe um espaço reservado, se estiver definido. Porém, não é possível limpar o conteúdo de um controle de conteúdo se ele tiver revisões. Se um controle de conteúdo não tiver espaço reservado, cinco espaços serão inseridos como no MS Word (exceto seções repetidas, itens de seção repetidos, grupos, caixas de seleção, citações). Se um controle de conteúdo for mapeado para XML customizado, o nó XML referenciado será limpo.

O exemplo de código a seguir mostra como limpar o conteúdo do controle de conteúdo:

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

Alterar cores de fundo e borda do controle de conteúdo

A propriedade StructuredDocumentTag.color permite obter ou definir a cor do controle de conteúdo. A cor afeta o controle de conteúdo em duas situações:

  1. O MS Word destaca o plano de fundo do controle de conteúdo quando o mouse passa sobre o controle de conteúdo. Isso ajuda a identificar o controle de conteúdo. A cor do realce é um pouco mais “suave” que a do color. Por exemplo, o MS Word destaca o fundo com a cor rosa, quando color está vermelho.
  2. Quando você interage (edição, seleção, etc.) com o controle de conteúdo, a borda do controle de conteúdo é colorida com o color.

O exemplo de código a seguir mostra como alterar a cor do controle de conteúdo:

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

Como definir o estilo para formatar o texto digitado no controle de conteúdo

Se quiser definir o estilo do controle de conteúdo, você pode usar as propriedades StructuredDocumentTag.style ou StructuredDocumentTag.style_name. Ao digitar o texto no controle de conteúdo do documento de saída, o texto digitado terá o estilo “Citação”.

O exemplo de código a seguir mostra como definir o estilo do controle de conteúdo:

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

Trabalhando com controle de conteúdo de seção repetida

O controle de conteúdo da seção de repetição permite repetir o conteúdo contido nela. Usando Aspose.Words, os nós de tag de documento estruturado da seção de repetição e dos tipos de item de seção de repetição podem ser criados e, para esse propósito, o tipo de enumeração SdtType fornece propriedade REPEATING_SECTION_ITEM.

O exemplo de código a seguir mostra como vincular um controle de conteúdo de seção repetida a uma tabela:

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