Visión general

Los documentos de hoja de cálculo son documentos que contienen datos en forma de tabla — dentro de filas y columnas. También se les conoce como libros de trabajo. Existen muchos formatos de documentos de hoja de cálculo — Office Open XML (como XLSX, XLSM, etc.), Microsoft Excel Binary File Format (XLS, XLT), formato OpenDocument Spreadsheet (ODS, FODS, OTS), formatos basados en texto delimitado por separadores (CSV, TSV etc.) y así sucesivamente. Todos ellos forman la llamada familia de formatos de hoja de cálculo. GroupDocs.Viewer admite casi todos los formatos de hoja de cálculo en la importación y permite renderizarlos (convertirlos) a HTML, PDF, PNG y JPEG. Este artículo explica cómo hacerlo, qué opciones están disponibles y cuándo y por qué deberían usarse.

Rendering a workbook, opened in MS Excel, to the HTML format

Uso básico

Primero debemos hablar sobre las opciones. Existe una clase separada en la API pública: SpreadsheetOptions en el espacio de nombres GroupDocs.Viewer.Options. Esta clase está diseñada específicamente para ajustar la renderización de la familia de formatos de hoja de cálculo. Es accesible para las cuatro opciones de vista a través de la propiedad SpreadsheetOptions de:

Cuando no se especifica explícitamente, la propiedad SpreadsheetOptions tiene un valor implícito predeterminado de una instancia de la clase SpreadsheetOptions, que se explicará más adelante en este artículo.

En resumen, renderizar un documento de hoja de cálculo con GroupDocs.Viewer es muy fácil y similar a todos los demás formatos: crear una instancia de ViewOptions, crear una instancia de Viewer con el documento de hoja de cálculo de entrada especificado y llamar al método Viewer.View(viewOptions). El siguiente fragmento de código muestra la renderización del único archivo de hoja de cálculo de entrada a los 4 formatos de salida: HTML, PDF, PNG y JPEG. Tenga en cuenta que, aparte de crear las instancias de las clases de opciones, no hay afinación relacionada con hojas de cálculo, por lo que todas las opciones de hoja de cálculo están establecidas en sus valores predeterminados.

using GroupDocs.Viewer;
using GroupDocs.Viewer.Options;
// ...

HtmlViewOptions htmlOptions = HtmlViewOptions.ForEmbeddedResources("worksheet_{0}.html");
PdfViewOptions pdfOptions = new PdfViewOptions("Output_spreadsheet.pdf");
PngViewOptions pngOptions = new PngViewOptions("worksheet_{0}.png");
JpgViewOptions jpegOptions = new JpgViewOptions("worksheet_{0}.jpeg");

using (Viewer viewer = new Viewer("spreadsheet.xlsx"))
{
    viewer.View(htmlOptions);
    viewer.View(pdfOptions);
    viewer.View(pngOptions);
    viewer.View(jpegOptions);
}

Ahora hablemos de las hojas de trabajo. Cada hoja de cálculo tiene al menos una hoja de trabajo. En la mayoría del software de procesamiento de tablas como Microsoft Excel, las hojas de trabajo se representan como pestañas. Algunos formatos de hoja de cálculo pueden tener solo una hoja de trabajo; esto incluye, por ejemplo, todos los formatos basados en texto delimitado por separadores (CSV, TSV etc.).

Por defecto, GroupDocs.Viewer renderiza todas las hojas de trabajo dentro de la hoja de cálculo dada. Pero esto puede cambiarse. El método Viewer.View() tiene una sobrecarga que recibe un conjunto de números de página como segundo parámetro — Int32[] pageNumbers. Cuando se usa este parámetro, solo se renderizarán esas páginas. Este parámetro es universal y se aplica a todos los formatos compatibles que tienen páginas, pero en el contexto de la familia de formatos de hoja de cálculo describe exactamente los números de hoja de trabajo a visualizar.

