@embedpdf-editor/vue3-chapter-viewer 1.0.0 → 1.0.3

package/README.md

@@ -136,7 +136,12 @@ type ChapterManifest = {
     title: string;
     globalPageRange: [number, number];
     localPageRange: [number, number];
-    source?: { url: string } | { buffer: ArrayBuffer } | { load: () => Promise<{ url: string } | { buffer: ArrayBuffer }> };
+    source?:
+      | { url: string }
+      | { buffer: ArrayBuffer }
+      | { load: () => Promise<{ url: string } | { buffer: ArrayBuffer }> }
+      | { urls: string[]; segmentPageThreshold: number }; // legacy
+    segmentPageThreshold?: number;
     encrypted?: boolean;
     ownedGlobalPages?: number[];
   }>;
@@ -144,7 +149,7 @@ type ChapterManifest = {
 };
 ```
 
-`globalPageRange` 和 `localPageRange` 都是闭区间，且页数必须一致。`chapterId` 同时作为内部 `documentId`，需要在整本书内唯一。
+`globalPageRange` 和 `localPageRange` 都是闭区间，且页数必须一致。`chapterId` 在整本书内唯一；单 URL 章时 `documentId === chapterId`，分段章内部为 `chapterId#s0`、`#s1`…（业务存储仍只用 `chapterId`）。
 
 | 字段 | 说明 |
 | --- | --- |
