@embedpdf-editor/chapter-snippet 1.0.0 → 1.0.2

package/README.md

@@ -43,7 +43,18 @@ import ChapterEmbedPDF from '@embedpdf-editor/chapter-snippet';
 
 发包构建会对 `dist/embedpdf-chapter.js` 做语法降级（去掉 `??` 等 ES2020 语法），Webpack / Vue CLI 默认可 parse。默认 `wasmUrl` 指向 jsDelivr 上的 `pdfium.wasm`，无需复制到 `public/`。
 
-离线或内网部署时，可传 `wasmUrl: '/pdfium.wasm'`（自行把 `node_modules/@embedpdf-editor/chapter-snippet/dist/pdfium.wasm` 放到静态目录）。
+离线或内网部署时，可传 `wasmUrl`（**init 顶层**，与 `options` 同级）：
+
+```js
+// 相对路径：自行把 dist/pdfium.wasm 放到静态目录
+wasmUrl: '/pdfium.wasm',
+
+// 自有 OSS / CDN（完整 HTTPS 地址，示例）
+wasmUrl:
+  'https://hep-editor.oss-cn-beijing.aliyuncs.com/public/editor-public/js/pdfium.wasm',
+```
+
+详见 [docs/get-started/01-installation.md](../../docs/get-started/01-installation.md)。
 
 `@embedpdf-editor/chapter-snippet/webpack` 为**可选**辅助（仅 monorepo Vue 2.6 解析、或自定义 devServer COOP/COEP），普通用户不必使用。
 
@@ -132,6 +143,25 @@ viewer?.addEventListener(CHAPTER_SNIPPET_EVENTS.ready, (event) => {
 
 旧版本的 `editorInput` 仍可使用，但新代码应改为 `options`，并把 `features` 写在 `options.features` 或顶层 `features`。
 
+### 章内多 PDF 分段（`source.urls[]`）
+
+```js
+source: {
+  urls: [part0Url, part1Url, part2Url],
+  segmentPageThreshold: 5, // 例：13 页 → 3 段
+},
+```
+
+- 先加载第一段，滚动懒加载后续段；`localPageIndex` 仍为章内连续页。
+- 引擎内部 `documentId` 为 `chapterId#s0`、`#s1`…；**业务 API / 数据库只存 `chapterId` + `localPageIndex`**。
+- `chapterPdfLoader.loadPdf(chapter, segmentIndex)` 第二参数为段索引（0-based）。
+
+[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)
+
+### 按章持久化
+
+`options.notes` / `options.bookmarks` 回调里的 `chapterId`、`localPageIndex` 与单 URL 章相同。划线备份用 `exportChapterAnnotations`，JSON 键为 `chapters[chapterId]`（导出 markup 时会拉全部分段）。
+
 ### `ChapterViewerOptions`（与 React / Vue3 一致）
 
 | 字段 | 说明 |
@@ -155,7 +185,7 @@ viewer?.addEventListener(CHAPTER_SNIPPET_EVENTS.ready, (event) => {
 | `notes` | `marker.renderIcon`、`renderMenuActions`、`highlightColor` |
 | `zoom` | `pageWidth`、`min` / `max` / `enabled`；实际上限不超过 `[data-chapter-scroll-viewport]` 宽度，resize 时自动 clamp |
 | `scrollViewport` | `background`（默认 `#f1f5f9`），`[data-chapter-scroll-viewport]` 背景 |
-| `selectionToolbar` | `hiddenBuiltinActions`、`extraActions`；扩展动作监听 `selectionExtraAction` 事件 |
+| `selectionToolbar` | `hiddenBuiltinActions`（含 `copy`）、`renderCopyIcon`、`extraActions`；扩展动作监听 `selectionExtraAction` 事件 |
 
 ```js
 features: {
@@ -182,12 +212,27 @@ features: {
     },
   },
   selectionToolbar: {
+    // 复制默认开启，浮窗最左侧；隐藏：hiddenBuiltinActions: ['copy']
+    renderCopyIcon: () => {
+      const span = document.createElement('span');
+      span.textContent = '📋';
+      span.setAttribute('aria-hidden', 'true');
+      return span;
+    },
     extraActions: [{ id: 'cite', label: '引用', order: 10 }],
   },
 },
 ```
 
-`renderMenu` / `renderIcon` 在 snippet（Preact）内执行，请返回 **DOM 或 Preact 节点**；Vue 2 宿主不要用 `h()` 直接塞进 Shadow DOM。
+划词后点**复制**会将选中文本写入剪贴板。程序化：
+
+```js
+import { copyTextToClipboard } from '@embedpdf-editor/chapter-snippet';
+
+await copyTextToClipboard('文本');
+```
+
+`renderMenu` / `renderIcon` / `renderCopyIcon` 在 snippet（Preact）内执行，请返回 **DOM 或 Preact 节点**；Vue 2 宿主不要用 `h()` 直接塞进 Shadow DOM。
 
 ## 事件
 
@@ -247,11 +292,21 @@ import {
 | 选项 | 说明 |
 | --- | --- |
 | `mode` | `replace` 清空后导入；`merge` 合并 |
-| `ensureChapterLoaded` | 默认 true，导入 markup 前打开 PDF |
+| `ensureChapterLoaded` | 默认 true；含 markup 的分段章会加载 **全部段** 再合并页码 |
 | `bookmarks` / `notes` / `markup` | 默认 true，可关闭某一类 |
 | `persistNotes` / `persistBookmarks` | 导入后写回业务存储 |
 
-示例见 `examples/chapter-viewer-demo-vue2/src/components/AnnotationsDemoBar.vue`。
+示例见 `examples/chapter-viewer-demo-vue2/src/components/AnnotationsDemoBar.vue`。详见 [10-annotations-io.md](../../docs/get-started/10-annotations-io.md)。
+
+## 教程索引
+
+| 主题 | 文档 |
+| --- | --- |
+| 目录 | [docs/get-started/README.md](../../docs/get-started/README.md) |
+| `wasmUrl`（含 OSS 示例） | [01-installation.md](../../docs/get-started/01-installation.md) |
+| 划词复制 | [07-selection-toolbar.md](../../docs/get-started/07-selection-toolbar.md) |
+| 事件常量 | [11-events-callbacks-and-component-api.md](../../docs/get-started/11-events-callbacks-and-component-api.md) |
+| 分段 + 按章存储 | [12-segmented-pdf-and-per-chapter-storage.md](../../docs/get-started/12-segmented-pdf-and-per-chapter-storage.md) |
 
 ## 与 React / Vue3 渲染器的区别
 
@@ -277,3 +332,4 @@ import {
 | 只显示空白 | 确认宿主元素有高度，且没有被父容器 `overflow`/flex 布局压到 0 |
 | 划词后没有笔记弹窗 | 监听 `chapter-note-request-create`，保存后调用 `detail.complete(noteId)` |
 | Vue/Vite 开发环境异常预构建 | 使用 `chapterSnippetViteResolve()`，确保 snippet 和 PDFium 引擎没有被 optimizeDeps 预构建 |
+| 分段章存了 `#sN` | 业务层只用 `chapterId`；引擎段 ID 勿写入库 |

package/dist/embedpdf-chapter.d.ts

@@ -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>;
 }
 
 /**