GroupDocs.Viewer for .NET에서 스프레드시트 작업

Overview

Spreadsheet documents는 행과 열 형태의 표에 데이터를 담고 있는 문서입니다. 이들은 워크북이라고도 불립니다. 스프레드시트 문서는 다양한 형식이 존재합니다 — Office Open XML(XLSX, XLSM 등), Microsoft Excel Binary File Format(XLS, XLT), OpenDocument Spreadsheet 형식(ODS, FODS, OTS), 텍스트 기반 구분자‑구분 형식(CSV, TSV 등) 등. 이 모든 형식은 이른바 Spreadsheet formats family를 이룹니다. GroupDocs.Viewer는 거의 모든 스프레드시트 형식을 가져올 수 있으며, 이를 HTML, PDF, PNG, JPEG으로 렌더링(변환)할 수 있습니다. 이 문서에서는 그 방법과 사용 가능한 옵션, 언제·왜 사용해야 하는지를 설명합니다.

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

Basic usage

먼저 옵션에 대해 이야기해야 합니다. 공개 API에는 별도의 클래스가 있습니다: SpreadsheetOptions (속해 있는 네임스페이스는 GroupDocs.Viewer.Options). 이 클래스는 Spreadsheet formats family의 렌더링을 조정하기 위해 특별히 설계되었습니다. 네 가지 뷰 옵션 모두에서 SpreadsheetOptions 속성을 통해 접근할 수 있습니다:

HtmlViewOptions.SpreadsheetOptions — Spreadsheet 문서를 HTML로 렌더링할 때,
PdfViewOptions.SpreadsheetOptions — Spreadsheet 문서를 PDF로 렌더링할 때,
PngViewOptions.SpreadsheetOptions — Spreadsheet 문서를 PNG로 렌더링할 때,
JpgViewOptions.SpreadsheetOptions — Spreadsheet 문서를 JPEG으로 렌더링할 때.

명시적으로 지정하지 않으면, SpreadsheetOptions 속성은 기본적으로 SpreadsheetOptions 클래스 인스턴스의 암시적 값을 갖게 되며, 이는 본 문서에서 추후 설명됩니다.

한눈에 보면, GroupDocs.Viewer로 스프레드시트를 렌더링하는 과정은 매우 간단하며 다른 형식과 동일합니다 — ViewOptions 인스턴스를 만들고, 입력 스프레드시트를 지정한 뒤 Viewer 인스턴스를 생성한 뒤, Viewer.View(viewOptions) 메서드를 호출하면 됩니다. 아래 코드 샘플은 단일 입력 스프레드시트 파일을 HTML, PDF, PNG, JPEG 네 가지 출력 형식으로 렌더링하는 예시입니다. 옵션 클래스 인스턴스를 생성하는 부분을 제외하고는 스프레드시트와 관련된 별도 튜닝이 없으며, 모든 스프레드시트 옵션은 기본값으로 설정됩니다.

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

이제 워크시트에 대해 이야기해 보겠습니다. 모든 스프레드시트는 최소 하나의 워크시트를 가지고 있습니다. Microsoft Excel과 같은 대부분의 표 처리 소프트웨어에서는 워크시트를 탭 형태로 표시합니다. 일부 스프레드시트 형식은 워크시트가 하나만 존재할 수도 있습니다. 예를 들어 모든 텍스트 기반 구분자‑구분 형식(CSV, TSV 등)이 해당됩니다.

기본적으로 GroupDocs.Viewer는 주어진 스프레드시트에 포함된 모든 워크시트를 렌더링합니다. 하지만 이를 변경할 수 있습니다. Viewer.View() 메서드에는 2번째 매개변수로 페이지 번호 배열(Int32[] pageNumbers)을 받는 오버로드가 있습니다. 이 매개변수를 사용하면 지정된 페이지(워크시트)만 렌더링됩니다. 이 매개변수는 모든 지원 형식에 적용되는 범용 매개변수이며, 스프레드시트 형식군에서는 정확히 워크시트 번호를 의미합니다.

페이지 번호와 워크시트 번호는 모두 1부터 시작한다는 점을 유의하세요. 즉 0이 아니라 “1”부터 번호가 매겨집니다.

아래 예시는 3개의 워크시트를 가진 스프레드시트에서 1번째와 3번째 워크시트를 PNG로 렌더링하는 방법을 보여줍니다.

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

Splitting worksheets into pages

