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

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { AnnotationCapability } from '@embedpdf/plugin-annotation';
+import { AnnotationTransferItem } from '@embedpdf/plugin-annotation';
 import { BasePlugin } from '@embedpdf/core';
 import { BasePluginConfig } from '@embedpdf/core';
 import { ChapterTreeNode } from '../vue/chapter-tree';
@@ -22,8 +23,23 @@ import { ToolbarSchema } from '@embedpdf/plugin-ui';
 import { UISchema } from '@embedpdf/plugin-ui';
 import { useCapability } from '@embedpdf/core/vue';
 import { usePdfiumEngine } from '@embedpdf/engines/vue';
+import { useRegistry } from '@embedpdf/core/vue';
 
-declare const __VLS_export: DefineComponent<ChapterPdfViewerProps, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<ChapterPdfViewerProps> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+declare const __VLS_base: DefineComponent<ChapterPdfViewerProps, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<ChapterPdfViewerProps> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+
+declare type __VLS_Slots = {} & {
+    prepend?: (props: typeof __VLS_9) => any;
+} & {
+    default?: (props: typeof __VLS_11) => any;
+};
+
+declare type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};
 
 /** 对当前选区应用 PDF 划线/高亮，支持按类型自定义颜色、粗细与偏移 */
 export declare function applySelectionMarkup(documentId: string, kind: SelectionMarkupKind, annotation: AnnotationCapability, selection: SelectionCapability, styles?: MarkupStylesConfig): boolean;
@@ -44,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;
@@ -61,6 +82,37 @@ export declare class CallbackPasswordProvider implements IPasswordProvider {
     resolvePassword(chapter: ChapterDescriptor, attempt: number): Promise<string | null>;
 }
 
