@embedpdf-editor/vue3-chapter-viewer 0.3.2 → 0.3.4

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,49 @@ 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` |
+| `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,6 +310,83 @@ usePdfiumEngine({ wasmUrl: '/assets/pdfium.wasm', worker: true });
 
 使用 `worker: true` 时，部署环境需要允许 worker 加载 wasm。若只在 worker 模式失败，可先用 `worker: false` 定位资源或响应头问题。
 
+## `features` 配置示例
+
+完整字段表见 [React README 的 `features` 配置](../react-chapter-viewer/README.md#features-配置)。
+
+### 划线颜色、粗细与位置
+
+```ts
+features: {
+  markup: {
+    styles: {
+      highlight: { color: '#fef08a', opacity: 0.45 },
+      underline: { color: '#dc2626', thickness: 1.5, offsetY: 2.5 },
+      squiggly: { color: '#dc2626', thickness: 1.5, offsetY: 4 },
+      strikeout: { color: '#64748b', offsetY: 0 },
+    },
+  },
+},
+```
+
+`offsetY` 为 PDF 点、正值向下；波浪线默认 `4`，减轻盖住字形。`markup: false` 关闭划线。
+
+### 点击已有划线：删除
+
+选中高亮/下划线/波浪线/删除线后，默认在标注下方显示「删除」。可自定义：
+
+```ts
+import { h } from 'vue';
+
+features: {
+  markup: {
+    annotationMenu: {
+      renderMenu: ({ onDelete }) =>
+        h('button', { type: 'button', onClick: onDelete }, '移除'),
+    },
+  },
+},
+```
+
+`PdfChapterViewport` 上传 `annotation-selection-menu` 时宿主优先，未渲染时再回退默认删除菜单。
+
+### 笔记、书签图标
+
+```ts
+import { h } from 'vue';
+
+features: {
+  notes: {
+    marker: {
+      renderIcon: () => h('img', { src: '/icons/note.svg', width: 20, height: 20 }),
+      iconSize: 22,
+      renderMenuActions: ({ onEdit, onDelete }) =>
+        h('div', [
+          h('button', { onClick: onEdit }, '编辑'),
+          h('button', { onClick: onDelete }, '删除'),
+        ]),
+    },
+  },
+  bookmarks: {
+    marker: { renderIcon: () => h('img', { src: '/icons/bookmark.svg' }) },
+    hover: { renderAddIcon: () => h('span', '＋') },
+  },
+},
+```
+
+### 选区工具栏
+
+```ts
+features: {
+  selectionToolbar: {
+    hiddenBuiltinActions: ['strikeout'],
+    extraActions: [{ id: 'cite', label: '引用', order: 10 }],
+  },
+},
+```
+
+配合 `ChapterPdfViewer` 的 `@extra-selection-action` 或 `build-selection-menu`。
+
 ## 进阶组合
 
 内置 `ChapterPdfViewer` 已完成插件注册和章节视口渲染。需要插入自定义 shell、目录、工具栏或直接访问 registry 时，可以使用低层组合：
@@ -271,19 +415,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#标注导入导出)。
 
 ## 常见问题