# @capgo/capacitor-pdf-viewer 中文文档

规范地址：https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/

版本：8\.2\.8
npm 元数据更新时间：2026-10-15T06:49:00.868Z
中文译文更新时间：2026-11-09T04:07:16.662Z
软件包许可：MPL-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40capgo/capacitor-pdf-viewer
原文对照：https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/?lang=original
项目主页：https://capgo.app/docs/plugins/pdf-viewer/
源码仓库：https://github.com/Cap-go/capacitor-pdf-viewer

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

- 包体积（解压后）：195 kB，32 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2026-10-01T14:18:56.456Z
- 最新版本发布：2026-10-15T06:49:00.567Z
- 近 30 天下载量：40181（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

在应用程序内打开 PDF 的电容插件 .

## 安装

```sh
npm install @capgo/capacitor-pdf-viewer
```

也可以使用：`pnpm add @capgo/capacitor-pdf-viewer`、`yarn add @capgo/capacitor-pdf-viewer`、`bun add @capgo/capacitor-pdf-viewer`

## README

# @ capgo/ 电容器- pdf- 查看器

[![Capgo - Build Capacitor apps with AI, ship updates instantly](https://capgo.app/readme-banner.svg?repo=Cap-go/capacitor-pdf-viewer)](https://capgo.app/?ref=plugin_pdf_viewer)

**队长**:在几分钟内将修正推给您的 Capacitor 用户,在没有Mac的情况下构建已签名的iOS和Android apps,并在一击中回滚.

## [\*免费开始\*](https://capgo.app/register/?ref=plugin_pdf_viewer)

14天无限自由审判. 不需要信用卡

> 🤖 **建筑与AI编码代理?** 安装 [Capgo 技能](https://capgo.app/skills/?ref=plugin_pdf_viewer) 所以克劳德代码,代码,光标,副驾驶,或双子座CLI知道如何安装和使用 `@capgo/capacitor-pdf-viewer` 在您的电容应用程序中: `npx skills add Cap-go/capgo-skills`。然后问你的经纪人: _添加@capgo/capor-pdf-viewer到我的Capacitor应用上,并把它接上"_ [代理设置指南](https://capgo.app/agents/?ref=plugin_pdf_viewer) • 妇女 [主机磁共振](https://capgo.app/docs/ai/mcp/?ref=plugin_pdf_viewer)

**@ capgo/ 电容器- pdf- 查看器** 在iOS,Android,和web上嵌入了Capacitor应用的本地PDF取景. 与其对抗WebView限制或传输重的JavaScript PDF渲染器,不如从路径打开文件,HTTPS URL(带有自定义头头),或 Base64,并获得系统级渲染:页面导航,剪接缩放,连续或单页滚动,密码保护文档,全屏或内线布局,以及加载,错误,页面更改,链接自带和关闭等事件. 在iOS上它使用PDFKit;在Android上它使用Pdfium;在网络上它使用带有blob URL的浏览器PDF查看器.

## 特征

-   从设备路径打开 PDF, `file://` URL,HTTPS URL,或 Base64(包括 `data:` (URIs) (英语)
-   可选 `headers` 下载远程 URL( 自动令牌、 饼干) 时
-   IOS和Android上加密的 PDF 密码支持
-   全屏覆盖或 **内入** 模式锁定到 DOM 元素(`elementId`(中文(简体) )
-   连续垂直滚动或单页模式
-   程序化 **转到页面**, (中文(简体) ), **设置Zoom**,以及 **关闭**
-   活动 : `load`, (中文(简体) ), `pageChange`, (中文(简体) ), `error`, (中文(简体) ), `close`, (中文(简体) ), `linkTap`

## 使用大小写

-   存储在设备上的发票、手册和机票,或从你的API中作为基数返回64
-   从带有自定义 HTTP 头的已签名的 URL 下载文件
-   嵌入式 PDF 预览以窗体或仪表板区域(内置模式)
-   引导读取流程跳入一页,并听取 PDF 内部的链接水龙头

## 文档

-   [插件文件](https://capgo.app/docs/plugins/pdf-viewer/) (原始内容存档于2017-03-21). capp. app
-   [教学](https://capgo.app/plugins/capacitor-pdf-viewer/) 安装步骤和实例
-   [队长](https://capgo.app/) 用于实时更新、本地构建和插件支持

![Android emulator showing the example PDF open on two pages](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/screenshots/android-demo.webp) ![Example app with inline PDF and controls](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/screenshots/example-app.webp)

## 兼容性

| 插件版本 | 电容兼容性 | 维护 |
| --- | --- | --- |
| 联合国 | 联合国 | ✅ |
| 页:1 | 页:1 | 应要求 |
| 页:1 | 页:1 | 应要求 |

政策:

-   新的插件从版本开始 `8.0.0` (8号电站基线).
-   对更古老的Capacitor主机的后向相容性按需支持.

## 安装

```bash
npm i @capgo/capacitor-pdf-viewer
npx cap sync
```

与 Bun 键 :

```bash
bun add @capgo/capacitor-pdf-viewer
bunx cap sync
```

## iOS 设置

此插件不需要额外的 Info. plist 密钥或权限 。 它使用苹果PDFKit. 使用远程 PDF `URLSession` 用你传入的信头 `open`。对于 HTTPS URL,请遵循您的应用程序通常的 App Transport 安全规则.

## 机器人设置

插件库目标 **分数 24** (Android 7.0)并捆绑出Pdfium (`io.legere:pdfiumandroid`) (中文(简体) ). 插件 `AndroidManifest.xml` 是空的: 它没有声明 `INTERNET`,存储,或FileProvider条目。 如果你打开 **网页** 源,添加 `INTERNET` 给您的 **应用** 显示 :

```xml
<uses-permission android:name="android.permission.INTERNET" />
```

本地文件和 Base64 不需要额外的权限, 超出您的应用程序已经使用的读取路径 .

## 网页

网络不需要电容同步步骤 。 URL 来源随您一起获取 `headers`· ; `setZoom` 由于缩放由浏览器控制,所以是不可操作的。 密码不能在网络上被注入;浏览器可能自行提示.

## 使用量

```typescript
import { PdfViewer } from '@capgo/capacitor-pdf-viewer';

await PdfViewer.addListener('pageChange', ({ page, pageCount }) => {
  console.log(`Page ${page} of ${pageCount}`);
});

const { pageCount, page } = await PdfViewer.open({
  source: 'https://example.com/manual.pdf',
  headers: { Authorization: 'Bearer YOUR_TOKEN' },
  mode: 'fullscreen',
  scrollMode: 'continuous',
  page: 1,
});

await PdfViewer.goToPage({ page: 2 });
await PdfViewer.setZoom({ scale: 1.25 });
await PdfViewer.close();
```

**内置预览** 隐藏中 :

```typescript
await PdfViewer.open({
  source: base64FromYourApi,
  sourceType: 'base64',
  mode: 'inline',
  elementId: 'pdf-host',
});
```

**密码保护文件** (iOS和Android): (英语:

```typescript
await PdfViewer.open({
  source: '/path/on/device/encrypted.pdf',
  sourceType: 'path',
  password: 'secret',
});
```

在本地贝壳上,从 WebView 源 URL 上加载 PDF 经常失败,因为该源不是真实的文件服务器. 获取 JavaScript 中的字节并传递 `sourceType: 'base64'` 相反(见 `example-app/`) (中文(简体) ).

## API 密码

-   [`open(...)`](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/#readme-open)
-   [`close()`](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/#readme-close)
-   [`goToPage(...)`](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/#readme-gotopage)
-   [`setZoom(...)`](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/#readme-setzoom)
-   [`getPluginVersion()`](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/#readme-getpluginversion)
-   [`addListener('load', ...)`](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/#readme-addlistenerload-)
-   [`addListener('pageChange', ...)`](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/#readme-addlistenerpagechange-)
-   [`addListener('error', ...)`](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/#readme-addlistenererror-)
-   [`addListener('close', ...)`](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/#readme-addlistenerclose-)
-   [`addListener('linkTap', ...)`](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/#readme-addlistenerlinktap-)
-   [接口](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/#readme-type-aliases)

Capacitor的原生PDF取景器(iOS上的PDFKit,Android上的Pdfium,网页上的浏览器取景器).

### 打开(...)

```typescript
open(options: OpenPdfOptions) => Promise<OpenPdfResult>
```

从文件、路径、 URL 或 Base64 来源打开 PDF .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[OpenPdfOptions](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/#readme-openpdfoptions)` |

**回返情况:** `Promise<[OpenPdfResult](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/#readme-openpdfresult)>`

**自:** 8.0.0 (单位:千美元)

* * *

### 关闭( c)

```typescript
close() => Promise<void>
```

关闭活动查看器并删除任何覆盖 .

**自:** 8.0.0 (单位:千美元)

* * *

### gotoPage (...) (中文(简体) )

```typescript
goToPage(options: GoToPageOptions) => Promise<void>
```

跳转到打开文档中基于 1 的页码.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[GoToPageOptions](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/#readme-gotopageoptions)` |

**自:** 8.0.0 (单位:千美元)

* * *

### 设置Zoom (...)

```typescript
setZoom(options: SetZoomOptions) => Promise<void>
```

设置缩放比值乘数( E)`1` 是本地的默认适配比例. 在网页上此解析而不更改浏览器缩放 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[SetZoomOptions](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/#readme-setzoomoptions)` |

**自:** 8.0.0 (单位:千美元)

* * *

### 获取 PluginVersion ()

```typescript
getPluginVersion() => Promise<PluginVersionResult>
```

获取本地或网络执行版本标记 .

**回返情况:** `Promise<[PluginVersionResult](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/#readme-pluginversionresult)>`

**自:** 8.0.0 (单位:千美元)

* * *

### 添加倾听器( “ 装入 ” ,...)

```typescript
addListener(eventName: 'load', listenerFunc: (event: PdfLoadEvent) => void) => Promise<PluginListenerHandle>
```

听好 PDF 装入成功 .

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'load'` |
| **`listenerFunc`** | `(event: [PdfLoadEvent](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/#readme-pdfloadevent)) => void` |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/#readme-pluginlistenerhandle)>`

**自:** 8.0.0 (单位:千美元)

* * *

### 添加倾听器( “ pageChange ” ,...)

```typescript
addListener(eventName: 'pageChange', listenerFunc: (event: PdfPageChangeEvent) => void) => Promise<PluginListenerHandle>
```

在用户滚动时或当 QQlink PdfviewerPlugin.go ToPage} 运行时聆听页面变化 .

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'pageChange'` |
| **`listenerFunc`** | `(event: [PdfPageChangeEvent](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/#readme-pdfpagechangeevent)) => void` |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/#readme-pluginlistenerhandle)>`

**自:** 8.0.0 (单位:千美元)

* * *

### 添加倾听器( 'error',...)

```typescript
addListener(eventName: 'error', listenerFunc: (event: PdfErrorEvent) => void) => Promise<PluginListenerHandle>
```

打开或显示 PDF 时倾听出错 .

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'error'` |
| **`listenerFunc`** | `(event: [PdfErrorEvent](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/#readme-pdferrorevent)) => void` |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/#readme-pluginlistenerhandle)>`

**自:** 8.0.0 (单位:千美元)

* * *

### 添加倾听器( “ 关闭 ” ,...)

```typescript
addListener(eventName: 'close', listenerFunc: (event: PdfCloseEvent) => void) => Promise<PluginListenerHandle>
```

收听观看器关闭(用户手势或QQlink PdfviewerPlugin.close}).

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'close'` |
| **`listenerFunc`** | `(event: [PdfCloseEvent](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/#readme-pdfcloseevent)) => void` |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/#readme-pluginlistenerhandle)>`

**自:** 8.0.0 (单位:千美元)

* * *

### 添加倾听器('linkTap',...)

```typescript
addListener(eventName: 'linkTap', listenerFunc: (event: PdfLinkTapEvent) => void) => Promise<PluginListenerHandle>
```

监听PDF内部的链接.

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'linkTap'` |
| **`listenerFunc`** | `(event: [PdfLinkTapEvent](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/#readme-pdflinktapevent)) => void` |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/#readme-pluginlistenerhandle)>`

**自:** 8.0.0 (单位:千美元)

* * *

### 接口

#### OpenPdf 结果

PDF 成功打开后返回结果 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`pageCount`** | `number` | 文件总页数. |
| **`page`** | `number` | 目前页面,基于 1 . |

#### OpenPdf 选项

QQlink PdfviewPlugin. open} 的选项 .

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`source`** | `string` | PDF 位置: 文件 URL, 设备路径, https URL, 或 base64 (raw 或 `data:` (原始内容存档于2017-03-21). URI. |  |  |
| **`sourceType`** | `[PdfSourceType](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/#readme-pdfsourcetype)` | 明源类. 省略时: - `data:` 或无计划的生基64 `base64` - 说吧 `http`编号 :`https` => `url` - 否则.. `file` (处理方式为路径或文件 URL; `path` 土生土长的别名) |  | 8.0.0 (单位:千美元) |
| **`headers`** | `[Record](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/#readme-record)<string, string>` | 下载 https 时使用的 HTTP 头 `url` 源(例如认证符). |  | 8.0.0 (单位:千美元) |
| **`password`** | `string` | IOS和Android上加密的PDF的密码. 在网络上,密码不能被注入浏览器查看器;浏览器可能仍然会被提示. |  | 8.0.0 (单位:千美元) |
| **`mode`** | `[PdfDisplayMode](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/#readme-pdfdisplaymode)` | 如何是呈出观者. | `'fullscreen'` | 8.0.0 (单位:千美元) |
| **`elementId`** | `string` | DOM 元素 ID 当 `mode` 实值 `inline`原生代码测量此元素,并将取景者置于其上. |  | 8.0.0 (单位:千美元) |
| **`page`** | `number` | 首页 1分. |  | 8.0.0 (单位:千美元) |
| **`scrollMode`** | `[PdfScrollMode](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/#readme-pdfscrollmode)` | 卷行于观者内. | `'continuous'` | 8.0.0 (单位:千美元) |

#### GotoPage 选项

QQlink PdfViewerPlugin.go ToPage 的选项 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`page`** | `number` | 目标页面,基于1. |

#### 设置Zoom 选项

链接 PdfViewerPlugin.setZoom 的选项 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`scale`** | `number` | 放大乘数. `1` 是本地的默认适配比例. |

#### 插件变压器

来自QQlink PdfViewerPlugin.getPluginVersion的插件版本有效载荷 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`version`** | `string` | 平台执行返回的版本标识符(`native` 在iOS/Android上, `web` ) (中文(简体) ). |

#### 插件听筒

| Prop | 类型 |
| --- | --- |
| **`remove`** | `() => Promise<void>` |

#### PdfLoad 活动

有效载荷 `load` 活动.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`pageCount`** | `number` | 总页数. |
| **`page`** | `number` | 目前页面,基于 1 . |

#### PdfPageChangeEvent 移动事件

有效载荷 `pageChange` 活动.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`page`** | `number` | 目前页面,基于 1 . |
| **`pageCount`** | `number` | 总页数. |

#### 错误事件

有效载荷 `error` 活动.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`message`** | `string` | 人可读错误信息. |

#### PdfLinkTapEvent 游戏

有效载荷 `linkTap` 活动.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`url`** | `string` | 已调取链接的目标 URL . |

### 类型异名

#### Pdf 源代码

怎么样 `source` 弦应该被解释. 在省略时,插件从字符串形状中推断出类型.

`'file' | 'path' | 'url' | 'base64'`

#### 记录

构造 T 类型 K 的一组属性类型

`{ [P in K]: T; }`

#### PdfDisplay 模式

查看器的演示模式 .

-   `fullscreen`:用本地或浏览器覆盖应用程序.
-   `inline`: 将查看器放置在由 `elementId`。 。 。 .

`'fullscreen' | 'inline'`

#### Pdf 滚动模式

页面滚动行为.

-   `continuous`: 页面作为可滚动文档垂直流动.
-   `single`:一页一页.

`'continuous' | 'single'`

#### 关闭事件

有效载荷 `close` 事件(空对象).

`[Record](https://npmcn.com/package/%40capgo/capacitor-pdf-viewer/#readme-record)<string, never>`

## 常见问题

### @capgo/capacitor-pdf-viewer 是什么？

在应用程序内打开 PDF 的电容插件 \.

### 如何安装 @capgo/capacitor-pdf-viewer？

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

### @capgo/capacitor-pdf-viewer 支持 TypeScript 吗？

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

### @capgo/capacitor-pdf-viewer 支持 ESM 还是 CommonJS？

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

### @capgo/capacitor-pdf-viewer 可以商用吗？

@capgo/capacitor-pdf-viewer 使用 MPL-2\.0 许可。弱 Copyleft：可以商用，也可以和闭源代码一起使用；但如果分发时修改了 MPL 授权的文件，这些文件的修改需以 MPL 开源。以上为概括，不构成法律意见，请以许可原文为准。

### @capgo/capacitor-pdf-viewer 的下载量有多少？

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

### @capgo/capacitor-pdf-viewer 还在维护吗？

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