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

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

版本：8\.1\.1
npm 元数据更新时间：2026-10-19T05:59:55.803Z
中文译文更新时间：2026-11-09T01:52:37.968Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：190 kB，32 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2022-08-04T17:42:53.901Z
- 最新版本发布：2026-10-19T05:59:55.416Z
- 近 30 天下载量：575263（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：51（近 12 个月 10 个）

## 中文简介

控制器插件,允许用户在Android,iOS,和Web上选择一个文件,目录,图像,或视频.

## 安装

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

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

## README

# 电容文件拾取器插件

控制器插件,允许用户从设备的文件系统或相册中选择文件,目录,图像,或视频.

[![Thousands of teams ship faster with Capawesome Cloud Native Builds and Live Updates](https://capawesome.io/assets/banners/cloud-teams-ship-faster-with-capacitor.png)](https://capawesome.io/)

## 特征

Capacitor File Picker插件是Capacitor app最完整的文件选择解决方案之一. 以下是一些关键特征:

-   🖥️ **跨平台**:支持Android,iOS和Web.
-   📂 **目录选择**:允许用户选择一个目录来检索所有文件.
-   🖼️ **图像选择**:让用户从画廊中选择一个或多个图像.
-   🎥 **视频采集**:让用户从画廊中选择一个或多个视频.
-   📄 **文件选择**: 让用户从文件系统中选择一个或多个杂项文件.
-   📸 **HEIC 到 JPEG 转换**:在iOS上将HEIC图像转换为JPEG格式.
-   📜 **文件元数据**:检索文件大小,名称,mime类型等元数据,以及最后修改的时间戳.
-   🤝 **兼容性**: 与 [文件压缩器](https://capawesome.io/docs/sdks/capacitor/file-compressor/), (中文(简体) ), [文件打开器](https://capawesome.io/docs/sdks/capacitor/file-opener/) 财务报告和审定财务报表 [共享目标](https://capawesome.io/docs/sdks/capacitor/share-target/) 插件 .
-   📦 **可可花和SPM**:支持CocoaPods和Swift软件包管理器用于iOS.
-   🔁 **最新数据**:总是支持最新的Capacitor版本.

缺少一个功能? 刚刚 [打开一个问题](https://github.com/capawesome-team/capacitor-plugins/issues) 我们看看!

## 使用大小写

文件拾取器插件通常在应用程序需要用户交出文件时使用,例如:

-   **文件上传**:让用户将PDF或电子表格等文档附加到一个表格上并上传到服务器上.
-   **简介和封面图片**:让用户从他们的画廊中选择一张照片.
-   **媒体附件**: 将图像和视频添加到聊天消息,帖子,或支持票.
-   **数据导入**: 导入 CSV, JSON, 或备份文件到您的应用程序中 .

## 兼容性

| 插件版本 | 电容版本 | 状态 |
| --- | --- | --- |
| 8.x.x (英语) | \>=8.x.x | 积极支持 |
| 6.x.x (中文(简体) ) | 6.x.x (中文(简体) ) | 折旧 |
| 5.x.x (中文(简体) ) | 5.x.x (中文(简体) ) | 折旧 |

## 指南

-   [处理器文件处理指南](https://capawesome.io/blog/capacitor-file-handling-guide/)

## 安装

你可以用我们的 **AI 辅助设置** 以安装插件. 添加数据 [超级技能](https://github.com/capawesome-team/skills) 至您的 AI 工具,使用以下命令:

```bash
npx skills add capawesome-team/skills --skill capacitor-plugins
```

然后使用下列提示:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-file-picker` plugin in my project.
```

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

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

### 机器人

#### 变量

此插件将使用以下工程变量( 在您的应用程序中定义) `variables.gradle` 文件名 :

-   `$androidxActivityVersion` 版本 `androidx.activity:activity` (默认 : `1.13.0`(中文(简体) )

#### 权限

此 API 需要将以下权限添加到您 `AndroidManifest.xml` 开始之前或之后 `application` 标签 :

```xml
<!-- Needed if you want to retrieve unredacted EXIF metadata from photos -->
<uses-permission android:name="android.permission.ACCESS_MEDIA_LOCATION" />
<!-- Needed if you want to read files from external storage -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
```

### iOS系统

#### 应享权利

要使用这个带有Mac Cactoryst的插件, 您的应用程序必须拥有 `com.apple.security.files.user-selected.read-only` 已启用。 这允许应用程序读取用户选择的文件. 看看这个 [苹果文档](https://developer.apple.com/documentation/bundleresources/entitlements/com.apple.security.files.user-selected.read-only) 更多信息.

```xml
<key>com.apple.security.files.user-selected.read-only</key>
<true/>
```

如果您不想使用带有Mac Catalyst的插件,可以跳过这个步骤.

## 配置

此插件不需要配置 .

## 使用量

以下例子显示了如何选择文件,图像,视频和目录,以及如何处理所选文件.

### 选择一个或多个文件

打开系统文件拾取器,让用户选择一个或多个任意类型的文件. 其结果包括元数据(名称、大小、mime类型、最后修改的时间戳)以及Android和iOS上每个所选文件的路径:

```typescript
import { FilePicker } from '@capawesome/capacitor-file-picker';

const pickFiles = async () => {
  const result = await FilePicker.pickFiles();
  const file = result.files[0];
};
```

### 将拾取器限制为特定文件类型

使用 `types` 只接受某些选项 [IANA 媒体类型](https://www.iana.org/assignments/media-types/media-types.xhtml),例如PDF文档:

```typescript
import { FilePicker } from '@capawesome/capacitor-file-picker';

const pickPdfFiles = async () => {
  const result = await FilePicker.pickFiles({
    types: ['application/pdf'],
  });
};
```

在Android上,系统文件取取器只能提供设备出自文件扩展名的媒体类型文件. 在Android 9 岁及以上, `.json` 文件没有映射到 `application/json` 报告为: `application/octet-stream`第三方文件提供者在任何版本上的行为都可能相同。 添加 `application/octet-stream` 改为 `types` 如果这些文件必须是可选择的.

### 从画廊取出图像或视频

使用 `pickImages(...)`, (中文(简体) ), `pickVideos(...)` 或者说 `pickMedia(...)` 打开相册,而不是文件取取器。 这些方法仅在Android和iOS上提供:

```typescript
import { FilePicker } from '@capawesome/capacitor-file-picker';

const pickImages = async () => {
  const result = await FilePicker.pickImages();
};

const pickVideos = async () => {
  const result = await FilePicker.pickVideos();
};

const pickMedia = async () => {
  // Pick both images and videos
  const result = await FilePicker.pickMedia({ limit: 3 });
};
```

### 在网页视图中显示所选图像

使用 `webPath` 在网页视图中加载所选文件的属性, 例如 `src` 一、导 言 `<img>` 元素 :

```typescript
import { FilePicker } from '@capawesome/capacitor-file-picker';

const displayImage = async () => {
  const { files } = await FilePicker.pickImages({ limit: 1 });
  const image = document.createElement('img');
  image.src = files[0].webPath!;
  document.body.appendChild(image);
};
```

### 选择目录

让用户选择一个目录,例如导入它包含的所有文件. 仅在Android和iOS上提供:

```typescript
import { FilePicker } from '@capawesome/capacitor-file-picker';

const pickDirectory = async () => {
  const { path } = await FilePicker.pickDirectory();
};
```

### 将选中的文件上传到服务器

在网络上,选中的文件包含 `Blob` 举个例子 在Android和iOS上,使用 [获取 API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) 和文档的 `webPath`。然后您可以将 blob 附加到 a `FormData` 对象并上传:

```typescript
import { FilePicker } from '@capawesome/capacitor-file-picker';

const uploadFile = async () => {
  const result = await FilePicker.pickFiles({ limit: 1 });
  const file = result.files[0];

  let blob: Blob;
  if (file.blob) {
    // Web
    blob = file.blob;
  } else {
    // Android and iOS
    const response = await fetch(file.webPath!);
    blob = await response.blob();
  }

  const formData = new FormData();
  formData.append('file', blob, file.name);
  await fetch('https://example.com/upload', {
    method: 'POST',
    body: formData,
  });
};
```

**请注意**: 避开 `readData` 选项。 它将整个文件装入内存作为 Base64 字符串,这可以崩溃您的应用. 基于获取的方法在文件上方流出 .

### 将 HEIC 图像转换为 JPEG

在iOS上,相片经常被以HEIC格式存储,许多服务器和浏览器无法显示. 使用 `convertHeicToJpeg(...)` 以转换它们。 仅在iOS上可用 :

```typescript
import { FilePicker } from '@capawesome/capacitor-file-picker';

const convertHeicToJpeg = async () => {
  const { path } = await FilePicker.convertHeicToJpeg({
    path: 'path/to/image.heic',
  });
};
```

### 将 RAW 图像转换为 JPEG

RAW图像(如DNG)在被取出时没有被转码. 使用 `convertRawToJpeg(...)` 以转换它们。 仅在iOS上可用 :

```typescript
import { FilePicker } from '@capawesome/capacitor-file-picker';

const convertRawToJpeg = async () => {
  const { path } = await FilePicker.convertRawToJpeg({
    path: 'path/to/image.dng',
  });
};
```

### 检查和请求权限

取取文件不需要任何权限,因为操作系统呈现取取取器. 不过,如果你需要的话 `ACCESS_MEDIA_LOCATION` 或者说 `READ_EXTERNAL_STORAGE` android上的权限(参见 [安装](https://npmcn.com/package/%40capawesome/capacitor-file-picker/#readme-installation)),你可以检查和要求它们:

```typescript
import { FilePicker } from '@capawesome/capacitor-file-picker';

const checkPermissions = async () => {
  const result = await FilePicker.checkPermissions();
};

const requestPermissions = async () => {
  const result = await FilePicker.requestPermissions();
};
```

### 听好,被开除的选手

在iOS上,当用户关闭拾取器而不选择任何内容时,可以通知您:

```typescript
import { FilePicker } from '@capawesome/capacitor-file-picker';

const addPickerDismissedListener = async () => {
  await FilePicker.addListener('pickerDismissed', () => {
    console.log('Picker was dismissed');
  });
};
```

### 复制文件

将选中的文件复制到新位置, 例如, 复制到您的应用程序的数据目录 :

```typescript
import { FilePicker } from '@capawesome/capacitor-file-picker';

const copyFile = async () => {
  await FilePicker.copyFile({
    from: 'path/to/file',
    to: 'path/to/destination',
  });
};
```

## API 密码

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

### 检查( )

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

检查访问文件的权限 .

只能从Android上找到.

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

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

* * *

### 转换HeicToJpeg(...)

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

将 HEIC 图像转换为 JPEG .

仅在iOS上可用.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[ConvertHeicToJpegOptions](https://npmcn.com/package/%40capawesome/capacitor-file-picker/#readme-convertheictojpegoptions)` |

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

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

* * *

### 转换RawToJpeg(...)

```typescript
convertRawToJpeg(options: ConvertRawToJpegOptions) => Promise<ConvertRawToJpegResult>
```

将 RAW 图像转换为 JPEG .

仅在iOS上可用.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[ConvertRawToJpegOptions](https://npmcn.com/package/%40capawesome/capacitor-file-picker/#readme-convertrawtojpegoptions)` |

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

**自:** 8.1.0 联合国

* * *

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

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

复制文件到新位置 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[CopyFileOptions](https://npmcn.com/package/%40capawesome/capacitor-file-picker/#readme-copyfileoptions)` |

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

* * *

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

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

打开文件拾取器,允许用户选择一个或多个文件.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[PickFilesOptions](https://npmcn.com/package/%40capawesome/capacitor-file-picker/#readme-pickfilesoptions)` |

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

* * *

### 选择目录( )

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

打开一个可让用户选择目录的拾取器对话框 .

仅在Android和iOS上提供.

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

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

* * *

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

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

从画廊取出一个或多个图像.

在iOS 13 和 更年长时,它只允许选择一个图像.

仅在Android和iOS上提供.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[PickMediaOptions](https://npmcn.com/package/%40capawesome/capacitor-file-picker/#readme-pickmediaoptions)` |

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

**自:** 0.5.3 (韩语)

* * *

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

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

从画廊中取出一个或多个图像或视频.

在iOS 13及更年长时,它只能选择一个图像或视频.

仅在Android和iOS上提供.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[PickMediaOptions](https://npmcn.com/package/%40capawesome/capacitor-file-picker/#readme-pickmediaoptions)` |

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

**自:** 0.5.3 (韩语)

* * *

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

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

从画廊取出一或多段视频.

在iOS 13 岁及更年长时,只能选择一个视频.

仅在Android和iOS上提供.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[PickMediaOptions](https://npmcn.com/package/%40capawesome/capacitor-file-picker/#readme-pickmediaoptions)` |

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

**自:** 0.5.3 (韩语)

* * *

### 请求(...)

```typescript
requestPermissions(options?: RequestPermissionsOptions | undefined) => Promise<PermissionStatus>
```

请求访问文件的权限 .

只能从Android上找到.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[RequestPermissionsOptions](https://npmcn.com/package/%40capawesome/capacitor-file-picker/#readme-requestpermissionsoptions)` |

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

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

* * *

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

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

取取文件者被开除时打电话.

仅在iOS上可用.

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'pickerDismissed'` |
| **`listenerFunc`** | `() => void` |

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

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

* * *

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

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

删除此插件的所有听众 .

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

* * *

### 接口

#### 权限状态

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`accessMediaLocation`** | `[PermissionState](https://npmcn.com/package/%40capawesome/capacitor-file-picker/#readme-permissionstate)` | 访问媒体位置的权限状态 。 在Android上,这个请求/检查 `ACCESS_MEDIA_LOCATION` 允许. | 6.1.0 (中文(简体) ) |
| **`readExternalStorage`** | `[PermissionState](https://npmcn.com/package/%40capawesome/capacitor-file-picker/#readme-permissionstate)` | 读取外部存储的权限状态 。 在Android上,这个请求/检查 `READ_EXTERNAL_STORAGE` 允许. | 6.1.0 (中文(简体) ) |

#### 转换HeicToJpeg结果

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`path`** | `string` | 转换后 JPEG 图像的路径 . | 0.6.0 (中文(简体) ) |

#### 转换HeicToJpeg 选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`path`** | `string` | HEIC图像的路径. | 0.6.0 (中文(简体) ) |

#### 转换RawToJpeg结果

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`path`** | `string` | 转换后 JPEG 图像的路径 . | 8.1.0 联合国 |

#### 转换 RawToJpeg 选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`path`** | `string` | RAW图像的路径. | 8.1.0 联合国 |

#### 复制文件选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`from`** | `string` | 要复制的文件路径 . |  | 7.1.0 (中文(简体) ) |
| **`overwrite`** | `boolean` | 是否覆盖目标文件已存在 . | `true` | 7.2.0 联合国 |
| **`to`** | `string` | 复制文件的路径 . |  | 7.1.0 (中文(简体) ) |

#### 拾荒档案

| Prop | 类型 |
| --- | --- |
| **`files`** | `PickedFile[]` |

#### 选中文件

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`blob`** | `Blob` | 文件的 Blob 实例 。 仅在Web上提供. |  |
| **`data`** | `string` | Base64 字符串表示文件中的数据. 只有在 `readData` 设置为 `true`。 。 。 . |  |
| **`duration`** | `number` | 视频持续时间以秒计. 仅在Android和iOS上提供. | 0.5.3 (韩语) |
| **`height`** | `number` | 图像或视频以像素表示的高度. 仅在Android和iOS上提供. | 0.5.3 (韩语) |
| **`mimeType`** | `string` | 文件的MIME类型. |  |
| **`modifiedAt`** | `number` | 文件以毫秒计的最后修改时间戳 . | 0.5.9 (中文(简体) ) |
| **`name`** | `string` | 文件名称. |  |
| **`path`** | `string` | 文件路径. 仅在Android和iOS上提供. |  |
| **`size`** | `number` | 以字节表示的文件大小 . |  |
| **`webPath`** | `string` | 可用于在网页视图中加载的文件的路径, 例如 `src` 一、导 言 `&lt;img&gt;` 键。 在网络上,这是一个对象URL. 打电话 `URL.revokeObjectURL(...)` 当它不再需要的时候. | 8.1.0 联合国 |
| **`width`** | `number` | 图像或视频以像素表示的宽度. 仅在Android和iOS上提供. | 0.5.3 (韩语) |

#### PickFiles 选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`types`** | `string[]` | 已接受文件类型列表 。 看着 [IANA 媒体类型](https://www.iana.org/assignments/media-types/media-types.xhtml) 为标准媒体类型的完整列表。 通关卡,例如 `image/*` 被支持。 在Android上,系统文件取取器只能提供设备出自文件扩展名的媒体类型文件. 在Android 9 岁及以上, `.json` 文件没有映射到 `application/json` 报告为: `application/octet-stream`第三方文件提供者在任何版本上的行为都可能相同。 添加 `application/octet-stream` 改为 `types` 如果这些文件必须是可选择的. |  |  |
| **`limit`** | `number` | 用户可以选择的最大文件数量 。 设为 `0` 将选择限制设定为无限。 目前,仅 `0` 财务报告和审定财务报表 `1` 被支持. | `0` | 6.0.0 (单位:千美元) |
| **`readData`** | `boolean` | 是否读取文件数据 . **请注意**:读取大文件会导致应用程序崩溃. 因此不建议使用这个选项. 相反,使用 [获取 API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) 将文件装入为 blob, 查看 [此示例](https://capawesome.io/blog/capacitor-file-handling-guide/#read-a-file)。 。 。 . | `false` |  |

#### 选取剪贴板

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`bookmark`** | `string` | 选定目录的基础64-编码安全范围书签. 它可用于在整个应用程序发布过程中保留对目录的访问. 仅在iOS上可用. | 8.1.0 联合国 |
| **`path`** | `string` | 选定目录的路径 . | 6.2.0 (单位:千美元) |

#### 选择媒体选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`readData`** | `boolean` | 是否读取文件数据 . | `false` |  |
| **`skipTranscoding`** | `boolean` | 是否避免转码, 如果可能的话 。 例如,在iOS上,HEIC图像被自动转码为JPEG. 仅在iOS上可用. | `true` |  |
| **`limit`** | `number` | 用户可以选择的最大文件数量 。 设为 `0` 将选择限制设定为无限。 仅在Android和Web上 `0` 财务报告和审定财务报表 `1` 被支持. | `0` | 5.2.0 (中文(简体) ) |
| **`ordered`** | `boolean` | 选择徽章中是否显示命令编号而不是检查标记 。 仅在iOS(15+)上提供. | `false` | 5.3.0 (中文(简体) ) |

#### 请求允许选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`permissions`** | `PermissionType[]` | 请求权限 . | `["accessMediaLocation", "readExternalStorage"]` | 6.1.0 (中文(简体) ) |

#### 插件听筒

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

### 类型异名

#### 权限状态

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

#### 选项

`[PickMediaOptions](https://npmcn.com/package/%40capawesome/capacitor-file-picker/#readme-pickmediaoptions)`

#### 选择图像

`[PickMediaResult](https://npmcn.com/package/%40capawesome/capacitor-file-picker/#readme-pickmediaresult)`

#### 选择媒体

`[PickFilesResult](https://npmcn.com/package/%40capawesome/capacitor-file-picker/#readme-pickfilesresult)`

#### 选择视频选项

`[PickMediaOptions](https://npmcn.com/package/%40capawesome/capacitor-file-picker/#readme-pickmediaoptions)`

#### 选择视频结果

`[PickMediaResult](https://npmcn.com/package/%40capawesome/capacitor-file-picker/#readme-pickmediaresult)`

#### 权限类型

`'accessMediaLocation' | 'readExternalStorage'`

## 财务问题

### 我怎么把选中的文件上传到服务器?

在网络上,所选文件已经包含 `Blob` 实例 `FormData` 对象。 在Android和iOS上,将文件作为blob上载,使用获取API和文件路径,再以同样方式上载. 见 [使用示例](https://npmcn.com/package/%40capawesome/capacitor-file-picker/#readme-upload-a-picked-file-to-a-server) 上文及 [处理器文件处理指南](https://capawesome.io/blog/capacitor-file-handling-guide/) 完全通过.

### 为什么我的应用程序在选取大文件时会崩溃?

这通常发生在 `readData` 选项已启用。 它将整个文件读入内存为Base64字符串,可以超过大文件可用的内存. 保留 `readData` 禁用(默认),并用取取 API 作为 blob 装入文件, 如 [使用示例](https://npmcn.com/package/%40capawesome/capacitor-file-picker/#readme-upload-a-picked-file-to-a-server) 见上文.

### 两者有什么区别 `pickFiles`, (中文(简体) ), `pickImages`, (中文(简体) ), `pickMedia` 财务报告和审定财务报表 `pickVideos`? 吗?

这个 `pickFiles(...)` 方法打开系统文件拾取器,并支持Android,iOS和Web上的任何文件类型. 这个 `pickImages(...)`, (中文(简体) ), `pickVideos(...)` 财务报告和审定财务报表 `pickMedia(...)` 取而代之的是打开相册,它为选择相片和视频提供了更熟悉的经验,并且只在Android和iOS上提供.

### 我需要任何运行时间权限来选择文件吗?

不, 选择文件本身不需要任何运行时间权限, 因为操作系统代表您的应用程序呈现选择器 。 安卓号上 `ACCESS_MEDIA_LOCATION` 只需从照片中获取未编辑的 EXIF 元数据即可,并且 `READ_EXTERNAL_STORAGE` 只用于从外部存储读取文件。 在iOS上,不需要隐私描述.

### 此插件与相机相机和文件系统插件有何不同?

Capacitor相机插件会与相机相接相机相接相机或从相廊取出相机相机相机相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相接相机相接相接相机相机相接相接相接相机相接相机相接相机相接相机相机相接相相机相机相接相相相机相接相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相 Capacitor 文件系统插件在已知路径读取并写入文件,但它没有为选择它们提供任何用户界面. File Picker 插件填补了这个空白:它让用户选择任何文件,目录,图像,或视频,并返回其路径和元数据,然后用其他插件处理.

### 我能用这个插件吗? 有Ionic、React、Vue或Angular?

是的,插件是框架不可知的。 它在任意网络框架的Capacitor app中工作,包括有Angular,React,或Vue的Ionic,以及平版JavaScript等项目.

## 相关插件

-   [文件压缩器](https://capawesome.io/docs/sdks/capacitor/file-compressor/):在上传图像之前压缩图像.
-   [文件打开器](https://capawesome.io/docs/sdks/capacitor/file-opener/): 打开带有默认应用程序的所选文件.
-   [共享目标](https://capawesome.io/docs/sdks/capacitor/share-target/):接收其他应用程序共享的文件.
-   [齐普](https://capawesome.io/docs/sdks/capacitor/zip/): Zip和unzip文件和目录.

## 通讯

随时更新有关卡帕韦索姆、Capacitor和Ionic生态系统的最新消息和最新消息,因为我们 [《卡帕索克通讯》](https://cloud.capawesome.io/newsletter/)。 。 。 .

## 更改日志

见 [变动情况](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/file-picker/CHANGELOG.md)。 。 。 .

## 许可证

见 [自由主义](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/file-picker/LICENSE)。 。 。 .

## 贷项

此插件基于 [电容文件拾取器](https://github.com/capawesome-team/capacitor-file-picker) 插件 . 感谢所有为这个项目捐款的人!

## 常见问题

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

控制器插件,允许用户在Android,iOS,和Web上选择一个文件,目录,图像,或视频\.

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

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

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

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

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

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

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

@capawesome/capacitor-file-picker 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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