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

개요

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

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

기본 사용법

먼저 옵션에 대해 이야기해야 합니다. 공개 API에는 별도의 클래스가 있습니다: SpreadsheetOptions (속성은 GroupDocs.Viewer.Options에 포함). 이 클래스는 스프레드시트 형식군의 렌더링을 조정하기 위해 특별히 설계되었습니다. 네 가지 뷰 옵션 모두에서 SpreadsheetOptions 속성을 통해 접근할 수 있습니다.

HtmlViewOptions.SpreadsheetOptions – 스프레드시트 문서를 HTML로 렌더링할 때
PdfViewOptions.SpreadsheetOptions – 스프레드시트 문서를 PDF로 렌더링할 때
PngViewOptions.SpreadsheetOptions – 스프레드시트 문서를 PNG로 렌더링할 때
JpgViewOptions.SpreadsheetOptions – 스프레드시트 문서를 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() 메서드에는 두 번째 매개변수로 페이지 번호 배열(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);
}

워크시트를 페이지로 분할하기

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

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

워크시트를 한 페이지에 전체 표시

SpreadsheetOptions.ForOnePagePerSheet()

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

페이지 구분선에 따라 워크시트 분할

SpreadsheetOptions.ForRenderingByPageBreaks()

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

GroupDocs.Viewer는 이 방식을 그대로 따라 페이지 구분선에 따라 워크시트를 분할합니다.

이 옵션(ForRenderingByPageBreaks())은 BaseViewOptions.SpreadsheetOptions 속성의 기본값이므로, 뷰 옵션 클래스를 생성하면 자동으로 선택됩니다.

인쇄 영역만 렌더링

SpreadsheetOptions.ForRenderingPrintArea()

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

인쇄 영역과 페이지 구분선 동시에 적용

SpreadsheetOptions.ForRenderingPrintAreaAndPageBreaks()

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

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

Render print area and split by page breaks

행·열 수로 워크시트를 수동으로 페이지 나누기

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

위에서 소개한 분할 방법이 모두 적합하지 않거나, CSV와 같이 페이지 구분선·인쇄 영역을 지원하지 않는 형식인 경우가 있습니다. 이런 경우 GroupDocs.Viewer는 각 페이지에 포함될 행 수와(또는 열 수)를 직접 지정할 수 있게 합니다. 아래 스크린샷은 “행만 기준”과 “행·열 모두 기준” 분할 차이를 보여줍니다.

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

Split worksheet into pages manually by rows and columns

추가 옵션 조정

위에서 설명한 내용만으로도 스프레드시트를 렌더링하는 데는 충분합니다. 그러나 렌더링 결과를 더욱 세밀하게 조정하고 싶다면 다양한 추가 옵션을 활용할 수 있습니다.

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

행·열 헤더 렌더링

MS Excel 등 표 처리 프로그램이 스프레드시트를 열면 열은 문자(A, B, C, AA, AB, …)로, 행은 숫자(1, 2, 3, …)로 표시됩니다. 기본적으로 GroupDocs.Viewer는 이러한 헤더를 표시하지 않는데, 이는 문서 자체가 아니라 프로그램 인터페이스의 일부이기 때문입니다. 하지만 RenderHeadings 속성을 true로 설정하면 헤더가 출력에 포함됩니다. 기본값은 false이며, true로 변경하면 아래 스크린샷과 같이 행·열 헤더가 보입니다.

워크시트 격자선 렌더링

이 옵션도 앞의 옵션과 비슷합니다. 기본적으로 격자선은 표시되지 않으며, 이는 격자선이 스프레드시트 자체가 아니라 표 처리 프로그램의 시각적 보조 요소이기 때문입니다. RenderGridLines 속성을 true로 설정하면 격자선이 출력에 포함됩니다.

셀 텍스트 오버플로우 제어

셀 안의 텍스트가 셀 경계를 초과하는 경우가 흔히 발생합니다. 이를 어떻게 처리할까요? GroupDocs.Viewer는 SpreadsheetOptions.TextOverflowMode 속성을 제공하여 네 가지 동작 방식을 선택할 수 있게 합니다. TextOverflowMode는 동일한 이름의 열거형(TextOverflowMode)이며, 아래와 같이 4가지 옵션을 가집니다.

OverlayIfNextIsEmpty

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

