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

package/dist/index.d.ts

@@ -131,6 +131,11 @@ export declare interface ChapterDescriptor {
      * PDF 来源。可省略：须在 ChapterManager 配置 `chapterPdfLoader` 中统一加载。
      */
     source?: ChapterSource;
+    /**
+     * 章内多 PDF 分段时，每段最多页数（如 5 表示 13 页 → 3 段）。
+     * URL 由 `chapterPdfLoader.loadChapterUrls` 按章拉取，**不要**写在 `source` 里。
+     */
+    segmentPageThreshold?: number;
     encrypted?: boolean;
     /**
      * 仅当 OverlapOwnerStrategy = 'explicit' 时使用：
@@ -155,8 +160,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;
@@ -171,10 +184,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";
@@ -186,15 +197,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);
@@ -202,16 +212,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;
@@ -241,6 +256,26 @@ export declare interface ChapterManifest {
     totalGlobalPages?: number;
 }
 
+declare interface ChapterPageDocumentRef {
+    documentId: string;
+    pageIndex: number;
+}
+
+/**
+ * 打开某一段 PDF 时的上下文（步骤 2 已拿到 urls，步骤 3 可选处理）。
+ */
+export declare interface ChapterPdfLoadContext {
+    chapter: ChapterDescriptor;
+    /** 当前要打开的段，0-based */
+    segmentIndex: number;
+    /** 该章总段数 */
+    segmentCount: number;
+    /** 步骤 2：`loadChapterUrls` 返回的完整列表 */
+    urls: string[];
+    /** 当前段对应 URL：`urls[segmentIndex]` */
+    url: string;
+}
+
 /**
  * Backend-supplied chapter contract.
  *
@@ -277,6 +312,22 @@ export declare interface ChapterPdfViewerProps {
     viewportClassName?: string;
 }
 
+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[];
+}
+
 /**
  * 章节 PDF 来源（由业务在 manifest 中提供）：
  * - `url`：直接打开该地址
@@ -291,6 +342,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 {
@@ -313,6 +372,8 @@ export declare type ChapterTreeInput = {
     startPage: number;
     endPage: number;
     source?: ChapterSource;
+    /** 章内分段阈值；URL 由 `chapterPdfLoader.loadChapterUrls` 拉取 */
+    segmentPageThreshold?: number;
     encrypted?: boolean;
     children?: ChapterTreeInput[];
 };
@@ -424,6 +485,9 @@ declare interface ChapterViewerZoomConfig {
     pageWidth?: number;
 }
 
+/** 将划选文本写入系统剪贴板（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>[];
@@ -545,17 +609,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>;
 }
 
 /**

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,yBAAyB,EACzB,yBAAyB,EACzB,sBAAsB,EACtB,gCAAgC,EAChC,+BAA+B,EAC/B,6BAA6B,EAC7B,oBAAoB,EACpB,4BAA4B,EAC5B,wBAAwB,EACxB,QAAQ,EACR,aAAa,GACd,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,yCAAyC,CAAC;AAC/E,OAAO,EACL,wBAAwB,EACxB,2BAA2B,EAC3B,wBAAwB,EACxB,+BAA+B,EAC/B,+BAA+B,EAC/B,kCAAkC,EAClC,gCAAgC,EAChC,mCAAmC,EACnC,iCAAiC,EACjC,kCAAkC,EAClC,gBAAgB,EAChB,mCAAmC,EACnC,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,EAC9B,KAAK,kCAAkC,EACvC,KAAK,+BAA+B,EACpC,KAAK,+BAA+B,GACrC,MAAM,gCAAgC,CAAC;AACxC,YAAY,EACV,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,EACnB,2BAA2B,EAC3B,qCAAqC,EACrC,6BAA6B,EAC7B,2BAA2B,EAC3B,+BAA+B,EAC/B,aAAa,EACb,UAAU,EACV,SAAS,EACT,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,oCAAoC,CAAC;AAC5C,YAAY,EACV,oBAAoB,EACpB,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,sBAAsB,EACtB,+BAA+B,EAC/B,kBAAkB,EAClB,6BAA6B,EAC7B,yBAAyB,EACzB,kBAAkB,GACnB,MAAM,+BAA+B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,yBAAyB,EACzB,yBAAyB,EACzB,sBAAsB,EACtB,gCAAgC,EAChC,+BAA+B,EAC/B,6BAA6B,EAC7B,oBAAoB,EACpB,4BAA4B,EAC5B,wBAAwB,EACxB,QAAQ,EACR,aAAa,GACd,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,yCAAyC,CAAC;AAC/E,OAAO,EACL,wBAAwB,EACxB,2BAA2B,EAC3B,wBAAwB,EACxB,+BAA+B,EAC/B,+BAA+B,EAC/B,kCAAkC,EAClC,gCAAgC,EAChC,mCAAmC,EACnC,iCAAiC,EACjC,kCAAkC,EAClC,gBAAgB,EAChB,mCAAmC,EACnC,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,EAC9B,KAAK,kCAAkC,EACvC,KAAK,+BAA+B,EACpC,KAAK,+BAA+B,GACrC,MAAM,gCAAgC,CAAC;AACxC,YAAY,EACV,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,EACnB,2BAA2B,EAC3B,qCAAqC,EACrC,6BAA6B,EAC7B,2BAA2B,EAC3B,+BAA+B,EAC/B,aAAa,EACb,UAAU,EACV,SAAS,EACT,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,oCAAoC,CAAC;AAC5C,YAAY,EACV,oBAAoB,EACpB,oBAAoB,EACpB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,sBAAsB,EACtB,+BAA+B,EAC/B,kBAAkB,EAClB,6BAA6B,EAC7B,yBAAyB,EACzB,kBAAkB,GACnB,MAAM,+BAA+B,CAAC"}