Trabalhando com Planilhas no GroupDocs.Viewer para .NET

Visão Geral

Documentos de planilha são documentos que contêm dados em forma de tabela — dentro de linhas e colunas. Eles também são conhecidos como pastas de trabalho. Existem muitos formatos de documentos de planilha — Office Open XML (como XLSX, XLSM, etc.), Microsoft Excel Binary File Format (XLS, XLT), formato OpenDocument Spreadsheet (ODS, FODS, OTS), formatos baseados em texto delimitados por separadores (CSV, TSV etc.) e assim por diante. Todos eles formam a chamada família de formatos de planilha. O GroupDocs.Viewer oferece suporte a quase todos os formatos de planilha na importação e permite renderizá‑los (convertê‑los) para HTML, PDF, PNG e JPEG. Este artigo explica como fazer isso, quais opções estão disponíveis e quando e por que elas devem ser usadas.

Uso básico

Primeiro, precisamos falar sobre opções. Existe uma classe separada na API pública: SpreadsheetOptions em GroupDocs.Viewer.Options. Essa classe foi criada especialmente para ajustar a renderização da família de formatos de planilha. Ela é acessível para todas as quatro opções de visualização através da propriedade SpreadsheetOptions de:

• HtmlViewOptions.SpreadsheetOptions ao renderizar um documento de planilha para HTML,
• PdfViewOptions.SpreadsheetOptions ao renderizar um documento de planilha para PDF,
• PngViewOptions.SpreadsheetOptions ao renderizar um documento de planilha para PNG,
• JpgViewOptions.SpreadsheetOptions ao renderizar um documento de planilha para JPEG.

Quando não especificada explicitamente, a propriedade SpreadsheetOptions recebe um valor implícito padrão da instância da classe SpreadsheetOptions, que será explicada mais adiante neste artigo.

De forma resumida, renderizar um documento de planilha com o GroupDocs.Viewer é super‑fácil e semelhante a todos os outros formatos — crie uma instância de ViewOptions, crie uma instância de Viewer com o documento de planilha de entrada especificado e chame o método Viewer.View(viewOptions). O exemplo de código a seguir demonstra a renderização do único arquivo de planilha de entrada para os quatro formatos de saída: HTML, PDF, PNG e JPEG. Observe que, exceto pela criação das instâncias das classes de opções, não há ajustes específicos de planilha, portanto todas as opções de planilha permanecem com seus valores padrão.

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);
}

Agora vamos falar sobre as planilhas. Cada planilha tem ao menos uma aba. Na maioria dos softwares de processamento de tabelas, como o Microsoft Excel, as planilhas são representadas como abas. Alguns formatos de planilha podem ter apenas uma única aba; isso inclui, por exemplo, todos os formatos baseados em texto delimitados por separadores (CSV, TSV etc.).

Por padrão, o GroupDocs.Viewer renderiza todas as planilhas dentro da planilha fornecida. Mas isso pode ser alterado. O método Viewer.View() possui uma sobrecarga que aceita um conjunto de números de página como segundo parâmetro — Int32[] pageNumbers. Quando esse parâmetro é usado, apenas as páginas indicadas são renderizadas. Esse parâmetro é universal e se aplica a todos os formatos suportados que possuem páginas, porém, no contexto da família de formatos de planilha, ele descreve exatamente os números das planilhas a serem visualizadas.

Observe que a numeração de páginas em geral e a numeração de planilhas em particular são baseadas em 1, não em 0, portanto começam em “1”, não em “0”.

O exemplo abaixo mostra como renderizar a 1ª e a 3ª planilha para PNG em uma planilha que contém 3 abas.

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);
}

Dividindo planilhas em páginas

O GroupDocs.Viewer renderiza documentos em páginas, onde por página entendemos uma área retangular relativamente pequena, comparável ao tamanho da tela ou a uma folha A4. Por outro lado, as planilhas podem ser muito grandes. Em particular, o formato já obsoleto XLS suporta máximo de 256 colunas e 65 536 linhas, enquanto o formato mais recente XLSX (Office Open XML Workbook) e o Microsoft Excel suportam até 16 384 colunas e 1 048 576 linhas. “Ajustar” planilhas às páginas é uma parte crucial da renderização de planilhas com o GroupDocs.Viewer. Para encaixar a planilha em uma(s) página(s), o GroupDocs.Viewer realiza um divisão de planilha — a planilha é dividida em vários blocos retangulares, e cada um deles é colocado em uma página separada. Existem 5 métodos diferentes, listados e descritos a seguir.

