@embedpdf-editor/chapter-snippet 1.0.0 → 1.0.3

package/README.md

@@ -43,7 +43,18 @@ import ChapterEmbedPDF from '@embedpdf-editor/chapter-snippet';
 
 发包构建会对 `dist/embedpdf-chapter.js` 做语法降级（去掉 `??` 等 ES2020 语法），Webpack / Vue CLI 默认可 parse。默认 `wasmUrl` 指向 jsDelivr 上的 `pdfium.wasm`，无需复制到 `public/`。
 
-离线或内网部署时，可传 `wasmUrl: '/pdfium.wasm'`（自行把 `node_modules/@embedpdf-editor/chapter-snippet/dist/pdfium.wasm` 放到静态目录）。
+离线或内网部署时，可传 `wasmUrl`（**init 顶层**，与 `options` 同级）：
+
+```js
+// 相对路径：自行把 dist/pdfium.wasm 放到静态目录
+wasmUrl: '/pdfium.wasm',
+
+// 自有 OSS / CDN（完整 HTTPS 地址，示例）
+wasmUrl:
+  'https://hep-editor.oss-cn-beijing.aliyuncs.com/public/editor-public/js/pdfium.wasm',
+```
+
+详见 [docs/get-started/01-installation.md](../../docs/get-started/01-installation.md)。
 
 `@embedpdf-editor/chapter-snippet/webpack` 为**可选**辅助（仅 monorepo Vue 2.6 解析、或自定义 devServer COOP/COEP），普通用户不必使用。
 
