@embedpdf-editor/chapter-snippet 0.3.3 → 0.3.5

package/README.md

@@ -1,6 +1,8 @@
 # @embedpdf-editor/chapter-snippet
 
-框架无关的章节 PDF 阅读器运行时。它把 Preact 阅读器封装成 Web Component，适合 Vue 2、传统页面、微前端或任何不想引入 React/Vue3 渲染器的宿主。
+框架无关的章节 PDF 阅读器运行时。它把 Preact 阅读器封装成 Web Component。
+
+**Vue 2 请使用本包**（`@embedpdf-editor/chapter-snippet`），不要用已移除的 `@embedpdf-editor/vue2-chapter-viewer`。宿主为 Vue 2 / 传统页面 / 微前端，或任何不想引入 React/Vue3 渲染器的场景。
 
 能力与 React/Vue3 渲染器保持一致：多章连续滚动、划线/高亮、附注、段落书签、章节目录和标注导入导出。
 
@@ -12,7 +14,7 @@ pnpm add @embedpdf-editor/chapter-snippet
 
 ## Vite
 
-`chapterSnippetViteResolve()` 用于 Vue2/snippet 场景：
+`chapterSnippetViteResolve()` 用于 Vite + Vue2/snippet 场景：
 
 ```ts
 // vite.config.ts
@@ -31,6 +33,22 @@ export default defineConfig({
 | `server.headers` | 开发环境添加 COOP/COEP，满足 worker/wasm 常见要求 |
 | `optimizeDeps.exclude` | 避免 Vite 二次预构建 snippet 和 PDFium 引擎 |
 
+## Vue CLI / Webpack
+
+**无需修改 `vue.config.js`。** 安装后直接：
+
+```js
+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` 放到静态目录）。
+
+`@embedpdf-editor/chapter-snippet/webpack` 为**可选**辅助（仅 monorepo Vue 2.6 解析、或自定义 devServer COOP/COEP），普通用户不必使用。
+
+完整示例见 `examples/chapter-viewer-demo-vue2`。
+
 ## 快速开始
 
 不需要把 `pdfium.wasm` 手动放到宿主项目的 `public/`。默认会从 `@embedpdf-editor/chapter-snippet/dist/pdfium.wasm` 加载。只有当你要走 CDN 或自定义静态域名时，才需要传 `wasmUrl`。
@@ -114,6 +132,62 @@ viewer?.addEventListener(CHAPTER_SNIPPET_EVENTS.ready, (event) => {
 
 旧版本的 `editorInput` 仍可使用，但新代码应改为 `options`。`options.features` 会参与合并，顶层 `features` 仅作为兼容覆盖保留。
 
+### `ChapterViewerOptions`（与 React / Vue3 一致）
+
+| 字段 | 说明 |
+| --- | --- |
+| `manifest` | 章节目录，见 [React README Manifest](../react-chapter-viewer/README.md#manifest) |
+| `notes` | `NoteCallbacks`，见 [React README](../react-chapter-viewer/README.md#notes附注回调) |
+| `bookmarks` | `ParagraphBookmarkCallbacks`，见 [React README](../react-chapter-viewer/README.md#bookmarks段落书签回调) |
+| `chapterPdfLoader` / `overlapStrategy` | 自定义 PDF 加载与重叠页策略 |
+| `features` | 功能开关与 UI 定制，见下 |
+
+加密 PDF 可在底层 `createPdfChapterEditor` 选项中设置 `passwordProvider`（如 `CallbackPasswordProvider` from `@embedpdf-editor/chapter-core`）。
+
+### `features` 配置
+
+与 React / Vue3 **同一套** `ChapterViewerConfig`（`@embedpdf-editor/chapter-viewer`）。完整字段表见 [React README：`features` 配置](../react-chapter-viewer/README.md#features-配置)。
+
+| 模块 | 要点 |
+| --- | --- |
+| `markup` | `styles` 四类划线；`annotationMenu` 默认选中后在下方显示「删除」；`squiggly.offsetY` 默认 **4** |
+| `bookmarks` | `marker` / `hover` 自定义图标 |
+| `notes` | `marker.renderIcon`、`renderMenuActions`、`highlightColor` |
+| `zoom` | `pageWidth`、`min` / `max` / `enabled` |
+| `selectionToolbar` | `hiddenBuiltinActions`、`extraActions`；扩展动作监听 `selectionExtraAction` 事件 |
+
+```js
+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 },
+    },
+    annotationMenu: {
+      enabled: true,
+      renderMenu: ({ onDelete }) => {
+        const btn = document.createElement('button');
+        btn.textContent = '移除';
+        btn.onclick = onDelete;
+        return btn;
+      },
+    },
+  },
+  notes: {
+    marker: {
+      renderIcon: () => /* DOM */,
+      renderMenuActions: ({ onEdit, onDelete }) => /* DOM */,
+    },
+  },
+  selectionToolbar: {
+    extraActions: [{ id: 'cite', label: '引用', order: 10 }],
+  },
+},
+```
+
+`renderMenu` / `renderIcon` 在 snippet（Preact）内执行，请返回 **DOM 或 Preact 节点**；Vue 2 宿主不要用 `h()` 直接塞进 Shadow DOM。
+
 ## 事件
 
 snippet 通过 DOM `CustomEvent` 把需要宿主 UI 参与的动作抛出来。
@@ -169,6 +243,24 @@ import {
 
 在 snippet 中可通过 `chapter-viewer-ready` 事件拿到 `registry`，再调用这些 API。导出格式包含 `bookmarks`、`notes`、`markup`，版本常量为 `CHAPTER_ANNOTATIONS_ARCHIVE_VERSION`。
 
+| 选项 | 说明 |
+| --- | --- |
+| `mode` | `replace` 清空后导入；`merge` 合并 |
+| `ensureChapterLoaded` | 默认 true，导入 markup 前打开 PDF |
+| `bookmarks` / `notes` / `markup` | 默认 true，可关闭某一类 |
+| `persistNotes` / `persistBookmarks` | 导入后写回业务存储 |
+
+示例见 `examples/chapter-viewer-demo-vue2/src/components/AnnotationsDemoBar.vue`。
+
+## 与 React / Vue3 渲染器的区别
+
+| 项 | React / Vue3 | chapter-snippet（本包，含 Vue 2） |
+| --- | --- | --- |
+| 运行时 | 框架内 `editor-engine` 组件 | Shadow DOM Web Component + Preact |
+| 初始化 | `<ChapterPdfViewer options={...} />` | `ChapterEmbedPDF.init({ type: 'container', target, options })` |
+| Registry | hook / ref | `chapter-viewer-ready` → `detail.registry` |
+| Vite | `chapterViewerViteResolve()` | `chapterSnippetViteResolve()` |
+
 ## 常见问题
 
 | 现象 | 处理 |