Trabajar con SDT de control de contenido

En Microsoft Word, puede crear un formulario comenzando con una plantilla y agregando controles de contenido, incluidas casillas de verificación, cuadros de texto, selectores de fechas y listas desplegables. En Aspose.Words, una etiqueta de documento estructurado o un control de contenido de cualquier documento cargado en Aspose.Words se importa como un nodo StructuredDocumentTag. Las etiquetas de documentos estructuradas (SDT o control de contenido) permiten incorporar en un documento la semántica definida por el cliente, así como su comportamiento y apariencia. StructuredDocumentTag puede aparecer en un documento en los siguientes lugares:

• Nivel de bloque: entre párrafos y tablas, como hijo de un nodo Body, HeaderFooter, Comment, Footnote o Shape
• Nivel de fila: entre filas de una tabla, como hijo de un nodo Table
• Nivel de celda: entre celdas de una fila de la tabla, como elemento secundario de un nodo Row
• Nivel en línea: entre el contenido en línea interno, como hijo de un Paragraph
• Anidado dentro de otro StructuredDocumentTag

Insertar controles de contenido en un documento

En esta versión de Aspose.Words se pueden crear los siguientes tipos de SDT o control de contenido:

• Casilla de verificación
• La lista desplegable
• Caja combo
• Fecha
• Galería de bloques de construcción
• Grupo
• Imagen
• Texto rico
• Texto sin formato

El siguiente ejemplo de código demuestra cómo crear un control de contenido de tipo casilla de verificación.

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

El siguiente ejemplo de código demuestra cómo crear un control de contenido de tipo cuadro de texto enriquecido.

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

El siguiente ejemplo de código demuestra cómo crear un control de contenido del tipo cuadro combinado.

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

Cómo actualizar los controles de contenido

Esta sección explica cómo actualizar los valores de SDT o control de contenido mediante programación.

El siguiente ejemplo de código muestra cómo establecer el estado actual de la casilla de verificación:

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

El siguiente ejemplo de código muestra cómo modificar controles de contenido de tipo cuadro de texto sin formato, lista desplegable e imagen:

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

Puede descargar el archivo de muestra de estos ejemplos desde Aspose.Words GitHub.

Vincular el control de contenido a partes XML personalizadas

Puede vincular controles de contenido con datos XML (parte XML personalizada) en documentos de Word.

El siguiente ejemplo de código muestra cómo vincular el control de contenido 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")

Mapeo XML del rango de etiquetas de documentos estructurados

Puede obtener la asignación de este rango de etiquetas de documento estructurado a datos XML en una parte XML personalizada del documento actual utilizando la propiedad StructuredDocumentTagRangeStart.xml_mapping. Sin embargo, el método set_mapping se puede utilizar para asignar un rango de etiquetas de documento estructurado a datos XML.

El siguiente ejemplo de código muestra cómo configurar la asignación 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")

Borrar el contenido de un control de contenido

Puede borrar el contenido de un control de contenido mostrando un marcador de posición. El método StructuredDocumentTag.clear borra el contenido de esta etiqueta de documento estructurado y muestra un marcador de posición si está definido. Sin embargo, no es posible borrar el contenido de un control de contenido si tiene revisiones. Si un control de contenido no tiene marcador de posición, se insertan cinco espacios como en MS Word (excepto secciones repetidas, elementos de sección repetidos, grupos, casillas de verificación y citas). Si un control de contenido se asigna a XML personalizado, el nodo XML al que se hace referencia se borra.

El siguiente ejemplo de código muestra cómo borrar el contenido del control de contenido:

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

Cambiar el fondo del control de contenido y los colores del borde

La propiedad StructuredDocumentTag.color le permite obtener o establecer el color del control de contenido. El color afecta el control de contenido en dos situaciones:

1. MS Word resalta el fondo del control de contenido cuando el mouse se mueve sobre el control de contenido. Esto ayuda a identificar el control de contenido. El color del resaltado es un poco más “suave” que el color. Por ejemplo, MS Word resalta el fondo con color rosa, cuando color es rojo.
2. Cuando interactúa (edición, selección, etc.) con el control de contenido, el borde del control de contenido se colorea con el color.

El siguiente ejemplo de código muestra cómo cambiar el color del control de contenido:

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

Cómo configurar el estilo para dar formato al texto escrito en el control de contenido

Si desea establecer el estilo de control de contenido, puede utilizar las propiedades StructuredDocumentTag.style o StructuredDocumentTag.style_name. Cuando escribe el texto en el control de contenido del documento de salida, el texto escrito tendrá el estilo “Cita”.

Tenga en cuenta que solo se pueden aplicar los estilos Vinculado y Carácter al control de contenido. Se genera una excepción (“No se puede aplicar este estilo al SDT”) cuando se aplica un estilo que existe pero que no está vinculado o es un estilo de carácter.

El siguiente ejemplo de código muestra cómo configurar el estilo de control de contenido:

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

Trabajar con control de contenido de sección repetida

El control de contenido de la sección repetida permite repetir el contenido contenido en ella. Con Aspose.Words, se pueden crear los nodos de etiquetas de documentos estructurados de la sección repetida y los tipos de elementos de sección repetida y, para este propósito, el tipo de enumeración SdtType proporciona propiedad REPEATING_SECTION_ITEM.

El siguiente ejemplo de código muestra cómo vincular un control de contenido de sección repetida a una tabla:

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