Lavorare con i fogli di calcolo in GroupDocs.Viewer per .NET

Panoramica

Documenti di foglio di calcolo sono documenti che contengono dati in forma tabellare — all’interno di righe e colonne. Sono anche conosciuti come cartelle di lavoro. Esistono molti formati di documenti di foglio di calcolo — Office Open XML (come XLSX, XLSM, ecc.), Microsoft Excel Binary File Format (XLS, XLT), formato OpenDocument Spreadsheet (ODS, FODS, OTS), formati basati su testo delimitati da separatori (CSV, TSV ecc.) e così via. Tutti loro formano la cosiddetta famiglia di formati di foglio di calcolo. GroupDocs.Viewer supporta quasi tutti i formati di foglio di calcolo in importazione e consente di rendere (convertire) in HTML, PDF, PNG e JPEG. Questo articolo spiega come farlo, quali opzioni sono disponibili e quando e perché dovrebbero essere usate.

Uso di base

Prima di tutto dobbiamo parlare delle opzioni. Esiste una classe separata nell’API pubblica: SpreadsheetOptions in GroupDocs.Viewer.Options. Questa classe è progettata appositamente per regolare il rendering della famiglia di formati di foglio di calcolo. È accessibile per tutte e quattro le opzioni di visualizzazione tramite la proprietà SpreadsheetOptions di:

• HtmlViewOptions.SpreadsheetOptions quando si rende un documento di foglio di calcolo in HTML,
• PdfViewOptions.SpreadsheetOptions quando si rende un documento di foglio di calcolo in PDF,
• PngViewOptions.SpreadsheetOptions quando si rende un documento di foglio di calcolo in PNG,
• JpgViewOptions.SpreadsheetOptions quando si rende un documento di foglio di calcolo in JPEG.

Quando non specificata esplicitamente, la proprietà SpreadsheetOptions ha un valore implicito predefinito dell’istanza della classe SpreadsheetOptions, che sarà spiegato più avanti in questo articolo.

A colpo d’occhio, il rendering di un documento di foglio di calcolo con GroupDocs.Viewer è super‑facile e simile a tutti gli altri formati — creare un’istanza di ViewOptions, creare un’istanza di Viewer con il documento di foglio di calcolo di input specificato, e chiamare il metodo Viewer.View(viewOptions). Il seguente esempio di codice dimostra il rendering di un unico file di foglio di calcolo di input in tutti e 4 i formati di output: HTML, PDF, PNG e JPEG. Si noti che, a parte la creazione delle istanze delle classi di opzioni, non vi è alcuna messa a punto specifica per i fogli di calcolo, quindi tutte le opzioni dei fogli sono impostate sui valori predefiniti.

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

Ora parliamo dei fogli di lavoro. Ogni foglio di calcolo ha almeno un foglio di lavoro. Nella maggior parte dei software di elaborazione tabelle come Microsoft Excel, i fogli di lavoro sono rappresentati come schede. Alcuni formati di foglio di calcolo possono avere un solo foglio di lavoro; ciò include, ad esempio, tutti i formati basati su testo delimitati da separatori (CSV, TSV ecc.).

Per impostazione predefinita GroupDocs.Viewer rende tutti i fogli di lavoro all’interno del foglio di calcolo fornito. Ma questo può essere modificato. Il metodo Viewer.View() ha una overload che accetta un insieme di numeri di pagina come secondo parametro — Int32[] pageNumbers. Quando questo parametro è usato, verranno renderizzate solo le pagine indicate. Questo parametro è universale e si applica a tutti i formati supportati che hanno pagine, ma nel contesto della famiglia di formati di foglio di calcolo descrive esattamente i numeri dei fogli da visualizzare.

Si noti che la numerazione delle pagine in generale e quella dei fogli in particolare è basata su 1, non su 0, quindi inizia da “1”, non da “0”.

L’esempio qui sotto mostra come rendere il 1° e il 3° foglio di lavoro in PNG in un foglio di calcolo che contiene 3 fogli.

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

Suddivisione dei fogli di lavoro in pagine

