@embedpdf-editor/vue3-chapter-viewer 1.0.2 → 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' 时使用：
@@ -197,6 +202,9 @@ export declare class ChapterManagerPlugin extends BasePlugin<ChapterManagerPlugi
     private readonly passwordAttempts;
     private readonly pendingChapterLoadPromises;
     private readonly pendingSegmentLoadPromises;
+    /** 步骤 2：`loadChapterUrls` 按章缓存 */
+    private readonly chapterUrlsCache;
+    private readonly pendingChapterUrlsPromises;
     private unloadTimer;
     private documentManagerUnsubs;
     constructor(id: string, registry: PluginRegistry);
@@ -215,6 +223,8 @@ export declare class ChapterManagerPlugin extends BasePlugin<ChapterManagerPlugi
     ensureAllSegmentsLoaded(chapterId: string): Promise<ChapterLoadStatus>;
     ensureSegmentLoaded(chapterId: string, segmentIndex: number): Promise<ChapterLoadStatus>;
     private ensureSingleDocumentChapter;
+    private resolveChapterUrls;
+    private openPayloadFromUrl;
     private resolvePdfPayload;
     private startLoadSegment;
     private waitForTerminalStatus;
@@ -251,6 +261,21 @@ declare interface ChapterPageDocumentRef {
     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.
  *
@@ -289,6 +314,7 @@ export declare interface ChapterPdfViewerProps {
 
 declare interface ChapterSegmentInfo {
     index: number;
+    /** 静态 manifest 有值；动态 loader 时为空，打开段时再解析 URL */
     url: string;
     localPageStart: number;
     localPageEnd: number;
@@ -318,8 +344,8 @@ export declare type ChapterSource = {
     load: () => Promise<ChapterPdfPayload>;
 }
 /**
-* 章内多 PDF 分段（后端已按段拆分）。
-* `urls.length` 须为 ceil(章页数 / segmentPageThreshold)。
+* @deprecated 请用章节级 `segmentPageThreshold` + `chapterPdfLoader.loadChapterUrls`。
+* 静态多 URL 时：`urls.length` 须为 ceil(章页数 / segmentPageThreshold)。
 */
 | {
     urls: string[];
@@ -346,6 +372,8 @@ export declare type ChapterTreeInput = {
     startPage: number;
     endPage: number;
     source?: ChapterSource;
+    /** 章内分段阈值；URL 由 `chapterPdfLoader.loadChapterUrls` 拉取 */
+    segmentPageThreshold?: number;
     encrypted?: boolean;
     children?: ChapterTreeInput[];
 };
@@ -581,20 +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 {
     /**
+     * 步骤 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>;
+    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,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,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"}