@embedpdf-editor/react-chapter-viewer 0.1.0 → 0.2.1

package/README.md

@@ -1,90 +1,395 @@
 # @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。  
+> 完整可运行示例见 monorepo：`examples/chapter-viewer-demo-react`。
+
+---
 
 ## 安装
 
 ```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` |
+
+---
 
-目录与 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 已就绪」的页面。
 
 ```tsx
 import {
   usePdfiumEngine,
   ChapterPdfViewer,
-  type ChapterViewerFeaturesConfig,
+  createChapterViewerEditorOptions,
+  DEFAULT_CHAPTER_VIEWER_FEATURES,
+} from '@embedpdf-editor/react-chapter-viewer';
+
+export function Reader({ manifest }: { manifest: ChapterManifest }) {
+  const { engine, isLoading, error } = usePdfiumEngine();
+
+  if (error) return <div>引擎失败：{error.message}</div>;
+  if (isLoading || !engine) return <div>正在加载 PDFium…</div>;
+
+  const editorOptions = createChapterViewerEditorOptions({
+    manifest,
+    bookmarks: {
+      callbacks: {
+        load: () => fetchBookmarks(),
+        persist: (list) => saveBookmarks(list),
+        onRequestRemove: async (b) => {
+          await api.deleteBookmark(b.id);
+          return true;
+        },
+      },
+    },
+    notes: {
+      callbacks: {
+        loadNotes: () => fetchNotes(),
+        onRequestCreateNote: ({ draft, complete }) => {
+          // 打开你的弹窗，用户确认后：
+          openCreateModal(draft).then((noteId) => complete(noteId));
+        },
+        onRequestEditNote: (noteId) => openEditModal(noteId),
+        onDeleteNote: (id) => api.deleteNote(id),
+      },
+    },
+  });
+
+  return (
+    <div style={{ height: '100vh' }}>
+      <ChapterPdfViewer
+        engine={engine}
+        editorOptions={editorOptions}
+        features={{
+          ...DEFAULT_CHAPTER_VIEWER_FEATURES,
+          zoom: { enabled: true, pageWidth: 800 },
+        }}
+        onExtraSelectionAction={(actionId) => {
+          if (actionId === 'translate') {
+            /* 选区浮窗扩展按钮 */
+          }
+        }}
+      />
+    </div>
+  );
+}
+```
+
+**交互说明（默认开启时）：**
+
+- 划词 → 浮窗：高亮、下划线、波浪线、删除线、笔记
+- 鼠标移到文本行末 → 显示「添加书签」；已加书签点击 → 删除确认（走 `onRequestRemove`）
+- 笔记区域悬停 → 编辑 / 删除
+- `Ctrl/Cmd + 滚轮`、双指捏合 → 缩放（写入文档 `scale`，非单纯 CSS 放大）
+
+---
+
+## 进阶：自定义布局（目录 + 首章预加载）
+
+官方 React Demo 使用 **`EmbedPDF` + `PdfChapterViewport` + `ChapterTreePanel`**，便于：
+
+- 左侧树切换章节（`ChapterManagerPlugin.ensureChapterLoaded`）
+- 首章加载完成后再挂载视口，避免空白
+
+核心步骤：
+
+```tsx
+import {
+  usePdfiumEngine,
+  EmbedPDF,
+  useCapability,
+  ChapterManagerPlugin,
+  ChapterTreePanel,
+  PdfChapterViewport,
+  createChapterViewerEditor,
+  createChapterViewerEditorOptions,
+  DEFAULT_CHAPTER_VIEWER_FEATURES,
 } from '@embedpdf-editor/react-chapter-viewer';
 
+function App({ catalog }: { catalog: ChapterViewerCatalog }) {
+  const { engine } = usePdfiumEngine();
+  const editorOptions = useMemo(
+    () => createChapterViewerEditorOptions({ manifest: catalog.manifest, /* bookmarks, notes */ }),
+    [catalog],
+  );
+  const plugins = useMemo(
+    () =>
+      createChapterViewerEditor({
+        ...editorOptions,
+        features: DEFAULT_CHAPTER_VIEWER_FEATURES,
+      }).plugins,
+    [editorOptions],
+  );
+
+  if (!engine) return null;
+
+  return (
+    <EmbedPDF engine={engine} plugins={plugins}>
+      {({ pluginsReady }) =>
+        pluginsReady ? (
+          <Layout catalog={catalog} />
+        ) : (
+          <div>正在初始化插件…</div>
+        )
+      }
+    </EmbedPDF>
+  );
+}
+
+function Layout({ catalog }: { catalog: ChapterViewerCatalog }) {
+  const [activeId, setActiveId] = useState(catalog.manifest.chapters[0]?.chapterId ?? '');
+  const { provides: chapterManager } = useCapability(ChapterManagerPlugin.id);
+  const [ready, setReady] = useState(false);
+
+  useEffect(() => {
+    if (!chapterManager || !activeId) return;
+    void chapterManager.ensureChapterLoaded(activeId).then((s) => setReady(s === 'loaded'));
+  }, [chapterManager, activeId]);
+
+  return (
+    <div style={{ display: 'flex', height: '100%' }}>
+      <ChapterTreePanel
+        tree={catalog.tree}
+        activeChapterId={activeId}
+        onActiveChapterChange={setActiveId}
+      />
+      <div style={{ flex: 1, minWidth: 0 }}>
+        {ready ? (
+          <PdfChapterViewport features={DEFAULT_CHAPTER_VIEWER_FEATURES} />
+        ) : (
+          <div>正在加载章节 PDF…</div>
+        )}
+      </div>
+    </div>
+  );
+}
+```
+
+参考实现：`examples/chapter-viewer-demo-react/src/App.tsx`。
+
+---
+
+## 笔记与书签回调
+
+### 笔记 `editorOptions.notes.callbacks`
+
+| 回调 | 说明 |
+|------|------|
+| `loadNotes` | 初始化加载已有笔记 |
+| `onRequestCreateNote` | **推荐**：只发事件，宿主弹窗后 `complete(noteId)` |
+| `onCreateNote` | 内置流程：直接 `Promise<{ noteId }>`（与上一项二选一） |
+| `onRequestEditNote` | 自定义编辑，传出 `noteId` |
+| `onUpdateNote` / `onDeleteNote` | 更新、删除 |
+
+### 书签 `editorOptions.bookmarks.callbacks`
+
+| 回调 | 说明 |
+|------|------|
+| `load` | 加载已有书签 |
+| `persist` | 增删改后持久化整表 |
+| `onRequestRemove` | 用户点删除 → 业务删库 → 返回 `true` 后渲染器移除 |
+| `onRemoveSuccess` | 移除后的收尾通知 |
+
+---
+
+## 功能配置 `features`
+
+通过 `ChapterPdfViewer` 的 `features`，或 `createChapterViewerEditor({ features })` 传入。默认见 `DEFAULT_CHAPTER_VIEWER_FEATURES`。
+
+```ts
+import type { ChapterViewerFeaturesConfig } from '@embedpdf-editor/react-chapter-viewer';
+
 const features: ChapterViewerFeaturesConfig = {
   markup: {
     enabled: true,
     styles: {
-      underline: { color: '#dc2626', offsetY: 3, thickness: 1.5 },
+      underline: { color: '#dc2626', thickness: 1.5, offsetY: 3 },
+      highlight: { color: '#facc15', opacity: 0.35 },
     },
   },
-  zoom: { enabled: false },
+  bookmarks: { enabled: true },
+  notes: { enabled: true },
   selectionToolbar: {
+    enabled: true,
+    hiddenBuiltinActions: ['squiggly'],
     extraActions: [{ id: 'translate', label: '翻译', order: 10 }],
   },
+  zoom: {
+    enabled: true,
+    min: 0.5,
+    max: 3,
+    initial: 1,
+    pageWidth: 800, // 按 CSS 宽度适配首页 PDF
+  },
 };
+```
 