Tenga en cuenta que la numeración de páginas en general y la numeración de hojas de trabajo en particular son basadas en 1, no en 0, por lo que comienzan en “1”, no en “0”.

El ejemplo a continuación muestra cómo renderizar la 1ª y la 3ª hoja de trabajo a PNG en una hoja de cálculo que tiene 3 hojas de trabajo.

using GroupDocs.Viewer;
using GroupDocs.Viewer.Options;
// ...

PngViewOptions pngOptions = new PngViewOptions("worksheet_{0}.png");
using (Viewer viewer = new Viewer("spreadsheet.xlsx"))
{
    viewer.View(pngOptions, 1, 3);
}

Dividir hojas de trabajo en páginas

GroupDocs.Viewer renderiza los documentos en páginas, donde bajo “página” entendemos alguna área rectangular de tamaño relativamente pequeño, comparable al área de una pantalla o a una hoja A4. Por otro lado, las hojas de trabajo pueden ser muy grandes. En particular, el formato ahora obsoleto XLS admite máximo 256 columnas y 65536 filas, mientras que el formato más reciente XLSX (Office Open XML Workbook) y Microsoft Excel ambos soportan hasta 16384 columnas y 1048576 filas. “Ajustar” las hojas de trabajo a páginas es una parte crucial de la renderización de hojas de cálculo con GroupDocs.Viewer. Para encajar la hoja de trabajo en una(s) página(s), GroupDocs.Viewer realiza una división de hoja de trabajo: la hoja se divide en varios fragmentos rectangulares, y cada uno de ellos se coloca en una página separada. Existen 5 métodos diferentes, que se enumeran y describen a continuación.

Lo importante — todos estos métodos de división se especifican de la misma manera — usando un método estático específico (método de fábrica) que crea una instancia de la clase SpreadsheetOptions.

Renderizar toda la hoja de trabajo en una página

SpreadsheetOptions.ForOnePagePerSheet()

La forma más fácil y sencilla — desactivar la división y ajustar el tamaño de página para que quepa todo el contenido de la hoja completa. Esta es una buena opción cuando ya se sabe que la hoja tiene un tamaño pequeño. Sin embargo, si la hoja es realmente grande, este enfoque puede producir resultados desastrosos. En particular, al renderizar al formato HTML, el documento HTML resultante puede ser enorme, de decenas o incluso cientos de MiB, lo que puede causar problemas al visualizar archivos tan grandes en los navegadores web. Al renderizar al formato JPEG, la situación puede empeorar si el ancho o la altura superan el límite máximo de 65535 píxeles. Por lo tanto, use este modo de forma deliberada.

Render worksheet on one page

Dividir la hoja de trabajo por saltos de página

SpreadsheetOptions.ForRenderingByPageBreaks()

Microsoft Excel agrega automáticamente saltos de página basados en el tamaño del papel y la configuración de página, como la orientación y los márgenes. Si cambia a la pestaña “Vista” y entra en el modo “Vista previa de salto de página”, verá líneas azules que dividen toda el área de la hoja en fragmentos rectangulares, cada uno etiquetado como “Página 1”, “Página 2”, etc. Así es como Microsoft Excel “sugiere” dividir una hoja de trabajo en páginas.

Con este método, GroupDocs.Viewer sigue a Microsoft Excel y divide las hojas de trabajo según los saltos de página, tal como lo hace Excel.

Cabe mencionar que esta opción — dividir una hoja de trabajo por salto de página — es la opción predeterminada de la propiedad BaseViewOptions.SpreadsheetOptions, por lo que al crear una instancia de la clase de opciones de vista, la opción “ForRenderingByPageBreaks()” se selecciona por defecto.

Renderizar solo el área de impresión

SpreadsheetOptions.ForRenderingPrintArea()

