@embedpdf-editor/vue3-chapter-viewer 0.3.0 → 0.3.1

package/dist/index.d.ts

@@ -60,6 +60,11 @@ declare interface BookmarkMarkerUiConfig_2 {
     iconSize?: number;
 }
 
+export declare function buildChapterViewerCatalog(nodes: ChapterTreeInput[]): {
+    tree: ChapterTreeNode_2[];
+    manifest: ChapterManifest;
+};
+
 export declare function buildParagraphBookmarkAnchor(chapterId: string, localPageIndex: number, rectsPdfCoord: Rect[], virtualPage?: {
     globalPageIndex: number;
     globalPageNumber: number;
@@ -134,6 +139,8 @@ export declare interface ChapterDescriptor {
     ownedGlobalPages?: number[];
 }
 
+export declare function chapterDescriptorFromTreeNode(node: ChapterTreeInput): ChapterDescriptor;
+
 /**
  * 章节级加载状态。区别于 `@embedpdf/core` 的 DocumentState：
  * - `idle` = manifest 已注册但尚未触发 open
@@ -280,7 +287,9 @@ export declare type ChapterSource = {
     url: string;
 } | {
     buffer: ArrayBuffer;
-} | {
+}
+/** 按章预处理：拉取、解密、转换后返回 url 或 buffer */
+| {
     load: () => Promise<ChapterPdfPayload>;
 };
 
@@ -294,8 +303,31 @@ declare interface ChapterStatusEvent {
     };
 }
 
+/**
+ * 业务目录树输入：父节点页范围可覆盖子节点；flatten 后每条对应一个可加载的 PDF 章节。
+ * 父节点若仅作分组、无独立 PDF，请勿放入 manifest（不要 flatten 该节点）。
+ */
+export declare type ChapterTreeInput = {
+    chapterId: string;
+    title: string;
+    startPage: number;
+    endPage: number;
+    source?: ChapterSource;
+    encrypted?: boolean;
+    children?: ChapterTreeInput[];
+};
+
 export { ChapterTreeNode }
 
+/** 侧栏目录树节点（仅 UI；渲染以 flatten 后的 manifest 为准） */
+declare type ChapterTreeNode_2 = {
+    id: string;
+    title: string;
+    startPage: number;
+    endPage: number;
+    children?: ChapterTreeNode_2[];
+};
+
 export { ChapterTreePanel }
 
 export { ChapterViewerCatalog }
@@ -354,6 +386,13 @@ export declare interface ChapterViewerOptions {
     /** 书签持久化与删除回调 */
     bookmarks: ParagraphBookmarkCallbacks;
     chapterPdfLoader?: IChapterPdfLoader;
+    /**
+     * 同一全局页被多个章节条目覆盖时，用哪一个章节的 PDF 渲染（非 owner 的章节在该页不绘制真实 PDF）。
+     * - `{ kind: 'first-wins' }`：manifest 中先出现的章节（默认）
+     * - `{ kind: 'last-wins' }`：后出现的章节（目录 flatten 后常用于「以当前页最后一节为准」）
+     * 亦可用 `overlapStrategyForSamePageOwner('first' | 'last')`（chapter-core 包）
+     */
+    overlapStrategy?: OverlapOwnerStrategy;
     /** 功能开关与样式；省略则全开 */
     features?: ChapterViewerConfig;
 }
@@ -445,6 +484,8 @@ export declare const DEFAULT_CHAPTER_VIEWER_CONFIG: ChapterViewerConfig;
 /** 默认全开的功能配置（内部规范化结果） */
 export declare const DEFAULT_CHAPTER_VIEWER_FEATURES: ChapterViewerFeaturesConfig;
 
+export declare const defaultOverlapStrategy: OverlapOwnerStrategy;
+
 export declare function downloadChapterAnnotationsArchive(archive: ChapterAnnotationsArchive, filename?: string): void;
 
 export declare function downloadChapterAnnotationsSnapshot(snapshot: ChapterAnnotationsSnapshot, filename?: string): void;
@@ -476,6 +517,9 @@ export declare type ExportChapterAnnotationsOptions = ChapterAnnotationsContentF
     ensureChapterLoaded?: boolean;
 };
 
