@embedpdf-editor/react-chapter-viewer 0.2.0 → 0.2.2

package/README.md

@@ -1,92 +1,408 @@
 # @embedpdf-editor/react-chapter-viewer
 
-章节 PDF 阅读器 React 统一入口：划线、笔记、书签、选区浮窗、可选缩放。
+面向 React 的**章节 PDF 阅读器**统一入口：多章 PDF 纵向拼接滚动、划词高亮/划线、段落书签、选区笔记，以及可选缩放。
+
+业务侧只需安装本包与 `react` / `react-dom`；PDFium（`@embedpdf/engines`）、`scheduler` 及阅读器依赖的 `@embedpdf/*` 插件由本包 **dependencies** 带入，**不必**在业务 `package.json` 里逐个声明 `@embedpdf/engines` 等。
+
+> 组件样式以 **inline style** 为主，**不需要** Tailwind。  
+> 下文提供可直接复制到业务项目中的完整示例（不依赖仓库内 demo 工程）。
+
+---
 
 ## 安装
 
 ```bash
-pnpm add @embedpdf-editor/react-chapter-viewer react react-dom
+pnpm add @embedpdf-editor/react-chapter-viewer
+# 或 npm / yarn
 ```
 
-`@embedpdf/engines`（PDFium WASM）、`scheduler`、`@embedpdf/*` 插件与 editor 能力由本包作为依赖一并安装，无需在业务项目里逐个声明。
+| 依赖 | 说明 |
+|------|------|
+| `react` `react-dom` | **peerDependencies**（建议 React 18+） |
+| 本包 `dependencies` | 已包含 `@embedpdf/engines`、`scheduler`、章节插件与 `editor-engine` |
 
-**样式**：组件使用 inline style，**不需要**在业务项目安装或配置 Tailwind CSS。
+---
 
-目录与 PDF 均由业务提供：`ChapterManifest` 中每章的 `source.url` 写 PDF 地址；若需统一鉴权下载，可实现 `IChapterPdfLoader` 并传入 `chapterPdfLoader`（或单章 `source.load`）。
+## Vite 项目（推荐）
 
-### Vite
+若 dev 时出现 `scheduler` 解析失败，可合并本包提供的 Vite 片段（将 `scheduler` 指到本包依赖目录并加入预构建）：
 
 ```ts
+// vite.config.ts
 import { defineConfig, mergeConfig } from 'vite';
+import react from '@vitejs/plugin-react';
 import { chapterViewerViteResolve } from '@embedpdf-editor/react-chapter-viewer/vite';
 
-export default mergeConfig(defineConfig({ /* ... */ }), chapterViewerViteResolve());
+export default mergeConfig(
+  defineConfig({
+    plugins: [react()],
+  }),
+  chapterViewerViteResolve(),
+);
 ```
 
