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

package/README.md

@@ -5,7 +5,7 @@
 业务侧只需安装本包与 `react` / `react-dom`；PDFium（`@embedpdf/engines`）、`scheduler` 及阅读器依赖的 `@embedpdf/*` 插件由本包 **dependencies** 带入，**不必**在业务 `package.json` 里逐个声明 `@embedpdf/engines` 等。
 
 > 组件样式以 **inline style** 为主，**不需要** Tailwind。  
-> 完整可运行示例见 monorepo：`examples/chapter-viewer-demo-react`。
+> 下文提供可直接复制到业务项目中的完整示例（不依赖仓库内 demo 工程）。
 
 ---
 
@@ -114,14 +114,13 @@ const catalog: ChapterViewerCatalog = {
 
 ## 快速开始：`<ChapterPdfViewer />`
 
-适合「单容器铺满、manifest 已就绪」的页面。
+适合「单容器铺满、manifest 已就绪」的页面。推荐只传 **`options`**（不必再拆 `editorOptions` + `features`，也不必包一层 `callbacks`）。
 
 ```tsx
 import {
   usePdfiumEngine,
   ChapterPdfViewer,
-  createChapterViewerEditorOptions,
-  DEFAULT_CHAPTER_VIEWER_FEATURES,
+  type ChapterManifest,
 } from '@embedpdf-editor/react-chapter-viewer';
 
 export function Reader({ manifest }: { manifest: ChapterManifest }) {
@@ -130,44 +129,31 @@ export function Reader({ manifest }: { manifest: ChapterManifest }) {
   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') {
-            /* 选区浮窗扩展按钮 */
-          }
+        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 }) => {
+              openCreateModal(draft).then((noteId) => complete(noteId));
+            },
+            onRequestEditNote: (noteId) => openEditModal(noteId),
+            onDeleteNote: (id) => api.deleteNote(id),
+          },
+          features: {
+            zoom: { pageWidth: 800 },
+          },
         }}
       />
     </div>
@@ -175,87 +161,147 @@ export function Reader({ manifest }: { manifest: ChapterManifest }) {
 }
 ```
 
+### `features` 简写
+
+| 写法 | 含义 |
+|------|------|
+| 省略 | 划线、书签、笔记、选区浮窗、缩放 **全部开启** |
+| `markup: false` | 关闭划词高亮/划线 |
+| `zoom: false` | 关闭缩放 |
+| `zoom: { pageWidth: 800 }` | 按宽度适配 |
+
 **交互说明（默认开启时）：**
 
 - 划词 → 浮窗：高亮、下划线、波浪线、删除线、笔记
 - 鼠标移到文本行末 → 显示「添加书签」；已加书签点击 → 删除确认（走 `onRequestRemove`）
 - 笔记区域悬停 → 编辑 / 删除
-- `Ctrl/Cmd + 滚轮`、双指捏合 → 缩放（写入文档 `scale`，非单纯 CSS 放大）
+- **缩放**：`features.zoom.enabled !== false` 时，在 PDF 滚动区域内 **`Ctrl/Cmd + 滚轮`** 或 **双指捏合**（触控板）缩放；缩放写入 core 的 `document.scale`，PDF 与书签/笔记 overlay 同步变化（不是只放大外层 div）
+
+> 普通滚轮用于上下滚动章节，不会触发缩放；Mac 触控板请按住 Ctrl 或双指捏合。
 
 ---
 
 ## 进阶：自定义布局（目录 + 首章预加载）
 
-官方 React Demo 使用 **`EmbedPDF` + `PdfChapterViewport` + `ChapterTreePanel`**，便于：
+需要**左侧章节目录**、或要在挂载视口前**先 `ensureChapterLoaded`** 时，不要用一站式 `<ChapterPdfViewer />`，改用：
+
+`createChapterViewerBundle` → `EmbedPDF` → `ChapterTreePanel` + `PdfChapterViewport`
+
+**步骤简述：**
 
-- 左侧树切换章节（`ChapterManagerPlugin.ensureChapterLoaded`）
-- 首章加载完成后再挂载视口，避免空白
+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,
-  createChapterViewerEditor,
-  createChapterViewerEditorOptions,
-  DEFAULT_CHAPTER_VIEWER_FEATURES,
+  type ChapterViewerCatalog,
+  type ChapterViewerOptions,
 } 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(
+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(
     () =>
-      createChapterViewerEditor({
-        ...editorOptions,
-        features: DEFAULT_CHAPTER_VIEWER_FEATURES,
-      }).plugins,
-    [editorOptions],
+      createChapterViewerBundle({
+        manifest: catalog.manifest,
+        notes,
+        bookmarks,
+        features: { zoom: { pageWidth: 800 } },
+      }),
+    [catalog.manifest, notes, bookmarks],
   );
+  const firstChapterId = catalog.manifest.chapters[0]?.chapterId ?? '';
 
-  if (!engine) return null;
+  if (error) return <div>引擎失败：{error.message}</div>;
+  if (isLoading || !engine) return <div>正在加载 PDFium…</div>;
 
   return (
-    <EmbedPDF engine={engine} plugins={plugins}>
-      {({ pluginsReady }) =>
-        pluginsReady ? (
-          <Layout catalog={catalog} />
-        ) : (
-          <div>正在初始化插件…</div>
-        )
-      }
-    </EmbedPDF>
+    <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 Layout({ catalog }: { catalog: ChapterViewerCatalog }) {
-  const [activeId, setActiveId] = useState(catalog.manifest.chapters[0]?.chapterId ?? '');
-  const { provides: chapterManager } = useCapability(ChapterManagerPlugin.id);
-  const [ready, setReady] = useState(false);
+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 || !activeId) return;
-    void chapterManager.ensureChapterLoaded(activeId).then((s) => setReady(s === 'loaded'));
-  }, [chapterManager, activeId]);
+    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', height: '100%' }}>
+    <div style={{ display: 'flex', flex: 1, minHeight: 0, gap: 12 }}>
       <ChapterTreePanel
