React API

@imposia/react は、1 つの Core コントローラーと 1 つの canonical iframe を React のライフサイクルに結び付けます。Core と Viewer の API も再エクスポートするため、React アプリケーションでは通常、他の Imposia パッケージを import する必要はありません。@imposia/react/styles.css は一度だけ読み込んでください。

ImposiaPageViewer と ImposiaDocument

ImposiaPageViewer は Core のページ文書をマウントし、最初の確定後にページ Viewer を結び付けます。ImposiaDocument は同じ公開 props とハンドル型を持つ互換ラッパーです。ImposiaDocumentProps = ImposiaPageViewerProps、ImposiaDocumentHandle = ImposiaPageViewerHandle が成り立ちます。

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}
/>;

ImposiaPageViewerHandle

ハンドルのメソッドは、最後に確定した世代に作用します。Viewer または確定を必要とするメソッドは、最初の確定前とアンマウント後には例外をスローするか、Promise が reject されます。

ImposiaPublicationViewer

const publication = useRef<ImposiaPublicationViewerHandle>(null);

<ImposiaPublicationViewer
  ref={publication}
  snapshot={{
    metadata: { title: "ガイド", language: "ja" },
    entries: [{ id: "intro", title: "はじめに", html: "<h1>はじめに</h1>" }],
  }}
/>;

必須の prop は snapshot で、PublicationSnapshot を受け取ります。任意の props は snapshotRevision、publicationOptions、publicationOptionsRevision、viewerOptions（reader を除く）、readerOptions（controller を除く）、className、style、onReady、onError、onStateChange です。revision 系の props は、名前のとおり更新と再マウントを強制します。Reader とコントローラーの結び付けはコンポーネント自身が用意します。reader と controller がオプション props から除かれているのは、そのためです。

ImposiaPublicationViewerHandle

current と resolveDestination を除くすべての操作は、アンマウント後に例外をスローするか、Promise が reject されます。Reader に関わる操作と print()、exportEpub() は、Publication の Reader が準備できる前も同様です。

useImposiaDocument と useImposiaPublication

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

どちらの Hook も、hostRef、ライフサイクルの state、そしてマウントエフェクトが作るまで undefined のままの controller を返します。hostRef は 1 つの div に付けてください。loading や error の状態でも、最後に確定した文書・Publication は保持されることがあります。

useImposiaDocument は、ページコンポーネントと同じソース、revision、オプション、コールバックを受け取ります。HTML ソースは HTML または基準 URL が変わると更新され、light DOM ソースはノードの同一性が変わると更新されます。sourceRevision は更新を強制し、documentOptionsRevision はコントローラーを再マウントします。

useImposiaPublication は、Publication コンポーネントと同じスナップショット、revision、オプション、コールバックを受け取ります。スナップショットの参照または snapshotRevision が変わると更新し、publicationOptionsRevision はコントローラーを再マウントします。どちらの Hook もクリーンアップ時にコントローラーを破棄し、AbortError をライフサイクル上の中止として扱います。

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