-## 快速开始
+---
+
+## 你需要准备的数据
+
+阅读器**不内置**目录与 PDF 文件，全部由业务提供。
+
+### 1. `ChapterManifest`（引擎用）
+
+描述每一章对应的 PDF 与在「整本」中的页码区间：
+
+```ts
+import type { ChapterManifest } from '@embedpdf-editor/react-chapter-viewer';
+
+const manifest: ChapterManifest = {
+  chapters: [
+    {
+      chapterId: '001_封面',           // 唯一 ID，同时作为 documentId
+      title: '封面',
+      globalPageRange: [1, 1],       // 在整本中的全局页（闭区间）
+      localPageRange: [0, 0],          // 该 PDF 内 0-based 页（页数须与 global 一致）
+      source: { url: '/001_封面.pdf' }, // 或 buffer / load()
+    },
+    {
+      chapterId: '002_前言',
+      title: '前言',
+      globalPageRange: [2, 5],
+      localPageRange: [0, 3],
+      source: { url: '/002_前言.pdf' },
+    },
+  ],
+};
+```
+
+**`ChapterSource` 三种写法：**
+
+| 写法 | 场景 |
+|------|------|
+| `{ url: string }` | 静态或可直链的 PDF |
+| `{ buffer: ArrayBuffer }` | 已下载的二进制 |
+| `{ load: () => Promise<{ url } \| { buffer }> }` | 单章自定义拉取（鉴权等） |
+
+若 manifest 里**未写** `source`，需传入全局加载器 `chapterPdfLoader`（实现 `IChapterPdfLoader.loadPdf(chapter)`）。
+
+相邻章节的 `globalPageRange` **允许重叠**（例如上下章各含一页过渡页）；默认按 `first-wins` 解析归属。
+
+### 2. `ChapterViewerCatalog`（带目录树时）
+
+左侧章节目录由业务构造，与 manifest 对应：
+
+```ts
+import type { ChapterViewerCatalog } from '@embedpdf-editor/react-chapter-viewer';
+
+const catalog: ChapterViewerCatalog = {
+  tree: [
+    { id: '001_封面', title: '封面', startPage: 1, endPage: 1 },
+    {
+      id: '002_前言',
+      title: '前言',
+      startPage: 2,
+      endPage: 5,
+      children: [/* 可选子节点 */],
+    },
+  ],
+  manifest,
+};
+```
+
+`tree` 仅用于 UI；真正加载 PDF 以 `manifest.chapters` 为准。
+
+---
+
+## 快速开始：`<ChapterPdfViewer />`
+
+适合「单容器铺满、manifest 已就绪」的页面。推荐只传 **`options`**（不必再拆 `editorOptions` + `features`，也不必包一层 `callbacks`）。
 
 ```tsx
 import {
   usePdfiumEngine,
   ChapterPdfViewer,
-  type ChapterViewerFeaturesConfig,
+  type ChapterManifest,
 } from '@embedpdf-editor/react-chapter-viewer';
 
-const features: ChapterViewerFeaturesConfig = {
-  markup: {
-    enabled: true,
-    styles: {
-      underline: { color: '#dc2626', offsetY: 3, thickness: 1.5 },
-    },
-  },
-  zoom: { enabled: false },
-  selectionToolbar: {
-    extraActions: [{ id: 'translate', label: '翻译', order: 10 }],
-  },
-};
+export function Reader({ manifest }: { manifest: ChapterManifest }) {
+  const { engine, isLoading, error } = usePdfiumEngine();
 
-export function App({ manifest, tree }) {
-  const { engine } = usePdfiumEngine();
-  if (!engine) return null;
+  if (error) return <div>引擎失败：{error.message}</div>;
+  if (isLoading || !engine) return <div>正在加载 PDFium…</div>;
 
   return (
-    <ChapterPdfViewer
-      engine={engine}
-      editorOptions={{
-        // manifest.chapters[].source.url 由业务提供 PDF 地址
-        manifest,
-        notes: {
-          callbacks: {
+    <div style={{ height: '100vh' }}>
+      <ChapterPdfViewer
+        engine={engine}
+        options={{
+          manifest,
+          bookmarks: {
+            load: () => fetchBookmarks(),
+            persist: (list) => saveBookmarks(list),
+            onRequestRemove: async (b) => {
+              await api.deleteBookmark(b.id);
+              return true;
+            },
+          },
+          notes: {
+            loadNotes: () => fetchNotes(),
             onRequestCreateNote: ({ draft, complete }) => {
-              openYourModal(draft).then((id) => complete(id));
+              openCreateModal(draft).then((noteId) => complete(noteId));
             },
-            onRequestEditNote: (noteId) => openYourEditor(noteId),
-            loadNotes: () => api.loadNotes(),
+            onRequestEditNote: (noteId) => openEditModal(noteId),
             onDeleteNote: (id) => api.deleteNote(id),
           },
-        },
-        bookmarks: { callbacks: { load: () => api.loadBookmarks(), persist: api.save } },
-      }}
-      features={features}
-      onExtraSelectionAction={(id) => {
-        if (id === 'translate') { /* ... */ }
-      }}
-    />
+          features: {
+            zoom: { pageWidth: 800 },
+          },
+        }}
+      />
+    </div>
   );
 }
 ```
 
