Cómo trabajar con etiquetas de documento estructurado en .NET

Paso 1: Instalar el paquete

Aspose.Words FOSS for .NET aún no publica un paquete NuGet; en su lugar, compile la biblioteca desde el código fuente. Clone https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git, luego compile Aspose.Words.sln en configuración Release con el SDK .NET y haga referencia al ensamblado Aspose.Words resultante desde su proyecto. La biblioteca tiene como objetivo .NET Standard 2.0, por lo que se ejecuta en .NET Framework 4.6.2+ y .NET 6/8/10.

Paso 2: Importar las clases requeridas

Agregue una directiva using Aspose.Words; para Document y DocumentBuilder, y una directiva using Aspose.Words.Markup; para StructuredDocumentTag, SdtType, SdtListItem, SdtListItemCollection, XmlMapping, y las demás clases de controles de contenido que cubre esta guía.

Paso 3: Verifique qué tipos de control de contenido puede insertar

Antes de insertar, verifique si el objetivo SdtType es uno de los siete tipos aceptados por DocumentBuilder.InsertStructuredDocumentTag(SdtType): PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture y Date. RepeatingSection y RepeatingSectionItem no pueden insertarse en un cursor de texto con este método — envuelven párrafos completos o filas de tabla en su lugar. Los valores restantes de SdtType que pueden aparecer en un archivo 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 aceptados por este método de inserción en absoluto.

Paso 4: Insertar un control de contenido en el cursor

Llame a DocumentBuilder.InsertStructuredDocumentTag(SdtType) con uno de los siete tipos compatibles para insertar un nuevo control en la posición actual del cursor del constructor; la llamada devuelve el nuevo StructuredDocumentTag. Establezca Tag y Title en el control devuelto para darle las cadenas identificadoras que los autores ven en Word, y establezca PlaceholderName (respaldado por un Placeholder BuildingBlock) para el texto de sugerencia que Word muestra mientras el control está vacío — IsShowingPlaceholderText informa si esa sugerencia se muestra actualmente.

Paso 5: Configurar contenido específico del tipo

Para un control de casilla de verificación, lea o establezca StructuredDocumentTag.Checked, y llame a SetCheckedSymbol() / SetUncheckedSymbol() para personalizar los glifos mostrados en cada estado. Para un control de fecha, establezca FullDate, con DateDisplayFormat y DateDisplayLocale controlando cómo se representa, DateStorageFormat (SdtDateStorageFormat) controlando cómo se almacena cuando está vinculado a datos XML, y CalendarType (SdtCalendarType) seleccionando el sistema de calendario. Para una lista desplegable o cuadro combinado, rellene ListItems — un SdtListItemCollection de SdtListItem (DisplayText, Value) — antes de establecer SelectedValue para elegir la opción activa. Para un control de texto sin formato, Multiline es una propiedad bool en StructuredDocumentTag que puede configurarse para ajustar el control.

Paso 6: Apariencia del control y bloqueo

Establezca Appearance (SdtAppearance) para controlar cómo se delimita visualmente el control en Word, y Color para definir su color de resaltado. ContentsFont y EndCharacterFont controlan la fuente aplicada al contenido del control y a su carácter final de cierre. LockContentControl y LockContents son interruptores independientes — establezca LockContentControl para bloquear la eliminación del propio control, y LockContents para bloquear la edición de lo que contiene, sin afectar al otro.

Paso 7: Encontrar y eliminar controles de contenido

Lea Range.StructuredDocumentTags – un StructuredDocumentTagCollection delimitado a ese rango – y llame a GetById(), GetByTag() o GetByTitle() para localizar un control específico, o a Remove() / RemoveAt() en la colección para eliminar uno por referencia o índice. En un control individual, llame a Remove() para borrar el control junto con su contenido, a RemoveSelfOnly() para borrar solo el contenedor manteniendo su contenido en el documento, o a Clear() para vaciar su contenido mientras se conserva el control en su lugar.

Paso 8: Vincular un control a datos personalizados de XML

Lea StructuredDocumentTag.XmlMapping – una instancia de XmlMapping – y llame a SetMapping(customXmlPart, xPath, prefixMapping) para vincular el control a una parte personalizada de XML ya presente en el almacén de datos personalizados XML del documento, usando una expresión XPath para seleccionar el elemento vinculado. XmlMapping.IsMapped indica si una vinculación está activa, CustomXmlPart y StoreItemId identifican la parte de datos vinculada, y Delete() elimina la asignación.

Paso 9: Manejar controles de contenido que abarcan varias secciones

Un control de contenido que abarca más de una sección del documento – reportado por IsMultiSection – no se representa mediante un único nodo StructuredDocumentTag, sino mediante un par StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd, conectado a través de StructuredDocumentTagRangeStart.RangeEnd. Programe contra la interfaz compartida IStructuredDocumentTag (Tag, Title, Placeholder, PlaceholderName, Appearance, IsShowingPlaceholderText, RemoveSelfOnly()) cuando el código necesite manejar tanto las formas de nodo único como las de rango de manera uniforme, en lugar de ramificarse según el tipo concreto.