Junto con los saltos de página, Microsoft Excel tiene el concepto de “Área de impresión”. El Área de impresión es en realidad uno o más rangos de celdas en una hoja de trabajo, designados para imprimir, mientras que cualquier contenido fuera del Área de impresión no se imprimirá en absoluto. Para agregar un rango de celdas al Área de impresión, vaya a la pestaña “Diseño de página”, haga clic en el botón “Área de impresión” y luego seleccione el elemento “Establecer área de impresión” (ver captura de pantalla a continuación). Para agregar otro rango al Área de impresión, seleccione el nuevo rango, haga clic en el botón “Área de impresión” y luego en “Agregar al área de impresión”. En el modo “Vista previa de salto de página” puede ver todos los rangos de celdas en el Área de impresión.

Render only print area

Renderizar el área de impresión y dividir por saltos de página

SpreadsheetOptions.ForRenderingPrintAreaAndPageBreaks()

GroupDocs.Viewer tiene una característica única — combinar el Área de impresión y los saltos de página en un solo modo. En este caso, GroupDocs.Viewer tiene en cuenta todos los rangos de celdas del área de impresión y los saltos de página en la hoja y los aplica simultáneamente para dividir la hoja en páginas.

En la siguiente captura de pantalla, la línea roja muestra el área de impresión y la línea azul muestra los saltos de página.

Render print area and split by page breaks

Dividir la hoja de trabajo en páginas manualmente por filas y columnas

SpreadsheetOptions.ForSplitSheetIntoPages(int countRowsPerPage)
SpreadsheetOptions.ForSplitSheetIntoPages(int countRowsPerPage, int countColumnsPerPage)

A veces ninguno de los métodos de división descritos arriba es aceptable, o la hoja de cálculo tiene un formato que no soporta saltos de página ni Áreas de impresión, por ejemplo, el CSV basado en texto. Para esos casos, GroupDocs.Viewer permite especificar manualmente el número de filas y/o columnas que deben aparecer en cada página. En resumen, la diferencia entre dividir solo por filas y dividir por filas y columnas se ilustra en la captura de pantalla siguiente.

Si se usa la primera sobrecarga del método ForSplitSheetIntoPages, con un solo parámetro, se habilita la división solo por filas. Si se usa la segunda sobrecarga, donde se especifican dos parámetros, se habilita la división por filas y columnas.

Split worksheet into pages manually by rows and columns

Ajuste de opciones adicionales

Todo lo descrito arriba es esencial y suficiente para renderizar hojas de cálculo usando GroupDocs.Viewer. Sin embargo, existen muchas opciones adicionales, que no son obligatorias, pero permiten a los usuarios ajustar el resultado de la renderización aún más.

Algunas de estas opciones se representan como propiedades de la clase SpreadsheetOptions, que a su vez es accesible como propiedad SpreadsheetOptions de la clase de opciones de vista. Otras, sin embargo, se encuentran en la clase abstracta ViewOptions, común a los 4 modos de renderización.

Renderizar encabezados de filas y columnas

Cuando MS Excel o un programa similar de procesamiento de tablas abre un documento de hoja de cálculo, muestra los encabezados de columnas y filas; las columnas se etiquetan con letras (A, B, C, AA, AB, …) y las filas con números (1, 2, 3, …, 1048576). Al renderizar, GroupDocs.Viewer por defecto no muestra estos encabezados, porque forman parte de la interfaz del procesador de tablas, no del documento en sí. Pero esto puede cambiarse con la propiedad RenderHeadings de tipo booleano. Por defecto está deshabilitada y tiene el valor false; cuando se habilita (true), los encabezados de filas y columnas estarán presentes en el documento de salida, como se muestra en la captura de pantalla a continuación.

Render row and column headings

Renderizar líneas de cuadrícula de la hoja

El concepto de esta opción es muy similar al anterior. Por defecto GroupDocs.Viewer no muestra las líneas de cuadrícula entre celdas, porque no forman parte de la hoja de cálculo, sino que son una forma de representar el contenido de la tabla en un procesador concreto. Sin embargo, usando la propiedad RenderGridLines de tipo booleano es posible imitar el comportamiento de MS Excel. Asigne el valor true a la propiedad SpreadsheetOptions.RenderGridLines y las líneas de cuadrícula estarán presentes en el documento de salida, como se muestra en la captura de pantalla a continuación.

