API リファレンス

React、Core、Viewer から必要な契約を選び、共通のパッケージ構成とライフサイクル指針を確認します。

最初の文書を表示した後に使うリファレンスです。パッケージ別のページで、正確なコンポーネント、コントローラー、オプション、ライフサイクル上の制約を確認してください。

パッケージ構成

パッケージ	役割	主要 API
`@imposia/react`	React 統合	`ImposiaPageViewer`、`ImposiaDocument`、`ImposiaPublicationViewer`、2 つのライフサイクル Hook
`@imposia/core`	フレームワーク非依存のページ分割と Publication	`mountPageDocument`、`mountPublication`、`prepareDocument`
`@imposia/viewer`	確定済みページの表示	`mountPageViewer`、ディープリンクヘルパー
`@imposia/client`	フレームワーク非依存の統合エントリーポイント	Core と Viewer の主要統合 API を再エクスポート

React パッケージを使う場合は、@imposia/react/styles.css を一度だけ読み込んでください。

API を選ぶ

React API

React アプリケーション向けのコンポーネント、Hook、命令型ハンドル。

Core API

フレームワーク非依存のページ文書と Publication のコントローラー。

Viewer API

ページ表示、Reader、Inspector。

ライフサイクルとエラー

状況	結果
最初の世代が処理中	`current` は `undefined`、React の状態は `loading` です。
確定後の更新が処理中	前回の確定が表示にも React の状態にも残ります。
より新しい更新が始まった	進行中だった古い世代は `AbortError` で reject されます。
呼び出し側が中止した	対応する世代・書き出しが DOM の `AbortError` で reject されます。
確定後の更新が失敗した	Promise が reject され、前回の確定が現在値のまま残ります。
コントローラーを破棄した	処理は中止され、リソースとフレームが解放され、`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 のメソッドは、現在の状態で実行できない呼び出しをおおむね無視します。所有権に関わる呼び出しは例外をスローします。ページ Viewer の mount と refresh は canonical iframe を検証し、Publication のナビゲーションは古い移動先を、Reader の選択は別の世代のサムネイルを、Inspector の選択は別の世代の警告を拒否します。