🖨️ 리액트 페이지를 PDF로 변환하기: 웹 페이지 그대로 PDF로 만드는 마법

들어가며

회사 프로젝트에서 웹 페이지를 자동으로 PDF로 변환하여 서버로 전송해야 하는 요구사항이 있었습니다. 서버 측에서 PDF를 생성하는 방법도 있었지만, CSS 사용이 제한적이고 웹 페이지와 레이아웃이 달라지는 문제가 있었습니다. 그래서 프론트엔드에서 직접 페이지를 PDF로 변환하는 방법을 선택했습니다.

사용한 라이브러리

웹 페이지를 PDF로 변환하기 위해 두 가지 핵심 라이브러리를 사용했습니다:

1. html2canvas: HTML 요소를 캡처하여 캔버스로 변환합니다.
2. jsPDF: 캔버스 이미지를 PDF 문서로 변환합니다.

이 두 라이브러리를 조합하면 웹 페이지의 모양을 그대로 유지하면서 PDF로 변환할 수 있습니다.

PDF 생성 함수 구현하기

기본 구조 설계

먼저 PDF 생성을 위한 함수의 기본 구조를 설계했습니다:

interface generateReportPageToPdfProps {
  patrolElements?: HTMLDivElement;
  alarmElements: HTMLDivElement[];
  startDate: string;
}

export const generateReportPageToPdf = async ({
  patrolElements,
  alarmElements,
}: generateReportPageToPdfProps) => {
  // PDF 생성 로직
};

함수는 두 종류의 HTML 요소를 받습니다:

• patrolElements: 보고서의 주요 내용
• alarmElements: 알람 보고서 목록 (여러 페이지에 걸쳐 표시될 수 있음)

HTML 요소를 이미지로 변환하기

첫 번째 단계는 HTML 요소를 캔버스로 변환한 후 이미지로 만드는 것입니다:

// patrolElements를 캡처하여 이미지로 변환
const PatrolDetail = await html2canvas(patrolElements, {
  allowTaint: true,
  useCORS: true,
  logging: false,
  scale: 2, // 해상도를 높이기 위해 scale 값을 2로 설정
});

const PatrolDetailImg = PatrolDetail.toDataURL('image/png', 1.0);

여기서 주목할 옵션들:

• allowTaint: 외부 도메인의 이미지 사용 허용
• useCORS: 크로스 도메인 이미지 사용
• scale: 2: 해상도를 높이기 위한 설정 (이 부분이 중요!)

PDF 문서 생성 및 이미지 추가

다음으로 jsPDF를 사용하여 PDF 문서를 생성하고 이미지를 추가합니다:

const imgWidth = 210; // A4 기준 가로 길이(mm)
const imgHeight = (PatrolDetail.height * imgWidth) / PatrolDetail.width;
const padding = 5;

// PDF 문서 생성
const doc = new jsPDF('p', 'mm', 'a4', true);

// 첫 페이지에 PatrolDetail 이미지 추가
doc.addImage(PatrolDetailImg, 'PNG', 0, 10, imgWidth, imgHeight);

여러 페이지 처리하기

alarmElements를 순회하면서 각각의 요소를 이미지로 변환하고 PDF에 추가합니다. 이때 페이지 크기를 넘어가면 새 페이지를 추가하는 로직이 필요합니다:

let curHeight = imgHeight + padding;
// alarmElements를 순회하며 각각을 이미지로 변환하여 PDF에 추가
for (let i = 0; i < alarmElements.length; i++) {
  const canvas = await html2canvas(alarmElements[i], {
    allowTaint: true,
    useCORS: true,
    logging: false,
    scale: 2,
  });

  const img = canvas.toDataURL('image/png', 1.0);
  const imageHeight = (canvas.height * imgWidth) / canvas.width;

  // 현재 페이지의 높이와 이미지의 높이를 비교하여 페이지를 추가
  if (curHeight + imageHeight > doc.internal.pageSize.height - padding) {
    doc.addPage();
    curHeight = padding;
  }

  doc.addImage(img, 'PNG', padding, curHeight, 200, imageHeight);
  curHeight += imageHeight + padding;
}

발생한 문제들과 해결 방법

1. 검정색 부분 발생 문제

캡처된 이미지에 검정색 부분이 나타나는 문제가 있었습니다.

해결방법: scale 값을 2로 설정하여 해상도를 높였습니다. 화면 크기에 비해 작은 scale 값이 문제였습니다.

2. MUI Board 표현 문제

Material-UI의 Paper 컴포넌트가 제대로 캡처되지 않는 문제가 있었습니다.

해결방법: div를 참조하는 Box 컴포넌트를 사용하고, 직접 border 스타일을 적용했습니다.

3. 페이지 자동 분할 문제

이미지가 원하는 대로 배치되지 않고 페이지가 임의로 넘어가는 문제가 있었습니다.

해결방법: 각 요소의 ref를 배열로 저장하고, 각 요소의 높이를 계산하여 페이지 분할을 정확하게 제어했습니다:

const alarmRef = useRef([]);

