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 | 在当前页面或有效跨页范围内限制并推进。 |
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() | 控制大纲面板。 |
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 导出中不存在。