-## Vue3 / Vue2
+### `features` 简写
 
-- `@embedpdf-editor/vue3-chapter-viewer`
-- `@embedpdf-editor/vue2-chapter-viewer`
+| 写法 | 含义 |
+|------|------|
+| 省略 | 划线、书签、笔记、选区浮窗、缩放 **全部开启** |
+| `markup: false` | 关闭划词高亮/划线 |
+| `zoom: false` | 关闭缩放 |
+| `zoom: { pageWidth: 800 }` | 按宽度适配 |
 
-视口内核仍是 React 实现的 `ChapterPdfViewer`，Vue 组件只在 DOM 节点上通过 `react-dom/client` 挂载，因此 **还需安装 `react`、`react-dom`**，且全应用只能有一份 React（勿重复打包进阅读器 dist）。
+**交互说明（默认开启时）：**
 
-```bash
-pnpm add @embedpdf-editor/vue3-chapter-viewer vue react react-dom
+- 划词 → 浮窗：高亮、下划线、波浪线、删除线、笔记
+- 鼠标移到文本行末 → 显示「添加书签」；已加书签点击 → 删除确认（走 `onRequestRemove`）
+- 笔记区域悬停 → 编辑 / 删除
+- **缩放**：`features.zoom.enabled !== false` 时，在 PDF 滚动区域内 **`Ctrl/Cmd + 滚轮`** 或 **双指捏合**（触控板）缩放；缩放写入 core 的 `document.scale`，PDF 与书签/笔记 overlay 同步变化（不是只放大外层 div）
+
+> 普通滚轮用于上下滚动章节，不会触发缩放；Mac 触控板请按住 Ctrl 或双指捏合。
+
+---
+
+## 进阶：自定义布局（目录 + 首章预加载）
+
+需要**左侧章节目录**、或要在挂载视口前**先 `ensureChapterLoaded`** 时，不要用一站式 `<ChapterPdfViewer />`，改用：
+
+`createChapterViewerBundle` → `EmbedPDF` → `ChapterTreePanel` + `PdfChapterViewport`
+
+**步骤简述：**
+
+1. 用 `createChapterViewerBundle(options)` 得到 `{ plugins, features }`（`options` 字段与上一节 `ChapterPdfViewer` 的 `options` 相同）。
+2. 用 `EmbedPDF` 挂载 `plugins`，在 `pluginsReady` 后再渲染子树。
+3. 在 `EmbedPDF` 子树内用 `useCapability(ChapterManagerPlugin.id)` 对**首章**（或当前章）调用 `ensureChapterLoaded`。
+4. 章节状态为 `loaded` 后再挂载 `PdfChapterViewport`，并传入 **`bundle.features`**（不要另写一套 `features`）。
+
+**完整示例（可复制）：**
+
+```tsx
+import { useEffect, useMemo, useState } from 'react';
+import {
+  usePdfiumEngine,
+  EmbedPDF,
+  useCapability,
+  ChapterManagerPlugin,
+  createChapterViewerBundle,
+  ChapterTreePanel,
+  PdfChapterViewport,
+  type ChapterViewerCatalog,
+  type ChapterViewerOptions,
+} from '@embedpdf-editor/react-chapter-viewer';
+
+type ReaderProps = {
+  catalog: ChapterViewerCatalog;
+  notes: ChapterViewerOptions['notes'];
+  bookmarks: ChapterViewerOptions['bookmarks'];
+};
+
+export function ChapterReaderWithSidebar({ catalog, notes, bookmarks }: ReaderProps) {
+  const { engine, isLoading, error } = usePdfiumEngine();
+  const bundle = useMemo(
+    () =>
+      createChapterViewerBundle({
+        manifest: catalog.manifest,
+        notes,
+        bookmarks,
+        features: { zoom: { pageWidth: 800 } },
+      }),
+    [catalog.manifest, notes, bookmarks],
+  );
+  const firstChapterId = catalog.manifest.chapters[0]?.chapterId ?? '';
+
+  if (error) return <div>引擎失败：{error.message}</div>;
+  if (isLoading || !engine) return <div>正在加载 PDFium…</div>;
+
+  return (
+    <div style={{ height: '100vh', display: 'flex', flexDirection: 'column' }}>
+      <EmbedPDF engine={engine} plugins={bundle.plugins}>
+        {({ pluginsReady }) =>
+          pluginsReady ? (
+            <ChapterWorkspace
+              tree={catalog.tree}
+              firstChapterId={firstChapterId}
+              features={bundle.features}
+            />
+          ) : (
+            <div>正在初始化插件…</div>
+          )
+        }
+      </EmbedPDF>
+    </div>
+  );
+}
+
+function ChapterWorkspace({
+  tree,
+  firstChapterId,
+  features,
+}: {
+  tree: ChapterViewerCatalog['tree'];
+  firstChapterId: string;
+  features: ReturnType<typeof createChapterViewerBundle>['features'];
+}) {
+  const [activeChapterId, setActiveChapterId] = useState(firstChapterId);
+  const [chapterReady, setChapterReady] = useState(false);
+  const { provides: chapterManager } = useCapability<ChapterManagerPlugin>(
+    ChapterManagerPlugin.id,
+  );
+
+  useEffect(() => {
+    if (!chapterManager || !firstChapterId) return;
+
+    let cancelled = false;
+    setChapterReady(false);
+
+    const unsub = chapterManager.onChapterStatusChange(() => {
+      if (cancelled) return;
+      if (chapterManager.getChapterStatus(firstChapterId) === 'loaded') {
+        setChapterReady(true);
+      }
+    });
+
+    void chapterManager.ensureChapterLoaded(firstChapterId).then((status) => {
+      if (!cancelled && status === 'loaded') setChapterReady(true);
+    });
+
+    return () => {
+      cancelled = true;
+      unsub();
+    };
+  }, [chapterManager, firstChapterId]);
+
+  return (
+    <div style={{ display: 'flex', flex: 1, minHeight: 0, gap: 12 }}>
+      <ChapterTreePanel
+        tree={tree}
+        activeChapterId={activeChapterId}
+        onActiveChapterChange={setActiveChapterId}
+      />
+      <div style={{ flex: 1, minWidth: 0, minHeight: 0, position: 'relative' }}>
+        {chapterReady ? (
+          <div style={{ position: 'absolute', inset: 0 }}>
+            <PdfChapterViewport features={features} />
+          </div>
+        ) : (
+          <div>正在加载章节 PDF…</div>
+        )}
+      </div>
+    </div>
+  );
+}
 ```
 
-Vite 使用 `@embedpdf-editor/vue3-chapter-viewer/vite` 导出同样的 `chapterViewerViteResolve()`。
+切换目录项时，可对新的 `activeChapterId` 同样调用 `ensureChapterLoaded`，再在 `loaded` 后更新视口（`ChapterTreePanel` 内部也会触发章节加载，按产品需求二选一或组合使用即可）。
+
+---
+
+## 笔记与书签回调
+
+直接写在 `options.notes` / `options.bookmarks`（不再嵌套 `callbacks`）。
+
+### 笔记 `options.notes`
+
+| 回调 | 说明 |
+|------|------|
+| `loadNotes` | 初始化加载已有笔记 |
+| `onRequestCreateNote` | **推荐**：宿主弹窗后 `complete(noteId)` |
+| `onCreateNote` | 内置创建（与上一项二选一） |
+| `onRequestEditNote` / `onUpdateNote` / `onDeleteNote` | 编辑、更新、删除 |
+
+### 书签 `options.bookmarks`
+
+| 回调 | 说明 |
+|------|------|
+| `load` | 加载已有书签 |
+| `persist` | 增删改后持久化 |
+| `onRequestRemove` | 删除确认，返回 `true` 后从渲染层移除 |
+
+---
+
+## 内部默认（无需配置）
+
+以下由引擎内置，业务**不用**再写：`overlapStrategy`、`passwordProvider`、`prefetchChapters`、`loadDefaultStampLibrary`、`toolbar`（Annotate 模式栏已关闭）、`placeholderPageWidth` 等。需要改时再使用进阶 API `createPdfChapterEditor`。
+
+---
+
+## 主要导出
+
+| 导出 | 用途 |
+|------|------|
+| `ChapterPdfViewer` | 一站式阅读器（传 `options`） |
+| `createChapterViewerBundle` | 生成 `{ plugins, features }`（自定义布局） |
+| `PdfChapterViewport` | 仅视口（需在 `EmbedPDF` 内） |
+| `ChapterTreePanel` | 章节目录树 |
+| `usePdfiumEngine` | PDFium 引擎 |
+| `ChapterViewerOptions` | `options` 的类型 |
+| `ChapterViewerConfig` | `options.features` 的类型 |
+| `ChapterManifest` / `ChapterDescriptor` / `IChapterPdfLoader` | 数据与加载契约 |
+| `ChapterViewerCatalog` / `ChapterTreeNode` | 目录树类型 |
+| `applySelectionMarkup` | 编程式应用划线（高级） |
+| `chapterViewerViteResolve` | Vite 配置辅助（`/vite` 子路径） |
+
+类型详见 `dist/index.d.ts`。
+
+---
+
+## 接入检查清单
+
+在业务项目中接入时，请确认：
+
+1. **静态资源**：`manifest` 里每章 `source.url` 可被浏览器访问（或实现 `chapterPdfLoader` / `load()`）。
+2. **目录数据**：若使用 `ChapterTreePanel`，自行从后端组装 `ChapterViewerCatalog`（`tree` + `manifest` 字段一致）。
+3. **首章加载**：自定义布局下，首章 `ensureChapterLoaded` 返回 `loaded` 后再挂载 `PdfChapterViewport`。
+4. **笔记 UI**：`onRequestCreateNote` 需在宿主弹窗后调用 `complete(noteId)`。
+
+本包随 npm 发布，**不包含**可运行的示例站点或 mock 数据；请以上文代码片段为模板，在业务仓库中创建页面并放置自有 PDF。
+
+---
+
+## 其他框架
+
+| 包 | 说明 |
+|----|------|
+| `@embedpdf-editor/vue3-chapter-viewer` | Vue 3 组件封装 |
+| `@embedpdf-editor/vue2-chapter-viewer` | Vue 2.6+（或 `@embedpdf-editor/chapter-snippet` Web Component） |
+
+Vue 3 包同样只需安装对应包 + `vue`；视口内核与 React 版能力对齐。
+
+---
+
+## 常见问题
+
+**Q：页面一直「正在加载」？**  
+确认 `manifest` 中每章 `source.url` 可访问，或 `chapterPdfLoader` / `ensureChapterLoaded` 返回 `loaded`。首章未加载完成时不要提前挂载 `PdfChapterViewport`。
+
+**Q：需要用户安装 `@embedpdf/engines` 吗？**  
+不需要，已作为本包依赖。只需 `react` / `react-dom`。
+
+**Q：如何关闭缩放？**  
+`features={{ ...DEFAULT_CHAPTER_VIEWER_FEATURES, zoom: { enabled: false } }}`。
+
+**Q：`zoom.enabled: true` 但缩放手势没反应？**  
+1. 确认使用 `<ChapterPdfViewer />` 或 `<PdfChapterViewport features={...} />`（缩放逻辑在 `PdfChapterViewport` 内）。  
+2. 在 PDF 区域使用 **Ctrl/Cmd + 滚轮**，不要用普通滚轮。  
+3. 重新构建 `@embedpdf-editor/editor-engine` 与 `@embedpdf-editor/react-chapter-viewer` 后硬刷新浏览器。
 
-使用 `<ChapterPdfViewer :viewer-props="..." />`。
+**Q：笔记弹窗想完全自定义？**  
+使用 `onRequestCreateNote` + `complete(noteId)`，不要实现 `onCreateNote`。