# @build-qube/papyra 中文文档

规范地址：https://npmcn.com/package/%40build-qube/papyra/

版本：0\.8\.0
npm 元数据更新时间：2026-10-26T16:14:24.145Z
中文译文更新时间：2026-11-08T19:06:27.843Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40build-qube/papyra
原文对照：https://npmcn.com/package/%40build-qube/papyra/?lang=original
项目主页：https://github.com/BuildQube/papyra#readme
源码仓库：https://github.com/BuildQube/papyra

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

- 包体积（解压后）：399 kB，118 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@build-qube/papyra-office-native 0\.8\.0
- 首次发布：2026-08-26T21:28:51.442Z
- 最新版本发布：2026-10-26T16:14:23.474Z
- 近 30 天下载量：4632（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

由 Rust 驱动的节点和浏览器快速 PDF 渲染

## 安装

```sh
npm install @build-qube/papyra
```

也可以使用：`pnpm add @build-qube/papyra`、`yarn add @build-qube/papyra`、`bun add @build-qube/papyra`

## README

# 帕皮拉语name

节点快速 PDF 渲染 **财务报告和审定财务报表** 浏览器,从一个 Rust 核心。 发动机 (单位:千美元)[红花](https://github.com/LaurenzV/hayro)页:1 二进制船和没有安装.

## 安装

```bash
npm install @build-qube/papyra
```

本地加通和浏览器是作为可选的依赖关系构建船; 您 软件包管理器选择正确的一个.

## 绘制一页

```ts
import { open, paintToCanvas } from '@build-qube/papyra';

const doc = await open(file); // Uint8Array | ArrayBuffer | Blob | File
const page = await doc.renderPage(0, { fitWidth: 1600 });

paintToCanvas(page, canvas);
```

`renderPage` 绝不屏蔽事件循环 . `page` 被紧紧包装 RGBA8,所以 `paintToCanvas` 这是一种便利而不是唯一的途径—— `toImageData`,则 编码器,或你自己的缓冲器处理同一字节的所有工作.

## 缩略图

`stream` 平分页时, 以货币表示:

```ts
for await (const { page, bitmap } of doc.stream({ fitWidth: 160 })) {
  paint(page, bitmap);
}
```

## 说急事

papyra并不猜测哪一页很重要——一个查看者知道屏幕上的内容和 图书馆没有。 附加优先级, 队列将尊重它 . **先放低一点**, (中文(简体) ), 而默认是最紧急的一级, 所以不关心的呼叫者可以忽略这一点 完全没有.

```ts
const doc = await open(file, { concurrency: 4 }); // viewers want a narrow pool

// Thumbnails yield to whatever is on screen.
for await (const t of doc.stream({ fitWidth: 160, priority: 2 })) { /* … */ }

// Reprioritise on scroll instead of cancelling and resubmitting.
const job = doc.render(12, { fitWidth: 1600, priority: 2 });
onScroll(() => job.setPriority(isVisible(12) ? 0 : 3));
```

对同一页大小的请求合并为一个渲染。 待定工作 自由重排; 已经运行的工作永远不会中断 .

## 导出、文本和大纲

```ts
const image = await doc.renderImage(0, { fitWidth: 2000 });
await writeFile('page-0.webp', (await image.toWebp()).bytes);

for await (const hit of doc.search('site plan')) {
  highlight(hit.page, hit.rects);
}

for (const node of await doc.outline()) {
  if (node.page !== null) goTo(node.page);
}
```

`renderImage` 保持像素在Rust 和编码的需求,所以除了 完成的文件交叉进入JS. 对于必须存活下来的产出 `doc.renderSvg(0)`,它返回向量标记而不是像素,因此不需要 大小和无质量.

## 链接,标签, 以及文件对自己的内容

```ts
const scale = rendered.width / doc.pageSize(index).width;
for (const link of await doc.links(index)) {
  const box = scaleRect(link.rect, scale);
  if (link.target.kind === 'uri') openExternally(link.target.uri);
  else goTo(link.target.dest.page);
}

const labels = await doc.pageLabels();
const shown = labels[index] || String(index + 1);   // "iv", not "4"

doc.metadata.title;   // null when the document never said
doc.fingerprint;      // stable key for per-document state
```

链接矩形与所提取的文本相同——从上到左的72 DPI, 采用旋转方式——这样一来,就把它们放在任何成份上. `pageLabels()` 为空 当文档定义了没有标签时,这是您按索引向数字发出的信号.

加密文件抛出 `PasswordRequiredError` 或者说 `IncorrectPasswordError`两者 扩展 `PasswordError` 带有 `retry` 旗下,所以一个对话框处理冷问和 错误的答案.

## 旋转视图

```ts
const vp = viewport(doc.pageSize(index), { fitWidth: 1600, rotation: 90 });

paintToCanvas(await doc.renderPage(index, { dpi: vp.dpi }), canvas, {
  rotation: vp.rotation,
});
const box = viewportRect(link.rect, vp);   // the link layer, turned to match
```

页面会变成不旋转, 画布会转弯, 所以一个旋转按钮不花费 调制。 大小通过视图端口而不是与 `fitWidth` 直接: 转动 屏幕上的宽度是页面的高度,和 `vp.dpi` 带回答案.

Renders 默认绘制注释 。 过 `{ annotations: false }` 当你在画的时候 您自己的链接或突出显示层,或者它们两次出现.

## 有三件事会咬你

**大小为 `fitWidth`没有 `dpi`。 。 。 .** 页面区域因数量级而异。 在一个 固定 36 DPI,US Letter是一款216x279缩略图,而一款42x30in绘图是一款1512x1080, 6.5 MB图像. 按输出宽度大小保持成本与实际成正比 显示; 超过 100 MP 被直接拒绝 .

**浏览器的构建需要交叉起源隔离.** 它使用共享的原生记忆,所以 `SharedArrayBuffer` 必须具备。 服务你的页面:

```
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp
```

**浏览器建设中的恐慌是致命的.** 它中止了原案例和papyra 失败, 直至页面重新装入; 在本地是被拒绝的许诺 .

## 发动机

其他引擎——为无法隔离的页面提供pdf.js,Tauri,以及实验性 文字和权力点 `@build-qube/papyra/office` - 包含在 [引擎指南](https://buildqube.github.io/Papyra/docs/guides/engines)。 。 。 . 用另一个引擎导入的打开文档的代码 `@build-qube/papyra/core`, (中文(简体) ), 它从来不装上papyra的原子弹.

## 再来

这个 [完整 API 参考](https://buildqube.github.io/Papyra/docs) 从 这些来源,所以它从来没有从它们漂移。 这个 [项目README](https://github.com/BuildQube/Papyra) 涵盖结构、基准 与pdf.js相对,以及这些默认背后的测量.

麻省理工学院.

## 常见问题

### @build-qube/papyra 是什么？

由 Rust 驱动的节点和浏览器快速 PDF 渲染

### 如何安装 @build-qube/papyra？

在项目目录运行 npm install @build-qube/papyra，或使用 pnpm add / yarn add / bun add。

### @build-qube/papyra 支持 TypeScript 吗？

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

### @build-qube/papyra 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @build-qube/papyra 可以商用吗？

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

### @build-qube/papyra 的下载量有多少？

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

### @build-qube/papyra 还在维护吗？

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