夜雨聆风学习资料网

ARTICLE · 1373275

PDF 预览别再塞 iframe 了!EmbedPDF 3.0 把查看器、无头组件和引擎一次给全

PDF 预览别再塞 iframe 了!EmbedPDF 3.0 把查看器、无头组件和引擎一次给全

大家好,我是 01。

做后台、合同、发票、知识库的产品,几乎都躲不开 PDF 预览。

最省事的做法是丢一个 <iframe>:浏览器自带阅读器,零代码。但它的界面由浏览器决定,工具栏去不掉,样式改不了,想加个“盖章”“驳回”按钮更是无从下手。

再进一步是用 pdf.js 自己搭:渲染、分页、缩放、搜索、文字选择、批注层,一层层补下来,最后相当于在项目里养了一个 PDF 阅读器。

EmbedPDF 想省掉这段重复劳动。它是一个开源的 JavaScript PDF 查看器,GitHub 上 4.6k star,Apache-2.0 协议。2026 年 11 月初,它发布了 3.0 版本,按官方的说法,是“从 PDF 引擎开始的一次重写”。

3.0 改了什么

2.x 时代的 EmbedPDF 更像一个“能嵌进页面的 PDF 组件”。3.0 把它拆成了三层,每一层单独可用:

  • • 完整查看器:一个标签或一个组件,工具栏、侧边栏、搜索、批注全都带
  • • 无头组件:同样的插件,但不带界面,UI 由你自己写
  • • 独立引擎:只处理 PDF 本身,打开、读取、渲染、修改、保存

这次重构还有两个连带变化。一是包名全换了:原来的 @embedpdf/snippet、@embedpdf/react-pdf-viewer 等,统一成 @embedpdf/viewer 加各框架包。二是引擎换了实现:浏览器里跑 PDFium 的 WebAssembly 版本,放在 Web Worker 里,不卡主线程。

三种用法,按你想要的掌控程度选

方式
适合谁
你要写的东西
完整查看器
想尽快上线
一个标签加一段配置
无头组件
界面要长在自己的产品里
插件加自己的组件
独立引擎
只要 PDF 处理能力
直接调引擎 API

三种方式共用同一套引擎和插件,所以可以先用查看器上线,后面再逐步换成无头方案,不用推倒重来。

一行标签跑起来

原生项目里,从 CDN 引入,写一个自定义标签就行:

<embedpdf-viewer
  src
="https://www.embedpdf.com/pdfs/welcome.pdf"
  style
="height: 100vh"
>
</embedpdf-viewer>

<script
  type
="module"
  src
="https://cdn.jsdelivr.net/npm/@embedpdf/viewer@3/dist/embedpdf.js"
>
</script>

标签会撑满你给的容器,所以必须有高度:固定值、100vh,或者 flex 布局里剩下的空间都行。

React、Vue、Svelte、Angular 各有对应的包,用法一致:

npm install @embedpdf/viewer-react
import { PDFViewer } from "@embedpdf/viewer-react";

export
 function App() {
  return
<PDFViewer src="/files/contract.pdf" style={{ height: "100vh" }} />;
}

对应的包名是 @embedpdf/viewer-vue、@embedpdf/viewer-svelte、@embedpdf/viewer-angular。

常用配置

EmbedPDF 3.0 的配置不写进组件属性里,而是一个普通对象:主题色、开哪些功能、自定义图标、命令、工具栏布局,全在这份数据里。

export const config = {
  theme
: { accent: "#7c3aed" },
  features
: { measurement: true, forms: false },
  commands
: [
    {
      id
: "acme:send",
      label
: "发送签署",
      run
: ({ documentId }) =>
        fetch
(`/api/send/${documentId}`, { method: "POST" }),
    },
  ],
  layout
: (layout) => layout.add("acme:send", { to: "main", section: "end" }),
};

自己加的命令和内置按钮享受同等待遇:有 tooltip,工具栏放不下时会自动收进“更多”菜单,键盘也能访问。

想在代码里跟查看器对话,监听 epdf:ready 事件,然后从 viewer.get() 按名字取插件:

element.addEventListener("epdf:ready", () => {
  const
 { viewer } = element;
  viewer.documents.onOpened(() =>
    viewer.get("search").search({ text: "总金额" }),
  );
});

无头组件

如果 PDF 只是产品界面的一部分,完整查看器的工具栏反而碍事。无头模式提供同样的能力,但不渲染任何界面。

React 里最小的组合长这样:

import { Viewer, DocumentGate } from "@embedpdf/react/runtime";
import
 { Stage, stagePlugin } from "@embedpdf/react/stage";
import
 { RenderLayer, renderPlugin } from "@embedpdf/react/render";
import
 { localEngine } from "@embedpdf/engine";

const
 engine = localEngine();
const
 plugins = [stagePlugin(), renderPlugin()];

