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

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { AnnotationCapability } from '@embedpdf/plugin-annotation';
+import { BasePlugin } from '@embedpdf/core';
 import { BasePluginConfig } from '@embedpdf/core';
 import { ChapterTreeNode } from '../vue/chapter-tree';
 import { default as ChapterTreePanel } from '../components/ChapterTreePanel.vue';
@@ -8,9 +9,11 @@ import { ComponentOptionsMixin } from 'vue';
 import { ComponentProvideOptions } from 'vue';
 import { DefineComponent } from 'vue';
 import { EmbedPDF } from '@embedpdf/core/vue';
+import { EventHook } from '@embedpdf/core';
 import { default as PdfChapterViewport } from '../components/PdfChapterViewport.vue';
 import { PdfEngine } from '@embedpdf/models';
 import { PluginBatchRegistration } from '@embedpdf/core';
+import { PluginRegistry } from '@embedpdf/core';
 import { PublicProps } from 'vue';
 import { ReactNode } from 'react';
 import { Rect } from '@embedpdf/models';
@@ -20,28 +23,24 @@ import { UISchema } from '@embedpdf/plugin-ui';
 import { useCapability } from '@embedpdf/core/vue';
 import { usePdfiumEngine } from '@embedpdf/engines/vue';
 
-declare const __VLS_export: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
-
-declare type __VLS_Props = {
-    viewerProps: ChapterPdfViewerProps;
-};
+declare const __VLS_export: DefineComponent<ChapterPdfViewerProps, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<ChapterPdfViewerProps> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
 
 /** 对当前选区应用 PDF 划线/高亮，支持按类型自定义颜色、粗细与偏移 */
 export declare function applySelectionMarkup(documentId: string, kind: SelectionMarkupKind, annotation: AnnotationCapability, selection: SelectionCapability, styles?: MarkupStylesConfig): boolean;
 
 declare interface BookmarkMarkerUiConfig {
-    /** 自定义图标；提供时仅渲染图标，无默认蓝色背景按钮 */
+    /** 自定义图标；提供时仅渲染图标，无默认蓝色圆角背景 */
     renderIcon?: (ctx: {
         bookmark: ParagraphBookmark;
-    }) => ReactNode;
+    }) => unknown;
     iconSize?: number;
 }
 
 declare interface BookmarkMarkerUiConfig_2 {
-    /** 自定义图标；提供时仅渲染图标，无默认蓝色圆角背景 */
+    /** 自定义图标；提供时仅渲染图标，无默认蓝色背景按钮 */
     renderIcon?: (ctx: {
         bookmark: ParagraphBookmark;
-    }) => unknown;
+    }) => ReactNode;
     iconSize?: number;
 }
 
