Viewer API
@imposia/viewer가 제공하는 페이지 표시, Reader, Inspector 컨트롤러입니다.
@imposia/viewer는 문서를 표시합니다. mountPageViewer는 확정된 Core 페이지 문서의 canonical iframe을 표시합니다. 페이지네이션은 실행하지 않습니다.
mountPageViewer
mountPageViewer(container: HTMLElement, document: PageDocument, options?: PageViewerOptions): PageViewerController;
validatePageViewerOptions(document: PageDocument, options?: PageViewerOptions): void;검증은 문서, sandbox, 테마, 선택적 Reader를 동기적으로 확인합니다. validatePageViewerOptions는 마운트하지 않고 같은 검사를 실행합니다.
Core 확정 이후, iframe의 컨테이너에서만 마운트하세요
mountPageViewer에는 확정된 PageDocument가 필요하고, container는 canonical iframe의 현재 부모 요소여야 합니다. 다른 요소를 전달하면 예외가 발생합니다. Viewer는 Core의 iframe을 제자리에서 표시하며, 옮기거나 복제하거나 다시 만들지 않습니다.
PageViewerOptions는 mode?: "continuous" | "single" | "spread", spread?: { cover? }, zoom?, controls?, theme?, inspector?, reader?를 받습니다. controls의 기본값은 true입니다. false로 두면 표시 컨트롤러는 유지하면서 내장 컨트롤 레일을 만들지 않습니다. 테마는 이름이 --imposia-viewer-로 시작하는 CSS 속성의 맵입니다.
PageViewerController
| 멤버 | 반환값 | 동작과 제약 |
|---|---|---|
goToPage(page), nextPage(), previousPage() | void | 현재 페이지 또는 유효 spread 범위 안에서 이동합니다. |
setZoom(zoom) | void | 유한한 입력을 반올림하고 범위로 제한합니다. |
setMode(mode), setSpreadCover(cover) | void | 요청 모드와 표지 배치를 바꿉니다. |
setTheme(theme?) | void | Viewer 변수를 교체하거나 제거합니다. |
subscribe(listener) | () => void | 상태를 즉시 전달한 뒤 표시 변경을 전달합니다. 구독 해제 함수를 반환합니다. |
refresh(document) | void | 같은 iframe과 더 새로운 세대가 필요합니다. 제거 후나 잘못된 입력에는 예외가 발생합니다. |
print() | Promise<void> | 제거 후나 iframe을 사용할 수 없을 때 거부됩니다. |
destroy() | void | Viewer 바인딩과 UI를 제거하고 Core iframe 컨테이너를 복원합니다. 여러 번 호출해도 안전합니다. |
state | PageViewerState | 페이지, 페이지 수, 배율, 요청·적용 모드, status, 세대입니다. |
reader | PublicationReaderController | undefined | Reader 옵션을 지정했을 때 존재합니다. |
inspector | ViewerInspectorController | undefined | inspector: true일 때 존재합니다. |
Viewer CSS는 .imposia-viewer로 한정됩니다. body 스타일, 미리보기 크기, 배경, 주변 스크롤은 호스트가 소유합니다.
Publication Reader와 딥 링크
Reader 옵션에는 표시 중인 PublicationDocument를 소유한 바로 그 PublicationController가 필요하며, initialDeepLink와 onDeepLinkChange를 포함할 수 있습니다.
PublicationReaderController 멤버 | 반환값과 동작 |
|---|---|
openTableOfContents(), closeTableOfContents(), toggleTableOfContents() | 목차(outline) 패널을 제어합니다. |
openThumbnails(), closeThumbnails(), toggleThumbnails() | 썸네일을 제어합니다. |
selectThumbnail(thumbnail) | 현재 세대의 썸네일로 이동합니다. 다른 세대의 썸네일에는 예외가 발생합니다. |
openSearch(), closeSearch(), toggleSearch() | 검색을 제어합니다. |
search(query) | readonly PublicationSearchResult[]를 반환합니다. |
nextSearchResult(), previousSearchResult() | PublicationSearchResult | undefined를 반환합니다. |
selectSearchResult(result) | 결과를 선택하고 그 위치로 이동합니다. |
navigate(destination) | 검증하고 이동한 뒤 딥 링크를 알립니다. |
restoreDeepLink(value) | PublicationDestination | undefined. 해석하고 이동합니다. |
state | 패널 상태, 썸네일, 목적지·딥 링크, 질의, 결과, 활성 결과 인덱스입니다. |
모든 Reader 메서드는 제거 후에 예외가 발생합니다. 보조 패널 하나를 열면 나머지가 닫힙니다. PublicationThumbnail은 페이지, 세대, 크기, previewLineCount를 노출합니다.
serializePublicationDeepLink(destination: PublicationDestination): string;
restorePublicationDeepLink(value: string, controller: PublicationController): PublicationDestination | undefined;직렬화는 목적지 ID에서 버전이 있는 값을 만듭니다. 독립 복원 도우미는 정식 인코딩만 받아 현재 세대에 대해 해석하며, Reader 메서드와 달리 이동하지 않습니다.
Viewer Inspector
ViewerInspectorController 멤버 | 반환값과 동작 |
|---|---|
open(), close(), toggle() | 진단 패널을 제어합니다. 제거 후에는 예외가 발생합니다. |
select(warning) | 위치가 있는 경고로 이동해 강조합니다. 다른 세대의 경고에는 예외가 발생합니다. |
state | { open, warnings, selected }입니다. |
Inspector 패널은 목차·검색·썸네일과 보조 패널 자리를 공유합니다. 어느 하나를 열면 나머지가 닫힙니다. 인쇄에서는 숨겨지고 EPUB 내보내기에는 포함되지 않습니다.