@embedpdf-editor/vue3-chapter-viewer 0.3.3 → 0.3.5

package/README.md

@@ -104,18 +104,28 @@ const options: ChapterViewerOptions = {
 </style>
 ```
 
-## `ChapterViewerOptions`
-
-`options` 是三端渲染器的统一配置入口。
+## 配置总览
 
-| 字段 | 说明 |
+| 层级 | 说明 |
 | --- | --- |
-| `manifest` | 章节清单，描述每章 PDF 和全局页码关系 |
-| `notes` | 附注加载、创建、更新、删除回调 |
-| `bookmarks` | 段落书签加载、持久化、删除确认回调 |
-| `chapterPdfLoader` | 可选：全局 PDF 预处理/拉取（见下文） |
-| `overlapStrategy` | 可选：同一全局页多章节重叠时，用先/后出现的章节 PDF 渲染 |
-| `features` | 可选：功能开关与样式配置，省略时使用默认能力 |
+| `ChapterViewerOptions` | `ChapterPdfViewer` 的 `options`：**manifest**、**notes**、**bookmarks**、**features** 等 |
+| `ChapterViewerConfig` | `options.features`：划线样式、图标、缩放、选区工具栏 |
+| `ChapterPdfViewer` props | `class-name`、`build-selection-menu`、`@extra-selection-action` 等 |
+
+省略 `features` 时默认全部开启。字段说明与 [React 包 README](../react-chapter-viewer/README.md) 一致，下文为 Vue 3 用法示例。
+
+---
+
+## `ChapterViewerOptions`
+
+| 字段 | 必填 | 说明 |
+| --- | --- | --- |
+| `manifest` | 是 | `ChapterManifest` |
+| `notes` | 是 | `NoteCallbacks`（须 `onCreateNote` 或 `onRequestCreateNote`） |
+| `bookmarks` | 是 | `ParagraphBookmarkCallbacks`（删除须 `onRequestRemove` 返回 `true`） |
+| `chapterPdfLoader` | 否 | 全局 `IChapterPdfLoader` |
+| `overlapStrategy` | 否 | 默认 `{ kind: 'first-wins' }` |
+| `features` | 否 | 见 [`features` 配置](#features-配置) |
 
 ### Manifest
 
@@ -136,6 +146,20 @@ type ChapterManifest = {
 
 `globalPageRange` 和 `localPageRange` 都是闭区间，且页数必须一致。`chapterId` 同时作为内部 `documentId`，需要在整本书内唯一。
 
+| 字段 | 说明 |
+| --- | --- |
+| `chapterId` / `title` | 唯一 ID 与标题 |
+| `globalPageRange` / `localPageRange` | 全局与 PDF 内闭区间，页数须一致 |
+| `source` | `url` \| `buffer` \| `load()`，见下文 |
+| `encrypted` | 可选标记；密码流见 [加密 PDF](#加密-pdf-与-passwordprovider) |
+| `ownedGlobalPages` | `overlapStrategy: explicit` 时使用 |
+
+### `notes` / `bookmarks` 回调
+
+**`NoteCallbacks`：** `loadNotes`、`onCreateNote` \| `onRequestCreateNote`（二选一）、`onRequestEditNote`、`onUpdateNote`、`onDeleteNote`。
+
+**`ParagraphBookmarkCallbacks`：** `load`、`persist`、`onRequestRemove`（返回 `true` 才删除）、`onRemoveSuccess`。
+
 ### 嵌套目录树与重叠页
 
 侧栏目录支持**任意层级**（`ChapterTreePanel` + `ChapterTreeNode.children`）。引擎滚动用的 `manifest.chapters` 是**扁平列表**：父节点页范围可包含子节点，相邻/重叠全局页由 **owner 策略** 决定只渲染一个章节的 PDF，避免同页画两遍。
@@ -227,6 +251,50 @@ const options: ChapterViewerOptions = {
 };
 ```
 
+### 加密 PDF 与 `passwordProvider`
+
+```ts
+import { CallbackPasswordProvider } from '@embedpdf-editor/vue3-chapter-viewer';
+
+// 在 createPdfChapterEditor / 自定义 bundle 中传入
+const passwordProvider = new CallbackPasswordProvider(async (chapter, attempt) =>
+  askPassword(chapter.chapterId, attempt),
+);
+```
+
+---
+
+## `features` 配置
+
+`ChapterViewerConfig`：每项可 `true` | `false` | 对象。
+
+| 模块 | 主要字段 |
+| --- | --- |
+| `markup` | `enabled`、`styles`（`color`/`thickness`/`offsetY`/`opacity`）、`annotationMenu`（`enabled`、`renderMenu`） |
+| `bookmarks` | `enabled`、`marker`（`renderIcon`、`iconSize`）、`hover`（`renderAddIcon`、`iconSize`） |
+| `notes` | `enabled`、`marker`（`renderIcon`、`renderMenuActions`、`iconSize`、`highlightColor`） |
+| `zoom` | `enabled`（默认 true）、`min` 0.5、`max` 3、`initial` 1、`pageWidth`；实际上限由 `[data-chapter-scroll-viewport]` 宽度决定，resize 时自动更新 |
+| `scrollViewport` | `background`（默认 `#f1f5f9`），滚动视口背景 |
+| `selectionToolbar` | `enabled`、`hiddenBuiltinActions`、`extraActions` |
+
+默认划线 `offsetY`：`squiggly` 为 **4**。内置工具条按钮：`highlight` | `underline` | `squiggly` | `strikeout` | `note`。
+
+---
+
+## `ChapterPdfViewer` 组件
+
+| Prop / 事件 | 说明 |
+| --- | --- |
+| `engine` / `options` | 必填引擎与配置 |
+| `class-name` / `viewport-class-name` | 布局 |
+| `build-selection-menu` | 包装划词菜单 |
+| `@extra-selection-action` | 扩展工具条 |
+| `#default` 子节点 | 视口内插槽 |
+
+`PdfChapterViewport`：`annotation-selection-menu`（宿主优先于默认划线删除）、`features` 等。
+
+---
+
 ## Worker 与 WASM
 
 `usePdfiumEngine()` 默认使用 `@embedpdf/engines` 内置的 PDFium CDN wasm 地址，并默认启用 worker：
@@ -243,9 +311,9 @@ usePdfiumEngine({ wasmUrl: '/assets/pdfium.wasm', worker: true });
 
 使用 `worker: true` 时，部署环境需要允许 worker 加载 wasm。若只在 worker 模式失败，可先用 `worker: false` 定位资源或响应头问题。
 
-## `features` 自定义：划线样式、删除菜单、图标
+## `features` 配置示例
 
-与 React 包相同，通过 `options.features` 配置。类型见 `@embedpdf-editor/vue3-chapter-viewer`（来自 `chapter-viewer`）。
+完整字段表见 [React README 的 `features` 配置](../react-chapter-viewer/README.md#features-配置)。
 
 ### 划线颜色、粗细与位置
 
@@ -348,19 +416,24 @@ const { plugins, features } = createChapterViewerBundle(options);
 
 ## 标注导入导出
 
-包内直接导出章节标注 IO：
-
 ```ts
 import {
+  exportChapterAnnotations,
   exportAllChapterAnnotations,
   importChapterAnnotationsArchive,
-  chapterAnnotationsArchiveToJson,
-  parseChapterAnnotationsArchiveJson,
+  CHAPTER_ANNOTATIONS_ARCHIVE_VERSION,
   useRegistry,
 } from '@embedpdf-editor/vue3-chapter-viewer';
 ```
 
-导出格式包含 `bookmarks`、`notes`、`markup`，版本常量为 `CHAPTER_ANNOTATIONS_ARCHIVE_VERSION`。导入时可选择 `mode: 'replace' | 'merge'`，并可传 `persistNotes` / `persistBookmarks` 把导入结果写回业务存储。
+| 选项 | 说明 |
+| --- | --- |
+| `mode` | `replace` \| `merge` |
+| `bookmarks` / `notes` / `markup` | 导入导出子集，默认 true |
+| `ensureChapterLoaded` | 默认 true |
+| `persistNotes` / `persistBookmarks` | 导入后写回存储 |
+
+详见 [React README 标注章节](../react-chapter-viewer/README.md#标注导入导出)。
 
 ## 常见问题