GroupDocs.Viewer rende i documenti in pagine, dove per pagina si intende un’area rettangolare di dimensioni relativamente piccole, comparabile all’area di visualizzazione o al foglio A4. D’altra parte, i fogli di lavoro possono essere molto grandi. In particolare, il ormai obsoleto formato XLS supporta max 256 colonne e 65536 righe, mentre il più recente formato XLSX (Office Open XML Workbook) e Microsoft Excel supportano fino a 16384 colonne e 1048576 righe. “Adattare” i fogli di lavoro alle pagine è una parte cruciale del rendering di fogli di calcolo con GroupDocs.Viewer. Per adattare il foglio a una o più pagine, GroupDocs.Viewer esegue una suddivisione del foglio — il foglio è diviso in più blocchi rettangolari, ognuno dei quali viene collocato su una pagina separata. Esistono 5 metodi diversi, elencati e descritti di seguito.

Ciò che è importante — tutti questi metodi di suddivisione sono specificati nello stesso modo — usando un metodo statico specifico (factory method) che crea un’istanza della classe SpreadsheetOptions.

Renderizzare l’intero foglio su una pagina

SpreadsheetOptions.ForOnePagePerSheet()

Il modo più semplice — disattivare la suddivisione e regolare la dimensione della pagina per far entrare tutto il contenuto del foglio intero. È una buona scelta quando si sa già che il foglio è di piccole dimensioni. Tuttavia, se il foglio è davvero grande, questo approccio può dare risultati disastrosi. In particolare, durante il rendering in formato HTML, il documento HTML risultante può diventare enorme, decine o anche centinaia di MiB, il che può causare problemi di visualizzazione in browser web. Durante il rendering in JPEG, la cosa può peggiorare se larghezza o altezza superano il limite massimo di 65535 pixel. Quindi usate questa modalità consapevolmente.

Suddividere il foglio per interruzioni di pagina

SpreadsheetOptions.ForRenderingByPageBreaks()

Microsoft Excel aggiunge automaticamente le interruzioni di pagina in base alla dimensione del foglio e alle impostazioni di pagina, come orientamento e margini. Se si passa alla scheda “Visualizza” e si entra nella modalità “Anteprima interruzioni di pagina”, si vedono linee blu che dividono l’intera area del foglio in blocchi rettangolari, ciascuno etichettato “Pagina 1”, “Pagina 2”, e così via. È così che Microsoft Excel “suggerisce” di suddividere un foglio in pagine.

Con questo metodo GroupDocs.Viewer segue Microsoft Excel e suddivide i fogli secondo le interruzioni di pagina, come fa Excel.

Vale la pena menzionare che questa opzione — suddividere un foglio per interruzioni di pagina — è l’opzione predefinita della proprietà BaseViewOptions.SpreadsheetOptions, quindi quando si crea un’istanza di una classe di opzioni di visualizzazione, l’opzione “ForRenderingByPageBreaks()” è selezionata per impostazione predefinita.

Renderizzare solo l’area di stampa

SpreadsheetOptions.ForRenderingPrintArea()

Oltre alle interruzioni di pagina, Microsoft Excel ha il concetto di “Area di stampa”. L’Area di stampa è in realtà uno o più intervalli di celle in un foglio, designati per la stampa; tutto il contenuto al di fuori dell’Area di stampa non verrà stampato. Per aggiungere un intervallo di celle all’Area di stampa, andare nella scheda “Layout di pagina”, cliccare sul pulsante “Area di stampa” e poi su “Imposta area di stampa” (vedi screenshot sotto). Per aggiungere un altro intervallo, selezionare il nuovo intervallo, cliccare nuovamente su “Area di stampa” e poi su “Aggiungi all’area di stampa”. Nella modalità “Anteprima interruzioni di pagina” si possono vedere tutti gli intervalli dell’Area di stampa.

Renderizzare l’area di stampa e suddividere per interruzioni di pagina

SpreadsheetOptions.ForRenderingPrintAreaAndPageBreaks()

GroupDocs.Viewer offre una funzionalità unica — combinare l’Area di stampa e le interruzioni di pagina in un’unica modalità. In questo caso GroupDocs.Viewer considera tutti gli intervalli dell’Area di stampa e le interruzioni di pagina nel foglio e li applica simultaneamente per suddividere il foglio in pagine.

Nello screenshot seguente la linea rossa indica l’area di stampa, mentre la linea blu indica le interruzioni di pagina.

Suddividere manualmente il foglio in pagine per righe e colonne

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

A volte nessuno dei metodi di suddivisione descritti sopra è accettabile, o il foglio di calcolo ha un formato che non supporta interruzioni di pagina e Aree di stampa, ad esempio i CSV basati su testo. Per questi casi GroupDocs.Viewer consente di specificare manualmente il numero di righe e/o colonne che devono essere presenti in ogni pagina. In breve, la differenza tra suddivisione solo per righe e suddivisione per righe e colonne è illustrata nello screenshot sotto.

