독립 HTML 내보내기

이미 페이지로 나눈 문서를 독립 HTML 문자열로 저장하려면 exportPageDocumentHtml()을 사용합니다. Core, Client, React 패키지에서 가져올 수 있습니다. 이 API는 브라우저에서 실행되며, 앱은 결과를 파일로 저장하거나 별도의 렌더러에 전달할 수 있습니다.

아래 Core 예제에는 Core 직접 의존성이 필요합니다. React를 이미 사용하고 있다면 같은 함수를 @imposia/react에서도 가져올 수 있습니다.

pnpm add @imposia/core@0.8.1

필요한 출력을 선택합니다

HTML에는 확정된 페이지, 해당 스타일과 페이지 장식이 포함됩니다. Viewer 표시용 스타일과 컨트롤은 제외합니다. EPUB은 페이지 래퍼와 장식도 제외합니다. 어느 API도 PDF 바이트를 반환하지 않습니다.

확정된 문서를 내보내고 내려받습니다

예제를 실행하기 전에 브라우저 페이지에 <div id="preview"></div>를 만드세요.

import { exportPageDocumentHtml, mountPageDocument } from "@imposia/core";

const controller = mountPageDocument(document.getElementById("preview")!, {
  html: "<article><h1>Invoice</h1><p>Committed pages</p></article>",
});
const committed = await controller.ready;
const markup = await exportPageDocumentHtml(committed, { title: "Invoice" });

const url = URL.createObjectURL(new Blob([markup], { type: "text/html;charset=utf-8" }));
const link = document.createElement("a");
link.href = url;
link.download = "invoice.html";
document.body.append(link);
link.click();
link.remove();
setTimeout(() => URL.revokeObjectURL(url), 1000);

출력에는 doctype과 UTF-8 선언이 들어갑니다. Core에서 이미 해결한 리소스는 data URL로 포함됩니다. 내보내기가 누락된 리소스를 가져오거나 차단된 리소스를 되살리지는 않습니다. 리소스가 없으면 문서 확정을 막아야 하는 경우에는 준비 단계에서 blockedResourcePolicy: "error"를 사용하세요.

React에서는 핸들에서 확정된 문서를 읽고, 재노출된 함수를 사용합니다.

import { exportPageDocumentHtml } from "@imposia/react";

// viewer is a ref to an ImposiaPageViewerHandle.
const committed = viewer.current?.current;
if (committed !== undefined) {
  const markup = await exportPageDocumentHtml(committed);
}

어느 세대를 내보낼지 선택합니다

HTML 내보내기는 전달한 문서를 직렬화하며, 진행 중인 갱신을 기다리지 않습니다. 새 원본이 필요하면 controller.update(nextSource)를 기다린 뒤 그 갱신이 반환한 문서를 내보내세요. controller.ready는 첫 확정만 나타냅니다.

이전 세대의 문서, 파기한 컨트롤러, 사용할 수 없는 확정 문서는 DOCUMENT_UNAVAILABLE로 거절됩니다. 유효한 내보내기가 스냅샷을 확보한 뒤에는 갱신이나 파기가 일어나도 해당 내보내기는 완료될 수 있습니다.

0.8.1에서 수정된 동작

내보내기는 원본의 모든 페이지를 렌더링한 상태에서 앵커 요소를 측정하므로, 미리보기 스크롤 위치에 따라 내보낸 위치가 달라지지 않습니다. 인라인·스타일시트 앵커 모두 요소 자신의 transform을 고려해 포함 블록 기준 위치로 고정합니다. 내보낸 모든 페이지는 화면과 인쇄 미디어에서 content-visibility: visible !important를 사용합니다. 측정 후 미리보기의 인라인 스타일 값과 지연 렌더링 정책을 복원합니다.

새 옵션 없이 적용되는 수정입니다. 브라우저, 글꼴 엔진, PDF 렌더러 사이에 동일한 결과를 보장하지는 않습니다. 실제 사용하는 렌더러에서 출력 HTML을 검증하세요.

대상 렌더러의 픽셀 비율을 맞춥니다

0.8.0에서 추가된 선택적 targetDevicePixelRatio는 출력 HTML을 받는 렌더러의 비율을 알고 있을 때만 지정합니다.

const markup = await exportPageDocumentHtml(committed, {
  title: "Invoice",
  targetDevicePixelRatio: 0.5, // Only if this is the receiving renderer's actual ratio.
});

낮은 비율의 렌더러는 1px 셀 테두리를 장치 픽셀 하나로 올림해 텍스트 공간을 줄일 수 있습니다. 내보낸 복제본에서는 해당 테두리를 넓히고 padding으로 공간을 보상합니다. collapsed 테두리 두께가 섞인 경계나 지원하지 않는 테두리 구조는 원본대로 둡니다. 복제본에만 적용되는 보정이며, 다른 글꼴이나 지원하지 않는 CSS까지 해결하지는 않습니다.

일반 내보내기에서는 옵션을 생략하세요. 값은 양수인 유한 숫자여야 하며, 0·음수·NaN·무한대는 TypeError로 거절됩니다. 미리보기의 window.devicePixelRatio를 다른 렌더러의 비율 대신 넣지 마세요.

병합된 행과 긴 셀은 표를 페이지에 나누기, 전체 내보내기 계약은 Core API를 참고하세요.