# @capgo/capacitor-file-picker 中文文档

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

版本：8\.2\.7
npm 元数据更新时间：2026-10-18T13:39:37.419Z
中文译文更新时间：2026-11-09T03:31:00.302Z
软件包许可：MPL-2\.0

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

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

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

- 包体积（解压后）：169 kB，25 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2025-12-16T03:40:08.731Z
- 最新版本发布：2026-10-18T13:39:37.068Z
- 近 30 天下载量：47326（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 21 个）

## 中文简介

文件拾取器 Capacitor 插件 - 拾取文件、图像、视频和目录

## 安装

```sh
npm install @capgo/capacitor-file-picker
```

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

## README

# @ capgo/ 电容器- 文件拾取器

让用户在iOS和Android上与本地取取取者一起取取文件,图像,视频和文件夹,并使用网页回落文件和媒体. 在 iOS 上转换 HEIC 相片并复制所选文件.

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

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

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

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

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

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

## 主要特点

-   **文件**数字 : `pickFiles()` 选择任何类型的一个或多个文件.
-   **媒体**数字 : `pickImages()`, (中文(简体) ), `pickVideos()` 财务报告和审定财务报表 `pickMedia()` 打开iOS和Android上的照片库取取取器。 他们在网络上打开按类型过滤的浏览器文件取取取器.
-   **文件夹**数字 : `pickDirectory()` 返回 iOS 和 Android 上的目录.
-   **HEIC和复制**数字 : `convertHeicToJpeg()` 转换 iOS 上的照片 `copyFile()` 复制选中的文件到新位置.
-   **拾取活动**(单位:千美元) `pickerDismissed` 听者加存储权限帮助者.
-   **平台**: iOS,Android和Web. 互联网档案馆的存檔,存档日期2013-12-02. 目录采取,HEIC转换和文件副本仅是本地的.

## 为什么是选手?

一个完整的文件拾取器插件 **完全本土支持** 用于iOS和Android:

-   **选择文件** - 选择任何带有 MIME 类型过滤的文件类型
-   **选择图像** - 具有多选择的原生照片库拾取器
-   **选择视频** - 具有持续时间和维度的本地取相器
-   **选择媒体** - 图像和视频综合采集器
-   **选择目录** - 选择文件夹(Android/iOS)
-   **HEIC 到 JPEG 数据** - 将 HEIC 图像转换为 JPEG( 仅iOS)
-   **复制文件** - 复制文件到新地点
-   **文件元数据** - 获得大小、尺寸、持续时间和更多

## 文档