GroupDocs.Viewer는 문서를 페이지 단위로 렌더링합니다. 여기서 페이지란 디스플레이 화면이나 A4 용지와 비슷한, 상대적으로 작은 사각형 영역을 의미합니다. 반면 워크시트는 매우 클 수 있습니다. 예를 들어 이제는 사용되지 않는 XLS 형식은 최대 256열·65536행을 지원하고, 최신 XLSX (Office Open XML Workbook) 형식과 Microsoft Excel은 최대 16384열·1048576행을 지원합니다. 워크시트를 페이지에 “맞추는” 작업은 GroupDocs.Viewer에서 핵심적인 역할을 합니다. 워크시트를 페이지에 맞추기 위해 GroupDocs.Viewer는 워크시트 분할을 수행합니다 — 워크시트를 여러 사각형 청크로 나누고, 각 청크를 별도의 페이지에 배치합니다. 아래에 5가지 분할 방법을 나열하고 설명합니다.

중요한 점 — 모든 분할 방법은 동일한 방식으로 지정됩니다. 즉, SpreadsheetOptions 클래스의 특정 정적(팩터리) 메서드를 호출해 인스턴스를 생성합니다.

Render whole worksheet on one page

SpreadsheetOptions.ForOnePagePerSheet()

가장 쉽고 간단한 방법 — 분할을 끄고 페이지 크기를 전체 워크시트 내용에 맞게 조정합니다. 워크시트가 작다는 것이 이미 알려져 있을 때 좋은 선택입니다. 그러나 워크시트가 매우 크면 결과가 좋지 않을 수 있습니다. 특히 HTML 형식으로 렌더링할 경우 결과 HTML 파일이 수십·수백 MiB에 달해 웹 브라우저에서 열기 어려울 수 있습니다. JPEG 형식으로 렌더링할 경우 가로나 세로가 65535 픽셀을 초과하면 문제가 발생합니다. 따라서 이 모드는 신중히 사용하세요.

Split worksheet by page breaks

SpreadsheetOptions.ForRenderingByPageBreaks()

Microsoft Excel 자체가 용지 크기와 페이지 설정(방향, 여백 등)에 따라 자동 페이지 나눔을 추가합니다. “View” 탭에서 “Page Break Preview” 모드로 전환하면 파란색 선으로 워크시트 전체가 사각형 청크로 나뉘어 각각 “Page 1”, “Page 2” 등으로 표시됩니다. 이것이 Microsoft Excel이 워크시트를 페이지로 나누는 제안 방식입니다.

이 방법을 사용하면 GroupDocs.Viewer가 Microsoft Excel과 동일하게 페이지 나눔을 따라 워크시트를 분할합니다.

참고로 이 옵션(페이지 나눔에 따라 워크시트 분할)은 BaseViewOptions.SpreadsheetOptions 속성의 기본값이며, 뷰 옵션 클래스를 생성하면 자동으로 [ForRenderingByPageBreaks()] 옵션이 선택됩니다.

Render only print area

SpreadsheetOptions.ForRenderingPrintArea()

Microsoft Excel에는 페이지 나눔 외에도 “Print Area”(인쇄 영역) 개념이 있습니다. 인쇄 영역은 워크시트 내에서 인쇄 대상으로 지정된 하나 이상의 셀 범위이며, 인쇄 영역 밖의 내용은 전혀 인쇄되지 않습니다. 인쇄 영역에 셀 범위를 추가하려면 “Page Layout” 탭에서 “Print Area” 버튼을 클릭한 뒤 “Set Print Area”를 선택합니다(아래 스크린샷 참고). 추가로 다른 셀 범위를 인쇄 영역에 포함하려면 새 범위를 선택하고 “Print Area” → “Add to Print Area”를 클릭합니다. “Page Break Preview” 모드에서는 인쇄 영역에 포함된 모든 셀 범위를 확인할 수 있습니다.

Render print area and split by page breaks

SpreadsheetOptions.ForRenderingPrintAreaAndPageBreaks()

GroupDocs.Viewer는 고유 기능을 제공하는데, 바로 인쇄 영역과 페이지 나눔을 하나의 모드에서 결합하는 것입니다. 이 경우 워크시트의 모든 인쇄 영역 셀 범위와 페이지 나눔을 동시에 고려해 워크시트를 페이지로 분할합니다.

아래 스크린샷에서 빨간 선은 인쇄 영역을, 파란 선은 페이지 나눔을 나타냅니다.

Render print area and split by page breaks

Split worksheet into pages manually by rows and columns

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

위에서 설명한 분할 방법 중 어느 것도 만족스럽지 않거나, CSV와 같이 페이지 나눔·인쇄 영역을 지원하지 않는 형식일 경우, GroupDocs.Viewer는 페이지당 표시할 행 수와(또는) 열 수를 직접 지정할 수 있게 합니다. 아래 스크린샷은 행만 분할하는 경우와 행·열 모두 분할하는 경우의 차이를 보여줍니다.

