# @capgo/capacitor-downloader 中文文档

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

版本：8\.3\.19
npm 元数据更新时间：2026-11-09T07:19:25.406Z
中文译文更新时间：2026-11-09T02:44:21.009Z
软件包许可：MPL-2\.0

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

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

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

- 包体积（解压后）：111 kB，30 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2024-10-24T20:05:26.573Z
- 最新版本发布：2026-11-09T07:19:25.106Z
- 近 30 天下载量：78475（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：101（近 12 个月 67 个）

## 中文简介

在背景或前景下下载文件

## 安装

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

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

## README

# @ capgo/ 电容器下載器

从您的 Capacitor app 下载背景或前景中的大文件, 并暂停、 恢复和推进事件 。 用户离开屏幕时下载会持续进行.

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

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

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

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

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

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

## 主要特点

-   **下载**数字 : `download()` 以可选的 HTTP 头和 a 启动任务 `wifi-only` 或者细胞网络规则.
-   **控制权**数字 : `pause()`, (中文(简体) ), `resume()` 财务报告和审定财务报表 `stop()` 每个下载ID.
-   **进展活动**数字 : `downloadProgress`, (中文(简体) ), `downloadCompleted` 财务报告和审定财务报表 `downloadFailed` 听众.
-   **状况和文件**数字 : `checkStatus()` 任务和 `getFileInfo()` 用于下载文件.
-   **平台**: iOS和Android. 互联网档案馆的存檔,存档日期2013-12-21. iOS 使用背景 `URLSession`,Android 用途 `DownloadManager`。在网上不可用.

## 为什么是电容下载器?

一个可靠的 **本地文件下载器** 为 Capacitor 应用程序所建, 即使您的应用程序有背景或关闭, 仍会继续下载 :

-   **背景下载** - 即使在应用程序最小化、背景化或关闭(主要优势)的情况下,下载仍在继续
-   **进展跟踪** - 下载时实时更新进度
-   **网络控制** - 在无线网络或蜂窝网络下载之间选择
-   **自定义信头** - 添加认证符和自定义 HTTP 信头
-   **有偿下载** - 暂停并恢复下载(平台依赖)
-   **活动听众** - 监测下载进度、完成和故障
-   **大型文件支持** - 处理没有内存问题的多基加比特文件
-   **自由和开放源代码** - 不需要有偿服务

适合下载大型媒体文件,下线内容,应用更新,以及任何下载需要生存应用生命周期事件的情况.

## 文档

