API 레퍼런스
API 레퍼런스
React, Core, Viewer 중 필요한 계약을 고르고 공통 패키지·수명 주기 지침을 확인합니다.
첫 문서를 렌더링한 뒤에 이 레퍼런스를 사용하세요. 정확한 컴포넌트, 컨트롤러, 옵션, 수명 주기 제약은 패키지별 페이지에서 확인합니다.
패키지 맵
| 패키지 | 용도 | 대표 API |
|---|---|---|
@imposia/react | React 통합 | ImposiaPageViewer, ImposiaDocument, ImposiaPublicationViewer, 두 수명 주기 훅 |
@imposia/core | 프레임워크 중립적인 페이지네이션과 Publication | mountPageDocument, mountPublication, prepareDocument |
@imposia/viewer | 확정된 페이지 표시 | mountPageViewer, 딥 링크 도우미 |
@imposia/client | 프레임워크 중립적인 통합 진입점 | 주요 Core·Viewer 통합 API를 다시 내보냅니다. |
React 패키지를 사용할 때는 @imposia/react/styles.css를 한 번만 불러오세요.
API를 선택하세요
React API
React 앱을 위한 컴포넌트, 훅, 명령형 핸들입니다.
Core API
프레임워크 중립적인 페이지 문서와 Publication 컨트롤러입니다.
Viewer API
페이지 표시, Reader, Inspector입니다.
수명 주기와 오류
| 상황 | 결과 |
|---|---|
| 첫 세대를 준비하는 중 | current는 undefined이고 React 상태는 loading입니다. |
| 확정 후 갱신을 준비하는 중 | 이전에 확정된 문서가 화면과 React 상태에 남습니다. |
| 더 새로운 갱신 시작 | 진행 중이던 이전 세대가 AbortError로 거부됩니다. |
| 호출자가 작업 중단 | 관련된 세대 생성·내보내기가 DOM AbortError로 거부됩니다. |
| 확정 후 갱신 실패 | Promise는 거부되고, 이전에 확정된 문서가 현재로 남습니다. |
| 컨트롤러 제거 | 작업이 중단되고 리소스와 iframe이 해제되며 current가 비워집니다. |
ImposiaError는 Error를 확장하며 readonly code: string을 가집니다. 취소는 보고해야 할 실패와 구분해서 다루세요.
try {
await controller.update(nextSource, { signal });
} catch (error) {
if (error instanceof DOMException && error.name === "AbortError") return;
if (error instanceof ImposiaError) console.error(error.code, error.message);
throw error;
}Viewer 메서드는 현재 상태에서 실행할 수 없는 호출을 대체로 무시합니다. 소유 관계에 민감한 호출은 예외를 발생시킵니다. Page Viewer의 마운트와 refresh는 canonical iframe을 검증하고, Publication 탐색은 이전 세대의 목적지를 거부하며, Reader 선택은 다른 세대의 썸네일을, Inspector 선택은 다른 세대의 경고를 거부합니다.