# @embedpdf/react 中文文档

规范地址：https://npmcn.com/package/%40embedpdf/react/

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

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

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

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

- 包体积（解压后）：1.4 MB，214 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：30 个
- peer 依赖：react \>=18，react-dom \>=18
- 首次发布：2026-08-05T21:42:20.150Z
- 最新版本发布：2026-11-11T23:25:31.757Z
- 近 30 天下载量：66116（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：27（近 12 个月 27 个）

## 中文简介

使用 EmbedPDF 创建您自己的 PDF 查看器的响应组件和钩子 .

## 安装

```sh
npm install @embedpdf/react
```

也可以使用：`pnpm add @embedpdf/react`、`yarn add @embedpdf/react`、`bun add @embedpdf/react`

## README

# @embedpdf/反应

使用 EmbedPDF 创建您自己的 PDF 查看器的响应组件和钩子 .

## 快开始

本指南构建一个小型 PDF 查看器: 页面、 文本人员可以选择、 缩放按钮、 a 高亮和保存按钮。 每个步骤都添加一个插件或一个控件,这样您就可以停止任何 台阶并有一个工作查看器.

### 1\. 安装

你需要两个包:一个是框架,一个是引擎.

```sh
npm install @embedpdf/react @embedpdf/engine
```

每个特性都是从框架包中单独导入的,例如 `@embedpdf/react/stage`, (中文(简体) ), 所以,你不用的东西 从来没有达到你的捆绑.

### 2\. 显示 PDF

一次创建引擎,然后把它给 `<Viewer>` 您想要的插件和文档 打开. `<Stage>` 显示页面,以及 `<RenderLayer>` 绘制每个 :

**`basic.tsx`**

```tsx
import { Viewer, DocumentGate } from '@embedpdf/react/runtime';
import type { OpenInput } from '@embedpdf/react/runtime';
import { Stage, stagePlugin } from '@embedpdf/react/stage';
import { RenderLayer, renderPlugin } from '@embedpdf/react/render';
import { localEngine } from '@embedpdf/engine';

// The engine is created synchronously and costs nothing until first use, so
// a module-scope `const engine = …` is safe, even under SSR. Only opening a
// document does real work: the UI renders at t≈0.
const engine = localEngine();
const plugins = [stagePlugin(), renderPlugin()];

// The local engine opens bytes: fetch lazily, under the loading tab.
const welcome = async (): Promise<OpenInput> => {
  const response = await fetch('https://www.embedpdf.com/pdfs/welcome.pdf');
  return { kind: 'bytes', id: 'welcome', bytes: new Uint8Array(await response.arrayBuffer()) };
};

export default function App() {
  return (
    <Viewer engine={engine} plugins={plugins} initialDocuments={[{ source: welcome }]}>
      <div style={{ height: 500 }}>
        {/* Document UI is defined over a document: gate it on having one. */}
        <DocumentGate fallback={<p>Loading…</p>}>
          <Stage style={{ height: '100%' }}>{() => <RenderLayer />}</Stage>
        </DocumentGate>
      </div>
    </Viewer>
  );
}
```