O que é importante — todos esses métodos de divisão são especificados da mesma forma — usando um método estático específico (método de fábrica) que cria uma instância da classe SpreadsheetOptions.

Renderizar a planilha inteira em uma página

SpreadsheetOptions.ForOnePagePerSheet()

A maneira mais fácil e simples — desativar a divisão e ajustar o tamanho da página para caber todo o conteúdo da planilha. Esta é uma boa escolha quando já se sabe que a planilha tem tamanho pequeno. Contudo, se a planilha for realmente grande, essa abordagem pode gerar resultados terríveis. Em particular, ao renderizar para HTML, o documento resultante pode ser enorme, com dezenas ou até centenas de MiB, o que pode causar problemas ao visualizar arquivos tão grandes em navegadores. Ao renderizar para JPEG, a situação pode ser ainda pior se a largura ou altura ultrapassar o limite máximo de 65 535 pixels. Portanto, use este modo deliberadamente.

Dividir a planilha por quebras de página

SpreadsheetOptions.ForRenderingByPageBreaks()

O próprio Microsoft Excel adiciona quebras de página automáticas com base no tamanho do papel e nas configurações de página, como orientação e margens. Se você mudar para a aba “View” e entrar no modo “Page Break Preview”, verá linhas azuis que dividem toda a área da planilha em blocos retangulares, cada um rotulado como “Page 1”, “Page 2”, e assim por diante. É assim que o Microsoft Excel “sugere” dividir uma planilha em páginas.

Com este método, o GroupDocs.Viewer segue o Microsoft Excel e divide as planilhas de acordo com as quebras de página, como o próprio Excel faz.

Vale mencionar que esta opção — dividir uma planilha por quebra de página — é a opção padrão da propriedade BaseViewOptions.SpreadsheetOptions. Portanto, ao criar uma instância da classe de opções de visualização, a opção [ForRenderingByPageBreaks()] já está selecionada por padrão.

Renderizar apenas a área de impressão

SpreadsheetOptions.ForRenderingPrintArea()

Além das quebras de página, o Microsoft Excel possui o conceito de “Área de Impressão”. A Área de Impressão consiste em um ou mais intervalos de células designados para impressão; qualquer conteúdo fora da Área de Impressão não será impresso. Para adicionar um intervalo à Área de Impressão, vá até a aba “Page Layout”, clique no botão “Print Area” e depois em “Set Print Area” (veja a captura de tela abaixo). Para acrescentar outro intervalo, selecione o novo intervalo, clique novamente em “Print Area” e escolha “Add to Print Area”. No modo “Page Break Preview” você pode ver todos os intervalos que compõem a Área de Impressão.

Renderizar a área de impressão e dividir por quebras de página

SpreadsheetOptions.ForRenderingPrintAreaAndPageBreaks()

O GroupDocs.Viewer possui um recurso exclusivo — combinar a Área de Impressão e as quebras de página em um único modo. Nesse caso, o GroupDocs.Viewer considera simultaneamente todos os intervalos da Área de Impressão e as quebras de página da planilha para dividi‑la em páginas.

Na captura de tela a seguir, a linha vermelha indica a área de impressão e a linha azul indica as quebras de página.

Dividir a planilha em páginas manualmente por linhas e colunas

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

Às vezes nenhum dos métodos de divisão descritos acima é aceitável, ou a planilha tem um formato que não suporta quebras de página nem Áreas de Impressão, como, por exemplo, o CSV baseado em texto. Nesses casos, o GroupDocs.Viewer permite especificar manualmente o número de linhas e/ou colunas que devem aparecer em cada página. Em resumo, a diferença entre dividir apenas por linhas e dividir por linhas e colunas é ilustrada na captura de tela abaixo.

Se a primeira sobrecarga do método ForSplitSheetIntoPages for usada (com um parâmetro), a divisão apenas por linhas será ativada. Se a segunda sobrecarga for usada (com dois parâmetros), a divisão por linhas e colunas será ativada.