@@ -132,6 +143,48 @@ viewer?.addEventListener(CHAPTER_SNIPPET_EVENTS.ready, (event) => {
 
 旧版本的 `editorInput` 仍可使用，但新代码应改为 `options`，并把 `features` 写在 `options.features` 或顶层 `features`。
 
+### PDF 三步加载（Vue 2 推荐）
+
+| 步骤 | 说明 |
+| --- | --- |
+| 1 | `manifest.chapters`：仅页码；`segmentPageThreshold` 写在章节上 |
+| 2 | `chapterPdfLoader.loadChapterUrls`：按章 `getOneChap`，**每章只调一次** |
+| 3 | `chapterPdfLoader.openPdf`（可选）：解密等；省略则直接打开 `ctx.url` |
+
+```js
+options: {
+  manifest: {
+    chapters: [
+      {
+        chapterId: item._id,
+        title: item.title,
+        globalPageRange: [item.startPage, item.endPage],
+        localPageRange: [0, item.endPage - item.startPage],
+        segmentPageThreshold: item.page,
+      },
+    ],
+  },
+  chapterPdfLoader: {
+    async loadChapterUrls(chapter) {
+      const res = await getOneChap(chapter.chapterId);
+      if (!res.success) throw new Error(res.message);
+      const raw = res.data.resourceUrl;
+      return Array.isArray(raw) ? raw : raw ? [raw] : [];
+    },
+  },
+  notes: { /* ... */ },
+  bookmarks: { /* ... */ },
+},
+```
+
+勿在 loader 外再请求章节详情；勿把 `segmentPageThreshold` 放进 `source`。
+
+[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)
+
+### 按章持久化
+
+`options.notes` / `options.bookmarks` 回调里的 `chapterId`、`localPageIndex` 与单 URL 章相同。划线备份用 `exportChapterAnnotations`，JSON 键为 `chapters[chapterId]`（导出 markup 时会拉全部分段）。
+
 ### `ChapterViewerOptions`（与 React / Vue3 一致）
 
 | 字段 | 说明 |
@@ -155,7 +208,7 @@ viewer?.addEventListener(CHAPTER_SNIPPET_EVENTS.ready, (event) => {
 | `notes` | `marker.renderIcon`、`renderMenuActions`、`highlightColor` |
 | `zoom` | `pageWidth`、`min` / `max` / `enabled`；实际上限不超过 `[data-chapter-scroll-viewport]` 宽度，resize 时自动 clamp |
 | `scrollViewport` | `background`（默认 `#f1f5f9`），`[data-chapter-scroll-viewport]` 背景 |
-| `selectionToolbar` | `hiddenBuiltinActions`、`extraActions`；扩展动作监听 `selectionExtraAction` 事件 |
+| `selectionToolbar` | `hiddenBuiltinActions`（含 `copy`）、`renderCopyIcon`、`extraActions`；扩展动作监听 `selectionExtraAction` 事件 |
 
 ```js
 features: {
@@ -182,12 +235,27 @@ features: {
     },
   },
   selectionToolbar: {
+    // 复制默认开启，浮窗最左侧；隐藏：hiddenBuiltinActions: ['copy']
+    renderCopyIcon: () => {
+      const span = document.createElement('span');
+      span.textContent = '📋';
+      span.setAttribute('aria-hidden', 'true');
+      return span;
+    },
     extraActions: [{ id: 'cite', label: '引用', order: 10 }],
   },
 },
 ```
 
-`renderMenu` / `renderIcon` 在 snippet（Preact）内执行，请返回 **DOM 或 Preact 节点**；Vue 2 宿主不要用 `h()` 直接塞进 Shadow DOM。
+划词后点**复制**会将选中文本写入剪贴板。程序化：
+
+```js
+import { copyTextToClipboard } from '@embedpdf-editor/chapter-snippet';
+
+await copyTextToClipboard('文本');
+```
+
+`renderMenu` / `renderIcon` / `renderCopyIcon` 在 snippet（Preact）内执行，请返回 **DOM 或 Preact 节点**；Vue 2 宿主不要用 `h()` 直接塞进 Shadow DOM。
 
 ## 事件
 
@@ -247,11 +315,21 @@ import {
 | 选项 | 说明 |
 | --- | --- |
 | `mode` | `replace` 清空后导入；`merge` 合并 |
-| `ensureChapterLoaded` | 默认 true，导入 markup 前打开 PDF |
+| `ensureChapterLoaded` | 默认 true；含 markup 的分段章会加载 **全部段** 再合并页码 |
 | `bookmarks` / `notes` / `markup` | 默认 true，可关闭某一类 |
 | `persistNotes` / `persistBookmarks` | 导入后写回业务存储 |
 
-示例见 `examples/chapter-viewer-demo-vue2/src/components/AnnotationsDemoBar.vue`。
+示例见 `examples/chapter-viewer-demo-vue2/src/components/AnnotationsDemoBar.vue`。详见 [10-annotations-io.md](../../docs/get-started/10-annotations-io.md)。
+
+## 教程索引
+
+| 主题 | 文档 |
+| --- | --- |
+| 目录 | [docs/get-started/README.md](../../docs/get-started/README.md) |
+| `wasmUrl`（含 OSS 示例） | [01-installation.md](../../docs/get-started/01-installation.md) |
+| 划词复制 | [07-selection-toolbar.md](../../docs/get-started/07-selection-toolbar.md) |
+| 事件常量 | [11-events-callbacks-and-component-api.md](../../docs/get-started/11-events-callbacks-and-component-api.md) |
+| 分段 + 按章存储 | [12-segmented-pdf-and-per-chapter-storage.md](../../docs/get-started/12-segmented-pdf-and-per-chapter-storage.md) |
 
 ## 与 React / Vue3 渲染器的区别
 
@@ -277,3 +355,4 @@ import {
 | 只显示空白 | 确认宿主元素有高度，且没有被父容器 `overflow`/flex 布局压到 0 |
 | 划词后没有笔记弹窗 | 监听 `chapter-note-request-create`，保存后调用 `detail.complete(noteId)` |
 | Vue/Vite 开发环境异常预构建 | 使用 `chapterSnippetViteResolve()`，确保 snippet 和 PDFium 引擎没有被 optimizeDeps 预构建 |
+| 分段章存了 `#sN` | 业务层只用 `chapterId`；引擎段 ID 勿写入库 |

package/dist/embedpdf-chapter.d.ts

@@ -110,6 +110,11 @@ export declare interface ChapterDescriptor {
      * PDF 来源。可省略：须在 ChapterManager 配置 `chapterPdfLoader` 中统一加载。
      */
     source?: ChapterSource;
+    /**
+     * 章内多 PDF 分段时，每段最多页数（如 5 表示 13 页 → 3 段）。
+     * URL 由 `chapterPdfLoader.loadChapterUrls` 按章拉取，**不要**写在 `source` 里。
+     */
+    segmentPageThreshold?: number;
     encrypted?: boolean;
     /**
      * 仅当 OverlapOwnerStrategy = 'explicit' 时使用：
@@ -140,8 +145,16 @@ declare interface ChapterManagerCapability {
     getVirtualPageMap(): VirtualPageMap;
     /** ChapterScrollPlugin 在可见页位变化时调用，用以驱动按需加载 */
     setVisibleGlobalPages(visiblePageIndices: number[]): void;
-    /** 显式触发某章节加载（如点击章节标题跳转时） */
+    /** 显式触发某章节加载（分段章节仅加载第 0 段） */
     ensureChapterLoaded(chapterId: string): Promise<ChapterLoadStatus>;
+    /** 加载章内指定分段 PDF */
+    ensureSegmentLoaded(chapterId: string, segmentIndex: number): Promise<ChapterLoadStatus>;
+    /** 加载章内全部分段（导出划线等） */
+    ensureAllSegmentsLoaded(chapterId: string): Promise<ChapterLoadStatus>;
+    /** 将章内 localPageIndex 映射为 documentManager 的 documentId + 段内页码 */
+    resolvePageDocument(chapterId: string, localPageIndex: number): ChapterPageDocumentRef | null;
+    getSegmentPlan(chapterId: string): ChapterSegmentPlan | null;
+    isSegmentLoaded(chapterId: string, segmentIndex: number): boolean;
     /** 状态查询 */
     getChapterStatus(chapterId: string): ChapterLoadStatus;
     getChapter(chapterId: string): ChapterDescriptor | null;
@@ -156,10 +169,8 @@ declare interface ChapterManagerCapability {
 /**
  * 章节生命周期管理：以章节为粒度懒加载/预取/卸载 PDF 文件，并屏蔽密码协议细节。
  *
- * 关键不变量：
- * - 每个章节对 DocumentManager 用 `documentId === chapterId`，从而保持 1:1 缓存。
- * - 视觉上的「activeDocumentId」由本插件根据当前可见页位维护；上层无须感知。
- * - 渲染层最终始终通过 `(chapterId, localPageIndex)` 索引到 owner 章节的 PDF 文档。
+ * - 单 URL：`documentId === chapterId`
+ * - 多段 URL：`documentId === chapterId#s{index}`，滚动时按段加载
  */
 export declare class ChapterManagerPlugin extends BasePlugin<ChapterManagerPluginConfig, ChapterManagerCapability> {
     static readonly id: "chapter-manager";
@@ -171,15 +182,14 @@ export declare class ChapterManagerPlugin extends BasePlugin<ChapterManagerPlugi
     private manifest;
     private overlapStrategy;
     private virtualPageMap;
-    /** 每个章节当前状态（in-memory；不需要 redux 同步） */
     private readonly chapterStatus;
-    /** 章节最近一次进入视口或被显式请求的时间戳，用于卸载判断 */
     private readonly chapterLastUsed;
-    /** 章节密码累计尝试次数 */
     private readonly passwordAttempts;
-    /** 等待 ensureChapterLoaded 完成的 Promise 列表（按章节去重） */
-    private readonly pendingLoadPromises;
-    /** unload tick 句柄 */
+    private readonly pendingChapterLoadPromises;
+    private readonly pendingSegmentLoadPromises;
+    /** 步骤 2：`loadChapterUrls` 按章缓存 */
+    private readonly chapterUrlsCache;
+    private readonly pendingChapterUrlsPromises;
     private unloadTimer;
     private documentManagerUnsubs;
     constructor(id: string, registry: PluginRegistry);
@@ -187,16 +197,21 @@ export declare class ChapterManagerPlugin extends BasePlugin<ChapterManagerPlugi
     protected buildCapability(): ChapterManagerCapability;
     destroy(): void;
     private setManifestInternal;
-    /** manifest 就绪后预取前 N 章（不依赖滚动视口是否已算出可见页） */
     private eagerPrefetchFromManifest;
     private findChapter;
-    private isOwnedChapter;
+    private getSegmentPlanForChapter;
+    private isSegmentDocumentOpen;
+    private syncChapterStatusFromDocuments;
     private handleVisibleChange;
     private collectIdleChapters;
     ensureChapterLoaded(chapterId: string): Promise<ChapterLoadStatus>;
+    ensureAllSegmentsLoaded(chapterId: string): Promise<ChapterLoadStatus>;
+    ensureSegmentLoaded(chapterId: string, segmentIndex: number): Promise<ChapterLoadStatus>;
+    private ensureSingleDocumentChapter;
+    private resolveChapterUrls;
+    private openPayloadFromUrl;
     private resolvePdfPayload;
-    private startLoad;
-    /** 阻塞等待该章节状态进入 loaded / error / password-required / closed */
+    private startLoadSegment;
     private waitForTerminalStatus;
     private handleDocumentError;
     private closeChapter;
@@ -238,6 +253,26 @@ export declare type ChapterNoteRequestEditDetail = {
     anchor: NoteAnchor;
 };
 
+declare interface ChapterPageDocumentRef {
+    documentId: string;
+    pageIndex: number;
+}
+
+/**
+ * 打开某一段 PDF 时的上下文（步骤 2 已拿到 urls，步骤 3 可选处理）。
+ */
+declare interface ChapterPdfLoadContext {
+    chapter: ChapterDescriptor;
+    /** 当前要打开的段，0-based */
+    segmentIndex: number;
+    /** 该章总段数 */
+    segmentCount: number;
+    /** 步骤 2：`loadChapterUrls` 返回的完整列表 */
+    urls: string[];
+    /** 当前段对应 URL：`urls[segmentIndex]` */
+    url: string;
+}
+
 /**
  * Backend-supplied chapter contract.
  *
@@ -253,6 +288,22 @@ export declare type ChapterPdfPayload = {
     buffer: ArrayBuffer;
 };
 
+declare interface ChapterSegmentInfo {
+    index: number;
+    /** 静态 manifest 有值；动态 loader 时为空，打开段时再解析 URL */
+    url: string;
+    localPageStart: number;
+    localPageEnd: number;
+    documentId: string;
+}
+
+declare interface ChapterSegmentPlan {
+    chapterId: string;
+    threshold: number;
+    pageCount: number;
+    segments: ChapterSegmentInfo[];
+}
+
 /** 划词工具栏扩展操作事件 */
 export declare type ChapterSelectionActionDetail = {
     actionId: string;
@@ -272,6 +323,14 @@ export declare type ChapterSource = {
 /** 按章预处理：拉取、解密、转换后返回 url 或 buffer */
 | {
     load: () => Promise<ChapterPdfPayload>;
+}
+/**
+* @deprecated 请用章节级 `segmentPageThreshold` + `chapterPdfLoader.loadChapterUrls`。
+* 静态多 URL 时：`urls.length` 须为 ceil(章页数 / segmentPageThreshold)。
+*/
+| {
+    urls: string[];
+    segmentPageThreshold: number;
 };
 
 declare interface ChapterStatusEvent {
@@ -294,6 +353,8 @@ export declare type ChapterTreeInput = {
     startPage: number;
     endPage: number;
     source?: ChapterSource;
+    /** 章内分段阈值；URL 由 `chapterPdfLoader.loadChapterUrls` 拉取 */
+    segmentPageThreshold?: number;
     encrypted?: boolean;
     children?: ChapterTreeInput[];
 };
@@ -429,6 +490,9 @@ export declare type ContainerInitConfig = ChapterViewerContainerConfig & {
     target: Element;
 };
 
+/** 将划选文本写入系统剪贴板（Clipboard API，失败时回退 execCommand） */
+export declare function copyTextToClipboard(text: string): Promise<boolean>;
+
 /** 生成插件列表 + 规范化后的 features（供 EmbedPDF / PdfChapterViewport 使用） */
 export declare function createChapterViewerBundle(input: ChapterViewerOptions | CreateChapterViewerEditorOptionsInput): {
     plugins: PluginBatchRegistration<any, any, any, any>[];
@@ -557,17 +621,32 @@ declare interface HoverBookmarkUiConfig_2 {
 }
 
 /**
- * 全局章节 PDF 加载器：在打开章节前由引擎调用，用于预处理/拉取 PDF。
+ * 章节 PDF 加载（推荐三步；`loadPdf` 仍兼容旧版单步写法）。
  *
- * 优先级（`ChapterManagerPlugin.resolvePdfPayload`）：
- * 1. `chapter.source.url` / `source.buffer` — 直接使用
- * 2. `chapter.source.load()` — 按章异步，返回 `{ url }` 或 `{ buffer }`
- * 3. `chapterPdfLoader.loadPdf(chapter)` — 全局统一逻辑（鉴权、解密、转 blob URL 等）
+ * | 步骤 | 方法 | 说明 |
+ * | --- | --- | --- |
+ * | 1 | manifest 章节树 | 仅 `chapterId`、页码、`segmentPageThreshold` 等，**无 URL** |
+ * | 2 | `loadChapterUrls(chapter)` | 按章请求详情，返回 URL 列表（分段时多项） |
+ * | 3 | `openPdf(ctx)`（可选） | 对 `ctx.url` 解密/下载；省略则直接用 `ctx.url` 打开 |
  *
- * 适合：所有章节走同一套 API、在内存中解密后再以 buffer 打开、动态签名 URL 等。
+ * 仍可使用 `loadPdf(chapter, segmentIndex)` 单步实现（等价于 2+3 合并）。
  */
 export declare interface IChapterPdfLoader {
-    loadPdf(chapter: ChapterDescriptor): Promise<ChapterPdfPayload>;
+    /**
+     * 步骤 2：按章拉取 PDF 地址列表。
+     * 单 PDF 章节返回长度为 1 的数组；分段章节返回与 `ceil(页数/threshold)` 一致的多项。
+     */
+    loadChapterUrls?(chapter: ChapterDescriptor): Promise<string[]>;
+    /**
+     * 步骤 3（可选）：将步骤 2 的 URL 转为可打开的 payload。
+     * 未实现时引擎使用 `{ url: ctx.url }`。
+     */
+    openPdf?(ctx: ChapterPdfLoadContext): Promise<ChapterPdfPayload>;
+    /**
+     * @deprecated 单步加载；新代码请用 `loadChapterUrls` + 可选 `openPdf`。
+     * @param segmentIndex 章内分段索引；单 URL 章节为 0 或省略
+     */
+    loadPdf?(chapter: ChapterDescriptor, segmentIndex?: number): Promise<ChapterPdfPayload>;
 }
 
 /**