Visión general
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.
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:
- HtmlViewOptions.SpreadsheetOptions al renderizar un documento de hoja de cálculo a HTML,
- PdfViewOptions.SpreadsheetOptions al renderizar un documento de hoja de cálculo a PDF,
- PngViewOptions.SpreadsheetOptions al renderizar un documento de hoja de cálculo a PNG,
- JpgViewOptions.SpreadsheetOptions al renderizar un documento de hoja de cálculo a JPEG.
Cuando no se especifica explícitamente, la propiedad SpreadsheetOptions tiene un valor implícito por defecto 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 súper 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 archivo de hoja de cálculo de entrada a los 4 formatos de salida: HTML, PDF, PNG y JPEG. Tenga en cuenta que, salvo la creación de las instancias de las clases de opciones, no hay afinación específica de 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 cálculo. 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 contener solo una hoja; esto incluye, por ejemplo, todos los formatos basados en texto delimitado por separadores (CSV, TSV etc.).
De forma predeterminada, GroupDocs.Viewer renderiza todas las hojas dentro de la hoja de cálculo dada. Pero esto puede modificarse. 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 soportados que tengan páginas, pero en el contexto de la familia de formatos de hoja de cálculo describe exactamente los números de hoja a visualizar.
Tenga en cuenta que la numeración de páginas en general y la numeración de hojas 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 a PNG en una hoja de cálculo que tiene 3 hojas.
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 en páginas
GroupDocs.Viewer renderiza documentos en páginas, donde bajo “página” entendemos un área rectangular de tamaño relativamente pequeño, comparable al área de una pantalla o a una hoja A4. Por otro lado, las hojas pueden ser muy grandes. En concreto, el ya obsoleto formato XLS admite máx. 256 columnas y 65 536 filas, mientras que el formato más reciente XLSX (Workbook Office Open XML) y Microsoft Excel admiten hasta 16 384 columnas y 1 048 576 filas. “Encajar” las hojas en páginas es una parte crucial de la renderización de hojas de cálculo con GroupDocs.Viewer. Para ajustar la hoja a una(s) página(s), GroupDocs.Viewer realiza una segmentación de hoja — la hoja se divide en varios fragmentos rectangulares y cada uno se coloca en una página independiente. Existen 5 métodos diferentes, que se enumeran y describen a continuación.
Lo importante: todos estos métodos de segmentación se especifican del mismo modo — mediante un método estático (de fábrica) que crea una instancia de la clase SpreadsheetOptions.
Renderizar toda la hoja en una página
SpreadsheetOptions.ForOnePagePerSheet()
La forma más sencilla: desactivar la segmentación y ajustar el tamaño de página para que quepa todo el contenido de la hoja completa. 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 a HTML, el documento resultante puede ser enorme, de decenas o incluso cientos de MiB, lo que puede generar problemas al visualizar archivos tan grandes en los navegadores web. Al renderizar a JPEG, la situación puede ser peor si el ancho o alto supera el límite máximo de 65 535 píxeles. Por lo tanto, use este modo deliberadamente.
Dividir la hoja por saltos de página
SpreadsheetOptions.ForRenderingByPageBreaks()
Microsoft Excel agrega automáticamente saltos de página según el tamaño del papel y la configuración de página (orientación, márgenes, etc.). Si cambia a la pestaña “Vista” y entra en el modo “Vista previa de salto de página”, podrá ver líneas azules que dividen el área completa de la hoja en fragmentos rectangulares, cada uno etiquetado como “Página 1”, “Página 2”, etc. Así es como Microsoft Excel “sugiere” dividir la hoja en páginas.
Con este método GroupDocs.Viewer sigue a Microsoft Excel y divide las hojas de acuerdo con los saltos de página, tal como lo hace Excel.
Cabe mencionar que esta opción — dividir una hoja por saltos 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()
Además de 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 que están designados para imprimirse; cualquier contenido fuera del Área de impresión no se imprimirá. Para añadir 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 “Establecer Área de impresión” (ver captura de pantalla a continuación). Para añadir otro rango, seleccione el nuevo rango, haga clic en “Área de impresión” y después en “Añadir al Área de impresión”. En el modo “Vista previa de salto de página” podrá ver todos los rangos que forman el Área de impresión.
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 único modo. En este caso GroupDocs.Viewer tiene en cuenta tanto los rangos del Área de impresión como los saltos de página de la hoja y los aplica simultáneamente para dividir la hoja en páginas.
En la captura siguiente, la línea roja muestra el Área de impresión y la línea azul muestra los saltos de página.
Dividir la hoja 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 descritos anteriormente es aceptable, o la hoja tiene un formato que no soporta saltos de página ni Áreas de impresión, por ejemplo, un CSV basado en texto. Para estos 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 a continuación.
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.
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 que permiten a los usuarios ajustar aún más el resultado de la renderización.
Algunas de estas opciones se expresan como propiedades de la clase SpreadsheetOptions, accesible a través de la propiedad SpreadsheetOptions de la clase de opciones de vista. Otras, sin embargo, se encuentran en la clase abstracta ViewOptions, común a los cuatro modos de renderizado.
Renderizar encabezados de filas y columnas
Cuando MS Excel o un programa similar 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). Por defecto, GroupDocs.Viewer no muestra estos encabezados, ya que forman parte de la interfaz del procesador de tablas y no del documento mismo. Esto puede modificarse mediante la propiedad booleana RenderHeadings. Por defecto está desactivada (false), pero si se habilita (true), los encabezados de filas y columnas estarán presentes en el documento de salida, como se muestra en la captura siguiente.
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 representación del procesador de tablas. Sin embargo, mediante la propiedad booleana RenderGridLines es posible imitar el comportamiento de MS Excel. Asigne 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 siguiente.
Controlar desbordamiento de texto en celdas
Es un escenario muy frecuente que algún texto sea demasiado largo para ajustarse a los límites de su celda. ¿Cómo mostrar este texto correctamente? GroupDocs.Viewer ofrece la propiedad especial SpreadsheetOptions.TextOverflowMode para resolver este problema. La propiedad TextOverflowMode tiene un valor del mismo nombre, TextOverflowMode, que es un enum con 4 posibles ítems, 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 se desborde a celdas adyacentes solo si esas celdas están vacías. Si las celdas adyacentes no están vacías, el texto desbordado se trunca.
La captura muestra el archivo HTML renderizado a partir de un XLSX 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, y se desborda sobre las celdas “D2” y “E2” porque están vacías.
Overlay
El valor TextOverflowMode.Overlay es algo similar al anterior, pero puede considerarse más agresivo: el texto largo que no cabe dentro de los límites de su celda siempre se desborda, sin importar el contenido de las celdas adyacentes. Si esas celdas también contienen datos, serán sobrescritos.
La captura muestra cómo funciona. El texto largo de la celda “B2” se desborda a las celdas adyacentes “C2”, “D2”, “E2”, “F2”. Como resultado, el texto original de las celdas “C2” y “F2” se elimina.
HideText
El modo TextOverflowMode.HideText actúa como el opuesto al modo Overlay: en lugar de desbordarse, el texto se trunca incondicionalmente cuando no cabe en los límites de su propia celda, sin importar si hay espacio libre en celdas adyacentes o no.
En la captura se observa la celda “C3”: aunque hay espacio libre en la celda adyacente “D3” y siguientes, el texto se trunca de forma definitiva.
AutoFitColumn
El valor TextOverflowMode.AutoFitColumn resuelve el problema de otra manera: aumenta el ancho de la columna para que el texto de cualquier celda quepa completamente. Por lo tanto, sin importar la longitud del texto dentro de una celda, el ancho de la(s) columna(s) donde se encuentra esa celda se ampliará para acomodar toda la cadena.
La captura muestra su funcionamiento. Claro está, este enfoque puede no ser adecuado en algunos casos, sobre todo cuando el texto de la(s) celda(s) es extremadamente largo, lo que produciría una página extremadamente ancha con molestos desplazamientos horizontales.
Renderizar filas y columnas ocultas
Microsoft Excel y otros procesadores de tablas permiten ocultar filas o columnas específicas. Por defecto, GroupDocs.Viewer no renderiza esas filas/columnas, 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 ocultas
Al igual que ocurre con filas y columnas ocultas, el archivo de hoja de cálculo puede contener una o más hojas ocultas. Por defecto, GroupDocs.Viewer no renderiza esas hojas ocultas. Esto puede cambiarse mediante la propiedad RenderHiddenPages al establecer su valor en true. Cabe señalar que, a diferencia de las propiedades anteriores, RenderHiddenPages se encuentra en la clase abstracta BaseViewOptions, común a todas las opciones de vista.
Omitir filas y columnas vacías
Algunas hojas son “dispersas”, contienen muchos espacios vacíos que pueden ocupar mucho espacio. GroupDocs.Viewer dispone de una función para omitir filas y columnas vacías durante la renderización. Si esta característica está activada, las filas y/o columnas vacías se excluyen del HTML, PDF, PNG o JPEG resultante. Las propiedades booleanas SpreadsheetOptions.SkipEmptyRows y SpreadsheetOptions.SkipEmptyColumns controlan esta funcionalidad.
La captura muestra que tanto SkipEmptyRows como SkipEmptyColumns están activados.
Renderizar o ocultar comentarios de celda
Las celdas de una hoja pueden contener comentarios, y por defecto GroupDocs.Viewer los renderiza todos. Esto puede desactivarse mediante la propiedad BaseViewOptions.RemoveComments; si se establece en true, no se renderizará ningún comentario. Tenga en cuenta que esta propiedad se encuentra en la clase BaseViewOptions, no en SpreadsheetOptions.
La captura muestra la renderización de un archivo XLSX con comentarios de celda a formato PNG usando las opciones predeterminadas — el comentario de la celda “E2” aparece en el PNG resultante.
Establecer márgenes de hoja en las páginas PDF de salida
Al renderizar hojas a 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:
SpreadsheetOptions.TopMarginSpreadsheetOptions.RightMarginSpreadsheetOptions.BottomMarginSpreadsheetOptions.LeftMargin
Por defecto, estas 4 propiedades tienen valores negativos, lo que indica que se aplican los márgenes predeterminados de GroupDocs.Viewer. Sin embargo, es posible establecer estos valores explícitamente. Es importante aclarar que los márgenes de página solo se aplican cuando el formato de destino es PDF.
El fragmento de código a continuación muestra cómo crear un 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:
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, cualquier usuario podrá ajustar la renderización para satisfacer sus propias necesidades.
Véase también
- Renderizar hojas de cálculo de Excel y Apple Numbers como HTML, PDF y archivos de imagen
- Dividir una hoja en páginas
- Especificar opciones de renderizado de hoja de cálculo
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 aquí.