@@ -95,6 +94,90 @@ export declare interface ChapterDescriptor {
  */
 export declare type ChapterLoadStatus = 'idle' | 'loading' | 'loaded' | 'error' | 'password-required' | 'closed';
 
+declare interface ChapterManagerCapability {
+    /** 替换 manifest（会触发已不存在章节的卸载） */
+    setManifest(manifest: ChapterManifest, strategy?: OverlapOwnerStrategy): void;
+    getManifest(): ChapterManifest;
+    getVirtualPageMap(): VirtualPageMap;
+    /** ChapterScrollPlugin 在可见页位变化时调用，用以驱动按需加载 */
+    setVisibleGlobalPages(visiblePageIndices: number[]): void;
+    /** 显式触发某章节加载（如点击章节标题跳转时） */
+    ensureChapterLoaded(chapterId: string): Promise<ChapterLoadStatus>;
+    /** 状态查询 */
+    getChapterStatus(chapterId: string): ChapterLoadStatus;
+    getChapter(chapterId: string): ChapterDescriptor | null;
+    /** 事件 */
+    onChapterStatusChange: EventHook<ChapterStatusEvent>;
+    onManifestChange: EventHook<{
+        manifest: ChapterManifest;
+        map: VirtualPageMap;
+    }>;
+}
+
+/**
+ * 章节生命周期管理：以章节为粒度懒加载/预取/卸载 PDF 文件，并屏蔽密码协议细节。
+ *
+ * 关键不变量：
+ * - 每个章节对 DocumentManager 用 `documentId === chapterId`，从而保持 1:1 缓存。
+ * - 视觉上的「activeDocumentId」由本插件根据当前可见页位维护；上层无须感知。
+ * - 渲染层最终始终通过 `(chapterId, localPageIndex)` 索引到 owner 章节的 PDF 文档。
+ */
+export declare class ChapterManagerPlugin extends BasePlugin<ChapterManagerPluginConfig, ChapterManagerCapability> {
+    static readonly id: "chapter-manager";
+    private readonly statusChange$;
+    private readonly manifestChange$;
+    private config;
+    private documentManager;
+    private passwordProvider?;
+    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 unloadTimer;
+    private documentManagerUnsubs;
+    constructor(id: string, registry: PluginRegistry);
+    initialize(config: ChapterManagerPluginConfig): Promise<void>;
+    protected buildCapability(): ChapterManagerCapability;
+    destroy(): void;
+    private setManifestInternal;
+    /** manifest 就绪后预取前 N 章（不依赖滚动视口是否已算出可见页） */
+    private eagerPrefetchFromManifest;
+    private findChapter;
+    private isOwnedChapter;
+    private handleVisibleChange;
+    private collectIdleChapters;
+    ensureChapterLoaded(chapterId: string): Promise<ChapterLoadStatus>;
+    private resolvePdfPayload;
+    private startLoad;
+    /** 阻塞等待该章节状态进入 loaded / error / password-required / closed */
+    private waitForTerminalStatus;
+    private handleDocumentError;
+    private closeChapter;
+    private updateStatus;
+}
+
+declare interface ChapterManagerPluginConfig extends BasePluginConfig {
+    manifest: ChapterManifest;
+    overlapStrategy?: OverlapOwnerStrategy;
+    passwordProvider?: IPasswordProvider;
+    /** 未在 descriptor.source 中指定 PDF 时，由此统一加载 */
+    chapterPdfLoader?: IChapterPdfLoader;
+    /** 视口前后预取多少章节，默认 1 */
+    prefetchChapters?: number;
+    /** 章节空闲多久后卸载（毫秒），默认 60s。设为 0 关闭卸载 */
+    unloadTimeoutMs?: number;
+    /** 第一个加载的章节是否自动设为 active，默认 true */
+    autoActivateOnLoad?: boolean;
+}
+
 export declare interface ChapterManifest {
     chapters: ChapterDescriptor[];
     /**
@@ -121,14 +204,21 @@ export declare type ChapterPdfPayload = {
 
 export declare const ChapterPdfViewer: typeof __VLS_export;
 
-/** React / Vue 共用的章节阅读器顶层 props（框架专属字段在各自入口扩展） */
+/** React / Vue 共用的章节阅读器顶层 props */
 export declare interface ChapterPdfViewerProps {
     engine: PdfEngine;
-    editorOptions: Omit<CreatePdfChapterEditorOptions, 'features'> & {
-        notes?: PdfChapterEditorNotesConfig;
-        bookmarks?: PdfChapterEditorBookmarksConfig;
-    };
-    features?: ChapterViewerFeaturesConfig;
+    /**
+     * 推荐：统一配置（manifest + 笔记/书签回调 + 可选 features）
+     */
+    options?: ChapterViewerOptions;
+    /**
+     * @deprecated 请改用 `options`
+     */
+    editorOptions?: Omit<CreatePdfChapterEditorOptions, 'features'>;
+    /**
+     * @deprecated 请并入 `options.features`
+     */
+    features?: ChapterViewerConfig;
     className?: string;
     viewportClassName?: string;
 }
@@ -147,13 +237,45 @@ export declare type ChapterSource = {
     load: () => Promise<ChapterPdfPayload>;
 };
 
+declare interface ChapterStatusEvent {
+    chapterId: string;
+    status: ChapterLoadStatus;
+    /** 仅在 status === 'error' 时有意义 */
+    error?: {
+        message: string;
+        code?: number;
+    };
+}
+
 export { ChapterTreeNode }
 
 export { ChapterTreePanel }
 
 export { ChapterViewerCatalog }
 
-/** 章节渲染器集成功能开关（与 demo 默认样式对齐） */
+/**
+ * 用户侧功能配置（简化写法）：
+ * - 省略或 `true`：开启并使用默认样式
+ * - `false`：关闭
+ * - 对象：开启并覆盖对应字段
+ */
+export declare type ChapterViewerConfig = {
+    markup?: boolean | {
+        styles?: MarkupStylesConfig;
+    };
+    bookmarks?: boolean | {
+        marker?: BookmarkMarkerUiConfig;
+        hover?: HoverBookmarkUiConfig;
+    };
+    notes?: boolean | {
+        marker?: NoteMarkerUiConfig;
+    };
+    zoom?: boolean | ChapterViewerZoomConfig;
+    /** 默认随划线/笔记开启；仅在有扩展按钮或需隐藏内置按钮时配置 */
+    selectionToolbar?: boolean | SelectionToolbarConfig;
+};
+
+/** 渲染器内部使用的规范化功能配置 */
 export declare interface ChapterViewerFeaturesConfig {
     /** 划线/高亮 */
     markup?: {
@@ -163,8 +285,8 @@ export declare interface ChapterViewerFeaturesConfig {
     /** 段落书签（含悬停添加） */
     bookmarks?: {
         enabled?: boolean;
-        marker?: BookmarkMarkerUiConfig_2;
-        hover?: HoverBookmarkUiConfig_2;
+        marker?: BookmarkMarkerUiConfig;
+        hover?: HoverBookmarkUiConfig;
     };
     /** 笔记 */
     notes?: {
@@ -177,27 +299,57 @@ export declare interface ChapterViewerFeaturesConfig {
     zoom?: ChapterViewerZoomConfig;
 }
 
+/** 章节阅读器统一配置（推荐入口） */
+export declare interface ChapterViewerOptions {
+    manifest: ChapterManifest;
+    /** 笔记持久化与弹窗回调 */
+    notes: NoteCallbacks;
+    /** 书签持久化与删除回调 */
+    bookmarks: ParagraphBookmarkCallbacks;
+    chapterPdfLoader?: IChapterPdfLoader;
+    /** 功能开关与样式；省略则全开 */
+    features?: ChapterViewerConfig;
+}
+
 declare interface ChapterViewerZoomConfig {
     /** 是否启用 pinch/滑块缩放容器，默认 true */
     enabled?: boolean;
     min?: number;
     max?: number;
+    /** 文档 scale 初始值；未设置且配置了 pageWidth 时由 pageWidth 按首页宽度推导 */
     initial?: number;
+    /**
+     * 页面布局目标宽度（CSS px）。
+     * 章节 PDF 加载后按 `pageWidth / pdfPageWidth` 设置 document scale，与 RenderLayer / 滚动占位一致。
+     */
+    pageWidth?: number;
 }
 
+/** 生成插件列表 + 规范化后的 features（供 EmbedPDF / PdfChapterViewport 使用） */
+export declare function createChapterViewerBundle(input: ChapterViewerOptions | CreateChapterViewerEditorOptionsInput): {
+    plugins: PluginBatchRegistration<any, any, any, any>[];
+    features: ChapterViewerFeaturesConfig;
+    editorOptions: CreatePdfChapterEditorOptions;
+};
+
 /**
  * 创建带默认划线/笔记/书签/选区 card 的章节编辑器插件包。
- * 传入的 `features` 与默认值浅合并。
  */
 export declare function createChapterViewerEditor(options: CreatePdfChapterEditorOptions): PdfChapterEditorBundle;
 
-export declare function createChapterViewerEditorOptions(input: CreateChapterViewerEditorOptionsInput): Omit<CreatePdfChapterEditorOptions, 'features'>;
+/** 进阶用法：仅生成 editor 配置（不含 features，需自行传给 PdfChapterViewport） */
+export declare function createChapterViewerEditorOptions(input: ChapterViewerOptions | CreateChapterViewerEditorOptionsInput): Omit<CreatePdfChapterEditorOptions, 'features'>;
 
+/** @deprecated 旧版嵌套 `callbacks` 写法，仍兼容 */
 export declare type CreateChapterViewerEditorOptionsInput = {
     manifest: ChapterManifest;
     chapterPdfLoader?: IChapterPdfLoader;
-    bookmarks: PdfChapterEditorBookmarksConfig;
-    notes: PdfChapterEditorNotesConfig;
+    bookmarks: {
+        callbacks: ParagraphBookmarkCallbacks;
+    };
+    notes: {
+        callbacks: NoteCallbacks;
+    };
 };
 
 declare interface CreateEditorUiSchemaOptions {
@@ -240,7 +392,10 @@ export declare interface CreatePdfChapterEditorOptions {
     features?: ChapterViewerFeaturesConfig;
 }
 
-/** 与 demo 对齐的默认集成功能 */
+/** 用户侧默认：省略 `options.features` 即等价于此空对象（全部功能开启） */
+export declare const DEFAULT_CHAPTER_VIEWER_CONFIG: ChapterViewerConfig;
+
+/** 默认全开的功能配置（内部规范化结果） */
 export declare const DEFAULT_CHAPTER_VIEWER_FEATURES: ChapterViewerFeaturesConfig;
 
 /** 与 snippet 主工具栏 mode tabs 对齐的编辑模式 */
@@ -252,13 +407,13 @@ declare const editorSecondaryToolbars: Record<string, ToolbarSchema>;
 export { EmbedPDF }
 
 declare interface HoverBookmarkUiConfig {
-    renderAddIcon?: () => ReactNode;
+    /** 悬停行末「添加书签」自定义图标；无背景 */
+    renderAddIcon?: () => unknown;
     iconSize?: number;
 }
 
 declare interface HoverBookmarkUiConfig_2 {
-    /** 悬停行末「添加书签」自定义图标；无背景 */
-    renderAddIcon?: () => unknown;
+    renderAddIcon?: () => ReactNode;
     iconSize?: number;
 }
 
@@ -469,8 +624,8 @@ declare interface ParagraphBookmarkCallbacks {
 
 declare interface ParagraphBookmarkPluginConfig extends BasePluginConfig {
     callbacks?: ParagraphBookmarkCallbacks;
-    ui?: BookmarkMarkerUiConfig;
-    hover?: HoverBookmarkUiConfig;
+    ui?: BookmarkMarkerUiConfig_2;
+    hover?: HoverBookmarkUiConfig_2;
 }
 
 export declare interface PdfChapterEditorBookmarksConfig {
@@ -516,4 +671,42 @@ export { useCapability }
 
 export { usePdfiumEngine }
 
+/**
+ * 一个虚拟页位的解析结果。`localPageIndex` 是 owner 章节 PDF 内的 0-based 索引。
+ */
+declare interface VirtualPageLocation {
+    globalPageIndex: number;
+    globalPageNumber: number;
+    chapterId: string;
+    localPageIndex: number;
+}
+
+/**
+ * 跨章节 PDF 的「全局页 ↔ (章节, 本地页)」映射。
+ *
+ * 设计要点：
+ * - 「globalPageNumber」是后端 manifest 里的业务页号，可能不连续（极端情况）。
+ * - 「globalPageIndex」是去重后排序的 0-based 紧凑索引，是滚动/虚拟列表使用的页位。
+ *   这样上层 `ChapterScroll` 不必关心业务页号是否连续。
+ */
+declare class VirtualPageMap {
+    private readonly _pages;
+    private readonly _byChapter;
+    private readonly _byGlobalNumber;
+    constructor(pages: VirtualPageLocation[]);
+    get totalPages(): number;
+    /** 顺序返回所有去重后的页位 */
+    list(): readonly VirtualPageLocation[];
+    /** 由 0-based 紧凑索引取页位 */
+    atIndex(globalPageIndex: number): VirtualPageLocation | null;
+    /** 由后端业务页号取页位 */
+    byGlobalNumber(globalPageNumber: number): VirtualPageLocation | null;
+    /** 由 (章节, 本地页) 反查到 owner 视图下的全局位置；非 owner 章节会返回 null */
+    toGlobal(chapterId: string, localPageIndex: number): VirtualPageLocation | null;
+    /** 该章节在虚拟视图中实际「被采用」的页（owner 命中的） */
+    pagesOfChapter(chapterId: string): readonly VirtualPageLocation[];
+    /** 拿一个章节首次出现的虚拟索引（用于 scrollToChapter） */
+    firstIndexOfChapter(chapterId: string): number;
+}
+
 export { }

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,sBAAsB,EACtB,gCAAgC,EAChC,+BAA+B,EAC/B,oBAAoB,EACpB,4BAA4B,EAC5B,wBAAwB,EACxB,QAAQ,EACR,aAAa,GACd,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,YAAY,EACV,qBAAqB,EACrB,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,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"}