Render worksheet gridlines

Controlar el desbordamiento de texto en celdas

Es un escenario bastante común que algún texto no quepa dentro de los límites de su celda. ¿Cómo mostrar ese texto correctamente? GroupDocs.Viewer proporciona una propiedad especial SpreadsheetOptions.TextOverflowMode para resolver este problema. La propiedad TextOverflowMode tiene un valor del tipo con el mismo nombre, TextOverflowMode, y es un enum con 4 posibles valores, explicados a continuación.

OverlayIfNextIsEmpty

Por defecto la propiedad SpreadsheetOptions.TextOverflowMode tiene el valor OverlayIfNextIsEmpty, que imita el comportamiento predeterminado de Microsoft Excel. En resumen, este valor permite que el texto desborde a celdas adyacentes, pero solo si esas celdas adyacentes están vacías. Si las celdas adyacentes no están vacías, el texto desbordado se trunca.

OverlayIfNextIsEmpty enum value

La captura de pantalla muestra el archivo HTML renderizado a partir de un XLSX de entrada con el valor OverlayIfNextIsEmpty. Observe la celda “B2”: tiene un texto largo que se trunca porque la celda “C2” no está vacía. La celda “C3”, sin embargo, también tiene un texto largo que no cabe, pero se desborda sobre las celdas “D2” y “E2”, ya que están vacías.

Overlay

El valor TextOverflowMode.Overlay es ligeramente similar al anterior, pero puede considerarse más agresivo: el texto largo que no cabe dentro de los límites originales de la celda siempre desborda, sin importar el contenido de las celdas adyacentes. Si las celdas adyacentes también contienen texto u otros datos, estos serán borrados.

Overlay enum value

La captura de pantalla muestra cómo funciona. El texto largo de la celda “B2” desborda a las celdas adyacentes “C2”, “D2”, “E2”, “F2”. Como resultado, el texto original de las celdas “C2” y “F2” se borra.

HideText

El modo TextOverflowMode.HideText funciona como el opuesto al modo Overlay: en lugar de desbordar, el texto que no cabe dentro de los límites de su propia celda se trunca incondicionalmente, sin importar si hay espacio libre en las celdas adyacentes.

HideText enum value

En la captura de pantalla se observa la celda “C3”: a pesar de que hay espacio libre en la celda adyacente “D3” y siguientes, el texto se trunca de forma incondicional.

AutoFitColumn

El valor TextOverflowMode.AutoFitColumn resuelve el problema con otro enfoque: aumenta el ancho de la columna para que quepa el texto de cualquier celda. Así, sin importar cuán largo sea el texto dentro de una celda concreta, el ancho de la(s) columna(s) donde se encuentra esa celda se incrementará para acomodar toda la cadena.

AutoFitColumn enum value

La captura de pantalla muestra cómo funciona. Por supuesto, este enfoque puede no ser adecuado en algunos casos, especialmente cuando el texto en la(s) celda(s) es extremadamente largo, lo que hará que la página sea extremadamente ancha y provoque un molesto desplazamiento horizontal.

Renderizar filas y columnas ocultas

Microsoft Excel y otros procesadores de tablas permiten ocultar filas y columnas específicas. Por defecto GroupDocs.Viewer no renderiza esas filas y columnas ocultas, pero este comportamiento puede modificarse. Las propiedades ViewOptions.SpreadsheetOptions.RenderHiddenRows y ViewOptions.SpreadsheetOptions.RenderHiddenColumns, al establecerse en true, permiten mostrar filas y columnas ocultas en el archivo de salida al renderizar la hoja de cálculo en HTML, PDF, PNG o JPEG.

Renderizar hojas de trabajo ocultas