这里有最完整的医生: [https://capgo.app/docs/plugins/file-picker/ 互联网档案馆的存檔,存档日期2013-12-02](https://capgo.app/docs/plugins/file-picker/)

## 兼容性

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

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

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

## 所需资源

-   iOS: iOS 15.0+ (英语)
-   Android:API 24+ (Android 7.0+) (英语)
-   Web: 文件 API 支持的现代浏览器

## Android 媒体权限和谷歌播放审查

此插件的设计围绕用户选择的拾取器流, 例如 `pickFiles()`, (中文(简体) ), `pickImages()`, (中文(简体) ), `pickVideos()`, (中文(简体) ), `pickMedia()`,以及 `pickDirectory()`。对于一次性或不频繁的文件、图像或视频选择,请使用这些取取器方法,并避免在您的应用程序显示中添加广泛的媒体权限.

仅允许 Google 播放 `READ_MEDIA_IMAGES` 财务报告和审定财务报表 `READ_MEDIA_VIDEO` 当照片或视频访问与您的应用程序的核心目的直接相关,而拾取器的替代品则不充分时. 不请求或保留这些权限,只允许用户选择文件、图像或视频.

在发布宣布这些权限的应用程序之前:

-   确保应用的核心功能需要宽相片或视频库访问.
-   准备好解释为什么Android Photo Picker或这个插件的取取器方法是不够的.
-   如果应用程序只能与用户选择的文件合作,则删除宽媒体权限 .

如果 Google Play 审查以类似消息拒绝应用程序 `Photo and Video Permissions policy: Permission use is not directly related to your app's core purpose`中,删除宽媒体权限并依赖此插件的拾取 API .

对于应用程序来自 `@capgo/capacitor-file`,自定义媒体浏览器,或者另一个宽存储流,推荐的选项是: `@capgo/capacitor-file-picker` 与 `pickImages()`, (中文(简体) ), `pickVideos()`, (中文(简体) ), `pickMedia()`,或 `pickFiles()`。 。 。 .

见谷歌 [图片和视频权限政策](https://support.google.com/googleplay/android-developer/answer/14115180) 目前审查所需经费.

## API 密码

-   [`pickFiles(...)`](https://npmcn.com/package/%40capgo/capacitor-file-picker/#readme-pickfiles)
-   [`pickImages(...)`](https://npmcn.com/package/%40capgo/capacitor-file-picker/#readme-pickimages)
-   [`pickVideos(...)`](https://npmcn.com/package/%40capgo/capacitor-file-picker/#readme-pickvideos)
-   [`pickMedia(...)`](https://npmcn.com/package/%40capgo/capacitor-file-picker/#readme-pickmedia)
-   [`pickDirectory()`](https://npmcn.com/package/%40capgo/capacitor-file-picker/#readme-pickdirectory)
-   [`convertHeicToJpeg(...)`](https://npmcn.com/package/%40capgo/capacitor-file-picker/#readme-convertheictojpeg)
-   [`copyFile(...)`](https://npmcn.com/package/%40capgo/capacitor-file-picker/#readme-copyfile)
-   [`checkPermissions()`](https://npmcn.com/package/%40capgo/capacitor-file-picker/#readme-checkpermissions)
-   [`requestPermissions()`](https://npmcn.com/package/%40capgo/capacitor-file-picker/#readme-requestpermissions)
-   [`addListener('pickerDismissed', ...)`](https://npmcn.com/package/%40capgo/capacitor-file-picker/#readme-addlistenerpickerdismissed-)
-   [`removeAllListeners()`](https://npmcn.com/package/%40capgo/capacitor-file-picker/#readme-removealllisteners)
-   [`getPluginVersion()`](https://npmcn.com/package/%40capgo/capacitor-file-picker/#readme-getpluginversion)
-   [接口](https://npmcn.com/package/%40capgo/capacitor-file-picker/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capgo/capacitor-file-picker/#readme-type-aliases)

用于选择文件、图像、视频和目录的Capacitor File Picker插件接口.

### pickFiles (...) (帮助)

```typescript
pickFiles(options?: PickFilesOptions | undefined) => Promise<PickFilesResult>
```

从设备中选择一个或多个文件 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[PickFilesOptions](https://npmcn.com/package/%40capgo/capacitor-file-picker/#readme-pickfilesoptions)` | \- 选择文件的选项 |

**回返情况:** `Promise<[PickFilesResult](https://npmcn.com/package/%40capgo/capacitor-file-picker/#readme-pickfilesresult)>`

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

* * *

### 选择图像(...)

```typescript
pickImages(options?: PickMediaOptions | undefined) => Promise<PickFilesResult>
```

从画廊取出一个或多个图像. 仅限Android/iOS. 关于Android, `limit` 可用时由系统取相器执行 (Android 13+,或称Android 11-12并配有Google Play系统取相机扩展). 旧的Android版本可能允许选择比 `limit`; 结果是 切换到 `limit` 在他们返回之前.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[PickMediaOptions](https://npmcn.com/package/%40capgo/capacitor-file-picker/#readme-pickmediaoptions)` | \- 选择图像的选项 |

**回返情况:** `Promise<[PickFilesResult](https://npmcn.com/package/%40capgo/capacitor-file-picker/#readme-pickfilesresult)>`

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

* * *

### 选择视频(...)

```typescript
pickVideos(options?: PickMediaOptions | undefined) => Promise<PickFilesResult>
```

从画廊取出一或多段视频. 仅限Android/iOS. 关于Android, `limit` 可用时由系统取相器执行 (Android 13+,或称Android 11-12并配有Google Play系统取相机扩展). 旧的Android版本可能允许选择比 `limit`; 结果是 切换到 `limit` 在他们返回之前.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[PickMediaOptions](https://npmcn.com/package/%40capgo/capacitor-file-picker/#readme-pickmediaoptions)` | \- 选择视频 |

**回返情况:** `Promise<[PickFilesResult](https://npmcn.com/package/%40capgo/capacitor-file-picker/#readme-pickfilesresult)>`

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

* * *

### 选择媒体(...)

```typescript
pickMedia(options?: PickMediaOptions | undefined) => Promise<PickFilesResult>
```

从画廊中取出一个或多个图像或视频. 仅限Android/iOS.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[PickMediaOptions](https://npmcn.com/package/%40capgo/capacitor-file-picker/#readme-pickmediaoptions)` | \- 选择媒体的选择 |

**回返情况:** `Promise<[PickFilesResult](https://npmcn.com/package/%40capgo/capacitor-file-picker/#readme-pickfilesresult)>`

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

* * *

### 选择目录( )

```typescript
pickDirectory() => Promise<PickDirectoryResult>
```

从设备中选择目录 . 仅限Android/iOS.

**回返情况:** `Promise<[PickDirectoryResult](https://npmcn.com/package/%40capgo/capacitor-file-picker/#readme-pickdirectoryresult)>`

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

* * *

### 转换HeicToJpeg(...)

```typescript
convertHeicToJpeg(options: ConvertHeicToJpegOptions) => Promise<ConvertHeicToJpegResult>
```

将 HEIC 图像转换为 JPEG 格式 . 仅iOS.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[ConvertHeicToJpegOptions](https://npmcn.com/package/%40capgo/capacitor-file-picker/#readme-convertheictojpegoptions)` | \- 转换方案 |

**回返情况:** `Promise<[ConvertHeicToJpegResult](https://npmcn.com/package/%40capgo/capacitor-file-picker/#readme-convertheictojpegresult)>`

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

* * *

### 复制文件(...)

```typescript
copyFile(options: CopyFileOptions) => Promise<void>
```

复制文件到新位置 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[CopyFileOptions](https://npmcn.com/package/%40capgo/capacitor-file-picker/#readme-copyfileoptions)` | 复制文件的选项 |

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

* * *

### 检查( )

```typescript
checkPermissions() => Promise<PermissionStatus>
```

请检查access-date=中的日期值 (帮助) 宽存储或媒体许可状态. 仅靠拾取器的流量不应设闸门 `pickFiles()`, (中文(简体) ), `pickImages()`, (中文(简体) ), `pickVideos()`,或 `pickMedia()` 在Android 13+的许可上. 仅限Android.

**回返情况:** `Promise<[PermissionStatus](https://npmcn.com/package/%40capgo/capacitor-file-picker/#readme-permissionstatus)>`

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

* * *

### 请求( )

```typescript
requestPermissions() => Promise<PermissionStatus>
```

请求宽存储或媒体权限. 不请求或声明 `READ_MEDIA_IMAGES` 或者说 `READ_MEDIA_VIDEO` 仅用于 picker API. Google Play 只允许这些权限 当拾取器的替代品不足以满足核心应用功能时. 使用 `@capgo/capacitor-file-picker` 选取方法代替 用户选择的文件、图像或视频访问. 仅限Android.

**回返情况:** `Promise<[PermissionStatus](https://npmcn.com/package/%40capgo/capacitor-file-picker/#readme-permissionstatus)>`

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

* * *

### 添加收听器( “ picker Dismission” ,...)

```typescript
addListener(eventName: 'pickerDismissed', listenerFunc: PickerDismissedListener) => Promise<PluginListenerHandle>
```

为拾取者开除事件增加一个收听器. 仅iOS.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`eventName`** | `'pickerDismissed'` | \- 活动名称 |
| **`listenerFunc`** | `[PickerDismissedListener](https://npmcn.com/package/%40capgo/capacitor-file-picker/#readme-pickerdismissedlistener)` | \- 听众的功能 |

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

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

* * *

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

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

删除此插件的所有听众 .

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

* * *

### 获取 PluginVersion ()

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

获取本地 Capacitor 插件版本 .

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

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

* * *

### 接口

#### 拾荒档案

选择文件的结果 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`files`** | `PickedFile[]` | 所选文件阵列 |

#### 选中文件

代表一个选中的文件 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`name`** | `string` | 文件名称 |
| **`path`** | `string` | 文件的路径 |
| **`mimeType`** | `string` | 文件的 MIME 类型 |
| **`size`** | `number` | 以字节计的文件大小 |
| **`data`** | `string` | Base64编码了文件的数据. 只有读取数据是真实存在的. |
| **`blob`** | `Blob` | 文件的 Blob 实例 。 只有网络. |
| **`width`** | `number` | 以像素表示的宽度( 仅图像/ 视频) |
| **`height`** | `number` | 高度以像素计(仅图像/视频) |
| **`duration`** | `number` | 持续时间以秒计(仅视频) |
| **`modifiedAt`** | `number` | 最后修改的时间戳以毫秒计 |

#### PickFiles 选项

选择文件的选项 .

| Prop | 类型 | 说明 | 默认 |
| --- | --- | --- | --- |
| **`types`** | `string[]` | 已接受的 MIME 类型或文件扩展名列表 。 在iOS上,只支持MIME类型. 例子:\['image/\*'\],\['application/pdf'\],\['.pdf','.doc'\] |  |
| **`limit`** | `number` | 要选择的文件的最大数量 。 为无限设定为 0(平台默认值). | `0` |
| **`readData`** | `boolean` | 是否将文件数据读取为 base64 。 注:读取大文件可能会引起内存问题. | `false` |

#### 选择媒体选项

选取介质的选项(图像/视频).

| Prop | 类型 | 说明 | 默认 |
| --- | --- | --- | --- |
| **`limit`** | `number` | 要选择的文件的最大数量 。 为无限设定为 0(平台默认值). 在Android上,当系统取相器可用时,平台执行这个限制(被设备最大封顶). 在更古老的Android版本上,拾取器可能不会执行限制;插件在必要时将返回的列表切入到这个值. | `0` |
| **`readData`** | `boolean` | 是否将文件数据读取为 base64 。 注:读取大文件可能会引起内存问题. | `false` |
| **`skipTranscoding`** | `boolean` | iOS只:跳过视频的转码. | `false` |
| **`ordered`** | `boolean` | iOS 15+只:显示所订购的选取徽章. | `false` |

#### 选取剪贴板

选择目录的结果 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`path`** | `string` | 选定目录的路径 |

#### 转换HeicToJpeg结果

HEIC到JPEG转换的结果.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`path`** | `string` | 转换后的 JPEG 文件的路径 |

#### 转换HeicToJpeg 选项

将 HIC 转换为 JPEG 的选项 .

| Prop | 类型 | 说明 | 默认 |
| --- | --- | --- | --- |
| **`path`** | `string` | 转换 HEIC 文件的路径 |  |
| **`quality`** | `number` | JPEG 的压缩质量( 0.0 - 1. 0) . | `0.9` |

#### 复制文件选项

复制文件的选项 .

| Prop | 类型 | 说明 | 默认 |
| --- | --- | --- | --- |
| **`from`** | `string` | 源文件路径 |  |
| **`to`** | `string` | 目标文件路径 |  |
| **`overwrite`** | `boolean` | 是否覆盖目标存在 . | `false` |

#### 权限状态

文件访问权限状态 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`readExternalStorage`** | `[PermissionState](https://npmcn.com/package/%40capgo/capacitor-file-picker/#readme-permissionstate)` | 是否获得广泛的外部存储或媒体许可. 返回用户所选择文件的Picker API在Android 13+上通常不需要这个. |
| **`accessMediaLocation`** | `[PermissionState](https://npmcn.com/package/%40capgo/capacitor-file-picker/#readme-permissionstate)` | 是否获准访问媒体位置 |

#### 插件听筒

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

### 类型异名

#### 权限状态

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

#### 拾取者解散听众

听者召回 捡取者解散事件.

`(event: null): void`

## 常见问题

### @capgo/capacitor-file-picker 是什么？

文件拾取器 Capacitor 插件 - 拾取文件、图像、视频和目录

### 如何安装 @capgo/capacitor-file-picker？

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

### @capgo/capacitor-file-picker 支持 TypeScript 吗？

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

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

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

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

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

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

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

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

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