# @capgo/capacitor-zip 中文文档

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

版本：8\.2\.2
npm 元数据更新时间：2026-10-21T14:53:28.180Z
中文译文更新时间：2026-11-09T03:41:27.480Z
软件包许可：MPL-2\.0

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

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

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

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

## 中文简介

IOS,Android,和Web上用于拉链和取出文件的免费Capacitor插件.

## 安装

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

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

## README

# @ capgo/ 电容- zip

在您的 Capacitor app 中 Zip 和 unzip 文件, 可以在 iOS 和 Android 上免费使用, 在网页的浏览器中解析 .

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

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

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

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

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

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

## 主要特点

-   **齐普**数字 : `zip()` 将文件或文件夹压缩到归档中.
-   **解齐普**数字 : `unzip()` 提取归档到目的文件夹 .
-   **土著图书馆**: ZIPFoundation on iOS和zip4j在Android上.
-   **Android 的密码**:AES-256在通过密码时加密了档案.
-   **网络解析**数字 : `unzip()` 在浏览器中工作,并单独下载每个文件,没有文件夹结构.
-   **进展活动**数字 : `addListener('progress', ...)` 报告字节和文件进度 `zip` 财务报告和审定财务报表 `unzip` (网:只提供unzip).
-   **平台**: iOS,Android和Web. 互联网档案馆的存檔,存档日期2013-12-02. `zip()` 无法在网上查阅.

## 为什么是Capacitor Zip?

A 类 **自由和开源选项** 对于 Capacitor apps 中的 ZIP 文件操作 :

-   **本地性能** - 使用平台-本地ZIP库进行快速压缩
-   **密码保护** - Android上的AES加密支持(iOS即将到来)
-   **跨平台** - 在iOS、Android和Web工作
-   **类型脚本** - 包括全部类型脚本定义
-   **现代 APIs** - 以最新的7个标准建造

适合需要文件压缩,备份功能,数据导出,或安全文件传输的应用程序.

## 文档

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

## 兼容性

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

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

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

### 进度倾听器

```typescript
import { CapacitorZip } from '@capgo/capacitor-zip';

const listener = await CapacitorZip.addListener('progress', (event) => {
  const percent = Math.round(event.progress * 100);
  console.log(`${event.operation} ${percent}%`, event.currentFile ?? '');
});

try {
  await CapacitorZip.zip({ source: '/path/to/folder', destination: '/path/to/archive.zip' });
} finally {
  await listener.remove();
}
```

## API 密码