첫 번째 오버로드(ForSplitSheetIntoPages)를 사용하면 행만 기준으로 분할됩니다. 두 번째 오버로드를 사용하면 행과 열을 모두 기준으로 분할됩니다.

Split worksheet into pages manually by rows and columns

Adjusting additional options

위에서 설명한 내용만으로도 스프레드시트를 GroupDocs.Viewer로 렌더링하는 데는 충분합니다. 그러나 렌더링 결과를 더욱 세밀하게 조정할 수 있는 추가 옵션도 많이 제공됩니다.

일부 옵션은 SpreadsheetOptions 클래스의 속성으로 제공되며, 이 클래스는 뷰 옵션 클래스의 SpreadsheetOptions 속성을 통해 접근합니다. 다른 옵션은 모든 4가지 렌더링 모드에 공통인 추상 클래스 ViewOptions에 정의되어 있습니다.

Render row and column headings

MS Excel이나 유사한 표 처리 프로그램이 스프레드시트를 열면 열과 행 머리글을 표시합니다. 열은 문자(A, B, C, AA, AB, …)로, 행은 숫자(1, 2, 3, …, 1048576)로 표시됩니다. 기본적으로 GroupDocs.Viewer는 이러한 머리글을 표시하지 않는데, 이는 문서 자체가 아니라 표 처리 프로그램의 UI 요소이기 때문입니다. 하지만 RenderHeadings 불리언 속성을 true 로 설정하면 머리글이 출력에 포함됩니다. 기본값은 false 입니다.

Render worksheet gridlines

이 옵션도 앞의 옵션과 매우 유사합니다. 기본적으로 GroupDocs.Viewer는 셀 사이의 그리드라인을 표시하지 않는데, 이는 그리드라인이 스프레드시트 자체가 아니라 표 처리 프로그램이 제공하는 시각적 보조선이기 때문입니다. 하지만 RenderGridLines 불리언 속성을 true 로 설정하면 그리드라인이 출력에 포함됩니다.

Control cell text overflow

셀 안의 텍스트가 셀 경계를 초과하는 경우가 흔히 발생합니다. 이를 어떻게 처리할까요? GroupDocs.Viewer는 이 문제를 해결하기 위해 SpreadsheetOptions.TextOverflowMode 속성을 제공합니다. TextOverflowMode는 동일한 이름의 열거형(TextOverflowMode)이며, 4가지 옵션을 가집니다.

OverlayIfNextIsEmpty

기본값은 OverlayIfNextIsEmpty이며, 이는 Microsoft Excel의 기본 동작을 모방합니다. 인접 셀이 비어 있을 경우에만 텍스트가 인접 셀로 넘쳐흐릅니다. 인접 셀이 비어 있지 않으면 텍스트가 잘립니다.

위 스크린샷은 OverlayIfNextIsEmpty 값을 사용해 XLSX 파일을 HTML로 렌더링한 결과입니다. 셀 “B2”는 긴 텍스트가 있지만 “C2”가 비어 있지 않아 잘렸습니다. 반면 “C3” 셀의 텍스트는 “D2”, “E2”가 비어 있어 넘쳐흐릅니다.

Overlay

Overlay 값은 앞의 옵션과 비슷하지만 더 공격적입니다. 셀 경계를 초과하는 텍스트는 인접 셀에 관계없이 무조건 넘쳐흐르며, 인접 셀에 기존 데이터가 있으면 덮어씁니다.

위 스크린샷에서 셀 “B2”의 긴 텍스트가 “C2”, “D2”, “E2”, “F2”로 넘쳐흐르고, 그 결과 “C2”와 “F2”에 있던 원래 텍스트가 사라졌습니다.

HideText

HideText 모드는 Overlay와 정반대 동작을 합니다. 셀 경계를 초과하는 텍스트는 인접 셀에 빈 공간이 있더라도 무조건 잘립니다.

위 스크린샷에서 셀 “C3”는 인접 “D3” 등에 빈 공간이 있음에도 불구하고 텍스트가 잘렸습니다.

AutoFitColumn

AutoFitColumn 값은 열 너비를 늘려 텍스트가 완전히 들어가도록 합니다. 따라서 특정 셀의 텍스트 길이에 관계없이 해당 셀이 속한 열의 너비가 자동으로 확대됩니다.

위 스크린샷은 이 동작을 보여줍니다. 다만 텍스트가 지나치게 길 경우 페이지가 매우 넓어져 가로 스크롤이 불편해질 수 있습니다.

