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

package/README.md

@@ -0,0 +1,473 @@
+# @embedpdf-editor/vue3-chapter-viewer
+
+面向 Vue 3 的**章节 PDF 阅读器**统一入口：多章 PDF 纵向拼接滚动、划词高亮/划线、段落书签、选区笔记，以及可选缩放。
+
+业务侧只需安装本包与 `vue`；PDFium（`@embedpdf/engines`）、`scheduler` 及阅读器依赖的 `@embedpdf/*` 插件由本包 **dependencies** 带入，**不必**在业务 `package.json` 里逐个声明 `@embedpdf/engines` 等。
+
+> 组件样式以 **inline style** 为主，**不需要** Tailwind。  
+> 下文提供可直接复制到业务项目中的完整示例（不依赖仓库内 demo 工程）。
+
+---
+
+## 安装
+
+```bash
+pnpm add @embedpdf-editor/vue3-chapter-viewer
+# 或 npm / yarn
+```
+
+| 依赖 | 说明 |
+|------|------|
+| `vue` | **peerDependencies**（建议 Vue 3.3+） |
+| 本包 `dependencies` | 已包含 `@embedpdf/engines`、`scheduler`、章节插件与 `editor-engine` |
+
+在业务入口注册本包组件前，请确保已 `import { createApp } from 'vue'` 并正常挂载应用（与常规 Vue 3 项目一致）。
+
+---
+
+## Vite 项目（推荐）
+
+若 dev 时出现 `scheduler` 解析失败，可合并本包提供的 Vite 片段（将 `scheduler` 指到本包依赖目录并加入预构建）：
+
+```ts
+// vite.config.ts
+import { defineConfig, mergeConfig } from 'vite';
+import vue from '@vitejs/plugin-vue';
+import { chapterViewerViteResolve } from '@embedpdf-editor/vue3-chapter-viewer/vite';
+
+export default mergeConfig(
+  defineConfig({
+    plugins: [vue()],
+  }),
+  chapterViewerViteResolve(),
+);
+```
+
+---
+
+## 你需要准备的数据
+
+阅读器**不内置**目录与 PDF 文件，全部由业务提供。
+
+### 1. `ChapterManifest`（引擎用）
+
+描述每一章对应的 PDF 与在「整本」中的页码区间：
+
+```ts
+import type { ChapterManifest } from '@embedpdf-editor/vue3-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/vue3-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`）。
+
+`usePdfiumEngine()` 返回的是 **ref**，模板里会自动解包；在 `<script setup>` 中请使用 `engine.value`。
+
+```vue
+<script setup lang="ts">
+import { computed } from 'vue';
+import {
+  usePdfiumEngine,
+  ChapterPdfViewer,
+  type ChapterManifest,
+  type ChapterViewerOptions,
+} from '@embedpdf-editor/vue3-chapter-viewer';
+
+const props = defineProps<{ manifest: ChapterManifest }>();
+const { engine, isLoading, error } = usePdfiumEngine();
+
+const options = computed<ChapterViewerOptions>(() => ({
+  manifest: props.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 },
+  },
+}));
+</script>
+
+<template>
+  <div v-if="error" style="padding: 16px">引擎失败：{{ error.message }}</div>
+  <div v-else-if="isLoading || !engine" style="padding: 16px">正在加载 PDFium…</div>
+  <ChapterPdfViewer
+    v-else
+    :engine="engine"
+    :options="options"
+    style="height: 100vh; width: 100%"
+  />
+</template>
+```
+
+### 笔记弹窗（推荐 `onRequestCreateNote`）
+
+阅读器不会自带 Modal，需在宿主里监听 `onRequestCreateNote` / `onRequestEditNote`，弹窗确认后调用 `complete(noteId)` 或 `onUpdateNote`：
+
+```vue
+<script setup lang="ts">
+import { ref, shallowRef } from 'vue';
+import type { NoteDraft } from '@embedpdf-editor/vue3-chapter-viewer';
+
+const pendingCreate = shallowRef<{
+  draft: NoteDraft;
+  complete: (noteId: string) => void | Promise<void>;
+} | null>(null);
+
+function onRequestCreateNote(payload: {
+  draft: NoteDraft;
+  complete: (noteId: string) => void | Promise<void>;
+}) {
+  pendingCreate.value = payload;
+}
+
+async function confirmCreate(content: string) {
+  const pending = pendingCreate.value;
+  if (!pending) return;
+  const noteId = await api.createNote({ ...pending.draft, content });
+  await pending.complete(noteId);
+  pendingCreate.value = null;
+}
+</script>
+
+<template>
+  <!-- YourNoteModal：业务自有组件 -->
+  <YourNoteModal
+    :open="!!pendingCreate"
+    :quoted-text="pendingCreate?.draft.selectedText"
+    @confirm="confirmCreate"
+    @cancel="pendingCreate = null"
+  />
+</template>
+```
+
+将 `onRequestCreateNote` 传入上一节的 `options.notes` 即可。
+
+### `features` 简写
+
+| 写法 | 含义 |
+|------|------|
+| 省略 | 划线、书签、笔记、选区浮窗、缩放 **全部开启** |
+| `markup: false` | 关闭划词高亮/划线 |
+| `zoom: false` | 关闭缩放 |
+| `zoom: { pageWidth: 800 }` | 按宽度适配 |
+
+**交互说明（默认开启时）：**
+
+- 划词 → 浮窗：高亮、下划线、波浪线、删除线、笔记
+- 鼠标移到文本行末 → 显示「添加书签」；已加书签点击 → 删除确认（走 `onRequestRemove`）
+- 笔记区域悬停 → 编辑 / 删除
+- **缩放**：`features.zoom.enabled !== false` 时，在 PDF 滚动区域内 **`Ctrl/Cmd + 滚轮`** 或 **双指捏合**（触控板）缩放；缩放写入 core 的 `document.scale`，PDF 与书签/笔记 overlay 同步变化
+
+> 普通滚轮用于上下滚动章节，不会触发缩放；Mac 触控板请按住 Ctrl 或双指捏合。
+
+---
+
+## 进阶：自定义布局（目录 + 首章预加载）
+
+需要**左侧章节目录**、或要在挂载视口前**先 `ensureChapterLoaded`** 时，不要用一站式 `<ChapterPdfViewer />`，改用：
+
+`createChapterViewerBundle` → `EmbedPDF` → `ChapterTreePanel` + `PdfChapterViewport`
+
+**步骤简述：**
+
+1. 用 `createChapterViewerBundle(options)` 得到 `{ plugins, features }`（`options` 与上一节相同）。
+2. 用 `<EmbedPDF>` 挂载 `plugins`，在 scoped slot 里等 `pluginsReady === true` 再渲染子树。
+3. 在 `EmbedPDF` 子树内用 `useCapability(ChapterManagerPlugin.id)` 对首章调用 `ensureChapterLoaded`。
+4. 章节状态为 `loaded` 后再挂载 `<PdfChapterViewport :features="bundle.features" />`。
+
+**父页面（可复制）：**
+
+```vue
+<script setup lang="ts">
+import { computed } from 'vue';
+import {
+  usePdfiumEngine,
+  EmbedPDF,
+  createChapterViewerBundle,
+  type ChapterViewerCatalog,
+  type ChapterViewerOptions,
+} from '@embedpdf-editor/vue3-chapter-viewer';
+import ChapterWorkspace from './ChapterWorkspace.vue';
+
+const props = defineProps<{
+  catalog: ChapterViewerCatalog;
+  notes: ChapterViewerOptions['notes'];
+  bookmarks: ChapterViewerOptions['bookmarks'];
+}>();
+
+const { engine, isLoading, error } = usePdfiumEngine();
+
+const bundle = computed(() =>
+  createChapterViewerBundle({
+    manifest: props.catalog.manifest,
+    notes: props.notes,
+    bookmarks: props.bookmarks,
+    features: { zoom: { pageWidth: 800 } },
+  }),
+);
+
+const firstChapterId = computed(
+  () => props.catalog.manifest.chapters[0]?.chapterId ?? '',
+);
+</script>
+
+<template>
+  <div v-if="error">引擎失败：{{ error.message }}</div>
+  <div v-else-if="isLoading || !engine">正在加载 PDFium…</div>
+  <div v-else style="height: 100vh; display: flex; flex-direction: column">
+    <EmbedPDF :engine="engine" :plugins="bundle.plugins">
+      <template #default="{ pluginsReady }">
+        <ChapterWorkspace
+          v-if="pluginsReady"
+          :tree="catalog.tree"
+          :first-chapter-id="firstChapterId"
+          :features="bundle.features"
+        />
+        <div v-else>正在初始化插件…</div>
+      </template>
+    </EmbedPDF>
+  </div>
+</template>
+```
+
+**`ChapterWorkspace.vue`（须在 `EmbedPDF` 子树内）：**
+
+```vue
+<script setup lang="ts">
+import { ref, watch } from 'vue';
+import {
+  useCapability,
+  ChapterManagerPlugin,
+  ChapterTreePanel,
+  PdfChapterViewport,
+  type ChapterViewerFeaturesConfig,
+  type ChapterTreeNode,
+} from '@embedpdf-editor/vue3-chapter-viewer';
+
+const props = defineProps<{
+  tree: ChapterTreeNode[];
+  firstChapterId: string;
+  features: ChapterViewerFeaturesConfig;
+}>();
+
+const activeChapterId = ref(props.firstChapterId);
+const chapterReady = ref(false);
+
+const { provides: chapterManager } = useCapability<ChapterManagerPlugin>(
+  ChapterManagerPlugin.id,
+);
+
+watch(
+  [chapterManager, () => props.firstChapterId],
+  ([mgr, chapterId], _prev, onCleanup) => {
+    if (!mgr || !chapterId) return;
+
+    let cancelled = false;
+    chapterReady.value = false;
+
+    const unsub = mgr.onChapterStatusChange(() => {
+      if (cancelled) return;
+      if (mgr.getChapterStatus(chapterId) === 'loaded') chapterReady.value = true;
+    });
+
+    void mgr.ensureChapterLoaded(chapterId).then((status) => {
+      if (!cancelled && status === 'loaded') chapterReady.value = true;
+    });
+
+    onCleanup(() => {
+      cancelled = true;
+      unsub();
+    });
+  },
+  { immediate: true },
+);
+</script>
+
+<template>
+  <div style="display: flex; flex: 1; min-height: 0; gap: 12px">
+    <ChapterTreePanel
+      :tree="tree"
+      :active-chapter-id="activeChapterId"
+      @active-chapter-change="activeChapterId = $event"
+    />
+    <div style="flex: 1; min-width: 0; min-height: 0; position: relative">
+      <div v-if="chapterReady" style="position: absolute; inset: 0">
+        <PdfChapterViewport :features="features" />
+      </div>
+      <div v-else style="padding: 16px">正在加载章节 PDF…</div>
+    </div>
+  </div>
+</template>
+```
+
+切换目录项时，可对新的 `activeChapterId` 同样调用 `ensureChapterLoaded`（`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 模式栏已关闭）等。需要改时再使用进阶 API `createPdfChapterEditor`。
+
+---
+
+## 主要导出
+
+| 导出 | 用途 |
+|------|------|
+| `ChapterPdfViewer` | 一站式阅读器（传 `engine` + `options`） |
+| `createChapterViewerBundle` | 生成 `{ plugins, features }`（自定义布局） |
+| `PdfChapterViewport` | 仅视口（需在 `EmbedPDF` 内） |
+| `ChapterTreePanel` | 章节目录树 |
+| `EmbedPDF` / `useCapability` | 插件宿主与能力钩子 |
+| `usePdfiumEngine` | PDFium 引擎（返回 ref） |
+| `ChapterManagerPlugin` | 章节加载（`ensureChapterLoaded`） |
+| `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)`。
+5. **Vue ref**：`usePdfiumEngine()` 的 `engine` 在 script 中为 ref，传给 `ChapterPdfViewer` 时模板写 `:engine="engine"` 即可。
+
+本包随 npm 发布，**不包含**可运行的示例站点或 mock 数据；请以上文代码片段为模板，在业务仓库中创建页面并放置自有 PDF。
+
+---
+
+## 其他框架
+
+| 包 | 说明 |
+|----|------|
+| `@embedpdf-editor/react-chapter-viewer` | React 18+ |
+| `@embedpdf-editor/chapter-snippet` | Vue 2.6+ Web Component / 无构建集成 |
+
+能力与 React 版视口内核对齐；API 命名一致，仅组合方式随框架变化。
+
+---
+
+## 常见问题
+
+**Q：页面一直「正在加载」？**  
+确认 `manifest` 中每章 `source.url` 可访问，或 `chapterPdfLoader` / `ensureChapterLoaded` 返回 `loaded`。首章未加载完成时不要提前挂载 `PdfChapterViewport`。
+
+**Q：需要用户安装 `@embedpdf/engines` 吗？**  
+不需要，已作为本包依赖。只需 `vue`。
+
+**Q：如何关闭缩放？**  
+`features: { zoom: false }`，或 `zoom: { enabled: false }`。
+
+**Q：`zoom.enabled: true` 但缩放手势没反应？**  
+1. 确认使用 `<ChapterPdfViewer />` 或 `<PdfChapterViewport :features="..." />`（缩放逻辑在视口内）。  
+2. 在 PDF 区域使用 **Ctrl/Cmd + 滚轮**，不要用普通滚轮。  
+3. 升级 `@embedpdf-editor/vue3-chapter-viewer` 后硬刷新浏览器。
+
+**Q：笔记弹窗想完全自定义？**  
+使用 `onRequestCreateNote` + `complete(noteId)`，不要实现 `onCreateNote`。
+
+**Q：`useCapability` 报错 “must be used inside EmbedPDF”？**  
+`ChapterWorkspace` 等子组件必须渲染在 `<EmbedPDF>` 的默认 slot 内，不能与它平级。