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

package/README.md

@@ -136,7 +136,11 @@ 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 };
     encrypted?: boolean;
     ownedGlobalPages?: number[];
   }>;
@@ -144,7 +148,7 @@ type ChapterManifest = {
 };
 ```
 
-`globalPageRange` 和 `localPageRange` 都是闭区间，且页数必须一致。`chapterId` 同时作为内部 `documentId`，需要在整本书内唯一。
+`globalPageRange` 和 `localPageRange` 都是闭区间，且页数必须一致。`chapterId` 在整本书内唯一；单 URL 章时 `documentId === chapterId`，分段章内部为 `chapterId#s0`、`#s1`…（业务存储仍只用 `chapterId`）。
 
 | 字段 | 说明 |
 | --- | --- |
@@ -236,8 +240,8 @@ const options: ChapterViewerOptions = {
 import type { ChapterViewerOptions, IChapterPdfLoader } from '@embedpdf-editor/vue3-chapter-viewer';
 
 const loader: IChapterPdfLoader = {
-  async loadPdf(chapter) {
-    const res = await api.getChapterPdf(chapter.chapterId);
+  async loadPdf(chapter, segmentIndex) {
+    const res = await api.getChapterPdf(chapter.chapterId, segmentIndex ?? 0);
     return { url: res.signedUrl };
     // 或 return { buffer: await res.arrayBuffer() };
   },
@@ -251,6 +255,26 @@ const options: ChapterViewerOptions = {
 };
 ```
 
+### 章内多 PDF 分段（`source.urls[]`）
+
+```ts
+source: {
+  urls: [part0Url, part1Url, part2Url],
+  segmentPageThreshold: 5, // 13 页 → 3 段
+},
+```
+
+- 先加载 `urls[0]`，滚动时懒加载后续段。
+- `localPageIndex` 为章内 0-based 连续页；Vue 侧无需为分段改 `features`。
+- 业务持久化：**`chapterId` + `localPageIndex`**，勿存 `chapterId#sN`。
+- 导出划线会加载全部分段并合并页码。
+
+[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)
+
+### 按章持久化（笔记 / 书签）
+
+`NoteAnchor` / `ParagraphBookmark.anchor` 的 `chapterId`、`localPageIndex` 与单 URL 章相同。`loadNotes` / `bookmarks.load` 按章查询即可。划线备份用 `exportChapterAnnotations`（归档键为 `chapterId`）。
+
 ### 加密 PDF 与 `passwordProvider`
 
 ```ts
@@ -275,9 +299,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 +327,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 +410,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 +441,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 +486,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 +504,4 @@ import {
 | 页码或滚动错位 | 检查 `globalPageRange` 与 `localPageRange` 页数是否一致 |
 | 划词笔记没有保存 | 实现 `notes.onCreateNote` 或自定义 `onRequestCreateNote` 流程 |
 | 书签删除无效 | `bookmarks.onRequestRemove` 需要返回 `true` 才会删除 |
+| 分段章业务 ID 混乱 | 对外只用 `chapterId` + `localPageIndex`，勿用 `chapterId#sN` |