Se si utilizza la prima overload del metodo ForSplitSheetIntoPages, con un solo parametro, viene attivata la suddivisione solo per righe. Se si usa la seconda overload, dove sono specificati due parametri, viene attivata la suddivisione per righe e colonne.

Regolazione delle opzioni aggiuntive

Tutto quanto descritto finora è essenziale e sufficiente per il rendering dei fogli di calcolo con GroupDocs.Viewer. Tuttavia, esistono numerose opzioni aggiuntive, non obbligatorie, che consentono agli utenti di perfezionare ulteriormente il risultato del rendering.

Alcune di queste opzioni sono rappresentate come proprietà della classe SpreadsheetOptions, accessibile tramite la proprietà SpreadsheetOptions delle classi di opzioni di visualizzazione. Altre, invece, si trovano nella classe astratta ViewOptions, comune a tutte e quattro le modalità di rendering.

Renderizzare intestazioni di righe e colonne

Quando MS Excel o un programma simile apre un documento di foglio di calcolo, visualizza le intestazioni di colonne e righe; le colonne sono etichettate con lettere (A, B, C, AA, AB, …) e le righe con numeri (1, 2, 3, …, 1048576). Per impostazione predefinita GroupDocs.Viewer non visualizza queste intestazioni, poiché fanno parte dell’interfaccia dell’elaboratore di tabelle, non del documento stesso. È possibile cambiarlo tramite la proprietà RenderHeadings di tipo booleano. Per impostazione predefinita è disattivata (false); se impostata a true, le intestazioni di righe e colonne saranno presenti nel documento di output, come mostrato nello screenshot sottostante.

Renderizzare le linee della griglia del foglio

Il concetto è molto simile al precedente. Per impostazione predefinita GroupDocs.Viewer non visualizza le linee della griglia tra le celle, poiché non fanno parte del foglio di calcolo, ma sono solo una rappresentazione dell’interfaccia dell’elaboratore. Tuttavia, usando la proprietà RenderGridLines di tipo booleano è possibile imitare il comportamento di MS Excel. Impostando true su SpreadsheetOptions.RenderGridLines, le linee della griglia saranno presenti nel documento di output, come mostrato nello screenshot sotto.

Controllare l’overflow del testo nelle celle

È uno scenario comune: del testo non riesce a stare nei confini di una cella. Come visualizzare correttamente tale testo? GroupDocs.Viewer fornisce la proprietà speciale SpreadsheetOptions.TextOverflowMode per risolvere il problema. La proprietà TextOverflowMode è di tipo enum TextOverflowMode, che presenta 4 possibili valori, spiegati di seguito.

OverlayIfNextIsEmpty

Per impostazione predefinita la proprietà SpreadsheetOptions.TextOverflowMode ha il valore OverlayIfNextIsEmpty, che imita il comportamento predefinito di Microsoft Excel. In breve, questo valore consente al testo di fuoriuscire in celle adiacenti, ma solo se tali celle sono vuote. Se le celle adiacenti contengono dati, il testo in eccesso viene troncato.

Lo screenshot mostra il file HTML renderizzato da un file XLSX con valore OverlayIfNextIsEmpty. Si noti la cella “B2”: ha un testo lungo che viene troncato perché la cella “C2” non è vuota. La cella “C3”, invece, ha anch’essa un testo lungo che oltreffà i limiti, ma si estende su “D2” ed “E2” perché queste sono vuote.

Overlay

Il valore TextOverflowMode.Overlay è simile al precedente, ma più aggressivo: il testo lungo che non entra nei confini originali della cella trabocca sempre, indipendentemente dal contenuto delle celle adiacenti, sovrascrivendo eventuali dati presenti.

Nello screenshot il testo lungo della cella “B2” si estende su “C2”, “D2”, “E2”, “F2”. Di conseguenza, il contenuto originale delle celle “C2” e “F2” viene cancellato.

HideText

Il valore TextOverflowMode.HideText funziona in maniera opposta al precedente: invece di traboccare, il testo che supera i limiti della cella viene semplicemente troncato, senza considerare se le celle adiacenti siano libere o meno.

Nello screenshot la cella “C3” illustra questo comportamento: nonostante ci siano spazi liberi in “D3” e oltre, il testo è troncato in modo incondizionato.

AutoFitColumn