Ajustando opções adicionais

Tudo que foi descrito acima é essencial e suficiente para renderizar planilhas usando o GroupDocs.Viewer. Contudo, há muitas opções adicionais, que não são obrigatórias, mas permitem ao usuário ajustar ainda mais o resultado da renderização.

Algumas dessas opções são representadas como propriedades da classe SpreadsheetOptions, que por sua vez está acessível como propriedade SpreadsheetOptions da classe de opções de visualização. Outras, porém, estão localizadas na classe abstrata ViewOptions, comum a todos os quatro modos de renderização.

Renderizar cabeçalhos de linhas e colunas

Quando o MS Excel ou um programa similar abre um documento de planilha, ele exibe os cabeçalhos de colunas e linhas; as colunas são nomeadas por letras (A, B, C, AA, AB, …) e as linhas são numeradas (1, 2, 3, …, 1 048 576). Na renderização, o GroupDocs.Viewer, por padrão, não exibe esses cabeçalhos, pois eles fazem parte da interface do processador de tabelas, não do próprio documento. Mas isso pode ser alterado com a propriedade RenderHeadings de tipo booleano. Por padrão está desativada (false); ao ser ativada (true), os cabeçalhos de linhas e colunas aparecerão no documento de saída, como mostra a captura de tela abaixo.

Renderizar linhas de grade da planilha

O conceito desta opção é muito parecido com o anterior. Por padrão o GroupDocs.Viewer não exibe as linhas de grade entre as células, pois elas não fazem parte da planilha, mas são apenas uma forma de representar visualmente o conteúdo da tabela. No entanto, usando a propriedade RenderGridLines (boolean), é possível replicar o comportamento do MS Excel. Defina true na propriedade SpreadsheetOptions.RenderGridLines e as linhas de grade aparecerão no documento de saída, conforme a captura de tela abaixo.

Controlar o transbordamento de texto nas células

É comum que um texto não caiba nos limites de sua célula. Como exibi‑lo corretamente? O GroupDocs.Viewer oferece a propriedade especial SpreadsheetOptions.TextOverflowMode para resolver esse problema. A propriedade TextOverflowMode tem o tipo TextOverflowMode, que é um enum com 4 valores possíveis, explicados a seguir.

OverlayIfNextIsEmpty

Por padrão, SpreadsheetOptions.TextOverflowMode tem o valor OverlayIfNextIsEmpty, que imita o comportamento padrão do Microsoft Excel. Em suma, esse valor permite que o texto transborde para células adjacentes somente se essas células estiverem vazias. Se as células adjacentes contiverem dados, o texto transbordado será truncado.

A captura acima mostra o arquivo HTML gerado a partir de um XLSX com o valor OverlayIfNextIsEmpty. Observe a célula “B2” — ela contém texto longo e foi truncada porque a célula “C2” não está vazia. A célula “C3”, porém, também tem texto longo que não cabe, e ele transborda para “D2” e “E2” porque essas células estão vazias.

Overlay

O valor TextOverflowMode.Overlay é semelhante ao anterior, porém mais agressivo: texto longo que não cabe nos limites da célula original sempre transborda, independentemente das células adjacentes. Se as células adjacentes contiverem algum texto ou dado, ele será apagado.

A captura demonstra o funcionamento. O texto longo da célula “B2” transborda para “C2”, “D2”, “E2” e “F2”. Como consequência, o conteúdo original das células “C2” e “F2” foi apagado.

HideText

O modo TextOverflowMode.HideText funciona como o oposto do modo Overlay — em vez de transbordar, ele simplesmente truncará o texto que não cabe nos limites da própria célula, independentemente de haver espaço livre nas células adjacentes.

Na captura acima isso pode ser visto na célula “C3” — apesar de haver espaço livre em “D3” e seguintes, o texto foi truncado incondicionalmente.

AutoFitColumn

O valor TextOverflowMode.AutoFitColumn resolve o problema de outra forma — amplia a largura da coluna para acomodar o texto da célula. Assim, independentemente do tamanho do texto, a largura da coluna em que a célula está será aumentada para exibir a string completa.

