API 参考
API 参考
按需选择 React、Core 或 Viewer 契约，并了解共用的包与生命周期指引。
渲染出第一个文档之后再使用本参考。选择一个包页面，查看确切的组件、控制器、选项和生命周期约束。
包映射
| 包 | 用途 | 主要 API |
|---|---|---|
@imposia/react | React 集成 | ImposiaPageViewer、ImposiaDocument、ImposiaPublicationViewer 与两个生命周期 Hook |
@imposia/core | 框架无关的分页与出版 | 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 拒绝。 |
| 调用方中止 | 相关的世代或导出以 DOM AbortError 拒绝。 |
| 提交后更新失败 | Promise 拒绝；上一次提交仍是当前文档。 |
| 控制器销毁 | 工作中止，资源与框架释放，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 选择拒绝其他世代的警告。