这里有最完整的医生: [https://capgo.app/docs/plugins/下行装入器/](https://capgo.app/docs/plugins/downloader/)

## 兼容性

| 插件版本 | 电容兼容性 | 维护 |
| --- | --- | --- |
| 联合国 | 联合国 | ✅ |
| 页: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-downloader` plugin in my project.
```

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

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

## API 密码

-   [`download(...)`](https://npmcn.com/package/%40capgo/capacitor-downloader/#readme-download)
-   [`pause(...)`](https://npmcn.com/package/%40capgo/capacitor-downloader/#readme-pause)
-   [`resume(...)`](https://npmcn.com/package/%40capgo/capacitor-downloader/#readme-resume)
-   [`stop(...)`](https://npmcn.com/package/%40capgo/capacitor-downloader/#readme-stop)
-   [`checkStatus(...)`](https://npmcn.com/package/%40capgo/capacitor-downloader/#readme-checkstatus)
-   [`getFileInfo(...)`](https://npmcn.com/package/%40capgo/capacitor-downloader/#readme-getfileinfo)
-   [`addListener('downloadProgress', ...)`](https://npmcn.com/package/%40capgo/capacitor-downloader/#readme-addlistenerdownloadprogress-)
-   [`addListener('downloadCompleted', ...)`](https://npmcn.com/package/%40capgo/capacitor-downloader/#readme-addlistenerdownloadcompleted-)
-   [`addListener('downloadFailed', ...)`](https://npmcn.com/package/%40capgo/capacitor-downloader/#readme-addlistenerdownloadfailed-)
-   [`removeAllListeners()`](https://npmcn.com/package/%40capgo/capacitor-downloader/#readme-removealllisteners)
-   [`getPluginVersion()`](https://npmcn.com/package/%40capgo/capacitor-downloader/#readme-getpluginversion)
-   [接口](https://npmcn.com/package/%40capgo/capacitor-downloader/#readme-interfaces)

用背景支持下载文件的电容插件. 提供可重复下载的进度跟踪.

### 下载(...)

```typescript
download(options: DownloadOptions) => Promise<DownloadTask>
```

开始一个新的下载任务 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[DownloadOptions](https://npmcn.com/package/%40capgo/capacitor-downloader/#readme-downloadoptions)` | \- 下载配置 |

**回返情况:** `Promise<[DownloadTask](https://npmcn.com/package/%40capgo/capacitor-downloader/#readme-downloadtask)>`

* * *

### 暂停(...)

```typescript
pause(options: { id: string; }) => Promise<void>
```

暂停活动下载 . 下载可以在稍后从同一位置恢复.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `{ id: string; }` | \- 包含下载任务ID的选项 |

* * *

### 恢复(...)

```typescript
resume(options: { id: string; }) => Promise<void>
```

恢复暂停下载 . 从暂停的地方继续.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `{ id: string; }` | \- 包含下载任务ID的选项 |

* * *

### 停止(...)

```typescript
stop(options: { id: string; }) => Promise<void>
```

停止并永久取消下载 . 下载后的数据将被删除 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `{ id: string; }` | \- 包含下载任务ID的选项 |

* * *

### 检查状态(...)

```typescript
checkStatus(options: { id: string; }) => Promise<DownloadTask>
```

请检查下载当前状态 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `{ id: string; }` | \- 包含下载任务ID的选项 |

**回返情况:** `Promise<[DownloadTask](https://npmcn.com/package/%40capgo/capacitor-downloader/#readme-downloadtask)>`

* * *

### 获取FileInfo (...)

```typescript
getFileInfo(options: { path: string; }) => Promise<{ size: number; type: string; }>
```

获取下载文件的信息 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `{ path: string; }` | \- 包含文件路径的选项 |

**回返情况:** `Promise<{ size: number; type: string; }>`

* * *

### 添加倾听器( “ 下载进度 ” ,...)

```typescript
addListener(eventName: 'downloadProgress', listenerFunc: (progress: { id: string; progress: number; bytesWritten?: number | undefined; bytesTotal?: number | undefined; }) => void) => Promise<PluginListenerHandle>
```

听取下载进度更新. 随着下载进度,定期放行.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`eventName`** | `'downloadProgress'` | \- 一定是"下载进展" |
| **`listenerFunc`** | `(progress: { id: string; progress: number; bytesWritten?: number; bytesTotal?: number; }) => void` | \- 召回接收进度更新 |

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

* * *

### 添加倾听器( “ 下载完成 ” ,...)

```typescript
addListener(eventName: 'downloadCompleted', listenerFunc: (result: { id: string; }) => void) => Promise<PluginListenerHandle>
```

听取下载完成 . 当下载成功完成时已解除 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`eventName`** | `'downloadCompleted'` | \- 一定是"下载完成" |
| **`listenerFunc`** | `(result: { id: string; }) => void` | \- 收到完成通知的召回 |

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

* * *

### 添加倾听器( “ 下载失败 ” ,...)

```typescript
addListener(eventName: 'downloadFailed', listenerFunc: (error: { id: string; error: string; }) => void) => Promise<PluginListenerHandle>
```

听取下载失败 . 当下载遇到错误时被解除 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`eventName`** | `'downloadFailed'` | \- 一定是"失败了" |
| **`listenerFunc`** | `(error: { id: string; error: string; }) => void` | \- 回调收到错误信息 |

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

* * *

### 删除所有收听器( )

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

删除全部事件听众 . 清理方法防止内存出漏.

* * *

### 获取 PluginVersion ()

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

获取插件版本号 .

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

* * *

### 接口

#### 下载任务

代表下载任务的现状和进度 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`id`** | `string` | 下载任务的独特标识符 |
| **`progress`** | `number` | 下载进度从 0 到 100 |
| **`state`** | `'PENDING' | 'RUNNING' | 'PAUSED' | 'DONE' | 'ERROR'` | 下载的当前状态 |

#### 下载选项

启动下载的配置选项 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`id`** | `string` | 此下载任务的独特标识符 |  |
| **`url`** | `string` | 要下载的文件的 URL |  |
| **`destination`** | `string` | 保存下载的本地文件路径 |  |
| **`headers`** | `{ [key: string]: string; }` | 在请求中包含的可选 HTTP 头 |  |
| **`network`** | `'cellular' | 'wifi-only'` | 下载的网络类型要求 |  |
| **`priority`** | `'high' | 'normal' | 'low'` | 下载优先级 |  |
| **`notification`** | `'completed' | 'progress' | 'hidden'` | Android DownloadManager 通知可见度. - `'completed'` (默认) : 下载时显示, 完成后保留通知 。 - `'progress'`: 下载时显示, 完成时删除通知 。 - `'hidden'`:没有系统通知;取而代之的是插件进度事件。 在iOS和Web上被忽略. | 8.2.0 (中文(简体) ) |

#### 插件听筒

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

### 信贷

此插件灵感来自 : [https://github.com/kesha-antonov/ react-native-background-downloader (中文(简体) )](https://github.com/kesha-antonov/react-native-background-downloader)

## 常见问题

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

在背景或前景下下载文件

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

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

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

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

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

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

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

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

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

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

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

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