@@ -206,50 +211,46 @@ const options: ChapterViewerOptions = {
 
 ### PDF 加载与预处理
 
-打开章节前，引擎按以下优先级解析 PDF（`ChapterManagerPlugin.resolvePdfPayload`）：
-
-1. `chapter.source.url` / `source.buffer` — 直接使用  
-2. `chapter.source.load()` — **按章**异步预处理，返回 `{ url }` 或 `{ buffer }`  
-3. `chapterPdfLoader.loadPdf(chapter)` — **全局**统一逻辑  
-
-**按章 `source.load`（单章解密、鉴权 URL）：**
+与 React 包一致，推荐 **三步 `chapterPdfLoader`**：`loadChapterUrls` → 可选 `openPdf`。  
+`loadChapterUrls` **每章只请求一次**（引擎缓存）；PDF 按段各打开一次。
 
 ```ts
-{
-  chapterId: 'ch-1',
-  title: '第一章',
-  globalPageRange: [1, 10],
-  localPageRange: [0, 9],
-  source: {
-    load: async () => {
-      const bytes = await fetchDecryptedPdf('ch-1');
-      return { buffer: bytes };
-      // 或 return { url: URL.createObjectURL(blob) };
+import type { ChapterViewerOptions, ChapterPdfLoadContext } from '@embedpdf-editor/vue3-chapter-viewer';
+
+const options: ChapterViewerOptions = {
+  manifest: {
+    chapters: [
+      {
+        chapterId: 'ch-1',
+        title: '第一章',
+        globalPageRange: [1, 13],
+        localPageRange: [0, 12],
+        segmentPageThreshold: 5,
+      },
+    ],
+  },
+  chapterPdfLoader: {
+    async loadChapterUrls(chapter) {
+      const res = await getOneChap(chapter.chapterId);
+      const raw = res.data.resourceUrl;
+      return Array.isArray(raw) ? raw : raw ? [raw] : [];
+    },
+    async openPdf(ctx: ChapterPdfLoadContext) {
+      return { url: ctx.url };
     },
   },
-}
+  notes: { /* ... */ },
+  bookmarks: { /* ... */ },
+};
 ```
 
-**全局 `chapterPdfLoader`（所有章走同一套 API）：**
+静态单文件仍可用 `source.url` / `load()`。兼容 `loadPdf(chapter, segmentIndex)`。
 
-```ts
-import type { ChapterViewerOptions, IChapterPdfLoader } from '@embedpdf-editor/vue3-chapter-viewer';
+[03-manifest.md](../../docs/get-started/03-manifest.md) · [12-segmented-pdf-and-per-chapter-storage.md](../../docs/get-started/12-segmented-pdf-and-per-chapter-storage.md)
 
-const loader: IChapterPdfLoader = {
-  async loadPdf(chapter) {
-    const res = await api.getChapterPdf(chapter.chapterId);
-    return { url: res.signedUrl };
-    // 或 return { buffer: await res.arrayBuffer() };
-  },
-};
+### 按章持久化（笔记 / 书签）
 
-const options: ChapterViewerOptions = {
-  manifest: { chapters: [/* 可省略各条 source */] },
-  chapterPdfLoader: loader,
-  notes: { /* ... */ },
-  bookmarks: { /* ... */ },
-};
-```
+`NoteAnchor` / `ParagraphBookmark.anchor` 的 `chapterId`、`localPageIndex` 与单 URL 章相同。`loadNotes` / `bookmarks.load` 按章查询即可。划线备份用 `exportChapterAnnotations`（归档键为 `chapterId`）。
 
 ### 加密 PDF 与 `passwordProvider`
 
@@ -275,9 +276,9 @@ const passwordProvider = new CallbackPasswordProvider(async (chapter, attempt) =
 | `notes` | `enabled`、`marker`（`renderIcon`、`renderMenuActions`、`iconSize`、`highlightColor`） |
 | `zoom` | `enabled`（默认 true）、`min` 0.5、`max` 3、`initial` 1、`pageWidth`；实际上限由 `[data-chapter-scroll-viewport]` 宽度决定，resize 时自动更新 |
 | `scrollViewport` | `background`（默认 `#f1f5f9`），滚动视口背景 |
-| `selectionToolbar` | `enabled`、`hiddenBuiltinActions`、`extraActions` |
+| `selectionToolbar` | `enabled`、`hiddenBuiltinActions`（含 `copy`）、`renderCopyIcon`、`extraActions` |
 
-默认划线 `offsetY`：`squiggly` 为 **4**。内置工具条按钮：`highlight` | `underline` | `squiggly` | `strikeout` | `note`。
+默认划线 `offsetY`：`squiggly` 为 **4**。内置工具条顺序：**`copy`** → 划线类 → 扩展 → **`note`**。
 
 ---
 
@@ -303,12 +304,21 @@ const passwordProvider = new CallbackPasswordProvider(async (chapter, attempt) =
 usePdfiumEngine();
 ```
 
-如果业务要求内网部署、固定版本或自定义 CDN，再传入自托管地址：
+如果业务要求内网部署、固定版本或自定义 CDN，再传入自托管地址（**完整 URL** 或站点相对路径）：
 
 ```ts
 usePdfiumEngine({ wasmUrl: '/assets/pdfium.wasm', worker: true });
+
+// 自有 OSS / CDN（示例）
+usePdfiumEngine({
+  wasmUrl:
+    'https://hep-editor.oss-cn-beijing.aliyuncs.com/public/editor-public/js/pdfium.wasm',
+  worker: true,
+});
 ```
 
+详见 [docs/get-started/01-installation.md](../../docs/get-started/01-installation.md)。
+
 使用 `worker: true` 时，部署环境需要允许 worker 加载 wasm。若只在 worker 模式失败，可先用 `worker: false` 定位资源或响应头问题。
 
 ## `features` 配置示例
@@ -377,6 +387,28 @@ features: {
 
 ### 选区工具栏
 
+#### 复制（默认开启，浮窗最左侧）
+
+```ts
+import { h } from 'vue';
+
+features: {
+  selectionToolbar: {
+    // hiddenBuiltinActions: ['copy'],
+    renderCopyIcon: () =>
+      h('span', { 'aria-hidden': true, style: { fontSize: '18px' } }, '📋'),
+  },
+},
+```
+
+```ts
+import { copyTextToClipboard } from '@embedpdf-editor/vue3-chapter-viewer';
+
+await copyTextToClipboard('文本');
+```
+
+#### 划线 + 扩展按钮
+
 ```ts
 features: {
   selectionToolbar: {
@@ -386,7 +418,8 @@ features: {
 },
 ```
 
-配合 `ChapterPdfViewer` 的 `@extra-selection-action` 或 `build-selection-menu`。
+配合 `ChapterPdfViewer` 的 `@extra-selection-action` 或 `build-selection-menu`。  
+更多字段说明见 [React 包 `features.selectionToolbar`](../react-chapter-viewer/README.md#featuresselectiontoolbar)。
 
 ## 进阶组合
 
@@ -430,10 +463,14 @@ import {
 | --- | --- |
 | `mode` | `replace` \| `merge` |
 | `bookmarks` / `notes` / `markup` | 导入导出子集，默认 true |
-| `ensureChapterLoaded` | 默认 true |
+| `ensureChapterLoaded` | 默认 true；导出含 markup 的分段章会加载 **全部段** |
 | `persistNotes` / `persistBookmarks` | 导入后写回存储 |
 
-详见 [React README 标注章节](../react-chapter-viewer/README.md#标注导入导出)。
+归档按 `chapterId` 分桶。详见 [10-annotations-io.md](../../docs/get-started/10-annotations-io.md)、[12-segmented-pdf-and-per-chapter-storage.md](../../docs/get-started/12-segmented-pdf-and-per-chapter-storage.md)、[React README 标注章节](../react-chapter-viewer/README.md#标注导入导出)。
+
+## 教程索引
+
+[docs/get-started/README.md](../../docs/get-started/README.md)（含 `wasmUrl`、划词复制、事件全集 [11](./../../docs/get-started/11-events-callbacks-and-component-api.md)、分段 [12](./../../docs/get-started/12-segmented-pdf-and-per-chapter-storage.md)）
 
 ## 常见问题
 
@@ -444,3 +481,4 @@ import {
 | 页码或滚动错位 | 检查 `globalPageRange` 与 `localPageRange` 页数是否一致 |
 | 划词笔记没有保存 | 实现 `notes.onCreateNote` 或自定义 `onRequestCreateNote` 流程 |
 | 书签删除无效 | `bookmarks.onRequestRemove` 需要返回 `true` 才会删除 |
+| 分段章业务 ID 混乱 | 对外只用 `chapterId` + `localPageIndex`，勿用 `chapterId#sN` |