Trabajando con etiquetas de documento estructurado (controles de contenido)

Trabajando con Etiquetas de Documento Estructurado (Controles de contenido)

Una etiqueta de documento estructurado (SDT), conocida en la interfaz de Word como control de contenido, envuelve una parte del contenido del documento con un comportamiento de edición tipado y restringido — una casilla de verificación, un selector de fecha, una lista desplegable, o un marcador de posición de texto plano o con formato. Aspose.Words FOSS para .NET modela estos a través del Aspose.Words.Markup namespace, encabezado por el StructuredDocumentTag clase. Esta página cubre la inserción de controles de contenido, la configuración de cada tipo, la búsqueda y eliminación de los mismos, y su vinculación a datos personalizados de XML.

El Modelo de Objetos de Etiqueta de Documento Estructurado

StructuredDocumentTag es un CompositeNode que también implementa IMarkupNode, ITrackableNode y IStructuredDocumentTag. SdtType identifica qué tipo de control es. Tag y Title contienen las cadenas de identificación que los autores establecen en Word; Placeholder (un BuildingBlock) y PlaceholderName suministran el texto de sugerencia que se muestra cuando el control está vacío, reportado a través de IsShowingPlaceholderText. LockContentControl impide que el control sea eliminado, y LockContents impide que su contenido sea editado, de forma independiente entre sí.

Insertando controles de contenido

DocumentBuilder.InsertStructuredDocumentTag(SdtType) inserta un nuevo control en el cursor, pero solo para siete de los valores SdtType: PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture y Date. RepeatingSection y RepeatingSectionItem no pueden insertarse en un cursor de texto de esta manera — en su lugar envuelven párrafos completos o filas de tabla. Los valores restantes de SdtType que aparecen en los archivos de Word pero que no están presentes en la interfaz de Word como tipos insertables — None, Bibliography, Citation, Equation, BuildingBlockGallery, DocPartObj, Group y EntityPicker — no son compatibles con este método de inserción.

Contenido Específico de Tipo

El estado de un control de casilla de verificación es StructuredDocumentTag.Checked; SetCheckedSymbol() y SetUncheckedSymbol() establecen los glifos mostrados para cada estado. Un control de fecha almacena su valor en FullDate, con DateDisplayFormat y DateDisplayLocale controlando cómo se representa, DateStorageFormat (un SdtDateStorageFormat) controlando cómo se almacena cuando está vinculado a datos XML, y CalendarType (un SdtCalendarType) seleccionando el sistema de calendario. Una lista desplegable o cuadro combinado expone sus opciones a través de ListItems, un SdtListItemCollection de SdtListItem (DisplayText, Value) con un SelectedValue. La propiedad Multiline de un control de texto sin formato permite o prohibe los saltos de línea dentro de él.

Apariencia y Bloqueo

Appearance (SdtAppearance) controla cómo se delimita visualmente el control en Word. Color establece su color de resaltado, y ContentsFont / EndCharacterFont controlan la fuente aplicada a su contenido y a su carácter final. LockContentControl y LockContents son interruptores independientes: el primero bloquea la eliminación del propio control, el segundo bloquea la edición de lo que contiene.

Buscar y eliminar controles de contenido

Range.StructuredDocumentTags devuelve un StructuredDocumentTagCollection limitado a ese rango, con GetById(), GetByTag() y GetByTitle() para búsqueda dirigida junto con Remove() y RemoveAt(). En un StructuredDocumentTag individual, Remove() elimina el control y su contenido juntos, RemoveSelfOnly() elimina solo el contenedor y conserva su contenido en el documento, y Clear() vacía el contenido del control mientras mantiene el propio control.

Vinculación de datos XML

StructuredDocumentTag.XmlMapping es una instancia XmlMapping que describe una vinculación a una parte XML personalizada en el documento: CustomXmlPart, XPath, PrefixMappings, StoreItemId y IsMapped. SetMapping() establece la vinculación a una parte XML personalizada existente y Delete() la elimina.

Controles de contenido multi-sección (por rango)

Un control de contenido que abarca más de una sección – reportado por IsMultiSection – no se representa mediante un único nodo StructuredDocumentTag, sino por un par de nodos StructuredDocumentTagRangeStart y StructuredDocumentTagRangeEnd, conectados a través de StructuredDocumentTagRangeStart.RangeEnd. Tanto la forma de nodo único como la de rango implementan la interfaz común IStructuredDocumentTag, de modo que el código que solo necesita Tag, Title, SdtType, Placeholder y propiedades de identificación similares puede trabajar con cualquiera de las dos formas de manera uniforme.

Consejos y Mejores Prácticas

• Verifique la lista de tipos admitidos de DocumentBuilder.InsertStructuredDocumentTag() antes de confiar en ella – solo PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture y Date pueden insertarse en el cursor; los demás tipos generan una excepción.
• Use RemoveSelfOnly() en lugar de Remove() cuando quiera “aplanar” un control de contenido – mantenga su contenido en el documento pero elimine el contenedor del control.
• Complete ListItems antes de que espere que un control DropDownList o ComboBox muestre opciones, y establezca SelectedValue para seleccionar el activo.
• Programe contra IStructuredDocumentTag en lugar de StructuredDocumentTag directamente si su código necesita manejar tanto controles de contenido ordinarios como de varias secciones (con rango) de la misma manera.
• XmlMapping.SetMapping() se enlaza a una parte personalizada XML que ya debe existir en el almacén de datos personalizado XML del documento – añada o cargue los datos XML antes de mapear un control a ellos.

Problemas Comunes

FAQ

¿Qué tipos de controles de contenido puedo insertar directamente con DocumentBuilder?

PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture y Date. Otros valores de SdtType no son compatibles con InsertStructuredDocumentTag().

¿Cómo encuentro todos los controles de contenido con una etiqueta específica?

Utilice Range.StructuredDocumentTags.GetByTag(), o GetByTitle() / GetById() si está comparando con esos en su lugar.

¿Cómo elimino un control de contenido pero mantengo su contenido?

Llame a StructuredDocumentTag.RemoveSelfOnly() en lugar de Remove().

¿Cómo vinculo un control de contenido a datos personalizados de XML?

Llame a XmlMapping.SetMapping() en el control, apuntándolo a una parte XML personalizada existente y a una expresión XPath dentro de ella.

¿Cuál es la diferencia entre un StructuredDocumentTag simple y uno con rango?

Un control de contenido que abarca más de una sección del documento se representa como un par StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd en lugar de un solo nodo; ambas formas implementan IStructuredDocumentTag.

API Reference Resumen

Ver también

• Aspose.Words for .NET — Enterprise Documentation