Il valore TextOverflowMode.AutoFitColumn risolve il problema aumentando la larghezza della colonna per far entrare il testo di qualsiasi cella. Così, indipendentemente dalla lunghezza del contenuto, la larghezza della colonna che contiene quella cella viene incrementata fino a contenere l’intera stringa.

Lo screenshot dimostra il risultato. Ovviamente, questo approccio può risultare inadatto in alcuni casi, specialmente quando il testo è molto lungo, poiché la pagina può diventare estremamente larga, richiedendo fastidiosi scorrimenti orizzontali.

Renderizzare righe e colonne nascoste

Microsoft Excel e altri elaboratori di tabelle consentono di nascondere righe e colonne specifiche. Per impostazione predefinita GroupDocs.Viewer non rende queste righe/colonne, ma è possibile cambiarlo. Le proprietà ViewOptions.SpreadsheetOptions.RenderHiddenRows e ViewOptions.SpreadsheetOptions.RenderHiddenColumns, impostate a true, mostrano le righe e colonne nascoste nel file di output quando si renderizza in HTML, PDF, PNG o JPEG.

Renderizzare fogli di lavoro nascosti

Come per righe e colonne nascoste, un file di foglio di calcolo può contenere uno o più fogli nascosti. Per impostazione predefinita GroupDocs.Viewer non li rende. È possibile cambiare questo comportamento usando la proprietà RenderHiddenPages impostandola a true. Da notare che, a differenza delle proprietà precedenti, RenderHiddenPages si trova nella classe astratta BaseViewOptions, comune a tutte le opzioni di visualizzazione.

Saltare righe e colonne vuote

Alcuni fogli sono “sparsi” — contengono molte celle vuote che occupano spazio inutile. GroupDocs.Viewer offre una funzionalità per saltare righe e colonne vuote durante il rendering. Se attivata, le righe e/o le colonne vuote vengono escluse dall’HTML, PDF, PNG o JPEG risultante. Le proprietà boolean SpreadsheetOptions.SkipEmptyRows e SpreadsheetOptions.SkipEmptyColumns controllano questa funzionalità.

Lo screenshot dimostra che sia SkipEmptyRows sia SkipEmptyColumns sono attivati.

Renderizzare o nascondere i commenti delle celle

Le celle di un documento di foglio di calcolo possono contenere commenti; per impostazione predefinita GroupDocs.Viewer li rende tutti. È possibile disabilitarli usando la proprietà BaseViewOptions.RemoveComments. Impostandola a true, nessun commento verrà renderizzato. Questa proprietà si trova nella classe BaseViewOptions, non in SpreadsheetOptions.

Lo screenshot mostra il rendering di un file XLSX con commenti delle celle in PNG usando le opzioni predefinite — il commento della cella “E2” è presente nel PNG risultante.

Impostare i margini del foglio nelle pagine PDF di output

Quando si renderizzano fogli in formato PDF, è possibile controllare i margini della pagina — la distanza in centimetri dal bordo della pagina al contenuto. Sono disponibili 4 proprietà per controllare i margini superiore, destro, inferiore e sinistro:

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

Per impostazione predefinita tutte queste proprietà hanno valori negativi, il che significa che i margini predefiniti sono applicati da GroupDocs.Viewer. È comunque possibile impostare esplicitamente valori diversi. È importante sottolineare che i margini della pagina si applicano solo quando il formato di destinazione è PDF.

Il seguente frammento di codice dimostra la creazione di un oggetto PdfViewOptions, l’impostazione dei 4 margini e il rendering del 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);
}

L’immagine seguente mostra il risultato:

Conclusione

I formati di foglio di calcolo sono piuttosto complessi e i documenti possono contenere contenuti di tipo e lunghezza molto variabili. In molti casi è impossibile renderizzare un documento di foglio di calcolo complesso in un certo formato usando le impostazioni predefinite; per questo GroupDocs.Viewer offre un insieme completo di proprietà, con le quali ogni utente può regolare il rendering per soddisfare le proprie esigenze.

Vedi anche

• Renderizzare fogli Excel e Apple Numbers come HTML, PDF e file immagine
• Dividere un foglio di lavoro in pagine
• Specificare le opzioni di rendering per fogli di calcolo

Prova gratuita

È possibile scaricare una versione di prova gratuita di GroupDocs.Viewer per .NET da releases.groupdocs.com. È inoltre possibile ottenere una licenza temporanea per testare tutte le funzionalità senza restrizioni da qui.