+/** 深度优先展开目录树为 manifest.chapters（含父、子各一条，与 demo flatten 一致） */
+export declare function flattenChapterTree(nodes: ChapterTreeInput[]): ChapterDescriptor[];
+
 declare interface HoverBookmarkUiConfig {
     /** 悬停行末「添加书签」自定义图标；无背景 */
     renderAddIcon?: () => unknown;
@@ -488,8 +532,14 @@ declare interface HoverBookmarkUiConfig_2 {
 }
 
 /**
- * 全局章节 PDF 加载器：当 `ChapterDescriptor.source` 未提供 url/buffer/load 时使用。
- * 适合统一走业务 API、鉴权下载等场景。
+ * 全局章节 PDF 加载器：在打开章节前由引擎调用，用于预处理/拉取 PDF。
+ *
+ * 优先级（`ChapterManagerPlugin.resolvePdfPayload`）：
+ * 1. `chapter.source.url` / `source.buffer` — 直接使用
+ * 2. `chapter.source.load()` — 按章异步，返回 `{ url }` 或 `{ buffer }`
+ * 3. `chapterPdfLoader.loadPdf(chapter)` — 全局统一逻辑（鉴权、解密、转 blob URL 等）
+ *
+ * 适合：所有章节走同一套 API、在内存中解密后再以 buffer 打开、动态签名 URL 等。
  */
 export declare interface IChapterPdfLoader {
     loadPdf(chapter: ChapterDescriptor): Promise<ChapterPdfPayload>;
@@ -660,12 +710,17 @@ declare interface OperationSpec {
 }
 
 /**
- * 决定相邻章节在重叠页上谁拥有该页（owner）。
- * - first-wins / last-wins：按 manifest 顺序的先到/后到
- * - explicit：依赖 `ChapterDescriptor.ownedGlobalPages`
- * - custom：开发者完全接管
+ * 决定同一全局页被多个章节 manifest 条目覆盖时，用哪一个章节的 PDF 渲染（owner）。
+ * 非 owner 章节在该页仅占位/不绘制真实 PDF，避免重复。
+ *
+ * - **first-wins**：manifest 中**先**出现的章节（默认）
+ * - **last-wins**：**后**出现的章节（目录 flatten 后，重叠页常以「当前页最后一节」为准）
+ * - **explicit**：`ChapterDescriptor.ownedGlobalPages` 声明归属
+ * - **custom**：`resolve(globalPage, candidates)` 完全自定义
+ *
+ * 简写：`overlapStrategyForSamePageOwner('first' | 'last')`（chapter-core）
  */
-declare type OverlapOwnerStrategy = {
+export declare type OverlapOwnerStrategy = {
     kind: 'first-wins';
 } | {
     kind: 'last-wins';
@@ -676,6 +731,8 @@ declare type OverlapOwnerStrategy = {
     resolve: (globalPage: number, candidates: ChapterDescriptor[]) => string;
 };
 
+export declare function overlapStrategyForSamePageOwner(owner: SamePageOverlapOwner): OverlapOwnerStrategy;
+
 export declare interface ParagraphBookmark {
     id: string;
     label: string;
@@ -744,6 +801,9 @@ declare interface PdfChapterEditorToolbarConfig extends CreateEditorUiSchemaOpti
 
 export { PdfChapterViewport }
 
+/** 同一全局页多章节重叠时，选用 manifest 中先/后出现的章节 PDF */
+export declare type SamePageOverlapOwner = 'first' | 'last';
+
 /** 划线类型 */
 declare type SelectionMarkupKind = 'highlight' | 'underline' | 'squiggly' | 'strikeout';
 
@@ -773,6 +833,8 @@ export declare interface SerializableAnnotationTransferItem {
     };
 }
 
+export declare function toChapterTreeNodes(nodes: ChapterTreeInput[]): ChapterTreeNode_2[];
+
 export { useCapability }
 
 export { usePdfiumEngine }

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"}
+{"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"}