첫 페이지 만들기
React 앱에 Imposia를 추가해 HTML을 A4 페이지로 표시하고, 인쇄하거나 PDF로 저장합니다.
이 가이드는 기존 React 앱에 페이지 미리보기를 추가합니다. 다 마치면 같은 컴포넌트에서 HTML을 A4 페이지로 확인하고, 종이나 PDF 출력을 위해 브라우저의 기본 인쇄 흐름을 열 수 있습니다.
시작하기 전에
React 18 이상과 브라우저에서 실행되는 클라이언트 환경이 필요합니다. Imposia는 Node.js나 서버 사이드 렌더링에서는 페이지를 만들지 않으므로, 프레임워크의 클라이언트 경계 아래에 마운트하세요.
React 패키지를 설치합니다
pnpm add @imposia/react react react-dom패키지 스타일시트는 이 컴포넌트나 앱의 클라이언트 진입 파일에서 한 번 불러오세요. 여러 번 불러와도 문제는 없지만, 아예 빠뜨리면 Viewer에 스타일이 적용되지 않습니다.
페이지 문서를 표시합니다
import { ImposiaPageViewer, type ImposiaPageViewerHandle } from "@imposia/react";
import { useRef } from "react";
import "@imposia/react/styles.css";
export function Preview() {
const viewer = useRef<ImposiaPageViewerHandle>(null);
return (
<>
<ImposiaPageViewer
ref={viewer}
source={{ html: "<article><h1>안녕하세요</h1><p>브라우저에서 만든 페이지입니다.</p></article>" }}
documentOptions={{ page: { size: "A4", margin: "18mm" } }}
/>
<button type="button" onClick={() => void viewer.current?.print()}>
인쇄 / PDF 저장
</button>
</>
);
}source.html은 페이지로 나눌 내용이고, documentOptions.page는 용지 크기와 여백을 정합니다. 핸들은 항상 마지막으로 완성에 성공한 페이지 문서를 가리키며, 아직 만들어지는 중인 문서를 가리키는 일은 없습니다.
결과를 확인합니다
브라우저에서 컴포넌트를 여세요. HTML이 Viewer 안에서 A4 페이지로 표시됩니다.
인쇄 / PDF 저장을 누르면 지금 보이는 페이지로 브라우저의 기본 인쇄 창이 열리고, 여기서 사용자가 프린터를 고르거나 PDF로 저장을 선택합니다. 이 메서드는 인쇄 창을 띄운 시점에 이행되며, PDF 바이트를 반환하지 않습니다.
진행 상태와 실패를 보여주세요
위 예제는 정적 문자열을 렌더링하므로 거의 즉시 확정됩니다. 실제 원본은 시간이 걸립니다. 이미지가 자리를 잡고, 글꼴이 로드되고, 긴 문서는 여러 페이지로 나뉩니다. 이 과정을 보여줘야 한다면 useImposiaDocument를 사용하세요.
import { useImposiaDocument } from "@imposia/react";
export function Preview({ html }: { html: string }) {
const { hostRef, state } = useImposiaDocument({ source: { html } });
return (
<>
{state.status === "loading" && <p role="status">페이지를 준비하는 중…</p>}
{state.status === "error" && <p role="alert">이 문서를 페이지로 나눌 수 없습니다.</p>}
<div ref={hostRef} />
</>
);
}state.status는 idle, loading, ready, error 중 하나입니다. 첫 성공 이후의 loading은 이전 페이지가 화면에 남은 채 다음 버전을 준비하고 있다는 뜻입니다. 따라서 스피너는 미리보기를 대체하지 말고 옆에 두세요. state.status가 error일 때도 화면에는 마지막으로 성공한 문서가 그대로 표시되고 있습니다.
선택 사항: EPUB 내보내기
제품에 의미 구조를 보존한 리플로우형 산출물도 필요하다면, 같은 확정된 문서에서 EPUB 3.3 Blob을 만들 수 있습니다. 이 출력은 부가 경로입니다. 위의 미리보기·인쇄 경로와는 별개이며, 필요 없으면 건너뛰어도 됩니다.
메타데이터는 필수입니다. 제목, 언어, 식별자가 없으면 내보내기가 거부됩니다.
const blob = await viewer.current?.exportEpub({
metadata: { title: "안녕하세요", language: "ko", identifier: "urn:example:hello" },
});이 메서드는 Blob을 반환합니다. 다운로드나 업로드에 연결하는 일은 앱의 몫입니다. EPUB은 페이지로 나뉜 DOM이 아니라 원본의 의미 구조에서 만들어지므로, 머리말·꼬리말 같은 페이지 장식과 생성된 페이지 번호는 의도적으로 제외됩니다.