-export function App({ manifest, tree }) {
-  const { engine } = usePdfiumEngine();
-  if (!engine) return null;
+`onExtraSelectionAction` / `buildSelectionMenu` 可处理 `extraActions` 或完全自定义选区菜单。
 
-  return (
-    <ChapterPdfViewer
-      engine={engine}
-      editorOptions={{
-        // manifest.chapters[].source.url 由业务提供 PDF 地址
-        manifest,
-        notes: {
-          callbacks: {
-            onRequestCreateNote: ({ draft, complete }) => {
-              openYourModal(draft).then((id) => complete(id));
-            },
-            onRequestEditNote: (noteId) => openYourEditor(noteId),
-            loadNotes: () => api.loadNotes(),
-            onDeleteNote: (id) => api.deleteNote(id),
-          },
-        },
-        bookmarks: { callbacks: { load: () => api.loadBookmarks(), persist: api.save } },
-      }}
-      features={features}
-      onExtraSelectionAction={(id) => {
-        if (id === 'translate') { /* ... */ }
-      }}
-    />
-  );
-}
-```
+---
+
+## 主要导出
+
+| 导出 | 用途 |
+|------|------|
+| `ChapterPdfViewer` | 一站式阅读器（引擎 + 插件 + 视口 + 缩放） |
+| `PdfChapterViewport` | 仅 PDF 滚动视口（需在 `EmbedPDF` 内） |
+| `ChapterTreePanel` | 章节目录树（需在 `EmbedPDF` 内） |
+| `usePdfiumEngine` | 创建 PDFium `engine` |
+| `EmbedPDF` / `useCapability` | 插件宿主与能力访问 |
+| `createChapterViewerEditorOptions` | 生成 `editorOptions`（manifest、书签、笔记） |
+| `createChapterViewerEditor` | 生成 `plugins` 数组 |
+| `DEFAULT_CHAPTER_VIEWER_FEATURES` | 默认功能开关 |
+| `ChapterManifest` / `ChapterDescriptor` / `IChapterPdfLoader` | 数据与加载契约 |
+| `ChapterViewerCatalog` / `ChapterTreeNode` | 目录树类型 |
+| `applySelectionMarkup` | 编程式应用划线（高级） |
+| `chapterViewerViteResolve` | Vite 配置辅助（`/vite` 子路径） |
 
-## Vue3 / Vue2
+类型详见 `dist/index.d.ts`。
 
-- `@embedpdf-editor/vue3-chapter-viewer`
-- `@embedpdf-editor/vue2-chapter-viewer`
+---
 
-视口内核仍是 React 实现的 `ChapterPdfViewer`，Vue 组件只在 DOM 节点上通过 `react-dom/client` 挂载，因此 **还需安装 `react`、`react-dom`**，且全应用只能有一份 React（勿重复打包进阅读器 dist）。
+## 本地运行官方 Demo
 
 ```bash
