@embedpdf-editor/chapter-snippet 1.0.2 → 1.0.3

package/README.md

@@ -143,18 +143,41 @@ viewer?.addEventListener(CHAPTER_SNIPPET_EVENTS.ready, (event) => {
 
 旧版本的 `editorInput` 仍可使用，但新代码应改为 `options`，并把 `features` 写在 `options.features` 或顶层 `features`。
 
-### 章内多 PDF 分段（`source.urls[]`）
+### PDF 三步加载（Vue 2 推荐）
+
+| 步骤 | 说明 |
+| --- | --- |
+| 1 | `manifest.chapters`：仅页码；`segmentPageThreshold` 写在章节上 |
+| 2 | `chapterPdfLoader.loadChapterUrls`：按章 `getOneChap`，**每章只调一次** |
+| 3 | `chapterPdfLoader.openPdf`（可选）：解密等；省略则直接打开 `ctx.url` |
 
 ```js
-source: {
-  urls: [part0Url, part1Url, part2Url],
-  segmentPageThreshold: 5, // 例：13 页 → 3 段
+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: { /* ... */ },
 },
 ```
 
-- 先加载第一段，滚动懒加载后续段；`localPageIndex` 仍为章内连续页。
-- 引擎内部 `documentId` 为 `chapterId#s0`、`#s1`…；**业务 API / 数据库只存 `chapterId` + `localPageIndex`**。
-- `chapterPdfLoader.loadPdf(chapter, segmentIndex)` 第二参数为段索引（0-based）。
+勿在 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)
 

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' 时使用：
@@ -182,6 +187,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);
@@ -200,6 +208,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;
@@ -248,6 +258,21 @@ declare interface ChapterPageDocumentRef {
     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.
  *
@@ -265,6 +290,7 @@ export declare type ChapterPdfPayload = {
 
 declare interface ChapterSegmentInfo {
     index: number;
+    /** 静态 manifest 有值；动态 loader 时为空，打开段时再解析 URL */
     url: string;
     localPageStart: number;
     localPageEnd: number;
@@ -299,8 +325,8 @@ export declare type ChapterSource = {
     load: () => Promise<ChapterPdfPayload>;
 }
 /**
-* 章内多 PDF 分段（后端已按段拆分）。
-* `urls.length` 须为 ceil(章页数 / segmentPageThreshold)。
+* @deprecated 请用章节级 `segmentPageThreshold` + `chapterPdfLoader.loadChapterUrls`。
+* 静态多 URL 时：`urls.length` 须为 ceil(章页数 / segmentPageThreshold)。
 */
 | {
     urls: string[];
@@ -327,6 +353,8 @@ export declare type ChapterTreeInput = {
     startPage: number;
     endPage: number;
     source?: ChapterSource;
+    /** 章内分段阈值；URL 由 `chapterPdfLoader.loadChapterUrls` 拉取 */
+    segmentPageThreshold?: number;
     encrypted?: boolean;
     children?: ChapterTreeInput[];
 };
@@ -593,20 +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 {
     /**
+     * 步骤 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>;
 }
 
 /**