`localEngine()` 所以在模块顶部创建它很安全,甚至 带有服务器侧渲染。 浏览器在挂载时启动它: 在 Web Worker in 背景,第一页在文档打开后立即显示。 发动机的 WebAssembly 是您自网站创建和加载的一部分 [设置](https://www.embedpdf.com/docs/headless/react/setup)。 。 。 .

`<DocumentGate>` 显示其 `fallback` 直到文档打开为止,所以舞台永远不会变成 没有一个.

## 每个插件

每个插件为一导入行 。 注册插件并导入其组件来自 同一个地方:

| 插件 | 它给你什么 | 从 |
| :-- | :-- | :-- |
| [阶段](https://www.embedpdf.com/docs/headless/react/viewing/stage) | 滚动、缩放、布局、页面导航 | `@embedpdf/react/stage` |
| [渲染器](https://www.embedpdf.com/docs/headless/react/viewing/render) | 每个缩放、深角瓦片的清晰页 | `@embedpdf/react/render` |
| [链接](https://www.embedpdf.com/docs/headless/react/viewing/links) | 可点击的网页和网站链接 | `@embedpdf/react/link` |
| [选择](https://www.embedpdf.com/docs/headless/react/text/selection) | 选择和复制文本 | `@embedpdf/react/selection` |
| [搜索](https://www.embedpdf.com/docs/headless/react/text/search) | 查找文本, 并显示每个匹配 | `@embedpdf/react/search` |
| [说明](https://www.embedpdf.com/docs/headless/react/annotations) | 突出显示、注解、形状、自由文本和你自己的工具 | `@embedpdf/react/annotation` |
| [邮票](https://www.embedpdf.com/docs/headless/react/annotations/stamps) | 邮票图书馆,通过点击或编码放置 | `@embedpdf/react/stamp` |
| [计量](https://www.embedpdf.com/docs/headless/react/annotations/measurements) | 实际规模的距离、周边和地区 | `@embedpdf/react/measurement` |
| [编辑](https://www.embedpdf.com/docs/headless/react/annotations/redaction) | 永远删除内容 | `@embedpdf/react/redaction` |
| [表单](https://www.embedpdf.com/docs/headless/react/forms) | 填充和建造PDF表格 | `@embedpdf/react/form` |
| [签署](https://www.embedpdf.com/docs/headless/react/forms/signatures) | 签署文件和检查签名 | `@embedpdf/react/signature` |
| [页面编辑](https://www.embedpdf.com/docs/headless/react/documents/pages) | 旋转、重排、插入和删除页面 | `@embedpdf/react/page-edit` |
| [元数据](https://www.embedpdf.com/docs/headless/react/documents/metadata) | 文件的标题、作者和您自己的字段 | `@embedpdf/react/metadata` |
| [字体](https://www.embedpdf.com/docs/headless/react/documents/fonts) | 文档的字体可以写入, 绘制为引擎写入的字体 | `@embedpdf/react/fonts` |
| [大纲](https://www.embedpdf.com/docs/headless/react/documents/outline) | 文档的大纲(其书签),用于显示、跟踪和编辑 | `@embedpdf/react/outline` |
| [附录](https://www.embedpdf.com/docs/headless/react/documents/attachments) | 包含 PDF 文件: 列出、保存、附加和删除 | `@embedpdf/react/attachment` |
| [行动](https://www.embedpdf.com/docs/headless/react/documents/actions) | PDF 本身做什么:按钮、脚本、打印 | `@embedpdf/react/actions` |
| [查看管理器](https://www.embedpdf.com/docs/headless/react/documents/tabs) | 几个文件并存 | `@embedpdf/react/view-manager` |
| [互动](https://www.embedpdf.com/docs/headless/react/ui/tools) | 活动工具、光标和触摸 | `@embedpdf/react/interaction` |
| [图标](https://www.embedpdf.com/docs/headless/react/ui/commands) | 用标签、图标和快捷键命名动作 | `@embedpdf/react/commands` |
| [贝壳](https://www.embedpdf.com/docs/headless/react/ui/panels) | 打开哪些面板、对话框和菜单 | `@embedpdf/react/shell` |
| [翻译](https://www.embedpdf.com/docs/headless/react/ui/translations) | 您的用户语言UI | `@embedpdf/react/i18n` |

## 文档

-   [快开始](https://www.embedpdf.com/docs/headless/react/quick-start): 一步一步地构建一个PDF取景器,其中包含文本选择,缩放按钮,亮点和保存按钮.
-   [设置](https://www.embedpdf.com/docs/headless/react/setup):服务器侧渲染,捆绑,字体,并亲自主持引擎.
-   [如何运作](https://www.embedpdf.com/docs/headless/react/concepts/how-it-works):插件,你的用户界面如何与它们交谈,层层,以及哪个组件的谈话文件.
-   [滚动、缩放和布局](https://www.embedpdf.com/docs/headless/react/viewing/stage):布局,缩放模式,页面导航和触摸.

## 许可证

阿帕奇 - 2.0

## 常见问题

### @embedpdf/react 是什么？

使用 EmbedPDF 创建您自己的 PDF 查看器的响应组件和钩子 \.

### 如何安装 @embedpdf/react？

在项目目录运行 npm install @embedpdf/react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18）、react-dom（\>=18）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @embedpdf/react 支持 TypeScript 吗？

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

### @embedpdf/react 支持 ESM 还是 CommonJS？

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

### @embedpdf/react 可以商用吗？

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

### @embedpdf/react 的下载量有多少？

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

### @embedpdf/react 还在维护吗？

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