-pnpm add @embedpdf-editor/vue3-chapter-viewer vue react react-dom
+# 在 monorepo 根目录
+pnpm install
+pnpm --filter @embedpdf-editor/react-chapter-viewer build
+pnpm --filter @embedpdf-editor/example-chapter-viewer-react dev
 ```
 
-Vite 使用 `@embedpdf-editor/vue3-chapter-viewer/vite` 导出同样的 `chapterViewerViteResolve()`。
+将章节 PDF 与 `mock.json` 放在 demo 的 `public/` 下（`title` 字段对应 `/{title}.pdf`）。Demo 的 `loadDemoCatalog` 仅作示例，生产环境请自行请求后端并组装 `ChapterViewerCatalog`。
+
+构建静态站点：
+
+```bash
+pnpm --filter @embedpdf-editor/example-chapter-viewer-react build
+pnpm --filter @embedpdf-editor/example-chapter-viewer-react preview
+```
+
+---
+
+## 其他框架
+
+| 包 | 说明 |
+|----|------|
+| `@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 } }}`。
 
-使用 `<ChapterPdfViewer :viewer-props="..." />`。
+**Q：笔记弹窗想完全自定义？**  
+使用 `onRequestCreateNote` + `complete(noteId)`，不要实现 `onCreateNote`。