# @embedpdf/plugin-annotation 中文文档

规范地址：https://npmcn.com/package/%40embedpdf/plugin-annotation/

版本：3\.2\.0
npm 元数据更新时间：2026-11-11T23:25:28.169Z
中文译文更新时间：2026-11-13T14:45:11.237Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40embedpdf/plugin-annotation
原文对照：https://npmcn.com/package/%40embedpdf/plugin-annotation/?lang=original
项目主页：https://github.com/embedpdf/embed-pdf-viewer#readme
源码仓库：https://github.com/embedpdf/embed-pdf-viewer

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.9 MB，33 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：11 个
- 首次发布：2025-06-12T17:20:51.955Z
- 最新版本发布：2026-11-11T23:25:27.851Z
- 近 30 天下载量：1804069（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：114（近 12 个月 64 个）

## 中文简介

注释特性插件:纯注释-核心被线接入引擎存储器(优化创建/patch/删除)+交互中枢(环境编辑+绘图工具). 行为(形式)插入这里.

## 安装

```sh
npm install @embedpdf/plugin-annotation
```

也可以使用：`pnpm add @embedpdf/plugin-annotation`、`yarn add @embedpdf/plugin-annotation`、`bun add @embedpdf/plugin-annotation`

## README

# @embedpdf/plugin - 注释

注释插件: 绘图、 选择、 移动、 重排、 输入和输入 删除注释, 在引擎拥有的文档上 。 纯洁的电线 [`@embedpdf/core-annotation`](https://npmcn.com/package/core/annotation/README.md) 到发动机 和互动中心。 它没有框架代码;适配器使其 读取.

## 三种数据,每个拥有者一个

用户所看到的是由三种数据构建的. 每个都有一个 主人,没有别的东西写.

| 数据 | 这是什么 | 拥有者 | 由 |
| --- | --- | --- | --- |
| **确认** | 每个注释记录引擎确认, 及其外观版本 | 记录镜像( e)`sync/records.ts`, (中文(简体) ), `records.get()` | 任何会话中确认的文档事件和负载 |
| **待处理** | 此会话的更改引擎尚未回复, 每个用户动作一次 | 内核的更改队列( n)`ctx.changes`(中文(简体) ) | 用户动作第一阶段; 引擎回答后退出 |
| **第二届会议** | 选择、 徘徊、 手势进行中、 文本编辑、 工具设置、 为新记录所持有的对象编号 | `session` 在插件状态中( e)`model.ts`(中文(简体) ) | 这是核心 `update` |

记录镜显示引擎之上的未决更改 已确认(`records.view()`:它重新播放它们,逐个操作,通过 `predictRecords`,同样的规则 引擎适用。 这个 **视图** (单位:千美元)`read/view.ts`)将这些记录变成核心记录,每张记录都是 上面写着变化 把它们和会话组成核心 `Model`每一个读取和手势都采用这个模型。 这是纪念品 记录,所以更改一个记录不会重算其他记录.

## 一个变化的生命

用户将正方形拖入新位置 :

```
 pointer up
    │
    ▼
 store.commit({ type: 'editPointer', phase: 'up', … })          services/store.ts
    │
    ├─ update(model, message)                                   core-annotation
    │     → session   (the drag is over)
    │     → change    (put: the square at its new place)
    │     → effects   ([{ type: 'patch', id: 'obj:12', patch: { box } }])
    │
    ├─ op builders                                              write/ops.ts
    │     patch → { type: 'annotations.update', ref, patch }
    │     (an annotation's link children follow it: write/links.ts)
    │
    └─ ctx.changes.stage({ label, ops, undo })                  the kernel
          the records mirror predicts it: the view shows the square at its
          new place at once. The queue sends it after everything staged
          before it; the engine applies it, all or nothing, and publishes
          `annotations.updated` before it answers:
            the records mirror folds it → confirmed obj:12 is at the new place
          the change leaves the view → the view shows the confirmed record
```

一个用户动作就是一个改变:移动五个说明就是五个改变 行动,一个请求,一个撤销步骤。 规则:

-   **拒绝** (取消赠款,在别处设置锁): 并显示确认的记录,包括任何 另一会话也随之改变。 无所不能由手取出 `onWriteFailed` 告诉UI为什么。 名称只有记录的更改 a 拒绝的变更本可以创造的 与它一起被拒绝.
-   **应用**: 当记录镜显示 答案, 即当其事件折叠时; 如果折叠要求读取 页面,视图将它保存到读取土地.
-   **顺序**: 引擎回答的顺序改变,所以 新的变化总是表现在 旧的答案.

同样的管道带来各种变化:

-   **新说明** 选中对象编号 (单位:千美元)`services/object-numbers.ts`因此,新的记录有 其最后的参考 从其 第一个框架:可以同时选择、编辑、链接或删除,以及 每一个被创造出来的人, 替换文本护栏和 它的罢工是两个创造的 在一个变化中,罢工回应 照着它的号码 如果文档的池是空的,一会儿 创建数字等值(绘图保留在屏幕上).
-   **删除**:记录及其内容(其答复,分组部分, 弹出后)立刻离开取景地,如果发动机拒绝,就回来.
-   **键入** 每暂停一次, 进入一个所持更改( q)`write/text-editing.ts`: 每个按键都会修正,所以文本一次显示,然后发送 暂停,当编辑结束, 当其他东西被摆出, 之前 下载。 输入时输入选中单词的格式 .
-   **代码中的更改** (单位:千美元)`create`, (中文(简体) ), `update`, (中文(简体) ), `delete`, (中文(简体) ), `reorder`, (中文(简体) ), 评论,链接,脚本)通过商店的第二扇门, `apply`: 每个 使用引擎本身的功能检查,同时显示,并发送, 回答和拒绝 就像一个手势。 一个呼叫就是改变.

