React-pdf SVG 로고: PDF에 경로 렌더링하기
Svg와 Path로 React-pdf 문서에 SVG 로고를 추가하고 구멍을 유지하세요. 크기를 명시하고 자신의 그림을 쓰기 전에 저장된 PDF를 확인합니다.
목차
@react-pdf/renderer에 작은 SVG 로고를 넣으려면 해당 패키지의 Svg, Path와 다른 지원 컴포넌트로 그림을 구성하세요. 바깥 Svg에 크기를 명시하고 원본 viewBox를 유지하세요. 렌더러의 Image 문서는 PNG와 JPG 입력을 나열합니다. SVG URL을 Image로 감싸는 것은 여기서 설명하는 벡터 방식이 아닙니다.
이 가이드는 중앙에 구멍이 있는 정사각형 문양으로 완전한 Node 예제를 제공합니다. 고정된 의존성으로 PDF를 렌더링하고 결과를 검사했습니다. 예제는 혼동하기 쉬운 세 가지, 즉 원본 그림, 컴포넌트 트리와 PDF의 배치 크기를 분리합니다.
사용하는 React PDF 패키지 확인하기
이 글은 @react-pdf/renderer로 문서를 생성합니다. 별도 이름의 react-pdf 패키지는 기존 PDF를 표시합니다. 검색 결과의 해결책을 복사하기 전에 파일의 import를 확인하세요.
렌더러 Document 내부에서는 해당 렌더러가 내보내는 컴포넌트를 사용하세요. 브라우저의 소문자 svg와 path 요소는 다른 렌더링 환경에 속합니다. 공식 SVG 컴포넌트 참고 문서는 Svg를 뷰포트 컨테이너로 정의하고 내부에 가져온 React-pdf 도형을 보여 줍니다.
| 소스 또는 목표 | 적합한 시작점 | 전달 전 확인 사항 |
|---|---|---|
| 단순한 경로의 작은 로고 | 가져온 Path, Rect 또는 다른 지원 프리미티브를 담은 Svg | 페인트, 구멍, viewBox와 크기 |
| 문자열로 들어오는 SVG 마크업 | 프로젝트의 SVG 파서를 평가하고 출력을 렌더링 작업 흐름에 연결 | 지원하지 않는 요소와 실제 출력 |
| 픽셀로 유지할 PNG 또는 JPG | Image | 배치 크기에서의 해상도 |
| 웹페이지에 표시할 기존 PDF | PDF 뷰어 | 그림을 생성하는 것이 아니라 문서를 보는 작업인지 확인 |
Image 참고 문서는 비트맵 입력을 설명합니다. 복잡한 모양을 유지하는 것이 벡터 도형 유지보다 중요하면 PNG 대체가 유용할 수 있습니다. 전달물이 달라지므로 벡터 원본은 따로 보관하세요.
공식 @react-pdf/svg 패키지도 있습니다. README는 프리미티브 노드 트리를 반환하고 속성 이름을 camelCase로 바꾸는 parseSvg()를 설명합니다. 지원하지 않는 요소는 경고와 함께 건너뛴다고 명시합니다. 이는 파서의 계약이며 모든 브라우저 SVG가 똑같이 렌더링된다는 보장은 아닙니다. 아래 예제는 도형과 페인트를 쉽게 검사하도록 명시적 컴포넌트를 사용합니다.
자신의 로고를 가져오기 전에 최소 로고 렌더링하기
@react-pdf/renderer 4.9.0, React 19.2.4, Node 22.19.0으로 이 예제를 실행했습니다. 이는 테스트한 구성을 나타내며 다른 의존성 트리의 동작을 보장하지는 않습니다.
새 디렉터리에서 런타임 패키지 두 개를 설치하세요.
npm install --save-exact @react-pdf/renderer@4.9.0 react@19.2.4다음을 logo.mjs로 저장하고 node logo.mjs를 실행하세요. React.createElement를 사용하므로 Node가 JSX 빌드 단계 없이 실행할 수 있습니다.
import React from 'react';
import { fileURLToPath } from 'node:url';
import {
Document, Page, Svg, Path, Rect, renderToFile,
} from '@react-pdf/renderer';
const h = React.createElement;
const ring = 'M10 10H90V90H10Z M30 30H70V70H30Z';
const logo = h(
Svg,
{ width: 144, height: 144, viewBox: '0 0 100 100' },
h(Rect, {
x: 0, y: 0, width: 100, height: 100, fill: '#f3ede2',
}),
h(Path, { d: ring, fill: '#087f8c', fillRule: 'evenodd' }),
);
await renderToFile(
h(Document, null,
h(Page, { size: 'A4', style: { padding: 36 } }, logo),
),
fileURLToPath(new URL('./logo.pdf', import.meta.url)),
);바깥과 안쪽 정사각형은 하나의 복합 경로를 공유합니다. fillRule: 'evenodd'가 안쪽 정사각형을 비워 아래의 옅은 사각형이 보이게 합니다. 중앙을 덮는 흰 패치는 없습니다. 따라서 내부 공간이나 구멍이 있는 로고로 예제를 교체할 때 확인에 유용합니다.
SVG 좌표는 각 방향으로 100단위이고 배치한 뷰포트는 144 × 144입니다. viewBox는 그림의 좌표계를 설명하고 width와 height는 표시 뷰포트를 설명합니다. 로고 크기를 조절할 때 이 차이를 유지하세요. 공식 Svg props 표는 이 제어 항목과 preserveAspectRatio를 설명합니다.
미리보기와 저장된 PDF 모두 검사하기
테스트 결과는 왼쪽 위 가까이에 청록색 정사각형 고리가 있는 A4 한 페이지였습니다. Poppler로 파일을 렌더링하고 구멍을 통해 옅은 배경이 보이는지 시각적으로 확인했습니다. Poppler의 pdfimages -list logo.pdf는 이 독립 문서에 삽입된 이미지가 없다고 보고했습니다.
이 결과의 범위는 의도적으로 좁습니다. 경로만 사용하는 이 예제를 설명합니다. 사진, 삽입 SVG 이미지나 지원하지 않는 효과가 있는 문서도 전체가 벡터라는 것을 입증하지는 않습니다.
컴퓨터에 Poppler가 있다면 다음 명령으로 서로 다른 두 검사를 할 수 있습니다.
pdfimages -list logo.pdf
pdftoppm -png -singlefile -scale-to 1000 logo.pdf logo-preview두 번째 명령은 시각적 검사용 래스터 미리보기를 만들며 원본 PDF를 비트맵으로 바꾸지는 않습니다. 미리보기에서 구멍, 모서리, 색상과 배치를 확인한 뒤 수신자가 쓰는 뷰어에서 저장된 PDF를 여세요. 선명한 미리보기만으로 원본에 경로가 있다고 판단할 수는 없습니다. 큰 비트맵도 선명해 보일 수 있습니다.
더 확실한 검사를 위해 PDF에서 로고 주변의 그리기 명령과 참조 객체를 확인하세요. 복잡한 보고서에는 중첩 객체가 있을 수 있으므로 전체 보고서를 진단하기 전에 독립 로고 문서부터 시작하세요. PDFKit SVG 가이드는 별도 SVG 가져오기 작업 흐름과 저장된 PDF 검사를 설명합니다.
그림을 기능 하나씩 옮기기
예제의 d 값을 자신의 경로 데이터로 교체하고 관련 채우기, 채우기 규칙, 스트로크와 변환을 유지하세요. 모양만 복사하고 페인트를 빠뜨리면 경로 데이터 자체가 유효해도 결과가 바뀔 수 있습니다.
작은 정적 표식은 지원 도형에 직접 색상을 지정하세요. 웹페이지 스타일시트에 의존하는 로고는 자체 포함 문서 컴포넌트가 되기 전에 의존성을 해결해야 합니다. 이후 수정 내용을 승인된 그림과 비교할 수 있도록 소스 SVG를 렌더링 코드 옆에 보관하세요.
| 증상 | 먼저 확인할 사항 | 유용한 다음 단계 |
|---|---|---|
| SVG URL을 전달해도 아무것도 표시되지 않음 | 코드가 Image를 사용하는지 | 위의 작동하는 Svg 예제로 시작 |
| 로고가 잘리거나 예상보다 작음 | viewBox, 뷰포트 크기와 원본 여백 | 비율을 명시적으로 맞춘 뒤 칠해진 경계 확인 |
| 구멍이 채워짐 | 복합 경로와 fillRule | 규칙 유지 후 대비되는 배경에서 테스트 |
| 일부가 사라짐 | 지원 프리미티브 목록과 파서 경고 | 작은 테스트 문서에서 해당 기능 분리 |
| 파일이 여전히 픽셀처럼 동작 | 원본의 삽입 이미지 콘텐츠 | PDF 설정을 바꾸기 전에 SVG 확인 |
공식 SVG 개요는 사용 가능한 프리미티브를 정리합니다. 브라우저의 전체 SVG 기능 목록이 아니라 지원 확인 목록으로 취급하세요. 운영 보고서에 추가하기 전에 설치 버전에서 글자, 클리핑과 그라디언트를 테스트하세요.
SVG에 PNG가 삽입되어 있다면 컨테이너를 변환해도 누락된 도형이 재구성되지 않습니다. 삽입 래스터 가이드는 경로와 SVG 안에 저장한 비트맵을 구분하는 방법을 보여 줍니다.
로고가 PNG나 JPG로 시작할 때
원본 SVG, AI 또는 다른 편집 가능 벡터 원본이 있다면 먼저 요청하세요. 픽셀만 남았다면 PerfectVector의 로고 벡터화 도구로 React-pdf 작업 앞 단계에서 SVG 후보를 준비할 수 있습니다. 지원 도형을 PDF 컴포넌트에 맞추기 전에 윤곽선, 작은 구멍과 별도 색상 영역을 원본과 비교하세요.
벡터화는 렌더러 통합을 고치거나 React 컴포넌트를 만들거나 모든 SVG 기능 지원을 보장하지 않습니다. 정확한 브랜드 도형이 필요한 글자는 수동 검토하세요. 로고 벡터화 가이드는 추적, 재입력과 다시 그리기 사이에서 선택하는 데 도움이 됩니다.
래스터 원본에서는 검토한 벡터 후보에 이어 확인된 PDF를 얻는 것이 유용한 결과입니다. 기존 벡터 원본에서는 바로 컴포넌트와 배치 검사로 진행하세요. 원본 준비에 관한 추가 안내는 블로그에 있습니다.
FAQ
SVG 파일을 React-pdf Image에 전달할 수 있나요? 문서화된 Image 입력은 PNG와 JPG입니다. 이 가이드의 경로 기반 작업에는 렌더러의 Svg 프리미티브를 사용하고, 다른 입력 동작에 의존하기 전에 설치 버전을 확인하세요.
모든 SVG를 수동으로 옮겨야 하나요? 아닙니다. 공식 @react-pdf/svg 패키지는 SVG 문자열을 프리미티브 노드 트리로 파싱합니다. 지원 요소와 경고를 검토하고 출력을 렌더링 작업 흐름에 연결해 테스트하세요. 여기의 명시적 컴포넌트 예제는 추가 파서 단계를 피합니다.
로고 중앙이 채워지는 이유는 무엇인가요? 복합 경로와 채우기 규칙을 확인하세요. 테스트 문양은 evenodd로 안쪽 정사각형을 비워 둡니다. 그림을 바꾸기 전에 원래 도형과 페인트 규칙을 유지하세요.
선명한 PDF 미리보기가 로고의 벡터 여부를 입증하나요? 아닙니다. 모양뿐 아니라 저장된 PDF 내용과 이미지 객체도 검사하세요. 이 가이드의 독립 예제에는 삽입 이미지가 없었지만 다른 로고에 자동으로 적용되지는 않습니다.
Sources
- React-pdf — Svg 컴포넌트 — 뷰포트, 크기, viewBox와 가로세로 비율 제어를 정의합니다.
- React-pdf — Image 컴포넌트 — 비트맵 배치용 PNG와 JPG 입력 형식을 설명합니다.
- React-pdf — SVG 프리미티브 — 렌더러가 지원하는 SVG 컴포넌트를 정리합니다.
- React-pdf — SVG 파서 — 프리미티브 노드 트리, 속성 변환과 지원하지 않는 요소 경고를 설명합니다.
PNG나 JPG 로고만 있나요? PerfectVector로 SVG 후보를 준비하고 윤곽선과 구멍을 원본과 비교하세요. 지원 도형을 맞춘 뒤 저장된 PDF를 검사하세요.