// 컴포넌트 내부 JSX에서
{AlarmReportData.map((data, index) => (
  <Box ref={(el) => (alarmRef.current[index] = el)} key={index}>
    <AlarmReport data={data} />
  </Box>
))}

// 각 요소를 이미지로 변환
const alramlists = [];
for (let i = 0; i < alarmRef.current.length; i++) {
  const canvas = await html2canvas(alarmRef.current[i], {...});
  const img = canvas.toDataURL('image/png', 1.0);
  const imageHeight = (canvas.height * imgWidth) / canvas.width;
  alramlists.push({ image: img, height: imageHeight });
}

// 페이지 분할 로직
let curHeight = padding;
for (let i = 0; i < alramlists.length; i++) {
  const image = alramlists[i].image;
  const imgHeight = alramlists[i].height;
  if (curHeight + imgHeight > 297 - padding * 2) { // A4 세로 길이 (297mm)
    doc.addPage();
    curHeight = padding;
  }
  doc.addImage(image, 'PNG', padding, curHeight, 200, imgHeight);
  curHeight += imgHeight;
}

4. 한글 폰트 깨짐 문제

PDF에 한글 텍스트를 추가할 때 폰트가 깨지는 문제가 있었습니다.

해결방법: 폰트 파일을 직접 import하여 jsPDF에 등록했습니다:

import hl from '../font/HyundaiHarmonyL.ttf';

// PDF 생성 시
const doc = new jsPDF('p', 'mm', 'a4', true);
doc.addFont(hl, 'HyundaiHarmonyL', 'normal');
doc.setFont('HyundaiHarmonyL');
doc.setFontSize(8);

5. 푸터 추가하기

각 페이지에 일관된 푸터를 추가하는 기능을 구현했습니다:

const addFooters = (doc) => {
  const pageCount = doc.internal.getNumberOfPages();
  doc.setFont('HyundaiHarmonyL');
  doc.setFontSize(8);
  
  for (let i = 1; i <= pageCount; i++) {
    doc.setPage(i);
    doc.text(
      'Page ' + String(i) + ' of ' + String(pageCount),
      doc.internal.pageSize.width / 2,
      287,
      { align: 'center' }
    );
    doc.text(
      `레포트 생성 일자: ${getToday()}`,
      doc.internal.pageSize.width / 2 + 40,
      287,
      { align: 'center' }
    );
  }
};

최종 코드

최종적으로 완성된 PDF 생성 함수는 다음과 같습니다:

export const generateReportPageToPdf = async ({
  patrolElements,
  alarmElements,
}: generateReportPageToPdfProps) => {
  if (!patrolElements) {
    console.error('Invalid patrolElements');
    return;
  }

  const PatrolDetail = await html2canvas(patrolElements, {
    allowTaint: true,
    useCORS: true,
    logging: false,
    scale: 2,
  });

  const PatrolDetailImg = PatrolDetail.toDataURL('image/png', 1.0);
  const imgWidth = 210; // 이미지 가로 길이(mm) / A4 기준 210mm
  const imgHeight = (PatrolDetail.height * imgWidth) / PatrolDetail.width;
  const padding = 5;

  // PDF 문서 생성 및 폰트 설정
  const doc = new jsPDF('p', 'mm', 'a4', true);
  doc.addFont(hl, 'HyundaiHarmonyL', 'normal');
  doc.setFont('HyundaiHarmonyL');
  doc.setFontSize(8);

  // 첫 페이지에 PatrolDetail 이미지 추가
  doc.addImage(PatrolDetailImg, 'PNG', 0, 10, imgWidth, imgHeight);

  let curHeight = imgHeight + padding;

  // alarmElements를 순회하며 각각을 이미지로 변환하여 PDF에 추가
  for (let i = 0; i < alarmElements.length; i++) {
    const canvas = await html2canvas(alarmElements[i], {
      allowTaint: true,
      useCORS: true,
      logging: false,
      scale: 2,
    });

    const img = canvas.toDataURL('image/png', 1.0);
    const imageHeight = (canvas.height * imgWidth) / canvas.width;

    // 현재 페이지의 높이와 이미지의 높이를 비교하여 필요시 새 페이지 추가
    if (curHeight + imageHeight > doc.internal.pageSize.height - padding) {
      doc.addPage();
      curHeight = padding;
    }

    doc.addImage(img, 'PNG', padding, curHeight, 200, imageHeight);
    curHeight += imageHeight + padding;
  }

  addWaterMark(doc); // 워터마크 추가

  return doc;
};

마치며

이 방법을 통해 웹 페이지를 원본 레이아웃과 스타일 그대로 PDF로 변환하고, 서버로 전송하는 기능을 성공적으로 구현했습니다. 물론 복잡한 페이지나 동적 컨텐츠가 많은 경우 추가적인 최적화가 필요할 수 있지만, 기본적인 요구사항을 충족하는 솔루션을 제공합니다.

리액트 프로젝트에서 PDF 변환 기능이 필요하신 분들께 이 글이 도움이 되길 바랍니다. 덕분에 저도 많은 것을 배웠고, 이 지식을 공유할 수 있어 기쁩니다.