## 记录如何使

引擎的外观光栅所形成的确认记录(`baked`(中文(简体) ) 除非本届会议编辑或创建了它,在这种情况下,它从 说明`vector`: `vector` 国家优先。 又一个 会话将记录转换回光栅上(`sync/confirmed.ts`) (中文(简体) ). 虽然本届会议有待改变,但记录的绘制方式如下: 从变化本身(核心) `drawnAfter`引擎的判断: 将光栅带上,任何其它可见的活画, 和改变 光栅已经显示(一面旗帜)已照原样离开. 邮票和部件没有 活生生的渲染 总是使用光栅: 邮票的分数保持在 调整框大小( 引擎适合它) `contain`),并加盖了本届会议的印章 显示它被放置的预览, 直到引擎的相片存在 (单位:千美元)`read/render.ts`) (中文(简体) ). 光栅再次被取回 恰好当记录 外观版本更改, 当引擎报告时镜像会推进 重生的外观.

## 东西住的地方

| 文件夹 | 里面有什么东西 |
| --- | --- |
| `controller.ts` | 构成根: 构建服务, 连接每个区域, 组装能力 |
| `model.ts` | 插件状态及其过渡(`withSession`,使偏好,.) |
| `services/` | 每个区域的基础是什么:商店、对象编号、事件、权威 |
| `sync/` | 记录镜(引擎确认的内容及其预测)和随后的 |
| `read/` | (注释、制成物品、铬) |
| `write/` | 动词,以及将核心效果转化为引擎操作的操作构建器 |
| `comments/` | 注释线程在相同记录上的镜头 |
| `tools/` | 工具定义, 注册, 工具的幽灵, 和枢纽上的指针处理器 |

## 测试

`test/harness.ts` 运行内核测试上下文中的控制器 假引擎 行为像真实的: 它一次应用一个变化, 他们被派去的顺序, 全部或无, 并公布事件之前 它回答;一个创建得到它命名的对象编号. `test/pending.test.ts` 是起始地点:用户在更改时和更改后所看到的内容 它的方式. `test/interleavings.test.ts` 播放种子随机序列 更改、拒绝和远程更新,并检查视图(数值和如何) 在每一步之后.

## 常见问题

### @embedpdf/plugin-annotation 是什么？

注释特性插件:纯注释-核心被线接入引擎存储器\(优化创建/patch/删除\)\+交互中枢\(环境编辑\+绘图工具\)\. 行为\(形式\)插入这里\.

### 如何安装 @embedpdf/plugin-annotation？

在项目目录运行 npm install @embedpdf/plugin-annotation，或使用 pnpm add / yarn add / bun add。

### @embedpdf/plugin-annotation 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @embedpdf/plugin-annotation 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @embedpdf/plugin-annotation 可以商用吗？

@embedpdf/plugin-annotation 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @embedpdf/plugin-annotation 的下载量有多少？

根据 npm 官方下载统计，@embedpdf/plugin-annotation 在 2026/10/14 – 2026/11/12 这 30 天内被下载 1,804,069 次，日均约 60,136 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @embedpdf/plugin-annotation 还在维护吗？

最新版本 3\.2\.0 发布于 2026/11/12（1 天前）；至今共发布 114 个版本，其中过去 12 个月发布了 64 个；首次发布于 2025/06/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。