위 스크린샷은 OverlayIfNextIsEmpty 옵션으로 렌더링한 HTML 파일을 보여줍니다. 셀 “B2”의 텍스트는 “C2”가 비어 있지 않아 잘리고, “C3”의 텍스트는 “D2”, “E2”가 비어 있어 넘쳐흐릅니다.

Overlay

Overlay 옵션은 보다 공격적인 동작을 합니다. 텍스트가 셀 경계를 초과하면 인접 셀에 관계없이 무조건 넘쳐흐르며, 인접 셀에 기존 데이터가 있으면 덮어씁니다.

스크린샷에서 “B2” 셀의 긴 텍스트가 “C2”, “D2”, “E2”, “F2” 셀까지 넘쳐흐르고, 그 결과 “C2”와 “F2”에 있던 원래 텍스트가 사라진 것을 확인할 수 있습니다.

HideText

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

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

AutoFitColumn

AutoFitColumn 옵션은 열 너비를 자동으로 확대해 텍스트 전체가 보이도록 합니다. 따라서 셀 내용이 얼마나 길든 해당 셀이 속한 열의 너비가 늘어나 전체 문자열을 표시합니다.

스크린샷에서 볼 수 있듯이 열 너비가 확대되어 텍스트가 모두 표시됩니다. 다만 텍스트가 지나치게 길 경우 페이지가 매우 넓어져 가로 스크롤이 불편해질 수 있습니다.

숨겨진 행·열 렌더링

Excel 등 표 처리 프로그램은 특정 행·열을 숨길 수 있습니다. 기본적으로 GroupDocs.Viewer는 숨겨진 행·열을 렌더링하지 않지만, 아래 속성을 true로 설정하면 HTML, PDF, PNG, JPEG 형식으로 렌더링할 때 숨겨진 행·열이 표시됩니다.

ViewOptions.SpreadsheetOptions.RenderHiddenRows
ViewOptions.SpreadsheetOptions.RenderHiddenColumns

숨겨진 워크시트 렌더링

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

빈 행·열 건너뛰기

일부 스프레드시트는 빈 공간이 많이 포함되어 파일 크기가 커질 수 있습니다. SkipEmptyRows와 SkipEmptyColumns 속성을 true로 설정하면 렌더링 결과에서 빈 행·열이 제외됩니다.

위 스크린샷에서 두 속성이 모두 활성화된 모습을 확인할 수 있습니다.

셀 주석 렌더링 여부

셀에 주석이 달려 있을 수 있으며, 기본적으로 GroupDocs.Viewer는 모든 주석을 렌더링합니다. 주석을 제외하려면 BaseViewOptions.RemoveComments 속성을 true로 설정하면 됩니다. 이 속성은 BaseViewOptions 클래스에 위치한다는 점을 유의하세요.

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

PDF 페이지에서 워크시트 여백 설정

워크시트를 PDF 형식으로 렌더링할 때 페이지 여백(페이지 경계와 내용 사이의 거리, cm)을 제어할 수 있습니다. 다음 네 가지 속성을 사용합니다.

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

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

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

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

결론

스프레드시트 형식은 구조가 복잡하고, 문서마다 내용과 길이가 크게 다를 수 있습니다. 기본 옵션만으로는 복잡한 스프레드시트를 원하는 형식으로 렌더링하기 어려운 경우가 많으며, GroupDocs.Viewer는 이러한 상황을 대비해 풍부한 옵션 세트를 제공합니다. 이를 활용하면 사용자는 자신의 요구에 맞게 렌더링 결과를 세밀하게 조정할 수 있습니다.

무료 체험 받기

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

개요#

기본 사용법#

워크시트를 페이지로 분할하기#

워크시트를 한 페이지에 전체 표시#

페이지 구분선에 따라 워크시트 분할#

인쇄 영역만 렌더링#

인쇄 영역과 페이지 구분선 동시에 적용#

행·열 수로 워크시트를 수동으로 페이지 나누기#

추가 옵션 조정#

행·열 헤더 렌더링#

워크시트 격자선 렌더링#

셀 텍스트 오버플로우 제어#

OverlayIfNextIsEmpty#

Overlay#

HideText#

AutoFitColumn#

숨겨진 행·열 렌더링#

숨겨진 워크시트 렌더링#

빈 행·열 건너뛰기#

셀 주석 렌더링 여부#

PDF 페이지에서 워크시트 여백 설정#

결론#

관련 문서#

무료 체험 받기#

개요