+/** 归档文件格式版本 */
+export declare const CHAPTER_ANNOTATIONS_ARCHIVE_VERSION: 1;
+
+/** 全书按 chapterId 分组的归档 */
+export declare interface ChapterAnnotationsArchive {
+    version: typeof CHAPTER_ANNOTATIONS_ARCHIVE_VERSION;
+    exportedAt: string;
+    chapters: Record<string, Omit<ChapterAnnotationsSnapshot, 'chapterId'>>;
+}
+
+export declare function chapterAnnotationsArchiveToJson(archive: ChapterAnnotationsArchive): string;
+
+declare type ChapterAnnotationsContentFlags = {
+    /** 默认 true */
+    bookmarks?: boolean;
+    /** 默认 true */
+    notes?: boolean;
+    /** 默认 true；对应 @embedpdf/plugin-annotation 的 export/import */
+    markup?: boolean;
+};
+
+/** 单章用户标注快照 */
+export declare interface ChapterAnnotationsSnapshot {
+    chapterId: string;
+    bookmarks?: ParagraphBookmark[];
+    notes?: NoteAnchor[];
+    markup?: SerializableAnnotationTransferItem[];
+}
+
+export declare function chapterAnnotationsSnapshotToJson(snapshot: ChapterAnnotationsSnapshot): string;
+
 export declare interface ChapterDescriptor {
     /** 业务唯一 ID；同时复用作 documentManager 的 documentId */
     chapterId: string;
@@ -87,6 +139,8 @@ export declare interface ChapterDescriptor {
     ownedGlobalPages?: number[];
 }
 
+export declare function chapterDescriptorFromTreeNode(node: ChapterTreeInput): ChapterDescriptor;
+
 /**
  * 章节级加载状态。区别于 `@embedpdf/core` 的 DocumentState：
  * - `idle` = manifest 已注册但尚未触发 open
@@ -233,7 +287,9 @@ export declare type ChapterSource = {
     url: string;
 } | {
     buffer: ArrayBuffer;
-} | {
+}
+/** 按章预处理：拉取、解密、转换后返回 url 或 buffer */
+| {
     load: () => Promise<ChapterPdfPayload>;
 };
 
@@ -247,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 }
@@ -307,12 +386,19 @@ 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;
 }
 
 declare interface ChapterViewerZoomConfig {
-    /** 是否启用 pinch/滑块缩放容器，默认 true */
+    /** 是否启用 Ctrl+滚轮 / 双指捏合等交互缩放，默认 true；为 false 时仍可用 pageWidth / initial 设置版面宽度 */
     enabled?: boolean;
     min?: number;
     max?: number;
@@ -398,6 +484,15 @@ 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;
+
+/** 触发浏览器下载 JSON 文件（仅浏览器环境） */
+export declare function downloadJsonFile(filename: string, json: string): void;
+
 /** 与 snippet 主工具栏 mode tabs 对齐的编辑模式 */
 declare type EditorModeId = 'view' | 'annotate' | 'shapes' | 'insert' | 'form' | 'redact';
 
@@ -406,6 +501,25 @@ declare const editorSecondaryToolbars: Record<string, ToolbarSchema>;
 
 export { EmbedPDF }
 
+/**
+ * 导出 manifest 中全部章节（按 chapterId 存 JSON 对象）。
+ */
+export declare function exportAllChapterAnnotations(registry: PluginRegistry, manifest: ChapterManifest, options?: ExportChapterAnnotationsOptions): Promise<ChapterAnnotationsArchive>;
+
+/**
+ * 导出单章用户标注（书签、笔记、划词划线）。
+ * `chapterId` 与章节 documentId 一致。
+ */
+export declare function exportChapterAnnotations(registry: PluginRegistry, chapterId: string, options?: ExportChapterAnnotationsOptions): Promise<ChapterAnnotationsSnapshot>;
+
+export declare type ExportChapterAnnotationsOptions = ChapterAnnotationsContentFlags & {
+    /** 导出前确保章节 PDF 已加载（划线需要），默认 true */
+    ensureChapterLoaded?: boolean;
+};
+
+/** 深度优先展开目录树为 manifest.chapters（含父、子各一条，与 demo flatten 一致） */
+export declare function flattenChapterTree(nodes: ChapterTreeInput[]): ChapterDescriptor[];
+
 declare interface HoverBookmarkUiConfig {
     /** 悬停行末「添加书签」自定义图标；无背景 */
     renderAddIcon?: () => unknown;
@@ -418,13 +532,42 @@ 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>;
 }
 
+/**
+ * 导入单章快照。
+ */
+export declare function importChapterAnnotations(registry: PluginRegistry, snapshot: ChapterAnnotationsSnapshot, options?: ImportChapterAnnotationsOptions): Promise<void>;
+
+/**
+ * 导入全书归档（仅处理 archive.chapters 中存在的 chapterId）。
+ */
+export declare function importChapterAnnotationsArchive(registry: PluginRegistry, archive: ChapterAnnotationsArchive, options?: ImportChapterAnnotationsOptions): Promise<void>;
+
+export declare type ImportChapterAnnotationsOptions = ChapterAnnotationsContentFlags & {
+    /**
+     * replace：先清空该章对应数据再写入；
+     * merge：划线/笔记/书签与现有合并（书签按 anchor 去重）。
+     */
+    mode?: 'replace' | 'merge';
+    /** 导入前确保章节已加载，默认 true */
+    ensureChapterLoaded?: boolean;
+    /** 导入完成后回调，便于写入 localStorage / 后端 */
+    persistNotes?: (allNotes: NoteAnchor[]) => void | Promise<void>;
+    persistBookmarks?: (allBookmarks: ParagraphBookmark[]) => void | Promise<void>;
+};
+
 /**
  * 章节加密的抽象接口：当某章节首次或重试加载因密码失败时，
  * `ChapterManagerPlugin` 会向 provider 询问密码。
@@ -567,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';
@@ -583,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;
@@ -628,6 +778,10 @@ declare interface ParagraphBookmarkPluginConfig extends BasePluginConfig {
     hover?: HoverBookmarkUiConfig_2;
 }
 
+export declare function parseChapterAnnotationsArchiveJson(json: string): ChapterAnnotationsArchive;
+
+export declare function parseChapterAnnotationsSnapshotJson(json: string): ChapterAnnotationsSnapshot;
+
 export declare interface PdfChapterEditorBookmarksConfig {
     callbacks: NonNullable<ParagraphBookmarkPluginConfig['callbacks']>;
 }
@@ -647,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';
 
@@ -667,10 +824,23 @@ declare interface SelectionToolbarExtraAction {
     order?: number;
 }
 
+/** JSON 中可存储的划线（stamp 的 ArrayBuffer 转为 base64） */
+export declare interface SerializableAnnotationTransferItem {
+    annotation: AnnotationTransferItem['annotation'];
+    ctx?: {
+        dataBase64?: string;
+        mimeType?: string;
+    };
+}
+
+export declare function toChapterTreeNodes(nodes: ChapterTreeInput[]): ChapterTreeNode_2[];
+
 export { useCapability }
 
 export { usePdfiumEngine }
 
+export { useRegistry }
+
 /**
  * 一个虚拟页位的解析结果。`localPageIndex` 是 owner 章节 PDF 内的 0-based 索引。
  */

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,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,yCAAyC,CAAC;AAC/E,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"}