# @boxpdf/reader 中文文档

规范地址：https://npmcn.com/package/%40boxpdf/reader/

版本：0\.2\.9
npm 元数据更新时间：2026-11-02T22:21:04.025Z
中文译文更新时间：2026-11-08T12:51:19.301Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.6 MB，33 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：4 个
- 首次发布：2026-08-25T16:03:56.636Z
- 最新版本发布：2026-11-02T22:21:03.628Z
- 近 30 天下载量：56818（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 26 个）

## 中文简介

用于JavaScript的流式,内存捆绑的PDF读取器和结构化数据提取器.

## 安装

```sh
npm install @boxpdf/reader
```

也可以使用：`pnpm add @boxpdf/reader`、`yarn add @boxpdf/reader`、`bun add @boxpdf/reader`

## README

# `@boxpdf/reader`

用于流式、内存范围 PDF 读取器和结构化数据提取器 Java脚本.

## 合同的定义

阅读器从大型 PDF 中解析和提取内容而无需缓冲 完整的文件。 明确的字节和对象缓存预算规范了内存的使用.

```text
peak parser-owned memory <= configured caches
  + active page window
  + compressed input and direct-read staging
  + largest permitted decoded object / selected-object buffers
  + measured parser and runtime overhead
```

正在递增扫描大型 Flate 对象流, 只扫描选中的 对象已实现. `maxObjectStreamDecodedBytes` 默认至少为 128 MiB 每次检查工作总预算,包括重放和重试;不 分配此大小的缓冲. `maxDecodedStreamBytes` 继续治理 普通的全缓冲解码 临时缓冲计数器不包括总数 解析值或运行时间内存。 见 [边框对象流提取](https://npmcn.com/package/%40boxpdf/reader/docs/BOUNDED_OBJECT_STREAMS.md) 用于回归固定、内存核算和工人检查.

每个输入执行随机访问源 :

```ts
interface PdfSource {
  readonly size: number;
  read(offset: number, length: number): Promise<Uint8Array>;
}
```

## 软件包边界

```text
@boxpdf/reader
├── source          random-access file, HTTP, Blob, and memory inputs
├── store           bounded sparse byte cache
├── syntax          PDF lexer, objects, xref, and page tree
├── content         graphics state, fonts, CMaps, and text operations
└── structure       optional reading order, paragraphs, lists, and tables

separate output packages
├── @boxpdf/html-writer  streaming visual or semantic HTML output
└── render               future Canvas, SVG, or bitmap rendering
```

核心结果保留了定位文本和出处. 语义结构 分别推断,包括信心和诊断理由。 A 类 未来的渲染器会消耗页面操作而不成为 文本或表格提取.

## HTML 写入器

`@boxpdf/html-writer` 通过等待的写入将 PDF 页面流到 HTML 调用。 默认 `visual` 配置保存显示演示文稿 `semantic` profile 将页面几何转换为可再流的读取顺序, 嵌入 区域、段落、列表、牌、标签/值组和表格。 边框 文档窗口连接各页表格并删除重复的页面 家具而不缓冲完整的PDF. 见 `packages/html-writer`。 。 。 .

## 使用量

在节点读取本地文件 :

```ts
import { openPdf } from "@boxpdf/reader";
import { fileSource } from "@boxpdf/reader/node";

const source = await fileSource("large.pdf");
const pdf = await openPdf(source, {
  chunkSize: 64 * 1024,
  maxBytes: 16 * 1024 * 1024,
  maxXrefCacheBytes: 16 * 1024 * 1024,
});

try {
  for await (const page of pdf.pages()) {
    console.log(page.number, page.spans);
  }
  console.log(pdf.stats);
} finally {
  pdf.close();
  await source.close();
}
```

HTTP来源更倾向于字节行距支持. 返回完整 HTTP 200 响应的服务器也是 支持: 读取器只将请求的切片保存在内存中并释放出一个传输效率 警告每个来源.

```ts
import { httpSource, openPdf } from "@boxpdf/reader";

const pdf = await openPdf(await httpSource("https://example.com/large.pdf"));
const firstPage = await pdf.getPage(0);
```

## v1 支持

V1 解析器支持 :

-   经典交叉参考表格、交叉参考流和 `/Prev` 链条
-   压缩对象流和线性PDF
-   懒惰的页面- 树检索, 带有继承的媒体框, 旋转, 和资源
-   未过滤的 Flate 和 ASCII- hex 有解码大小限制的流
-   字元和十六进制字符串,常见文本操作符,图形转换, WinAnsi 文本、 UTF-16 字符串、 0 类型字体和常见 `ToUnicode` 制图
-   标准14,明确,嵌入的TrueType,和PFA/PFB 第1型水平 计量
-   嵌入式 OpenType (`FontFile3` 与 `Subtype /OpenType`),使用现有的 TrueType 修补或 CFF 转换路径而不附加依赖性
-   水平和垂直 CID 宽度,垂直源, `TJ` 流离失所,以及 从上到下的结构分组
-   以读取源码和居民字节遥测为界的稀有字节缓存
-   具有常住字节遥测功能的可配置的 xref 字节天花板
-   语义 HTML 有恒温读取顺序和基于重复文本对齐的表格推论

加密 PDF 、 损坏的文件修复、 内容流中的内置图像, 不寻常 流过滤器, Type1C/ CFF 宽度回收, 命名为 CMap 收藏而无 `ToUnicode` 映射或可用嵌入的 TrueType cmap, OCR, 渲染在外 v1支持面 。 不支持的过滤器和配置的资源限制失败 有明显的错误.

OpenType 字体资产保存其大纲表格并使用 PDF 字符映射 用于浏览器文本。 嵌入式编码 CMaps 支持 `cidchar` 财务报告和审定财务报表 `cidrange` 条目. CID glyph再映射每条编码CMap最多接受65,536个有效记录, 包括跨区块的重复。 记录存储量按需增长至768 KiB. 较大的地图在不发布部分格氏映射的情况下倒回; 文本提取 继续使用 `ToUnicode`。 。 。 . 格式不当的 OpenType 目录、 CFF2 字体和字体收藏保留了现有的 字体倒置行为.

## 兼容性甲骨文

PDF.js 是页面几何、解码文本、文本的主要行为预言 方向,和定位。 测试比较了常态化的定位字符和 允许不同的文本宽边框。 波普勒是一个独立的中学 hTML 写入器的预告 。 它的外形门保留了精确的几何和 解码文本协议 每一个已知 同意在两个引擎. 报告记录了引擎之间的RTL和字体解码差异.

全方位门接受所有118个支持的非加密装置(100%). 其中115个与PDF.js相匹配,3个命名的固定装置有意在以下地点相去甚远: 视觉先知证实改进了 `.notdef`或UTF-16行为. 固定120文件分母中剩下的两个固定装置经过加密 故意无凭无据. 此分数覆盖了页数, 维度、 旋转、 已规范解码字符, 以及第一个文本来源 未旋转的页面。 重点几何测试 额外比较跨度宽度, 高度,字体大小,以及被改变的位置。 结构金色覆盖读取 顺序,推断出词条边界、表格行和语义HTML。 评分限制和 v.1.1 之后发现的布局缺口记录在 `docs/PARITY_PLAN.md`。 。 。 .

内存测试提取自 10 MB 和 1 GB 虚拟随机访问 PDF 相同的64 KiB字节-cache限制. 他们声称 缓存居住权,最大个人 源读取, 总字节取出, 处理 RSS, 和 ArrayBuffer 增长 .

## 内存比较

`pnpm memory:compare` 运行 `@boxpdf/reader`,原始 PDF.js 和 unpdf 在孤立中 进程与同一逻辑 PDF 相对应。 默认比较使用 10 MiB 和 100个米B输入. PDF.js 和 unpdf 完整接收 `Uint8Array` 投入; `@boxpdf/reader` 获得随机访问源。 PDF.js URL 和范围加载 是单独的输入模式,不在此比较之列.

1个节点24跑产生了这些测量结果:

| 投入 | 发动机 | RSS峰顶 | RSS增长 | 阵列缓冲器增长 | 原始数据已读取 |
| --: | --- | --: | --: | --: | --: |
| 10个小米B | `@boxpdf/reader` | 49.26 米贝 | 3.64 米贝 | 77.06 基贝 | 140 基贝 |
| 10个小米B | PDF.js (英语) | 130.13 米贝 | 84.49 米贝 | 10.15 米贝 | 全部输入 |
| 10个小米B | 未定义 | 82.37 米贝 | 36.74 米贝 | 10.14 米贝 | 全部输入 |
| 100个米B | `@boxpdf/reader` | 49.32 米贝 | 3.64 米贝 | 77.06 基贝 | 140 基贝 |
| 100个米B | PDF.js (英语) | 220.09 米贝 | 174.44 米贝 | 100.15 米贝 | 全部输入 |
| 100个米B | 未定义 | 172.37 米贝 | 126.75 米贝 | 100.14 米贝 | 全部输入 |

峰值 RSS 包括节点进程基线,其中大约46米B 运行。 RSS和分配器的行为因操作系统和依赖而异 版本。 基准脚本是当前测量数据的来源.

## 仓库布局

-   `src/source.ts`:公共随机存取源合同和便携式源
-   `src/store/`: 有限字节存储
-   `src/syntax/`: PDF 词汇和对象解析
-   `src/content/`: 页面内容和文本解释
-   `src/structure/`: 阅读顺序和表格推论
-   `src/render/`: 为可选的渲染器适配器保留边界
-   `test/unit/`: 焦点解析器和 API 测试
-   `test/fixtures/`: 固定完整性和黄金提取测试
-   `test/oracle/`: 差分 PDF.js 测试
-   `test/memory/`: 孤立处理内存的测试
-   `fixtures/`: 经修订的开放源码软件清单和出处

## 发展

```sh
pnpm install
pnpm fixtures:fetch
pnpm test:quick
pnpm test:oracle
pnpm test:memory
pnpm quality
```

## 常见问题

### @boxpdf/reader 是什么？

用于JavaScript的流式,内存捆绑的PDF读取器和结构化数据提取器\.

### 如何安装 @boxpdf/reader？

在项目目录运行 npm install @boxpdf/reader，或使用 pnpm add / yarn add / bun add。

### @boxpdf/reader 支持 TypeScript 吗？

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

### @boxpdf/reader 支持 ESM 还是 CommonJS？

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

### @boxpdf/reader 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @boxpdf/reader 可以商用吗？

@boxpdf/reader 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @boxpdf/reader 的下载量有多少？

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

### @boxpdf/reader 还在维护吗？

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