Al igual que las filas y columnas ocultas, una hoja de cálculo puede contener una o más hojas de trabajo ocultas. Y, como en el caso anterior, por defecto GroupDocs.Viewer no renderiza las hojas ocultas. Pero esto puede cambiarse usando la propiedad RenderHiddenPages estableciéndola en true. Cabe mencionar que, a diferencia de las propiedades descritas anteriormente, RenderHiddenPages se encuentra no en SpreadsheetOptions, sino en la clase abstracta BaseViewOptions, común a todas las opciones de vista.

Omitir filas y columnas vacías

Algunas hojas de cálculo son “dispersas”: contienen muchos espacios vacíos que pueden ocupar demasiado espacio. GroupDocs.Viewer tiene una función para omitir filas y columnas vacías durante la renderización. Si esta función está habilitada, las filas y/o columnas vacías se excluyen del HTML, PDF, PNG y JPEG resultantes. Las propiedades booleanas SpreadsheetOptions.SkipEmptyRows y SpreadsheetOptions.SkipEmptyColumns son responsables de esta característica.

Skip empty rows and columns

La captura de pantalla muestra que tanto SkipEmptyRows como SkipEmptyColumns están habilitados.

Renderizar o ocultar comentarios de celdas

Las celdas dentro de un documento de hoja de cálculo pueden tener comentarios, y por defecto GroupDocs.Viewer los renderiza todos. Pero esto puede desactivarse usando la propiedad BaseViewOptions.RemoveComments: si se establece en true, no se renderizarán comentarios. Tenga en cuenta que esta propiedad se encuentra en la clase BaseViewOptions, no en SpreadsheetOptions.

Render or hide cell comments

La captura de pantalla muestra la renderización de un archivo XLSX con comentarios de celda a formato PNG con las opciones predeterminadas: el comentario de la celda “E2” está presente en el archivo PNG resultante.

Establecer márgenes de hoja en las páginas PDF de salida

Al renderizar hojas de trabajo al formato PDF, es posible controlar los márgenes de página — la distancia en centímetros desde el borde de la página hasta el contenido. Hay 4 propiedades para controlar los márgenes superior, derecho, inferior e izquierdo:

Por defecto, estas 4 propiedades tienen valores negativos, lo que significa que los márgenes predeterminados son aplicados por GroupDocs.Viewer. Sin embargo, es posible establecer estos valores explícitamente. Es importante enfatizar que los márgenes de página solo se aplican cuando el formato de destino es PDF.

El siguiente fragmento de código muestra cómo crear PdfViewOptions, establecer los 4 márgenes y renderizar un documento:

using GroupDocs.Viewer;
using GroupDocs.Viewer.Options;
// ...

PdfViewOptions pdfViewOptions = new PdfViewOptions("Output.pdf");
pdfViewOptions.SpreadsheetOptions = SpreadsheetOptions.ForOnePagePerSheet();
pdfViewOptions.SpreadsheetOptions.TopMargin = 2;
pdfViewOptions.SpreadsheetOptions.BottomMargin = 4;
pdfViewOptions.SpreadsheetOptions.LeftMargin = 8;
pdfViewOptions.SpreadsheetOptions.RightMargin = 0;

using (var viewer = new Viewer("spreadsheet.xlsx"))
{
    viewer.View(pdfViewOptions);
}

La siguiente imagen muestra el resultado:

Set worksheet margins in the output PDF pages

Conclusión

Los formatos de hoja de cálculo son bastante complejos, y los documentos pueden contener contenido muy diverso en tipo y longitud. En muchos casos es imposible renderizar un documento de hoja de cálculo complejo a algún formato con las opciones predeterminadas, y por eso GroupDocs.Viewer ofrece un conjunto tan completo de propiedades; con ellas, cada usuario podrá ajustar la renderización para satisfacer sus propias necesidades.

Véase también

Obtenga una prueba gratuita

Puede descargar una versión de prueba gratuita de GroupDocs.Viewer para .NET desde releases.groupdocs.com. También puede obtener una licencia temporal para probar todas las funciones y características sin restricciones desde aquí.