Visão geral

Spreadsheet documents são documentos que contêm dados em forma de tabela — dentro de linhas e colunas. Também são conhecidos como workbooks. 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 suporta 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.

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

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 projetada especialmente para ajustar a renderização da família de formatos de planilha. Ela está acessível para as quatro opções de visualização através da propriedade SpreadsheetOptions:

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

Em linhas gerais, 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 de um ú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á nenhum ajuste relacionado a planilhas, portanto todas as opções de planilha permanecem com os 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 (worksheets). Cada planilha tem, no mínimo, uma planilha. 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 planilha; 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() tem uma sobrecarga que recebe um conjunto de números de página como segundo parâmetro — Int32[] pageNumbers. Quando esse parâmetro é usado, apenas essas páginas serão renderizadas. Esse parâmetro é universal e é aplicado a todos os formatos suportados que possuem páginas, mas 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 possui 3 planilhas.

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 alguma área retangular de tamanho relativamente pequeno, comparável à área de exibição ou ao papel A4. Por outro lado, as planilhas podem ser muito grandes. Em particular, o formato agora obsoleto XLS suporta no máximo 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 em páginas é uma parte crucial da renderização de planilhas com o GroupDocs.Viewer. Para encaixar a planilha em 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 abaixo.

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

Renderizar toda a planilha 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 inteira. Essa é 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 o formato HTML, o documento HTML resultante pode ser enorme, dezenas ou até centenas de MiB, o que pode causar problemas ao visualizar arquivos tão grandes em navegadores web. Ao renderizar para o formato JPEG, as coisas podem ser ainda piores se a largura ou altura ultrapassar o limite máximo de 65 535 pixels. Portanto, use este modo deliberadamente.

Render worksheet on one page

Dividir 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” etc. É 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 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 “Print Area”. A Área de Impressão é, na prática, um ou mais intervalos de células em uma planilha designados para impressão; qualquer conteúdo fora da Área de Impressão não será impresso. Para adicionar um intervalo de células à Á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 adicionar 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 da Área de Impressão.

Render only print area

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

SpreadsheetOptions.ForRenderingPrintAreaAndPageBreaks()

O GroupDocs.Viewer tem um recurso exclusivo — combinar a Área de Impressão e as quebras de página em um único modo. Nesse caso, o GroupDocs.Viewer leva em conta todos os intervalos da Área de Impressão e as quebras de página na planilha e os aplica simultaneamente para dividir a planilha 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.

Render print area and split by page breaks

Dividir 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 e Áreas de Impressão, por exemplo, o CSV baseado em texto. Para esses casos o GroupDocs.Viewer permite especificar manualmente o número de linhas e/ou colunas que devem estar presentes 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 (um parâmetro), a divisão apenas por linhas será habilitada. Se a segunda sobrecarga for usada (dois parâmetros), a divisão por linhas e colunas será habilitada.

Split worksheet into pages manually by rows and columns

Ajustando opções adicionais

Tudo o 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 aos usuários 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 de processamento de tabelas abre um documento de planilha, ele exibe os cabeçalhos de colunas e linhas; as colunas são identificadas por letras (A, B, C, AA, AB, …) e as linhas por números (1, 2, 3, …, 1048576). 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 documento em si. Mas isso pode ser alterado com a propriedade RenderHeadings de tipo booleano. Por padrão está desativada (false); ao habilitar (true), os cabeçalhos de linhas e colunas aparecerão no documento de saída, como pode ser visto na captura de tela abaixo.

Render row and column headings

Renderizar linhas de grade da planilha

O conceito desta opção é muito semelhante ao 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 sim de como o processador de tabelas representa o conteúdo. No entanto, usando a propriedade RenderGridLines de tipo booleano, é possível imitar o comportamento do MS Excel. Defina true na propriedade SpreadsheetOptions.RenderGridLines e as linhas de grade aparecerão no documento de saída, como mostrado na captura de tela abaixo.

Render worksheet gridlines

Controlar o transbordamento de texto nas células

É bastante comum que algum texto não caiba nos limites da célula. Como exibir esse texto corretamente? O GroupDocs.Viewer fornece a propriedade especial SpreadsheetOptions.TextOverflowMode para resolver esse problema. A propriedade TextOverflowMode tem um valor do tipo com o mesmo nome, TextOverflowMode, que é um enum com 4 itens possíveis, explicados a seguir.

OverlayIfNextIsEmpty

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

OverlayIfNextIsEmpty enum value

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

Overlay

O valor TextOverflowMode.Overlay é ligeiramente semelhante ao anterior, mas pode ser considerado mais agressivo: texto longo que não cabe nos limites originais da célula sempre transborda, independentemente das células adjacentes. Se as células adjacentes também contiverem texto ou outros dados, eles serão apagados.

Overlay enum value

A captura de tela acima demonstra como isso funciona. O texto longo da célula “B2” transborda para as células adjacentes “C2”, “D2”, “E2”, “F2”. Como resultado, o texto original das células “C2” e “F2” é apagado.

HideText

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

HideText enum value

Na captura de tela acima isso pode ser visto na célula “C3” — apesar de haver espaço livre nas células adjacentes “D3” etc., o texto é truncado incondicionalmente.

AutoFitColumn

O valor TextOverflowMode.AutoFitColumn resolve o problema de outra forma — aumenta a largura da coluna para acomodar o texto de qualquer célula. Assim, independentemente de quão longo seja o texto dentro da célula, a largura das colunas onde essa célula está localizada será aumentada para caber a string inteira.

AutoFitColumn enum value

A captura de tela acima mostra como funciona. Claro que essa abordagem pode não ser adequada em alguns casos, especialmente quando o texto nas células é extremamente longo — isso tornará a página muito larga, gerando rolagem horizontal incômoda.

Renderizar linhas e colunas ocultas

O Microsoft Excel e outros processadores de tabelas permitem ocultar linhas e colunas específicas. Por padrão o GroupDocs.Viewer não renderiza essas linhas e colunas, 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, explicadas acima, o arquivo de planilha pode conter uma ou mais planilhas ocultas. E, como no caso anterior, por padrão o GroupDocs.Viewer não renderiza as planilhas ocultas. Mas isso pode ser alterado usando a propriedade RenderHiddenPages definindo seu valor como true. Vale mencionar 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, o que pode ocupar muito espaço. O GroupDocs.Viewer possui um recurso para ignorar linhas e colunas vazias na renderização. Se esse recurso estiver habilitado, linhas e/ou colunas vazias são excluídas do HTML, PDF, PNG e JPEG resultantes. As propriedades booleanas SpreadsheetOptions.SkipEmptyRows e SpreadsheetOptions.SkipEmptyColumns são responsáveis por esse recurso.

Skip empty rows and columns

A captura de tela acima demonstra que tanto SkipEmptyRows quanto SkipEmptyColumns estão habilitados.

Renderizar ou ocultar comentários de célula

Células dentro de um documento de planilha podem ter comentários, e por padrão o GroupDocs.Viewer os renderiza todos. Mas isso pode ser desativado usando a propriedade BaseViewOptions.RemoveComments — ao definir seu valor como true, nenhum comentário será renderizado. Observe que essa propriedade está localizada na classe BaseViewOptions, não em SpreadsheetOptions.

Render or hide cell comments

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

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

Ao renderizar planilhas para o formato 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:

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

O trecho de código a seguir demonstra a criação de um 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:

Set worksheet margins in the output PDF pages

Conclusão

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

Veja também

Obtenha uma avaliação gratuita

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