React API

@imposia/react 把一个 Core 控制器和一个 canonical iframe 绑进 React 生命周期。它还重新导出 Core 与 Viewer 的 API 表面，因此 React 应用通常不需要其他 Imposia 导入。导入一次 @imposia/react/styles.css。

`ImposiaPageViewer` 与 `ImposiaDocument`

ImposiaPageViewer 挂载一份 Core 页面文档，并在首次提交后绑定页面 Viewer。ImposiaDocument 是公开 props 与句柄类型完全相同的兼容包装：ImposiaDocumentProps = ImposiaPageViewerProps，ImposiaDocumentHandle = ImposiaPageViewerHandle。

app/report-preview.tsx

const viewer = useRef<ImposiaPageViewerHandle>(null);

<ImposiaPageViewer
  ref={viewer}
  source={{ html: "<main><h1>报告</h1></main>" }}
  documentOptions={{ page: { size: "A4", margin: "18mm" } }}
  viewerOptions={{ mode: "single", inspector: true }}
  onError={console.error}
/>;

Prop	类型	必填	用途
`source`	`PageSource`	是	要分页的 HTML 或 light DOM。
`sourceRevision`	`string \| number`	否	源的标识或内容比较没有变化时强制更新。
`documentOptions`	`PageDocumentOptions`	否	Core 分页选项。
`documentOptionsRevision`	`string \| number`	否	以新的文档选项重建 Core。
`viewerOptions`	`PageViewerOptions`	否	页面展示、reader 与 inspector 选项。
`onViewerStateChange`	`(state: PageViewerState) => void`	否	接收页码、缩放、模式、生效模式和世代变化。
`className`、`style`	`string`、`CSSProperties`	否	宿主 `div` 的展示属性。
`onReady`	`(document: PageDocument) => void`	否	在文档与 Viewer 绑定就绪后运行。
`onError`	`(error: unknown) => void`	否	接收 Core 或 Viewer 绑定失败。
`onStateChange`	`(state: ImposiaDocumentState) => void`	否	接收 `idle`、`loading`、`ready` 和 `error`。

选项 props 只在 revision 变化时读取

documentOptions 在控制器挂载时被捕获。仅传入变化后的选项对象——新的解析器、扩展集合或页面几何——本身不会有任何效果：请递增 documentOptionsRevision，以新选项重建控制器。下方的 publicationOptions 与 publicationOptionsRevision 遵循同一规则。只有 source（和 snapshot）的变化会被自动检测。

`ImposiaPageViewerHandle`

句柄方法作用于最近一次已提交的世代。需要 Viewer 或提交结果的方法在首次提交前和卸载后抛出（或拒绝）。

成员	返回值	约束
`current`	`PageDocument \| undefined`	挂载期间为当前提交；其余情况为 `undefined`。
`viewerState`	`PageViewerState \| undefined`	就绪时的当前展示快照。
`goToPage(page)`、`nextPage()`、`previousPage()`	`void`	在已提交的全局页面序列中移动；未就绪或卸载后抛出。
`setZoom(zoom)`	`void`	对展示缩放取整并限制范围；未就绪或卸载后抛出。
`setMode(mode)`	`void`	接受 `continuous`、`single` 或 `spread`；未就绪或卸载后抛出。
`setSpreadCover(cover)`	`void`	未就绪或卸载后抛出。
`openInspector()`、`closeInspector()`、`toggleInspector()`	`void`	需要 `viewerOptions.inspector: true`。
`selectWarning(warning)`	`void`	需要 Inspector，且警告须来自其当前世代。
`print()`	`Promise<void>`	为最新完成的页面打开原生打印。读者可以选择另存为 PDF；该方法不返回 PDF 字节。未就绪或卸载后拒绝。
`exportEpub(options)`	`Promise<Blob>`	把当前提交导出为可重排 EPUB；未就绪或卸载后拒绝。

`ImposiaPublicationViewer`

app/guide-preview.tsx

const publication = useRef<ImposiaPublicationViewerHandle>(null);

<ImposiaPublicationViewer
  ref={publication}
  snapshot={{
    metadata: { title: "指南", language: "zh-CN" },
    entries: [{ id: "intro", title: "引言", html: "<h1>引言</h1>" }],
  }}