-   [`addListener('progress', ...)`](https://npmcn.com/package/%40capgo/capacitor-zip/#readme-addlistenerprogress-)
-   [`zip(...)`](https://npmcn.com/package/%40capgo/capacitor-zip/#readme-zip)
-   [`unzip(...)`](https://npmcn.com/package/%40capgo/capacitor-zip/#readme-unzip)
-   [`getPluginVersion()`](https://npmcn.com/package/%40capgo/capacitor-zip/#readme-getpluginversion)
-   [接口](https://npmcn.com/package/%40capgo/capacitor-zip/#readme-interfaces)

用于压缩和取出zip档案的Capacitor Zip插件.

为本地 ZIP 文件操作提供平台特定执行:

-   iOS: 使用 ZIPFoundation(不支持密码保护)
-   Android: 使用有 AES 加密支持的 zip4j
-   Web: 使用zip.js(只使用unzip,触发下载)

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

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

听到进度更新时同时 `zip` 或者说 `unzip` 正在运行.

行动开始前登记 事件在网络上表现得最好(只有unzip). 每个活动包括: `operationId`, (中文(简体) ), `source`,以及 `destination` 当多个操作同时运行时, 您可以过滤 . 传递一个独有 `operationId` 每个电话,如果你提供自己的.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`eventName`** | `'progress'` | 事件名称( E)`progress`) (中文(简体) ). |
| **`listenerFunc`** | `(event: [ZipProgressEvent](https://npmcn.com/package/%40capgo/capacitor-zip/#readme-zipprogressevent)) => void` | 打电话 [`ZipProgressEvent`](https://npmcn.com/package/%40capgo/capacitor-zip/#readme-zipprogressevent) 有效载荷(包括 `loaded`, (中文(简体) ), `total`,以及 `lengthComputable` 喜欢 `ProgressEvent`) (中文(简体) ). |

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

**自:** 8.2.0 (中文(简体) )

* * *

### zip(...)

```typescript
zip(options: ZipOptions) => Promise<void>
```

压缩一个文件或目录以创建 ZIP 归档.

从源文件或目录创建压缩归档。 存档 如果源是一个文件夹,则将包含整个目录结构.

平台专用说明:

-   iOS:不支持密码保护. 如果提供密码,就会被忽略并登录警告.
-   Android:在提供密码时支持AES-256加密.
-   网:不支持. 如果调用, 则丢出错误 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[ZipOptions](https://npmcn.com/package/%40capgo/capacitor-zip/#readme-zipoptions)` | \- zip操作的配置 |

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

* * *

### unzip(...)

```typescript
unzip(options: UnzipOptions) => Promise<void>
```

提取 ZIP 归档到指定的目的目录 .

从 ZIP 归档中提取所有文件和文件夹,同时保存 目录结构。 如果目标目录不存在,则创建该目录.

平台专用说明:

-   iOS:支持标准ZIP档案. 不支持密码保护的档案; 忽略提供的密码 .
-   Android:支持AES加密的有密码的档案. 包括拉链滑行脆弱性保护.
-   Web:将每个文件单独下载到浏览器的下载文件夹. 无法创建目录结构 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[UnzipOptions](https://npmcn.com/package/%40capgo/capacitor-zip/#readme-unzipoptions)` | \- 解析操作的配置 |

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

* * *

### 获取 PluginVersion ()

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

获取本地插件版本 .

返回本地插件代码的版本, 它遵循 Capacitor 主要版本(如Capacitor 7.x的7.0.0).

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

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

* * *

### 接口

#### 插件听筒

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

#### Zip 进步活动

载荷释放的进展 `progress` 收听时 `zip` 财务报告和审定财务报表 `unzip`。 。 。 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`operationId`** | `string` | 特殊编号 `zip` 或者说 `unzip` 电话导致这个事件。 在使用时用此来区分并行操作 `addListener`。 。 。 . | 8.3.0 (单位:千美元) |
| **`source`** | `string` | `source` 从路径 `zip` 或者说 `unzip` 选项. | 8.3.0 (单位:千美元) |
| **`destination`** | `string` | `destination` 从路径 `zip` 或者说 `unzip` 选项. | 8.3.0 (单位:千美元) |
| **`operation`** | `'zip' | 'unzip'` | 字节是否正在被压缩或提取 . |  |
| **`loaded`** | `number` | 迄今处理的字节( 已知时未压缩大小) 。 与 `ProgressEvent.loaded` 在网络平台. |  |
| **`total`** | `number` | 已知时操作的总字节数, 否则 `0`。含义与 `ProgressEvent.total` 在网络平台. |  |
| **`lengthComputable`** | `boolean` | 是否为 `total` (或文件总计)代表此操作的已知长度. 与 `ProgressEvent.lengthComputable`。 。 。 . |  |
| **`progress`** | `number` | 比率从 `0` 改为 `1` 基于字节 `total &gt; 0`,否则在可用时文件数. |  |
| **`currentFile`** | `string` | 正在处理的条目的路径或名称 . |  |
| **`filesCompleted`** | `number` | 迄今完成的档案条目数量. |  |
| **`filesTotal`** | `number` | 档案中已知的总条目 . |  |

#### Zip 选项

创建 ZIP 归档的选项 .

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`source`** | `string` | 要压缩的文件或目录的路径 。 这可以是相对于应用程序工作目录的绝对路径或路径. 如果源是一个目录,其所有内容在保留目录结构的同时会被递归压缩. 平台特有注释:- iOS:使用文件://URL或绝对路径. 相对路径由应用的文档目录解决. - Android:对通过Android存储访问框架访问的文件使用绝对文件路径或内容://URIs. - 网络:不支持。 关于iOS和Android, `file://` URL( 例如来自 Cordova) `FileEntry.nativeURL`)和%-编码路径段在zip/unzip运行前实现文件系统路径正常化. |  | 7.0.0 (单位:千美元) |
| **`destination`** | `string` | 创建 ZIP 归档的路径 。 目的地路径必须包括.zip文件扩展名. 如果母目录不存在,则会自动创建. 平台特有注释:- iOS:使用文件://URL或绝对路径. 相对路径由应用的文档目录解决. 使用绝对文件路径。 插件将创建任何缺失的父目录 。 - 网络:不支持。 关于iOS和Android, `file://` URL 和 %- 编码路径段在 zip 运行前正常化为文件系统路径 . |  | 7.0.0 (单位:千美元) |
| **`password`** | `string` | 加密 ZIP 存档的可选密码 。 提供后,归档会被加密并需要此密码来提取. 在Android上使用AES-256加密. 平台特有说明: - iOS:不支持密码保护. 密码将被忽略, 警告会被登录 。 - Android:通过zip4j库支持AES-256加密. 提取时必须提供密码 。 - 网络:不支持. |  | 7.0.0 (单位:千美元) |
| **`includeParentFolder`** | `boolean` | 是否在 ZIP 归档中包含父文件夹 。 当真实( 默认) 时, 源文件夹本身成为归档中的根目录 。 当错误时,仅包含源文件夹的内容为根级. 此选项仅适用于源是一个目录 。 对于单个文件,此选项被忽略 . | `true` | 8.0.5 (中文(简体) ) |
| **`onProgress`** | `((event: [ZipProgressEvent](https://npmcn.com/package/%40capgo/capacitor-zip/#readme-zipprogressevent)) => void)` | 仅为此zip操作调用进度更新 。 更喜欢这个 `addListener('progress')` 当一次运行多个操作时。 听者自动注册并删除. |  | 8.3.0 (单位:千美元) |
| **`operationId`** | `string` | 可选操作id. 如果提供,它必须是同时提供的独特产品 `zip` 财务报告和审定财务报表 `unzip` 打电话 省略时自动生成 id . |  | 8.3.0 (单位:千美元) |

#### 解析选项

提取 ZIP 归档的选项 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`source`** | `string` | ZIP 归档路径取出 。 来源必须是有效的 ZIP 文件 。 如果文件不存在或被损坏,操作会因出错而失败. 平台特有注释:- iOS:使用文件://URL或绝对路径. 相对路径由应用的文档目录解决. - Android:使用绝对文件路径或内容:// 通过Android存储访问框架访问文件的 URI. - Web:使用HTTP/HTTPS URL. 文件会在浏览器中取出并提取. 关于iOS和Android, `file://` URL( 例如来自 Cordova) `FileEntry.nativeURL`) 和 %- 编码的路径段在unzip 运行前实现文件系统路径的正常化 . | 7.0.0 (单位:千美元) |
| **`destination`** | `string` | 将提取文件的目录路径 。 目的地目录如果不存在,将会被创建. 归档中的所有文件和文件夹都会被取出,同时保留目录结构. 平台特有注释:- iOS:使用文件://URL或绝对路径. 相对路径由应用的文档目录解决. 使用绝对文件路径。 包括防止拉链滑行弱点。 - 网页:不适用。 文件被单独下载到浏览器的下载文件夹. 关于iOS和Android, `file://` URL 和 %- 编码路径段在 unzip 运行前实现文件系统路径正常化 . | 7.0.0 (单位:千美元) |
| **`password`** | `string` | 用于解密密码保护的档案的可选密码. 如果 ZIP 归档是用密码加密的, 则需要 。 如果密码不正确, 提取会因出错而失败 。 平台特有说明:- iOS:不支持密码保护的ZIP档案. 如果提供密码,则忽略并记录警告。 - Android:支持使用zip4j或标准密码保护的ZIP创建的AES加密档案. - 网络:不支持。 无法在浏览器中提取密码保护的档案 . | 7.0.0 (单位:千美元) |
| **`onProgress`** | `((event: [ZipProgressEvent](https://npmcn.com/package/%40capgo/capacitor-zip/#readme-zipprogressevent)) => void)` | 仅为此未zip 操作调用进度更新 。 事件在网络上表现得最好(只有unzip). 更喜欢这个 `addListener('progress')` 当一次运行多个操作时。 听者自动注册并删除. | 8.3.0 (单位:千美元) |
| **`operationId`** | `string` | 可选操作id. 如果提供,它必须是同时提供的独特产品 `zip` 财务报告和审定财务报表 `unzip` 打电话 省略时自动生成 id . | 8.3.0 (单位:千美元) |

## 使用量

### 基本齐平

```typescript
import { CapacitorZip } from '@capgo/capacitor-zip';

// Zip a directory
await CapacitorZip.zip({
  source: '/path/to/directory',
  destination: '/path/to/output.zip'
});

// Zip a single file
await CapacitorZip.zip({
  source: '/path/to/file.txt',
  destination: '/path/to/output.zip'
});
```

### 有密码的 Zip

```typescript
import { CapacitorZip } from '@capgo/capacitor-zip';

await CapacitorZip.zip({
  source: '/path/to/directory',
  destination: '/path/to/output.zip',
  password: 'mySecurePassword123'
});
```

### 基本 Unzip

```typescript
import { CapacitorZip } from '@capgo/capacitor-zip';

await CapacitorZip.unzip({
  source: '/path/to/archive.zip',
  destination: '/path/to/extract'
});
```

### 解开密码

```typescript
import { CapacitorZip } from '@capgo/capacitor-zip';

await CapacitorZip.unzip({
  source: '/path/to/encrypted.zip',
  destination: '/path/to/extract',
  password: 'mySecurePassword123'
});
```

### 获取插件版本

```typescript
import { CapacitorZip } from '@capgo/capacitor-zip';

const { version } = await CapacitorZip.getPluginVersion();
console.log('Plugin version:', version);
```

## 平台支持

| 平台 | 支助 | 密码保护 | 页:1 |
| --- | --- | --- | --- |
| iOS系统 | ✅ | ❌ | 使用 ZIPFoundation 库( 不支持密码字) |
| 机器人 | ✅ | ✅ | 使用 zip4j 库保存密码保护的档案, 标准 Java ZIP 非加密 |
| 网页 | ⚠️ | ❌ | 有限支持 - 仅触发文件下载 |

### 平台限制

#### iOS系统

-   密码保护的档案不支持当前 ZIPFoundation 库
-   如果提供密码, 则会忽略密码并发出控制台警告

#### 机器人

-   通过zip4j对使用 AES 加密的密码保护的 ZIP 档案提供全面支持

#### 网页

网络实施有以下局限性:

-   **齐普**: 不支持( 显示出错)
-   **解齐普**: 为归档中的每个文件触发浏览器下载
-   **密码**: 不支持密码保护的档案

对于生产网络应用,考虑使用服务器侧解决方案进行zip操作.

## 文件路径

### iOS系统

使用相对于应用程序文档目录或完整路径的路径 :

```typescript
import { Filesystem, Directory } from '@capacitor/filesystem';

const { uri } = await Filesystem.getUri({
  directory: Directory.Documents,
  path: 'myfile.zip'
});

await CapacitorZip.unzip({
  source: uri,
  destination: Directory.Documents + '/extracted'
});
```

### 机器人

使用相对于应用程序的数据目录或完整路径的路径 :

```typescript
import { Filesystem, Directory } from '@capacitor/filesystem';

const { uri } = await Filesystem.getUri({
  directory: Directory.Data,
  path: 'myfile.zip'
});

await CapacitorZip.unzip({
  source: uri,
  destination: Directory.Data + '/extracted'
});
```

## 处理错误

```typescript
import { CapacitorZip } from '@capgo/capacitor-zip';

try {
  await CapacitorZip.zip({
    source: '/path/to/directory',
    destination: '/path/to/output.zip'
  });
  console.log('Zip created successfully!');
} catch (error) {
  console.error('Failed to create zip:', error);
}
```

## 依赖关系

### iOS系统

-   [ZI 伙伴关系](https://github.com/weichsel/ZIPFoundation) - 提供ZIP压缩和AES加密

### 机器人

-   [拉链4j](https://github.com/srikanth-lingala/zip4j) - 提供密码保护的ZIP支持

### 网页

-   [拉链.js](https://gildas-lormeau.github.io/zip.js/) - JavaScript ZIP 库(有限功能)

## 许可证

麻省理工学院

## 贷项

马丁·多纳迪乌为 [队长](https://capgo.app/)

## 常见问题

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

IOS,Android,和Web上用于拉链和取出文件的免费Capacitor插件\.

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

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

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

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

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

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

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

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

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

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

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

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