@embedpdf-editor/chapter-snippet 0.3.2 → 0.3.4

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 渲染器保持一致：多章连续滚动、划线/高亮、附注、段落书签、章节目录和标注导入导出。
 
@@ -114,6 +116,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 +227,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()` |
+
 ## 常见问题
 
 | 现象 | 处理 |

package/dist/embedpdf-chapter.d.ts

@@ -320,6 +320,7 @@ export { ChapterViewerCatalog }
 export declare type ChapterViewerConfig = {
     markup?: boolean | {
         styles?: MarkupStylesConfig;
+        annotationMenu?: MarkupAnnotationMenuConfig;
     };
     bookmarks?: boolean | {
         marker?: BookmarkMarkerUiConfig;
@@ -341,6 +342,7 @@ export declare interface ChapterViewerFeaturesConfig {
     markup?: {
         enabled?: boolean;
         styles?: MarkupStylesConfig;
+        annotationMenu?: MarkupAnnotationMenuConfig;
     };
     /** 段落书签（含悬停添加） */
     bookmarks?: {
@@ -596,6 +598,20 @@ declare interface IPasswordProvider {
     getCachedPassword?(chapterId: string): string | null;
 }
 
+declare interface MarkupAnnotationMenuActionCtx {
+    pageIndex: number;
+    annotationId: string;
+    onDelete: () => void;
+}
+
+/** 点击已创建的划线标注时，选区菜单（删除等） */
+declare interface MarkupAnnotationMenuConfig {
+    /** 是否显示默认删除按钮，默认 true */
+    enabled?: boolean;
+    /** 完全自定义菜单；不提供则显示默认「删除」按钮 */
+    renderMenu?: (ctx: MarkupAnnotationMenuActionCtx) => unknown;
+}
+
 /** 单种划线的样式（颜色、粗细、垂直偏移，PDF 点） */
 declare interface MarkupKindStyle {
     /** 描边/填充色，如 #facc15 */