export
 function App() {
  return
 (
<Viewer
      engine
={engine}
      plugins
={plugins}
      initialDocuments
={[{ source: { kind: "url", url: "/demo.pdf" } }]}
    >

      <DocumentGate fallback={<p>
正在打开…</p>}>
        <Stage style={{ height: 600 }}>
{() => <RenderLayer />}</Stage>
      </DocumentGate>

    </Viewer>

  );
}

这套结构分五部分:引擎负责读 PDF,<Viewer> 启动引擎并管理文档,插件各管一个功能,图层画在页面里,hooks 把你自己的界面接进去。

插件是按需引入的。只注册 stage 和 render,你的包里就不会出现批注、表单、搜索的代码。官方列了二十多个插件,从搜索、批注、表单、签名到页面编辑、缩略图、多文档标签页,用哪个装哪个。

独立引擎

最底层是 @embedpdf/engine。不渲染界面,只提供 PDF 能力:

import { localEngine } from "@embedpdf/engine";

const
 engine = localEngine();
const
 response = await fetch("/files/invoice.pdf");
const
 doc = await engine.open({
  kind
: "bytes",
  bytes
: await response.arrayBuffer(),
});

const
 { pages } = await doc.pages.list();
const
 page = doc.page(pages[0].ref);
const
 image = await page.render.image({
  viewport
: { kind: "width", width: 800 },
});
const
 { url } = await image.objectUrl();

const
 { text } = await page.text.get();
const
 { matches } = await doc.search.query({ text: "total" });

批注也是同一套 API:拿到搜索结果的四个角坐标,直接建一个高亮;改完用 download() 拿回新的 PDF 字节。

引擎在浏览器里通过 Web Worker 跑 WebAssembly,不阻塞页面;引擎包在 Node 里也有原生构建,覆盖 macOS、Linux、Windows。服务端做批量处理、生成缩略图,可以复用同一套接口。

功能清单

官方把功能做成了“默认全开、可逐项关闭”:

  • • 批注:高亮、下划线、删除线、手绘、便签、文本框、图形、印章、带回复的评论
  • • 表单与签名:填写、创建表单字段,手写、打字或上传签名,校验签名
  • • 密文:标记后从文件里真正删除,而不只是盖一层
  • • 测量:按图纸比例算距离、周长、面积
  • • 页面:旋转、移动、插入、复制、删除,每一步可撤销
  • • 阅读:搜索、文字选择、缩略图、大纲、附件、快照、打印、下载、多文档标签页
  • • 多语言:希伯来语、阿拉伯语开箱支持从右到左排版

迁移和生态

从 2.x 升级,主要是换包名和配置键。官方迁移指南逐个列出了对应关系,2.x 的文档也保留在 v2.embedpdf.com,老项目可以慢慢迁。

EmbedPDF 背后的公司是 CloudPDF。开源版把 PDF 放在用户浏览器里打开;CloudPDF 则把引擎放到服务器上,PDF 不离开服务端,页面按需传到前端。两者共用同一个查看器,切换引擎只需要换个 localEngine() 为 cloudEngine()。

需要注意,CloudPDF 的 server 部分不是 Apache-2.0,而是 Fair Core License:源码可读可改,但运行需要授权。开源的是 @embedpdf/* 全家桶,这点别混淆。

注意事项

WASM 要自己托管

查看器包会带上 PDFium 的 WebAssembly 文件,构建时需要让这些资源从你自己的站点提供。用 CDN 引入最省事,走打包器就要按文档配置资源路径和工作线程。部署到有严格 CSP 的环境,也要放行 Worker 和 WASM。

包体不小

PDF 引擎不是几百 KB 的脚本。首屏就加载完整引擎,对轻量页面来说是负担。建议按需加载:先渲染页面骨架,用户真的要看 PDF 时再动态引入。

它不是“万能 PDF 阅读器”

纯前端方案有天然边界:加密 PDF、权限受限文档、超大文件,都要额外处理。真要做服务端权限、协作、水印,还是得配后端。

迭代很快

3.0 发布到 3.2 只隔了 5 天。功能推进快是好事,但生产项目建议锁死版本,升级前看一遍 changelog。

适合谁

  • • 后台系统:合同、发票、工单预览,要工具栏又要自己的按钮
  • • SaaS 产品:PDF 是产品界面的一部分,UI 必须统一
  • • 文档类应用:批注、表单、签名、密文一条龙
  • • 服务端处理:用 Node 版引擎做拆分、加水印、生成缩略图

写在最后

EmbedPDF 3.0 最大的变化不是加了什么功能,而是把“PDF 查看器”拆成了三个可组合的层次:想快就用现成组件,想控就上无头插件,只想处理文件就直接用引擎。

它替掉的是 pdf.js 之上那层又一层自己写的胶水代码。至于值不值得换,先打开在线 Demo 点两下,比看十篇介绍都直接。

官网:https://www.embedpdf.com

在线 Demo:https://www.embedpdf.com/demo

GitHub:https://github.com/embedpdf/embed-pdf-viewer

回首页,搜索你想要的文档

在首页搜索框输入关键词,快速定位资料

文库首页搜索指引 立即搜索

相关学习资料