A captura mostra o funcionamento. Claro que esse método pode não ser adequado em alguns casos, especialmente quando o texto nas células é excessivamente longo — isso pode tornar a página extremamente larga, gerando rolagem horizontal incômoda.

Renderizar linhas e colunas ocultas

Microsoft Excel e outros processadores de tabela permitem ocultar linhas e colunas específicas. Por padrão o GroupDocs.Viewer não renderiza essas linhas e colunas ocultas, mas esse comportamento pode ser alterado. As propriedades ViewOptions.SpreadsheetOptions.RenderHiddenRows e ViewOptions.SpreadsheetOptions.RenderHiddenColumns, quando definidas como true, permitem exibir linhas e colunas ocultas no arquivo de saída ao renderizar a planilha em HTML, PDF, PNG ou JPEG.

Renderizar planilhas ocultas

Assim como linhas e colunas ocultas, o arquivo de planilha pode conter uma ou mais planilhas ocultas. Por padrão o GroupDocs.Viewer não as renderiza. Isso pode ser modificado usando a propriedade RenderHiddenPages definida como true. Vale notar que, ao contrário das propriedades descritas anteriormente, RenderHiddenPages está localizada não em SpreadsheetOptions, mas na classe abstrata BaseViewOptions, comum a todas as opções de visualização.

Ignorar linhas e colunas vazias

Algumas planilhas são “esparsas” — contêm muitos espaços vazios que podem ocupar muito espaço. O GroupDocs.Viewer possui um recurso para ignorar linhas e colunas vazias durante a renderização. Quando ativado, linhas e/ou colunas vazias são excluídas do HTML, PDF, PNG ou JPEG resultantes. As propriedades booleanas SpreadsheetOptions.SkipEmptyRows e SpreadsheetOptions.SkipEmptyColumns controlam esse recurso.

A captura acima demonstra que tanto SkipEmptyRows quanto SkipEmptyColumns estão ativados.

Renderizar ou ocultar comentários de célula

Células de uma planilha podem conter comentários, e por padrão o GroupDocs.Viewer os renderiza todos. Isso pode ser desativado usando a propriedade BaseViewOptions.RemoveComments — ao defini‑la como true, nenhum comentário será renderizado. Observe que essa propriedade está na classe BaseViewOptions, não em SpreadsheetOptions.

A captura demonstra a renderização de um arquivo XLSX com comentários de célula para PNG usando as opções padrão — o comentário da célula “E2” aparece no PNG resultante.

Definir margens da planilha nas páginas PDF de saída

Ao renderizar planilhas para PDF, é possível controlar as margens da página — a distância em centímetros da borda da página ao conteúdo. Existem 4 propriedades para controlar as margens superior, direita, inferior e esquerda:

• SpreadsheetOptions.TopMargin
• SpreadsheetOptions.RightMargin
• SpreadsheetOptions.BottomMargin
• SpreadsheetOptions.LeftMargin

Por padrão, todas essas propriedades têm valores negativos, o que significa que as margens padrão são aplicadas pelo GroupDocs.Viewer. Entretanto, é possível definir esses valores explicitamente. É importante enfatizar que as margens de página são aplicadas apenas quando o formato de destino é PDF.

O trecho de código a seguir demonstra a criação de PdfViewOptions, a definição das 4 margens e a renderização de um 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);
}

A imagem a seguir demonstra o resultado:

Conclusão

Os formatos de planilha são bastante complexos, e os documentos podem ter conteúdo muito diverso em tipo e tamanho. Em muitos casos é impossível renderizar um documento de planilha complexo para algum formato usando apenas as opções padrão, e por isso o GroupDocs.Viewer oferece um conjunto tão abrangente de propriedades; com elas, qualquer usuário poderá ajustar a renderização para atender às suas necessidades.

Veja também

• Renderizar planilhas do Excel e do Apple Numbers como HTML, PDF e imagens
• Dividir uma planilha em páginas
• Especificar opções de renderização de planilha

Experimente gratuitamente

Você pode baixar uma versão de avaliação gratuita do GroupDocs.Viewer para .NET em releases.groupdocs.com. Também é possível obter uma licença temporária para experimentar todos os recursos e funcionalidades sem restrições aqui.