SpreadJS 블로그 MESCIUS 기술 블로그 ·

SpreadJS로 JavaScript 웹 앱에 인쇄·PDF 출력 추가하기

SpreadJS는 웹 애플리케이션에서 Excel 수준의 스프레드시트 기능을 제공하는 JavaScript 라이브러리로, PrintInfo API를 통해 용지 크기·여백·방향·헤더푸터·PDF 출력까지 모든 인쇄 옵션을 클라이언트 코드만으로 완전히 제어할 수 있습니다.

React·Vue·Angular 같은 프레임워크로 업무용 웹 앱을 개발하다 보면 "보고서나 청구서를 PDF로 저장하거나 출력해야 한다"는 요구사항을 맞닥뜨리게 됩니다. 브라우저 기본 window.print() 는 CSS 미디어 쿼리만으로 레이아웃을 제어해야 해서 복잡한 테이블이나 다페이지 보고서에서 한계가 뚜렷하고, 서버 사이드 PDF 라이브러리는 별도의 백엔드 인프라와 유지 비용이 따릅니다.

SpreadJS의 PrintInfo API를 사용하면 A4·Letter 용지 크기, 인쇄 여백, 가로·세로 방향 전환을 JavaScript 몇 줄로 처리할 수 있습니다. 반복 인쇄 행·열 설정, 헤더·푸터 포맷 코드, 한글 TTF 폰트 등록까지 조합하면 서버 없이도 엔터프라이즈 수준의 인쇄·PDF 출력 기능을 완성할 수 있습니다.

이 글에서는 SpreadJS를 처음 사용하는 프론트엔드 개발자가 바로 적용할 수 있도록, 용지 설정부터 PDF 저장까지 필요한 플러그인·API를 각 단계에서 명확하게 안내합니다.

⭐ Key Points
이 글에서 다루는 핵심 내용
01 PrintInfo API 한 객체로 A4/Letter 용지 크기, 인쇄 여백, 가로·세로 방향을 JavaScript로 직접 지정할 수 있습니다
02 반복 인쇄 행·열 ( repeatRowStart/End ) 설정으로 여러 페이지로 나뉜 보고서의 열 헤더를 모든 페이지 상단에 자동 반복합니다
03 헤더·푸터 텍스트에 &P (현재 페이지), &D (오늘 날짜) 같은 포맷 코드를 넣으면 출력 시 실제 값으로 자동 치환됩니다
04 savePDF() API에 NanumGothic TTF 파일을 등록하면 서버 없이 브라우저에서 한글이 올바르게 표시된 PDF를 생성할 수 있습니다
SpreadJS로 JavaScript 웹 앱에 인쇄·PDF 출력 추가하기 — 대표 이미지

PrintInfo API란? JavaScript로 용지 크기·여백·방향을 설정하는 방법

PrintInfo 는 SpreadJS에서 인쇄 관련 모든 옵션을 담는 객체입니다. new GC.Spread.Sheets.Print.PrintInfo() 로 인스턴스를 생성하고, sheet.printInfo(printInfo) 로 시트에 적용합니다.

아래 예제는 A4 세로·가로 전환 버튼과 인쇄 버튼이 있는 실무 설정 데모입니다.

STEP 1: 라이브러리 참조

STEP 2: HTML 구조

STEP 3: PrintInfo 설정 코드

실행 결과
💡 TIP
paperSize() 의 단위는 1/100인치입니다. A4(827×1169), Letter(850×1100), A3(1169×1654)를 참고하세요. 여백의 header / footer 값은 헤더·푸터 텍스트 영역의 안쪽 여백입니다.
⭐ IMPORTANT
PrintInfo는 SpreadJS가 생성하는 인쇄 콘텐츠의 설정을 정의하지만, 최종 인쇄 렌더링은 브라우저의 Print API에 의해 수행됩니다. 브라우저가 사용자 설정을 우선하거나 해당 옵션을 외부 스크립트에서 변경하지 못하도록 제한하는 경우, PrintInfo 설정이 그대로 반영되지 않을 수 있습니다.