Render hidden rows and columns

Microsoft Excel 등 표 처리 프로그램은 특정 행·열을 숨길 수 있습니다. 기본적으로 GroupDocs.Viewer는 숨긴 행·열을 렌더링하지 않지만, 이를 변경할 수 있습니다. ViewOptions.SpreadsheetOptions.RenderHiddenRows와 ViewOptions.SpreadsheetOptions.RenderHiddenColumns 속성을 true 로 설정하면 HTML, PDF, PNG, JPEG 형식으로 렌더링할 때 숨긴 행·열이 출력에 포함됩니다.

Render hidden worksheets

숨긴 워크시트도 마찬가지로 기본적으로 렌더링되지 않습니다. 하지만 RenderHiddenPages 속성을 true 로 설정하면 숨긴 워크시트도 출력에 포함됩니다. 이 속성은 SpreadsheetOptions가 아니라, 모든 뷰 옵션에 공통인 추상 클래스 BaseViewOptions에 정의되어 있다는 점을 기억하세요.

Skip empty rows and columns

일부 스프레드시트는 “희소” 형태로, 많은 빈 행·열이 존재해 파일 크기를 불필요하게 키울 수 있습니다. GroupDocs.Viewer는 빈 행·열을 렌더링에서 제외하는 기능을 제공합니다. 해당 기능을 활성화하면 빈 행·열이 최종 HTML, PDF, PNG, JPEG에 포함되지 않습니다. 이를 제어하는 불리언 속성은 SpreadsheetOptions.SkipEmptyRows와 SpreadsheetOptions.SkipEmptyColumns입니다.

위 스크린샷에서 SkipEmptyRows와 SkipEmptyColumns가 모두 활성화된 모습을 확인할 수 있습니다.

Render or hide cell comments

셀에 달린 주석도 기본적으로 모두 렌더링됩니다. 이를 비활성화하려면 BaseViewOptions.RemoveComments 속성을 true 로 설정하면 됩니다. 이 속성은 SpreadsheetOptions가 아니라 BaseViewOptions 클래스에 위치한다는 점을 유의하세요.

위 스크린샷은 기본 옵션으로 XLSX 파일을 PNG로 렌더링했을 때, “E2” 셀에 달린 주석이 결과 이미지에 포함된 모습을 보여줍니다.

Set worksheet margins in the output PDF pages

워크시트를 PDF 형식으로 렌더링할 때 페이지 여백(페이지 경계와 내용 사이의 거리, cm)을 제어할 수 있습니다. 상·우·하·좌 여백을 각각 설정하는 4가지 속성이 있습니다:

기본값은 모두 음수이며, 이는 GroupDocs.Viewer가 기본 여백을 적용한다는 의미입니다. 필요에 따라 명시적으로 값을 지정할 수 있습니다. 페이지 여백은 대상 형식이 PDF일 때만 적용됩니다.

아래 코드는 PdfViewOptions를 생성하고, 4가지 여백을 모두 설정한 뒤 문서를 렌더링하는 예시입니다.

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

아래 이미지는 적용 결과를 보여줍니다.

Set worksheet margins in the output PDF pages

Conclusion

스프레드시트 형식은 매우 복잡하고, 문서마다 내용의 종류와 길이가 크게 다를 수 있습니다. 대부분의 경우 기본 옵션만으로는 복잡한 스프레드시트를 원하는 형식으로 렌더링하기 어렵습니다. 그래서 GroupDocs.Viewer는 방대한 옵션 세트를 제공하며, 이를 통해 사용자는 자신의 요구에 맞게 렌더링을 세밀하게 조정할 수 있습니다.

Get a free trial

.NET용 GroupDocs.Viewer 무료 체험판은 releases.groupdocs.com에서 다운로드할 수 있습니다. 또한 여기에서 제한 없이 모든 기능을 시험해 볼 수 있는 임시 라이선스를 발급받을 수 있습니다.

Overview#

Basic usage#

Splitting worksheets into pages#

Render whole worksheet on one page#

Split worksheet by page breaks#

Render only print area#

Render print area and split by page breaks#

Split worksheet into pages manually by rows and columns#

Adjusting additional options#

Render row and column headings#

Render worksheet gridlines#

Control cell text overflow#

OverlayIfNextIsEmpty#

Overlay#

HideText#

AutoFitColumn#

Render hidden rows and columns#

Render hidden worksheets#

Skip empty rows and columns#

Render or hide cell comments#

Set worksheet margins in the output PDF pages#

Conclusion#

See Also#

Get a free trial#