# @capgo/capacitor-printer 中文文档

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

版本：8\.1\.8
npm 元数据更新时间：2026-10-15T03:54:20.733Z
中文译文更新时间：2026-11-09T02:23:12.454Z
软件包许可：MPL-2\.0

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

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

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

- 包体积（解压后）：198 kB，26 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2025-11-19T01:45:23.793Z
- 最新版本发布：2026-10-15T03:54:20.454Z
- 近 30 天下载量：130570（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：29（近 12 个月 29 个）

## 中文简介

用于打印文档、 HTML、 PDF 、 图像和网页视图的电容插件

## 安装

```sh
npm install @capgo/capacitor-printer
```

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

## README

# @ capgo/ 电容器打印器

打印文档, HTML, PDF, 图像和当前从您的 Capacitor app 的网页视图, 并使用 iOS 和 Android 上的本地打印对话框 .

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

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

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

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

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

![@capgo/capacitor-printer for Capacitor apps](https://raw.githubusercontent.com/Cap-go/capacitor-printer/main/assets/github-social-preview.png)

## 主要特点

-   **HTML 语言**数字 : `printHtml()` 打印 HTML 字符串.
-   **PDF 和文件**数字 : `printPdf()`, (中文(简体) ), `printFile()` 财务报告和审定财务报表 `printBase64()` 用于设备文件和基础64数据.
-   **网页内容**数字 : `printWebView()` 打印当前页面并 `printIframe()` 打印一个 iframe.
-   **本地对话框**数字 : `UIPrintInteractionController` iOS和Android打印框架.
-   **平台**: iOS,Android和Web. 互联网档案馆的存檔,存档日期2013-12-02. Web使用浏览器打印对话框.

## 为什么是电容打印机?

A 类 **自由和开源** 具有全面特性的打印解决方案 :

-   **多种格式** - 打印HTML、PDF、图像和基础64数据
-   **本地 APIs** - 使用UIPrint接口控制器(iOS)和打印管理器(Android)
-   **网络支持** - 在所有平台(包括网页浏览器)开展工作
-   **打印定制** - 支持CSS打印样式和自定义页面名称
-   **跨平台** - 一致的API跨iOS,Android,和Web

完全适合发票的生成、报告打印、文件共享以及任何需要本地印刷能力的应用程序.

## 文档

这里有最完整的医生: [https://capgo.app/docs/plugins/printer/ 页面存档备份,存于互联网档案馆](https://capgo.app/docs/plugins/printer/)

## 兼容性

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

> **说明:** 此插件的主要版本沿用了Capacitor的主要版本. 使用匹配您的 Capacitor 安装的版本( 如 Capacitor 8 的插件 v8) 。 只有最新的主要版本得到积极维护.

## 安装

您可以使用我们的 AI 辅助设置安装插件 。 使用以下命令将 Capgo 技能添加到您的 AI 工具 :

```bash
npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins
```

然后使用下列提示:

```text
Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-printer` plugin in my project.
```

如果您更喜欢手动设置,请通过运行以下命令来安装插件,并遵循下面的平台特定指令:

```bash
npm install @capgo/capacitor-printer
npx cap sync
```

## 使用量

```typescript
import { Printer } from '@capgo/capacitor-printer';

// Print HTML content
await Printer.printHtml({
  name: 'My Document',
  html: '<html><body><h1>Hello World</h1><p>This is a test document.</p></body></html>',
});

// Print PDF file
await Printer.printPdf({
  name: 'Invoice',
  path: 'file:///path/to/document.pdf',
});

// Print image from base64
await Printer.printBase64({
  name: 'Photo',
  data: 'JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL...',
  mimeType: 'image/jpeg',
});

// Print current web view
await Printer.printWebView({
  name: 'Web Page',
});
```

## API 密码

-   [`printBase64(...)`](https://npmcn.com/package/%40capgo/capacitor-printer/#readme-printbase64)
-   [`printFile(...)`](https://npmcn.com/package/%40capgo/capacitor-printer/#readme-printfile)
-   [`printHtml(...)`](https://npmcn.com/package/%40capgo/capacitor-printer/#readme-printhtml)
-   [`printPdf(...)`](https://npmcn.com/package/%40capgo/capacitor-printer/#readme-printpdf)
-   [`printIframe(...)`](https://npmcn.com/package/%40capgo/capacitor-printer/#readme-printiframe)
-   [`printWebView(...)`](https://npmcn.com/package/%40capgo/capacitor-printer/#readme-printwebview)
-   [`getPluginVersion()`](https://npmcn.com/package/%40capgo/capacitor-printer/#readme-getpluginversion)
-   [接口](https://npmcn.com/package/%40capgo/capacitor-printer/#readme-interfaces)

### 打印Base64(...)

```typescript
printBase64(options: PrintBase64Options) => Promise<void>
```

将打印的 UI 显示为已编码为 Base64 字符串的文件 .

**平台行为 :**

-   **iOS系统**: 使用具有基数64解码数据的 UIPrint 交互控制器
-   **机器人**: 使用带有基础64解码数据的打印管理器
-   **网页**: 从 Base64 数据创建 blob并打开打印对话框

**性能警告 :** 大型文件在解码基础64时会由于内存限制而导致应用崩溃. 对于大于5MB的文件,建议使用平面File()来取而代之.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[PrintBase64Options](https://npmcn.com/package/%40capgo/capacitor-printer/#readme-printbase64options)` | \- 用于印刷的基数64数据和配置 |

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

* * *

### 打印文件(...)

```typescript
printFile(options: PrintFileOptions) => Promise<void>
```

向打印设备文件提交打印 UI .

**平台行为 :**

-   **iOS系统**: 使用带有文件 URL 的 UIPrint Interaction 控制器. 支持文件://路径或路径相对于app的文档目录.
-   **机器人**: 使用带有文件路径的打印管理器. 支持内容://URIs和文件://路径.
-   **网页**: 读取文件并打开打印对话框

**支持的文件类型 :**

-   PDF 文档 (应用程序/pdf)
-   图像:JPEG、PNG、GIF、HEIC、HEIF

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[PrintFileOptions](https://npmcn.com/package/%40capgo/capacitor-printer/#readme-printfileoptions)` | \- 打印的文件路径和配置 |

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

* * *

### 打印Html(...)

```typescript
printHtml(options: PrintHtmlOptions) => Promise<void>
```

呈现打印 UI 打印 HTML 文档.

**平台行为 :**

-   **iOS系统**: WKWebView 中的 Renders HTML, 然后使用 UIPrint Interaction 控制器打印
-   **机器人**: WebView 中的渲染器 HTML, 然后使用打印管理器打印
-   **网页**: 创建带有 HTML 内容的 iframe并触发打印对话框

**HTML 要求 :**

-   应该是一个完整的HTML文档,并有适当的结构
-   可包含内置 CSS 样式或样式标签
-   外部资源(图像、样式表)应使用绝对 URL
-   可用 @ media 打印规则添加特定打印 CSS

**CSS 打印样式 :** 使用 CSS 媒体查询自定义打印输出 :

-   控制分页:分页前,分页后,分页后,分页后
-   隐藏元素: 显示: 无打印类
-   调整打印字体大小和颜色

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[PrintHtmlOptions](https://npmcn.com/package/%40capgo/capacitor-printer/#readme-printhtmloptions)` | \- HTML 打印的内容和配置 |

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

* * *

### 打印Pdf(...)

```typescript
printPdf(options: PrintPdfOptions) => Promise<void>
```

呈现打印 UI 打印 PDF 文档.

**平台行为 :**

-   **iOS系统**: 使用与 PDF 文件 URL 的 UIPrint 交互控制器
-   **机器人**: 使用带有 PdfDocument 的打印管理器
-   **网页**: 创建对象 URL并打开打印对话框

**文件路径要求 :**

-   **iOS系统**: 必须是文件://路径或相对于 app 文档目录
-   **机器人**: 支持内容://URI(从下载,媒体存储)或文件://路径
-   **网页**: 必须是可访问的文件路径

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[PrintPdfOptions](https://npmcn.com/package/%40capgo/capacitor-printer/#readme-printpdfoptions)` | \- 用于打印的PDF文件路径和配置 |

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

* * *

### 打印Iframe(...)

```typescript
printIframe(options: PrintIframeOptions) => Promise<void>
```

显示一个 iframe 元素内的内容的打印 UI .

当完整的 HTML 文档太大而无法通过打印时有用 .

**平台行为 :**

-   **iOS系统**: 在 WebView 中评价 JavaScript 打印 Iframe 内容
-   **机器人**: 在 WebView 中评价 JavaScript 打印 Iframe 内容
-   **网页**: 查找框架并触发其打印对话框

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[PrintIframeOptions](https://npmcn.com/package/%40capgo/capacitor-printer/#readme-printiframeoptions)` | \- CSS 选择器和可选打印作业名称 |

**自:** 8.0.19 联合国

* * *

### 打印WebView(...)

```typescript
printWebView(options?: PrintOptions | undefined) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[PrintOptions](https://npmcn.com/package/%40capgo/capacitor-printer/#readme-printoptions)` |

* * *

### 获取 PluginVersion ()

```typescript
getPluginVersion() => Promise<{ version: string; }>
```

获取本地 Capacitor 插件版本 .

从本地代码(iOS/Android)返回硬编码插件版本或 软件包版本 (Web). 用于调试和确保插件 兼容性.

**回返情况:** `Promise<{ version: string; }>`

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

* * *

### 接口

#### 打印Base64 选项

打印碱基64编码数据的选项.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`data`** | `string` | 有效的 Base64 编码字符串代表文件内容. base64字符串不应包括数据 URL 前缀(如"data:application/pdf;base64"). 只提供原始基础64编码内容. **业绩考量:** - Base64 编码将数据大小增加约33% - 大文件( > 5MB) 解码时可能造成内存问题 - 考虑对大文件使用打印File( ) **平台说明:** - 说吧 **iOS系统**: 解码为NSData, 并传递给 UIPrint Interaction 控制器 - **机器人**: 解码为字节数组并写入临时文件 - **网页**: 转换为 Blob 打印 | 7.0.0 (单位:千美元) |
| **`mimeType`** | `string` | Base64编码数据的MIME类型. **支持类型 :** - 说吧 `application/pdf` - PDF文档 - `image/jpeg` - JPEG 图像 `image/png` - PNG图像 `image/gif` - GIF图像(仅iOS/Android) - `image/heic` -HEIC图像(只有iOS) - `image/heif` - HEIF图像(只有iOS) **平台支持:** - 所有平台支持PDF、JPEG和PNG - GIF支持因平台而异 - HEIC/HEIF是iOS特定格式 | 7.0.0 (单位:千美元) |

#### 打印文件选项

从设备存储中打印文件的选项 .

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`path`** | `string` | 要打印的文件路径 . **iOS 路径格式 :** - 说吧 `file://` URL: 完整文件 URL 路径 - 相对路径: 相对于 app 文档目录的路径 - 必须在 app 可访问目录(文档,临时,缓存)内 **Android 路径格式 :** - 说吧 `content://` URI: 内容提供者 URI (推荐给外部文件) - `file://` 路径: 直接文件系统路径 - 文件必须有读取权限 **常用案例 :** - App文档:AP文档目录中保存的文件 - 下载:系统下载文件夹中的文件(使用内容://在Android上) - 临时文件:AP临时/cache目录中的文件 - 共享存储:外部存储中的文件(Android,需要权限) |  | 7.0.0 (单位:千美元) |
| **`mimeType`** | `string` | 文件的MIME类型. **平台行为 :** - 说吧 **机器人**: 内容需要QUIRED=URIs. 帮助系统决定如何处理文件。 可选文件://路径( 从扩展名自动检测) 。 - **iOS系统**:被忽略了. 文件类型是从文件扩展名中自动发现的 。 - **网页**: 可选。 未提供自动检测. **常见的 MIME 类型 :** - 说吧 `application/pdf` - PDF文档 - `image/jpeg` - JPEG 图像 `image/png` - PNG图像 `image/gif` - GIF图像 | `Undefined (auto-detected from file extension)` | 7.0.0 (单位:千美元) |

#### 打印Html 选项

打印 HTML 内容的选项 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`html`** | `string` | HTML 要打印的内容. **内容要求:** - 应该是一个完整的 HTML 文档与 `&lt;html&gt;`, (中文(简体) ), `&lt;head&gt;`,以及 `&lt;body&gt;` 标签 - 可包含内置 CSS 样式或 `&lt;style&gt;` 标签 - 外部资源( 图像, 字体) 应使用绝对 URL - JavaScript 在打印渲染过程中没有执行 **打印优化提示 :** - 使用( I) `@media print` 用于打印特定样式的 CSS 规则 - 控制页面间隔 `page-break-before`, (中文(简体) ), `page-break-after`, (中文(简体) ), `page-break-inside` - 使用 `.no-print { display: none; }` 类 - 调整可读性字体大小(12pt是打印的标准) - 使用方便打印的颜色(避免暗色背景) **平台渲染:** - 说吧 **iOS系统**:打印前在 WKWebView 中渲染 - **机器人**: 在打印前在 WebView 中渲染 - **网页**: 打印前在隐藏的 Iframe 中渲染 **字符编码 :** - UTF-8 推荐并默认 - 在 HTML 中包含字符集 : `&lt;meta charset="UTF-8"&gt;` | 7.0.0 (单位:千美元) |

#### 打印 Pdf 选项

打印 PDF 文档的选项.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`path`** | `string` | PDF 文档路径 . **iOS 路径格式 :** - 说吧 `file://` URL: PDF 文档的完整文件 URL 路径 - 相对路径: 相对于 app 文档目录的路径 - 必须在 app 的可访问目录(文档,临时,缓存)内 - PDF 必须是有效的且不受密码保护 **Android 路径格式 :** - 说吧 `content://` URI: 内容提供者 URI (推荐给外部 PDF) - `file://` 路径: 直接文件系统路径到 PDF - 文件必须读取权限 - 支持单页和多页 PDF **网络路径格式 :** - 从网络上下文访问相对或绝对路径 - 必须是有效的PDF文件 **验证 :** - 文件必须在指定的路径上存在 - 文件必须是有效的PDF(由魔法号码/标题检查) - 文件必须可以被应用读取 **共同来源:** - App文档:被保存在App文档目录中的PDFs - 下载:系统下载的PDFs(使用内容://在Android上) - 生成的PDFs:由App创建的临时PDFs - 网络下载:本地下载并保存的PDFs | 7.0.0 (单位:千美元) |

#### 打印框架选项

打印 Iframe 内容的选项 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`selector`** | `string` | 用于 Iframe 元素打印的 CSS 选择器 。 选择器必须匹配当前文档中的单个 Iframe . | 8.0.19 联合国 |

#### 打印选项

所有打印操作的基础选项 .

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`name`** | `string` | 打印作业的名称 . **用法 :** - 在系统打印队列中显示 - 在打印历史/日志中显示 - 可能在打印机状态显示中显示 - 用作“ 保存为PDF” 选项的默认文件名 **平台行为 :** - 说吧 **iOS系统**: 在打印预览页头和活动视图中显示 - **机器人**: 在打印任务通知和打印队列中显示 - **网页**: 在打印对话框中用作文档标题 **最佳做法:** - 使用描述性名称(例如"发票#12345","Q4报告") - 保留在50个字符以更好地显示 - 避免在文件名中引起问题的特殊字符 - 包含相关的标识符(顺序号,日期等) **实例:** -"发票#12345"-"销售报告-2024Q4"-"客户收据-约翰·多伊"-"出品相片-SKU-ABC123" | `'Document'` | 7.0.0 (单位:千美元) |

## Android 配置

### 保护

如果您使用ProGuard,请在您的 `proguard-rules.pro` 文件 :

```pro
-keep class com.capgo.printer.** { *; }
```

### 变量

您可以在您中配置以下工程变量 `variables.gradle` 文件 :

```gradle
ext {
  androidxDocumentFileVersion = '1.0.1'
  androidxPrintVersion = '1.0.0'
}
```

## 平台支持

| 平台 | 支助 |
| --- | --- |
| iOS系统 | ✅ |
| 机器人 | ✅ |
| 网页 | ✅ |

## 页:1

### 大文件

在打印基础64编码数据时,由于内存限制,大文件可能导致应用崩溃. 对于大型文件,建议先将其保存到设备并使用 `printFile()` 换句话说.

### 网络平台

网络平台上:

-   `printWebView()` 触发浏览器的本地打印对话框
-   其他方法创建并打印其内容
-   一些浏览器可能对某些文件类型的打印有安全限制

### 打印样式

在打印网页内容时, 您可以使用 CSS 媒体查询来自定义打印输出 :

```css
@media print {
  /* Your print styles here */
  body {
    font-size: 12pt;
  }
  .no-print {
    display: none;
  }
}
```

## 常见问题

### @capgo/capacitor-printer 是什么？

用于打印文档、 HTML、 PDF 、 图像和网页视图的电容插件

### 如何安装 @capgo/capacitor-printer？

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

### @capgo/capacitor-printer 支持 TypeScript 吗？

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

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

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

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

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

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

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

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

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