다페이지 보고서에서 열 헤더를 모든 페이지마다 자동 반복하는 방법

50행 이상의 보고서가 여러 페이지로 넘어가면 2페이지부터 컬럼 헤더가 사라져 독자가 어떤 열인지 파악하기 어렵습니다. repeatRowStart() 와 repeatRowEnd() 를 지정하면 지정 행 범위가 모든 페이지 상단에 반복 출력됩니다.

STEP 1: 라이브러리 참조

STEP 2: HTML 구조

STEP 3: 반복 행·열 설정 코드

실행 결과
ⓘ NOTE
열 제목을 좌측에 반복하려면 repeatColumnStart(0) / repeatColumnEnd(0) 을 같이 설정합니다. 시트에서 파란 점선으로 표시되는 인쇄 구분선(Print Line)은 sheet.isPrintLineVisible(true) 로 켤 수 있습니다.
↗
4가지
헤더·푸터 타입
normal·first·odd·even 개별 설정
↗
&P / &N
페이지 코드
현재 페이지 / 전체 페이지 수 동적 삽입
↗
1/100인치
여백 단위
top·bottom·left·right·header·footer 개별 지정

인쇄물 머리글·꼬리글에 페이지 번호와 날짜를 동적으로 삽입하는 방법

pageHeaderFooter() 에서 텍스트 안에 & 이스케이프 코드를 사용하면 페이지 번호, 날짜, 서식을 동적으로 삽입할 수 있습니다.

코드 출력 내용 예시
&P 현재 페이지 번호 &P / &N 페이지 → 3 / 10 페이지
&N 전체 페이지 수 —
&D 오늘 날짜 &D → 2025/06/15
&T 현재 시각 &T → 14:32:05
&B 굵게 &BMESCIUS → MESCIUS
&I 기울임 &I비공개 → 비공개
&"폰트명" 폰트 지정 &"맑은 고딕"보고서
&KFF0000 색상(HEX) &KFF0000기밀 → 빨간 텍스트
&A 시트 이름 현재 시트 이름 자동 삽입
⭐ BEST PRACTICE
첫 페이지에만 다른 헤더를 쓰려면 printInfo.differentFirstPage(true) 를 활성화하고 pageHeaderFooter({ first: { header: {...} } }) 를 추가로 설정합니다. 홀수/짝수 페이지 구분은 differentOddAndEvenPages(true) 로 활성화합니다.

한글 깨짐 없이 클라이언트 측 PDF를 생성하는 방법

savePDF() 는 서버 없이 브라우저에서 직접 PDF Blob을 생성합니다. 단, 기본 내장 폰트 14종은 CJK를 지원하지 않으므로 NanumGothic TTF를 PDFFontsManager 에 등록해야 한글이 깨지지 않습니다.

⭐ IMPORTANT
savePDF() 를 사용하려면 gc.spread.sheets.print.x.x.x.min.js 와 gc.spread.sheets.pdf.x.x.x.min.js 두 플러그인을 모두 로드해야 합니다.

STEP 1: 라이브러리 참조 (PDF 플러그인 포함)

STEP 2: HTML 구조

STEP 3: NanumGothic 폰트 등록 후 PDF 생성

실행 결과
⚠ WARNING
PDFFontsManager.registerFont() 에 등록할 폰트는 반드시 TTF 또는 OTF 형식이어야 합니다. TTC 파일은 지원되지 않으므로 온라인 변환 도구로 TTF로 변환 후 사용하세요. fetch 응답이 HTML 에러 페이지인 경우 ArrayBuffer에 잘못된 데이터가 들어가 "File read and write exception"이 발생하므로, res.ok 체크를 반드시 포함하세요.
한글 깨짐 없이 클라이언트 측 PDF를 생성하는 방법 — SpreadJS 개념도

웹 앱 화면 안에 인쇄 미리보기를 직접 구현하는 방법

SpreadJS에서 인쇄 미리보기 UX를 구현하는 방법은 크게 두 가지입니다.