-        tree={catalog.tree}
-        activeChapterId={activeId}
-        onActiveChapterChange={setActiveId}
+        tree={tree}
+        activeChapterId={activeChapterId}
+        onActiveChapterChange={setActiveChapterId}
       />
-      <div style={{ flex: 1, minWidth: 0 }}>
-        {ready ? (
-          <PdfChapterViewport features={DEFAULT_CHAPTER_VIEWER_FEATURES} />
+      <div style={{ flex: 1, minWidth: 0, minHeight: 0, position: 'relative' }}>
+        {chapterReady ? (
+          <div style={{ position: 'absolute', inset: 0 }}>
+            <PdfChapterViewport features={features} />
+          </div>
         ) : (
           <div>正在加载章节 PDF…</div>
         )}
@@ -265,66 +311,36 @@ function Layout({ catalog }: { catalog: ChapterViewerCatalog }) {
 }
 ```
 
-参考实现：`examples/chapter-viewer-demo-react/src/App.tsx`。
+切换目录项时，可对新的 `activeChapterId` 同样调用 `ensureChapterLoaded`，再在 `loaded` 后更新视口（`ChapterTreePanel` 内部也会触发章节加载，按产品需求二选一或组合使用即可）。
 
 ---
 
 ## 笔记与书签回调
 
-### 笔记 `editorOptions.notes.callbacks`
+直接写在 `options.notes` / `options.bookmarks`（不再嵌套 `callbacks`）。
+
+### 笔记 `options.notes`
 
 | 回调 | 说明 |
 |------|------|
 | `loadNotes` | 初始化加载已有笔记 |
-| `onRequestCreateNote` | **推荐**：只发事件，宿主弹窗后 `complete(noteId)` |
-| `onCreateNote` | 内置流程：直接 `Promise<{ noteId }>`（与上一项二选一） |
-| `onRequestEditNote` | 自定义编辑，传出 `noteId` |
-| `onUpdateNote` / `onDeleteNote` | 更新、删除 |
+| `onRequestCreateNote` | **推荐**：宿主弹窗后 `complete(noteId)` |
+| `onCreateNote` | 内置创建（与上一项二选一） |
+| `onRequestEditNote` / `onUpdateNote` / `onDeleteNote` | 编辑、更新、删除 |
 
-### 书签 `editorOptions.bookmarks.callbacks`
+### 书签 `options.bookmarks`
 
 | 回调 | 说明 |
 |------|------|
 | `load` | 加载已有书签 |
-| `persist` | 增删改后持久化整表 |
-| `onRequestRemove` | 用户点删除 → 业务删库 → 返回 `true` 后渲染器移除 |
-| `onRemoveSuccess` | 移除后的收尾通知 |
+| `persist` | 增删改后持久化 |
+| `onRequestRemove` | 删除确认，返回 `true` 后从渲染层移除 |
 
 ---
 
-## 功能配置 `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', thickness: 1.5, offsetY: 3 },
-      highlight: { color: '#facc15', opacity: 0.35 },
-    },
-  },
-  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
-  },
-};
-```
-
-`onExtraSelectionAction` / `buildSelectionMenu` 可处理 `extraActions` 或完全自定义选区菜单。
+以下由引擎内置，业务**不用**再写：`overlapStrategy`、`passwordProvider`、`prefetchChapters`、`loadDefaultStampLibrary`、`toolbar`（Annotate 模式栏已关闭）、`placeholderPageWidth` 等。需要改时再使用进阶 API `createPdfChapterEditor`。
 
 ---
 
@@ -332,14 +348,13 @@ const features: ChapterViewerFeaturesConfig = {
 
 | 导出 | 用途 |
 |------|------|
-| `ChapterPdfViewer` | 一站式阅读器（引擎 + 插件 + 视口 + 缩放） |
-| `PdfChapterViewport` | 仅 PDF 滚动视口（需在 `EmbedPDF` 内） |
-| `ChapterTreePanel` | 章节目录树（需在 `EmbedPDF` 内） |
-| `usePdfiumEngine` | 创建 PDFium `engine` |
-| `EmbedPDF` / `useCapability` | 插件宿主与能力访问 |
-| `createChapterViewerEditorOptions` | 生成 `editorOptions`（manifest、书签、笔记） |
-| `createChapterViewerEditor` | 生成 `plugins` 数组 |
-| `DEFAULT_CHAPTER_VIEWER_FEATURES` | 默认功能开关 |
+| `ChapterPdfViewer` | 一站式阅读器（传 `options`） |
+| `createChapterViewerBundle` | 生成 `{ plugins, features }`（自定义布局） |
+| `PdfChapterViewport` | 仅视口（需在 `EmbedPDF` 内） |
+| `ChapterTreePanel` | 章节目录树 |
+| `usePdfiumEngine` | PDFium 引擎 |
+| `ChapterViewerOptions` | `options` 的类型 |
+| `ChapterViewerConfig` | `options.features` 的类型 |
 | `ChapterManifest` / `ChapterDescriptor` / `IChapterPdfLoader` | 数据与加载契约 |
 | `ChapterViewerCatalog` / `ChapterTreeNode` | 目录树类型 |
 | `applySelectionMarkup` | 编程式应用划线（高级） |
@@ -349,23 +364,16 @@ const features: ChapterViewerFeaturesConfig = {
 
 ---
 
-## 本地运行官方 Demo
+## 接入检查清单
 
-```bash
-# 在 monorepo 根目录
-pnpm install
-pnpm --filter @embedpdf-editor/react-chapter-viewer build
-pnpm --filter @embedpdf-editor/example-chapter-viewer-react dev
-```
+在业务项目中接入时，请确认：
 
-将章节 PDF 与 `mock.json` 放在 demo 的 `public/` 下（`title` 字段对应 `/{title}.pdf`）。Demo 的 `loadDemoCatalog` 仅作示例，生产环境请自行请求后端并组装 `ChapterViewerCatalog`。
+1. **静态资源**：`manifest` 里每章 `source.url` 可被浏览器访问（或实现 `chapterPdfLoader` / `load()`）。
+2. **目录数据**：若使用 `ChapterTreePanel`，自行从后端组装 `ChapterViewerCatalog`（`tree` + `manifest` 字段一致）。
+3. **首章加载**：自定义布局下，首章 `ensureChapterLoaded` 返回 `loaded` 后再挂载 `PdfChapterViewport`。
+4. **笔记 UI**：`onRequestCreateNote` 需在宿主弹窗后调用 `complete(noteId)`。
 
-构建静态站点：
-
-```bash
-pnpm --filter @embedpdf-editor/example-chapter-viewer-react build
-pnpm --filter @embedpdf-editor/example-chapter-viewer-react preview
-```
+本包随 npm 发布，**不包含**可运行的示例站点或 mock 数据；请以上文代码片段为模板，在业务仓库中创建页面并放置自有 PDF。
 
 ---
 
@@ -391,5 +399,10 @@ Vue 3 包同样只需安装对应包 + `vue`；视口内核与 React 版能力
 **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` 后硬刷新浏览器。
+
 **Q：笔记弹窗想完全自定义？**  
 使用 `onRequestCreateNote` + `complete(noteId)`，不要实现 `onCreateNote`。