Cómo trabajar con tablas en .NET
Esta guía muestra cómo crear, formatear y leer tablas programáticamente en Aspose.Words FOSS para .NET, usando el Table, Row, y Cell clases en el Aspose.Words.Tables espacio de nombres junto con DocumentBuilder. Cubre la construcción de una tabla desde cero, el formateo de celdas y filas a medida que construyes, el control del diseño de toda la tabla y AutoFit, el establecimiento de anchos preferidos, la combinación de celdas y la lectura de tablas ya presentes en un documento cargado.
Guía paso a paso
Paso 1: Instalar el paquete
Aspose.Words FOSS for .NET aún no publica un paquete NuGet – construye la biblioteca desde el código fuente en su lugar. Clona https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git, luego construye Aspose.Words.sln en configuración Release con el SDK .NET y referencia el ensamblado Aspose.Words resultante desde tu 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
Añade una directiva using Aspose.Words; para las clases principales del documento (Document, DocumentBuilder), y una directiva using Aspose.Words.Tables; para las clases específicas de tablas que cubre esta guía – Table, Row, Cell, CellFormat, RowFormat, PreferredWidth, y los enums relacionados.
Paso 3: Construir una tabla nueva con DocumentBuilder
Crea un Document y un DocumentBuilder vinculados a él, luego llama a DocumentBuilder.StartTable() para iniciar una tabla en el cursor. Para cada celda en una fila, llama a DocumentBuilder.InsertCell(), y luego cierra la fila con DocumentBuilder.EndRow(). Repite tantas filas como necesite la tabla y cierra toda la tabla con DocumentBuilder.EndTable(). Cada StartTable() necesita un EndTable() correspondiente, y cada fila necesita un EndRow() correspondiente, o el estado interno del constructor — y el árbol de documentos resultante — quedarán malformados.
Paso 4: Formatear celdas y filas al construir
Establece DocumentBuilder.CellFormat y DocumentBuilder.RowFormat antes de llamar a InsertCell() o EndRow() para aplicar formato a las celdas y filas que el constructor está a punto de crear — estas dos propiedades actúan como una plantilla para contenido nuevo, no como un cambio retroactivo en celdas ya insertadas. CellFormat expone Borders, Shading, Width, WrapText, FitText, HorizontalMerge, VerticalMerge, VerticalAlignment, PreferredWidth, y las cuatro propiedades de relleno (LeftPadding, RightPadding, TopPadding, BottomPadding), que pueden establecerse todas a la vez con SetPaddings(). RowFormat expone Borders, Height, HeightRule, AllowBreakAcrossPages y HeadingFormat. Llama a CellFormat.ClearFormatting() o RowFormat.ClearFormatting() para restablecer cualquiera de ellas a los valores predeterminados antes de asignar nuevos valores para la siguiente fila o celda.
Paso 5: Establecer el diseño de toda la tabla y AutoFit
Una vez que la tabla existe, establece las propiedades de diseño directamente en el objeto Table: Alignment (TableAlignment), Bidi, LeftIndent, PreferredWidth, Style, StyleIdentifier, StyleName, StyleOptions (TableStyleOptions) y TextWrapping. Llama a Table.SetBorders() para aplicar un estilo de borde, ancho y color en toda la tabla, o a Table.SetBorder() para establecer un solo lado; ClearBorders() y ClearShading() restablecen esos valores. Table.AutoFit(AutoFitBehavior) redimensiona la tabla y sus celdas según el comportamiento elegido — llámalo de nuevo después de cualquier edición estructural, ya que refleja el estado de la tabla solo en el momento en que se ejecuta, no de forma continua.
Paso 6: Establecer anchos preferidos y de celda
Crea valores de ancho con los métodos de fábrica estáticos PreferredWidth.FromPercent() para un diseño que se adapta al ancho de página disponible, o PreferredWidth.FromPoints() para un ancho fijo; PreferredWidthType informa qué tipo de valor (Auto, Percent o Points) contiene un PreferredWidth dado. Asigna el resultado a Table.PreferredWidth para toda la tabla o a CellFormat.PreferredWidth para una celda.
Paso 7: Fusionar celdas
Marque las celdas como fusionadas estableciendo CellFormat.HorizontalMerge o CellFormat.VerticalMerge (ambos escritos CellMerge) en las celdas que deben participar en la fusión. Si las celdas solo parecían fusionadas al igualar sus anchos en lugar de estar marcadas explícitamente, llame a Table.ConvertToHorizontallyMergedCells() para convertir esa disposición visual en celdas con un estado real de CellMerge. CellVerticalAlignment controla cómo se justifica verticalmente el contenido dentro de una celda, independientemente de cualquier fusión.
Paso 8: Leer tablas de un documento existente
Para trabajar con tablas que ya están en un documento cargado, lea Body.Tables (o la propiedad Tables en cualquier otro Story) — un TableCollection — en lugar de crear nuevas. Table.Rows devuelve un RowCollection y Row.Cells devuelve un CellCollection; los tres tipos de colección admiten Add(), Insert(), Remove(), RemoveAt(), Contains() y IndexOf() para ediciones programáticas. Después de eliminar filas o celdas, llame a Table.EnsureMinimum(), Row.EnsureMinimum() o Cell.EnsureMinimum() para que el nodo mantenga la estructura mínima válida que Word espera — una fila vacía, una celda vacía o un párrafo vacío, respectivamente.
Problemas comunes y soluciones
Un documento guardado parece estar malformado, o ocurre un error al guardar Una fila o la tabla misma nunca se cerró. Siempre empareja DocumentBuilder.StartTable() con un final EndTable(), y cierra cada fila con EndRow() antes de pasar a la siguiente o terminar la tabla.
Las celdas nuevas no adoptan el formato que establecí CellFormat and RowFormat se cambiaron en el DocumentBuilder después de que las celdas afectadas ya fueron insertadas. Establece DocumentBuilder.CellFormat / RowFormat antes del InsertCell() or EndRow() llamada que crea el contenido que deseas formatear.
La tabla no cambia de tamaño como espero después de editar su contenido Table.AutoFit(AutoFitBehavior) refleja la estructura de la tabla solo en el momento en que se llama. Vuelve a llamarla después de cualquier edición estructural — agregar o eliminar filas, celdas o contenido — si el diseño necesita ajustarse nuevamente.
Las celdas que parecen combinadas se comportan como celdas separadas al volver a leerlas Las celdas solo se emparejaron por ancho, no se marcaron con CellMerge. Llamar Table.ConvertToHorizontallyMergedCells(), o establecer CellFormat.HorizontalMerge / VerticalMerge explícitamente en las celdas que deben combinarse.
Eliminar filas o celdas deja la tabla en un estado no válido Word espera cada Table, Row, y Cell para mantener una estructura mínima válida. Después de eliminar contenido programáticamente, llame a EnsureMinimum() en el nodo recién modificado.
Preguntas frecuentes
¿Cómo construyo una tabla desde cero en lugar de editar una existente?
Use DocumentBuilder: llame a StartTable(), luego InsertCell() para cada celda en una fila, EndRow() para cerrar la fila, repita para filas adicionales, y EndTable() para cerrar la tabla.
¿Cómo obtengo las tablas que ya existen en un documento cargado?
Lea la propiedad Tables (un TableCollection) en el Body de la sección que le interesa, o en cualquier otro Story como un encabezado o pie de página.
¿Cómo configuro una tabla a un porcentaje del ancho de la página en lugar de un ancho fijo?
Asigne Table.PreferredWidth = PreferredWidth.FromPercent(value) en lugar de PreferredWidth.FromPoints(value).
¿Cuál es la diferencia entre establecer bordes con SetBorders y SetBorder?
Table.SetBorders() aplica un estilo de línea, ancho y color a todos los bordes de la tabla de una vez; Table.SetBorder() establece un solo lado, permitiendo que diferentes lados tengan un formato distinto.
¿Cómo restablezco el formato en una celda o fila antes de reutilizarla?
Llame a CellFormat.ClearFormatting() en el CellFormat de la celda, o a RowFormat.ClearFormatting() en el RowFormat de la fila.