방법 1 — 시트 내 인쇄 구분선 표시 ( isPrintLineVisible )

sheet.isPrintLineVisible(true) 를 호출하면 스프레드시트 안에 파란 점선으로 페이지 경계가 표시됩니다. 사용자가 데이터를 편집하면서 어느 범위까지 한 페이지에 들어가는지 실시간으로 확인할 수 있습니다.

방법 2 — spread.print() 브라우저 인쇄 다이얼로그 활용

spread.print() 또는 spread.print(sheetIndex) 를 호출하면 브라우저 기본 인쇄 다이얼로그가 열리며, 여기에 인쇄 미리보기가 포함됩니다. PrintInfo 로 설정한 용지·여백·헤더푸터가 그대로 반영됩니다.

방법 3 — BeforePrint 이벤트로 인쇄 전 처리 추가

💡 TIP
완성도 높은 인쇄 미리보기 패널이 필요하다면 SpreadJS 디자이너 컴포넌트를 활용하세요. 파일 메뉴 → 인쇄에서 용지 설정·방향·배율·미리보기를 GUI로 제공하며, 코드 없이 최종 사용자가 직접 설정할 수 있습니다.

SpreadJS 인쇄·PDF 개발 자주 묻는 질문

Q01

SpreadJS로 웹 페이지에서 PDF를 직접 다운로드하게 하려면 어떻게 하나요?

gc.spread.sheets.print.js 와 gc.spread.sheets.pdf.js 두 플러그인을 HTML에 로드한 뒤 spread.savePDF(successCallback, errorCallback, options) 를 호출합니다. 성공 콜백에서 받은 blob 파라미터를 FileSaver.js나 URL.createObjectURL() 에 넘겨 파일로 저장할 수 있습니다.

Q02

스프레드시트 인쇄물에 회사명과 페이지 번호를 머리글·꼬리글로 넣으려면 어떻게 하나요?

printInfo.pageHeaderFooter({ normal: { header: { left: '회사명', center: '보고서' }, footer: { center: '&P/&N' } } }) 처럼 위치별로 텍스트를 지정합니다. &P 는 현재 페이지 번호, &N 은 전체 페이지 수, &D 는 출력 날짜로 자동 변환됩니다.

Q03

SpreadJS 스프레드시트 안에 인쇄 미리보기 화면을 직접 삽입할 수 있나요?

sheet.isPrintLineVisible(true) 를 호출하면 시트 내부에 페이지 경계선이 나타나 인쇄 범위를 미리 확인할 수 있습니다. 브라우저 인쇄 다이얼로그(미리보기 포함)를 열려면 spread.print() 를 사용하고, 더 풍부한 UI가 필요하면 SpreadJS 디자이너 컴포넌트의 인쇄 패널을 애플리케이션에 임베드할 수 있습니다.

Q04

보고서가 여러 페이지로 나뉠 때 각 페이지 상단에 열 머리글이 자동으로 출력되게 하려면?

printInfo.repeatRowStart(0) 과 printInfo.repeatRowEnd(0) 으로 반복할 행의 시작·끝 인덱스를 지정합니다. 열 제목을 좌측에도 반복하려면 repeatColumnStart() 와 repeatColumnEnd() 를 함께 설정하면 됩니다.

Q05

SpreadJS로 PDF를 만들 때 한글이 깨져 출력된다면 어떻게 해결하나요?

NanumGothic 등 한글 TTF 파일을 fetch() 로 가져와 ArrayBuffer로 변환한 다음, GC.Spread.Sheets.PDF.PDFFontsManager.registerFont('NanumGothic', { normal: buffer }) 로 PDF 폰트 매니저에 등록합니다. 등록되지 않은 CJK 폰트까지 처리하려면 fallbackFont 함수를 override해 자동으로 대체 폰트가 적용되도록 설정할 수 있습니다.

MESCIUS SpreadJS

지금 바로 SpreadJS 를 무료로 체험해 보세요

30일 무료 체험판으로 모든 기능을 직접 확인하세요.

SpreadJS 무료 체험판 다운로드