/>;

必需的 snapshot prop 接受 PublicationSnapshot。可选 props 为 snapshotRevision、publicationOptions、publicationOptionsRevision、viewerOptions（不含 reader）、readerOptions（不含 controller）、className、style、onReady、onError 和 onStateChange。各 revision prop 如其名称所示强制更新或重建。组件自己提供 reader 与控制器的绑定，这就是其选项 props 中排除 reader 和 controller 的原因。

`ImposiaPublicationViewerHandle`

除 current 和 resolveDestination 之外的所有操作在卸载后抛出。Reader 相关操作在 Publication Reader 就绪之前同样抛出。

成员	返回值	行为与约束
`current`	`PublicationDocument \| undefined`	挂载期间为当前提交。
`resolveDestination(id)`	`PublicationDestination \| undefined`	提交前、卸载后或 ID 未知时为 `undefined`。
`navigate(destination)`	`void`	过期的导航目标抛出。
`openTableOfContents()`、`closeTableOfContents()`、`toggleTableOfContents()`	`void`	控制大纲面板。
`openThumbnails()`、`closeThumbnails()`、`toggleThumbnails()`	`void`	控制缩略图面板。
`getThumbnails()`	`readonly PublicationThumbnail[]`	当前世代的缩略图。
`selectThumbnail(thumbnail)`	`void`	其他世代的缩略图抛出。
`restoreDeepLink(value)`	`PublicationDestination \| undefined`	解析并导航有效的当前链接。
`openSearch()`、`closeSearch()`、`toggleSearch()`	`void`	控制搜索面板。
`search(query)`	`readonly PublicationSearchResult[]`	搜索当前提交。
`nextSearchResult()`、`previousSearchResult()`	`PublicationSearchResult \| undefined`	在结果间移动。
`selectSearchResult(result)`	`void`	导航到结果。
`setMode(mode)`、`setSpreadCover(cover)`	`void`	控制页面展示。
`openInspector()`、`closeInspector()`、`toggleInspector()`	`void`	需要 `viewerOptions.inspector: true`。
`selectWarning(warning)`	`void`	需要来自当前世代的 Inspector 警告。
`print()`	`Promise<void>`	为最新提交打开原生打印，其中含浏览器的另存为 PDF 选项。未就绪或卸载后拒绝。
`exportEpub(options)`	`Promise<Blob>`	导出最新提交；未就绪或卸载后拒绝。

`useImposiaDocument` 与 `useImposiaPublication`

useImposiaDocument(props: UseImposiaDocumentProps): UseImposiaDocumentResult;
useImposiaPublication(props: UseImposiaPublicationProps): UseImposiaPublicationResult;

两个 Hook 都返回 hostRef、生命周期 state，以及一个在挂载 effect 创建之前为 undefined 的控制器。把 hostRef 挂到一个 div 上。loading 或 error 状态可以保留最后一次提交的文档或 Publication。

useImposiaDocument 接受页面组件的 source、revision、选项和回调。HTML 源在 HTML 或基准 URL 变化时更新；light DOM 源在节点身份变化时更新。sourceRevision 强制更新，documentOptionsRevision 重建控制器。

useImposiaPublication 接受出版组件的 snapshot、revision、选项和回调。它在快照引用或 snapshotRevision 变化时更新；publicationOptionsRevision 重建控制器。两个 Hook 都会在清理时销毁控制器，并把 AbortError 视为生命周期取消。

app/article.tsx

function Article({ html }: { html: string }) {
  const { hostRef, state } = useImposiaDocument({ source: { html } });
  return <div ref={hostRef} aria-busy={state.status === "loading"} />;
}

ImposiaPageViewer 与 ImposiaDocument

ImposiaPageViewerHandle

ImposiaPublicationViewer

ImposiaPublicationViewerHandle

useImposiaDocument 与 useImposiaPublication

On this page

`ImposiaPageViewer` 与 `ImposiaDocument`

`ImposiaPageViewerHandle`

`ImposiaPublicationViewer`

`ImposiaPublicationViewerHandle`

`useImposiaDocument` 与 `useImposiaPublication`