@embedpdf-editor/chapter-snippet 0.3.6 → 1.0.2

package/dist/embedpdf-chapter.d.ts

@@ -43,7 +43,7 @@ export declare function buildParagraphBookmarkAnchor(chapterId: string, localPag
 }): ParagraphBookmark['anchor'];
 
 /** 选区浮窗 card 内置操作 */
-declare type BuiltinSelectionToolbarAction = 'highlight' | 'underline' | 'squiggly' | 'strikeout' | 'note';
+declare type BuiltinSelectionToolbarAction = 'copy' | 'highlight' | 'underline' | 'squiggly' | 'strikeout' | 'note';
 
 /**
  * 回调型：把决策交给业务侧异步函数（最常用）。
@@ -140,8 +140,16 @@ declare interface ChapterManagerCapability {
     getVirtualPageMap(): VirtualPageMap;
     /** ChapterScrollPlugin 在可见页位变化时调用，用以驱动按需加载 */
     setVisibleGlobalPages(visiblePageIndices: number[]): void;
-    /** 显式触发某章节加载（如点击章节标题跳转时） */
+    /** 显式触发某章节加载（分段章节仅加载第 0 段） */
     ensureChapterLoaded(chapterId: string): Promise<ChapterLoadStatus>;
+    /** 加载章内指定分段 PDF */
+    ensureSegmentLoaded(chapterId: string, segmentIndex: number): Promise<ChapterLoadStatus>;
+    /** 加载章内全部分段（导出划线等） */
+    ensureAllSegmentsLoaded(chapterId: string): Promise<ChapterLoadStatus>;
+    /** 将章内 localPageIndex 映射为 documentManager 的 documentId + 段内页码 */
+    resolvePageDocument(chapterId: string, localPageIndex: number): ChapterPageDocumentRef | null;
+    getSegmentPlan(chapterId: string): ChapterSegmentPlan | null;
+    isSegmentLoaded(chapterId: string, segmentIndex: number): boolean;
     /** 状态查询 */
     getChapterStatus(chapterId: string): ChapterLoadStatus;
     getChapter(chapterId: string): ChapterDescriptor | null;
@@ -156,10 +164,8 @@ declare interface ChapterManagerCapability {
 /**
  * 章节生命周期管理：以章节为粒度懒加载/预取/卸载 PDF 文件，并屏蔽密码协议细节。
  *
- * 关键不变量：
- * - 每个章节对 DocumentManager 用 `documentId === chapterId`，从而保持 1:1 缓存。
- * - 视觉上的「activeDocumentId」由本插件根据当前可见页位维护；上层无须感知。
- * - 渲染层最终始终通过 `(chapterId, localPageIndex)` 索引到 owner 章节的 PDF 文档。
+ * - 单 URL：`documentId === chapterId`
+ * - 多段 URL：`documentId === chapterId#s{index}`，滚动时按段加载
  */
 export declare class ChapterManagerPlugin extends BasePlugin<ChapterManagerPluginConfig, ChapterManagerCapability> {
     static readonly id: "chapter-manager";
@@ -171,15 +177,11 @@ export declare class ChapterManagerPlugin extends BasePlugin<ChapterManagerPlugi
     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 readonly pendingChapterLoadPromises;
+    private readonly pendingSegmentLoadPromises;
     private unloadTimer;
     private documentManagerUnsubs;
     constructor(id: string, registry: PluginRegistry);
@@ -187,16 +189,19 @@ export declare class ChapterManagerPlugin extends BasePlugin<ChapterManagerPlugi
     protected buildCapability(): ChapterManagerCapability;
     destroy(): void;
     private setManifestInternal;
-    /** manifest 就绪后预取前 N 章（不依赖滚动视口是否已算出可见页） */
     private eagerPrefetchFromManifest;
     private findChapter;
-    private isOwnedChapter;
+    private getSegmentPlanForChapter;
+    private isSegmentDocumentOpen;
+    private syncChapterStatusFromDocuments;
     private handleVisibleChange;
     private collectIdleChapters;
     ensureChapterLoaded(chapterId: string): Promise<ChapterLoadStatus>;
+    ensureAllSegmentsLoaded(chapterId: string): Promise<ChapterLoadStatus>;
+    ensureSegmentLoaded(chapterId: string, segmentIndex: number): Promise<ChapterLoadStatus>;
+    private ensureSingleDocumentChapter;
     private resolvePdfPayload;
-    private startLoad;
-    /** 阻塞等待该章节状态进入 loaded / error / password-required / closed */
+    private startLoadSegment;
     private waitForTerminalStatus;
     private handleDocumentError;
     private closeChapter;
@@ -238,6 +243,11 @@ export declare type ChapterNoteRequestEditDetail = {
     anchor: NoteAnchor;
 };
 
+declare interface ChapterPageDocumentRef {
+    documentId: string;
+    pageIndex: number;
+}
+
 /**
  * Backend-supplied chapter contract.
  *
@@ -253,6 +263,21 @@ export declare type ChapterPdfPayload = {
     buffer: ArrayBuffer;
 };
 
+declare interface ChapterSegmentInfo {
+    index: number;
+    url: string;
+    localPageStart: number;
+    localPageEnd: number;
+    documentId: string;
+}
+
+declare interface ChapterSegmentPlan {
+    chapterId: string;
+    threshold: number;
+    pageCount: number;
+    segments: ChapterSegmentInfo[];
+}
+
 /** 划词工具栏扩展操作事件 */
 export declare type ChapterSelectionActionDetail = {
     actionId: string;
@@ -272,6 +297,14 @@ export declare type ChapterSource = {
 /** 按章预处理：拉取、解密、转换后返回 url 或 buffer */
 | {
     load: () => Promise<ChapterPdfPayload>;
+}
+/**
+* 章内多 PDF 分段（后端已按段拆分）。
+* `urls.length` 须为 ceil(章页数 / segmentPageThreshold)。
+*/
+| {
+    urls: string[];
+    segmentPageThreshold: number;
 };
 
 declare interface ChapterStatusEvent {
@@ -429,6 +462,9 @@ export declare type ContainerInitConfig = ChapterViewerContainerConfig & {
     target: Element;
 };
 
+/** 将划选文本写入系统剪贴板（Clipboard API，失败时回退 execCommand） */
+export declare function copyTextToClipboard(text: string): Promise<boolean>;
+
 /** 生成插件列表 + 规范化后的 features（供 EmbedPDF / PdfChapterViewport 使用） */
 export declare function createChapterViewerBundle(input: ChapterViewerOptions | CreateChapterViewerEditorOptionsInput): {
     plugins: PluginBatchRegistration<any, any, any, any>[];
@@ -567,7 +603,10 @@ declare interface HoverBookmarkUiConfig_2 {
  * 适合：所有章节走同一套 API、在内存中解密后再以 buffer 打开、动态签名 URL 等。
  */
 export declare interface IChapterPdfLoader {
-    loadPdf(chapter: ChapterDescriptor): Promise<ChapterPdfPayload>;
+    /**
+     * @param segmentIndex 章内分段索引；单 URL 章节为 0 或省略
+     */
+    loadPdf(chapter: ChapterDescriptor, segmentIndex?: number): Promise<ChapterPdfPayload>;
 }
 
 /**
@@ -831,6 +870,8 @@ declare interface SelectionToolbarConfig {
     enabled?: boolean;
     /** 隐藏部分内置按钮 */
     hiddenBuiltinActions?: BuiltinSelectionToolbarAction[];
+    /** 自定义复制按钮图标；不提供则使用默认图标 */
+    renderCopyIcon?: () => unknown;
     /** 扩展操作（由宿主在 buildSelectionMenu 或 onExtraAction 中处理） */
     extraActions?: SelectionToolbarExtraAction[];
 }