# @capgo/capacitor-file 中文文档

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

版本：8\.0\.24
npm 元数据更新时间：2026-10-15T05:59:29.227Z
中文译文更新时间：2026-11-09T03:55:18.794Z
软件包许可：MPL-2\.0

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

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

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

- 包体积（解压后）：469 kB，24 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2025-11-28T20:38:16.374Z
- 最新版本发布：2026-10-15T05:59:28.855Z
- 近 30 天下载量：41697（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 26 个）

## 中文简介

文件系统操作的电容插件, 兼容 Cordova 文件插件 API

## 安装

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

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

## README

# @ capgo/ 电容文件

使用兼容 API 的 Capacitor app 设备文件系统工作 `cordova-plugin-file`。在iOS、Android和网络上读取、撰写、复制并移动文件和文件夹.

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

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

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

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

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

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

## 主要特点

-   **读写**数字 : `readFile()`, (中文(简体) ), `readAsDataURL()`, (中文(简体) ), `writeFile()`, (中文(简体) ), `appendFile()` 财务报告和审定财务报表 `truncate()`。 。 。 .
-   **文件与文件夹**数字 : `mkdir()`, (中文(简体) ), `rmdir()`, (中文(简体) ), `readdir()`, (中文(简体) ), `copy()`, (中文(简体) ), `move()`, (中文(简体) ), `rename()` 财务报告和审定财务报表 `deleteFile()`。 。 。 .
-   **元数据**数字 : `stat()`, (中文(简体) ), `exists()`, (中文(简体) ), `getUri()` 财务报告和审定财务报表 `getFreeDiskSpace()`。 。 。 .
-   **Cordova 兼容**数字 : `requestFileSystem()`, (中文(简体) ), `resolveLocalFileSystemURL()`, (中文(简体) ), `getFile()` 财务报告和审定财务报表 `getDirectory()` 方便从 `cordova-plugin-file`。 。 。 .
-   **权限**数字 : `checkPermissions()` 财务报告和审定财务报表 `requestPermissions()` 用于存储访问.
-   **平台**: iOS,Android和Web. 互联网档案馆的存檔,存档日期2013-12-02. Web将核心文件操作保存在浏览器存储中.

## 为什么是控制器文件?

一个可靠的 **本地文件系统** 为 Capacitor 应用程序所建的插件, 具有官方文件系统插件中没有的高级特性 :

-   **部分文件读取** - 读取文件的具体部分 `offset` 财务报告和审定财务报表 `length` 参数( 大文件大)
-   **随机访问写入** - 在具体字节位置写作 `position` 参数
-   **Cordova 兼容的 API** - 熟悉的方法,比如: `requestFileSystem()`, (中文(简体) ), `resolveLocalFileSystemURL()`, (中文(简体) ), `getFile()`,以及 `getDirectory()`
-   **所有平台目录** - 查阅文件、图书馆、缓存、外部存储等
-   **进展活动** - 通过实时更新进度,监测阅读/写入操作
-   **自由和开放源代码** - 不需要有偿服务

适合需要与大文件合作,从Cordova迁移,或需要随机访问文件操作的应用程序.

## 文档

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

## 兼容性

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

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

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

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

在Android 13+上,此插件可以请求广泛的媒体权限,例如 `READ_MEDIA_IMAGES` 财务报告和审定财务报表 `READ_MEDIA_VIDEO` 当你打电话 `requestPermissions()` 在您的应用程序的私人目录之外访问 .

Google Play只允许这些相片和视频权限,当访问与你的app的核心目的直接相关,需要持续或频繁访问共享存储中的照片或视频. 如果您的应用只需要一次性或不频繁的媒体访问,例如导入一个配置图片,选择附件,或者选择一个文件上传,Google期望您使用一个系统拾取器代替.

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

-   确保照片或视频库的访问是您的应用程序核心功能的一部分.
-   准备好为Play Console审查中的许可使用说明理由.
-   如果应用程序只能与用户选择的文件合作,则删除宽媒体权限 .

如果 Google Play 审查以类似消息拒绝应用程序 `Photo and Video Permissions policy: Permission use is not directly related to your app's core purpose`,使用时 [@ capgo/ 电容器- 文件拾取器](https://github.com/Cap-go/capacitor-file-picker/) 或另一个系统采取器流,而不是请求宽相/视频权限.

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

## API 密码

-   [`requestFileSystem(...)`](https://npmcn.com/package/%40capgo/capacitor-file/#readme-requestfilesystem)
-   [`resolveLocalFileSystemURL(...)`](https://npmcn.com/package/%40capgo/capacitor-file/#readme-resolvelocalfilesystemurl)
-   [`getFile(...)`](https://npmcn.com/package/%40capgo/capacitor-file/#readme-getfile)
-   [`getDirectory(...)`](https://npmcn.com/package/%40capgo/capacitor-file/#readme-getdirectory)
-   [`readFile(...)`](https://npmcn.com/package/%40capgo/capacitor-file/#readme-readfile)
-   [`readAsDataURL(...)`](https://npmcn.com/package/%40capgo/capacitor-file/#readme-readasdataurl)
-   [`writeFile(...)`](https://npmcn.com/package/%40capgo/capacitor-file/#readme-writefile)
-   [`appendFile(...)`](https://npmcn.com/package/%40capgo/capacitor-file/#readme-appendfile)
-   [`deleteFile(...)`](https://npmcn.com/package/%40capgo/capacitor-file/#readme-deletefile)
-   [`mkdir(...)`](https://npmcn.com/package/%40capgo/capacitor-file/#readme-mkdir)
-   [`rmdir(...)`](https://npmcn.com/package/%40capgo/capacitor-file/#readme-rmdir)
-   [`readdir(...)`](https://npmcn.com/package/%40capgo/capacitor-file/#readme-readdir)
-   [`stat(...)`](https://npmcn.com/package/%40capgo/capacitor-file/#readme-stat)
-   [`getMetadata(...)`](https://npmcn.com/package/%40capgo/capacitor-file/#readme-getmetadata)
-   [`rename(...)`](https://npmcn.com/package/%40capgo/capacitor-file/#readme-rename)
-   [`move(...)`](https://npmcn.com/package/%40capgo/capacitor-file/#readme-move)
-   [`copy(...)`](https://npmcn.com/package/%40capgo/capacitor-file/#readme-copy)
-   [`exists(...)`](https://npmcn.com/package/%40capgo/capacitor-file/#readme-exists)
-   [`getUri(...)`](https://npmcn.com/package/%40capgo/capacitor-file/#readme-geturi)
-   [`truncate(...)`](https://npmcn.com/package/%40capgo/capacitor-file/#readme-truncate)
-   [`getDirectories()`](https://npmcn.com/package/%40capgo/capacitor-file/#readme-getdirectories)
-   [`getFreeDiskSpace()`](https://npmcn.com/package/%40capgo/capacitor-file/#readme-getfreediskspace)
-   [`addListener('readProgress', ...)`](https://npmcn.com/package/%40capgo/capacitor-file/#readme-addlistenerreadprogress-)
-   [`addListener('writeProgress', ...)`](https://npmcn.com/package/%40capgo/capacitor-file/#readme-addlistenerwriteprogress-)
-   [`removeAllListeners()`](https://npmcn.com/package/%40capgo/capacitor-file/#readme-removealllisteners)
-   [`getPluginVersion()`](https://npmcn.com/package/%40capgo/capacitor-file/#readme-getpluginversion)
-   [`checkPermissions()`](https://npmcn.com/package/%40capgo/capacitor-file/#readme-checkpermissions)
-   [`requestPermissions(...)`](https://npmcn.com/package/%40capgo/capacitor-file/#readme-requestpermissions)
-   [接口](https://npmcn.com/package/%40capgo/capacitor-file/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capgo/capacitor-file/#readme-type-aliases)
-   [数字](https://npmcn.com/package/%40capgo/capacitor-file/#readme-enums)

电容文件插件 执行类似 Cordova 文件插件的文件系统操作

### 请求FileSystem (...)

```typescript
requestFileSystem(options: RequestFileSystemOptions) => Promise<FileSystem>
```

请求文件系统 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[RequestFileSystemOptions](https://npmcn.com/package/%40capgo/capacitor-file/#readme-requestfilesystemoptions)` | \- 文件系统请求选项 |

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

* * *

### 解析本地文件SystemURL(...)

```typescript
resolveLocalFileSystemURL(options: ResolveURLOptions) => Promise<Entry>
```

将文件 URL 解析为条目 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[ResolveURLOptions](https://npmcn.com/package/%40capgo/capacitor-file/#readme-resolveurloptions)` | \- 要解决的 URL |

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

* * *

### 获取文件(...)

```typescript
getFile(options: GetFileOptions) => Promise<FileEntry>
```

获取文件条目 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[GetFileOptions](https://npmcn.com/package/%40capgo/capacitor-file/#readme-getfileoptions)` | \- 文件路径和选项 |

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

* * *

### 获取 Directy (...)

```typescript
getDirectory(options: GetDirectoryOptions) => Promise<DirectoryEntry>
```

获取目录条目 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[GetDirectoryOptions](https://npmcn.com/package/%40capgo/capacitor-file/#readme-getdirectoryoptions)` | \- 说吧 [目录](https://npmcn.com/package/%40capgo/capacitor-file/#readme-directory) 路径和选项 |

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

* * *

### 读取文件(...)

```typescript
readFile(options: ReadFileOptions) => Promise<ReadFileResult>
```

读取文件为文本或碱基64.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[ReadFileOptions](https://npmcn.com/package/%40capgo/capacitor-file/#readme-readfileoptions)` | \- 读取选项 |

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

* * *

### 读取 AsDataURL(...)

```typescript
readAsDataURL(options: ReadFileOptions) => Promise<{ data: string; }>
```

将一个文件读取为数据 URL(base64 有 MIME 类型前缀).

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[ReadFileOptions](https://npmcn.com/package/%40capgo/capacitor-file/#readme-readfileoptions)` | \- 读取选项 |

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

* * *

### 写入文件(...)

```typescript
writeFile(options: WriteFileOptions) => Promise<WriteFileResult>
```

将数据写入文件 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[WriteFileOptions](https://npmcn.com/package/%40capgo/capacitor-file/#readme-writefileoptions)` | \- 写选项 |

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

* * *

### 附加文件(...)

```typescript
appendFile(options: WriteFileOptions) => Promise<WriteFileResult>
```

将数据添加到文件中 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[WriteFileOptions](https://npmcn.com/package/%40capgo/capacitor-file/#readme-writefileoptions)` | \- 写选项( 附录被迫为真) |

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

* * *

### 删除文件(...)

```typescript
deleteFile(options: DeleteFileOptions) => Promise<void>
```

删除文件 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[DeleteFileOptions](https://npmcn.com/package/%40capgo/capacitor-file/#readme-deletefileoptions)` | \- 删除选项 |

* * *

### mkdir (...) (中文(简体) )

```typescript
mkdir(options: MkdirOptions) => Promise<void>
```

创建目录 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[MkdirOptions](https://npmcn.com/package/%40capgo/capacitor-file/#readme-mkdiroptions)` | \- 说吧 [目录](https://npmcn.com/package/%40capgo/capacitor-file/#readme-directory) 创建选项 |

* * *

### rmdir (...) (中文(简体) )

```typescript
rmdir(options: DeleteDirectoryOptions) => Promise<void>
```

删除目录 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[DeleteDirectoryOptions](https://npmcn.com/package/%40capgo/capacitor-file/#readme-deletedirectoryoptions)` | \- 删除选项 |

* * *

### 已读 dir (...)

```typescript
readdir(options: ReaddirOptions) => Promise<ReaddirResult>
```

读取目录内容 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[ReaddirOptions](https://npmcn.com/package/%40capgo/capacitor-file/#readme-readdiroptions)` | \- 读取选项 |

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

* * *

### 数据(...)

```typescript
stat(options: StatOptions) => Promise<StatResult>
```

获取文件或目录的元数据 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[StatOptions](https://npmcn.com/package/%40capgo/capacitor-file/#readme-statoptions)` | \- Stat 选项 |

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

* * *

### 获取气象数据(...)

```typescript
getMetadata(options: StatOptions) => Promise<Metadata>
```

获取文件或目录的元数据 . 别名为 stat ().

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[StatOptions](https://npmcn.com/package/%40capgo/capacitor-file/#readme-statoptions)` | \- Stat 选项 |

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

* * *

### 重命名(...)

```typescript
rename(options: RenameOptions) => Promise<void>
```

重命名或移动文件或目录.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[RenameOptions](https://npmcn.com/package/%40capgo/capacitor-file/#readme-renameoptions)` | \- 重命名选项 |

* * *

### 移动(...)

```typescript
move(options: RenameOptions) => Promise<void>
```

移动文件或目录 . 重命名的别名 ().

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[RenameOptions](https://npmcn.com/package/%40capgo/capacitor-file/#readme-renameoptions)` | \- 移动选项 |

* * *

### 复制(...)

```typescript
copy(options: CopyOptions) => Promise<CopyResult>
```

复制文件或目录 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[CopyOptions](https://npmcn.com/package/%40capgo/capacitor-file/#readme-copyoptions)` | \- 复制选项 |

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

* * *

### 已存在(...)

```typescript
exists(options: ExistsOptions) => Promise<ExistsResult>
```

检查文件或目录是否存在 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[ExistsOptions](https://npmcn.com/package/%40capgo/capacitor-file/#readme-existsoptions)` | \- 检查选项 |

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

* * *

### 获取Uri(...)

```typescript
getUri(options: GetUriOptions) => Promise<GetUriResult>
```

获取URI文件 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[GetUriOptions](https://npmcn.com/package/%40capgo/capacitor-file/#readme-geturioptions)` | \- URI选项 |

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

* * *

### 切变(...)

```typescript
truncate(options: TruncateOptions) => Promise<void>
```

将文件截断到指定大小.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[TruncateOptions](https://npmcn.com/package/%40capgo/capacitor-file/#readme-truncateoptions)` | \- 截断选项 |

* * *

### 获取董事( )

```typescript
getDirectories() => Promise<FileDirectories>
```

获取所有已知的文件系统目录 .

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

* * *

### 获取 FreeDisk Space ()

```typescript
getFreeDiskSpace() => Promise<{ free: number; }>
```

在字节中获取自由磁盘空间 .

**回返情况:** `Promise<{ free: number; }>`

* * *

### 添加倾听器( 读取进度 )..

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

听读进度事件.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`eventName`** | `'readProgress'` | \- 一定是"读取进步" |
| **`listenerFunc`** | `(progress: [ProgressEvent](https://npmcn.com/package/%40capgo/capacitor-file/#readme-progressevent)) => void` | \- 召回接收进度更新 |

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

* * *

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

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

听写进度事件.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`eventName`** | `'writeProgress'` | \- 一定是"写进步" |
| **`listenerFunc`** | `(progress: [ProgressEvent](https://npmcn.com/package/%40capgo/capacitor-file/#readme-progressevent)) => void` | \- 召回接收进度更新 |

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

* * *

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

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

删除全部事件听众 .

* * *

### 获取 PluginVersion ()

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

获取插件版本 .

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

* * *

### 检查( )

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

请检查当前文件操作的权限状态 . 在Android上,此检查外部存储权限. 在iOS和网络上,这总是返回"被授予",因为不需要特殊权限.

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

* * *

### 请求(...)

```typescript
requestPermissions(options?: PermissionRequestOptions | undefined) => Promise<FilePermissionStatus>
```

请求文件操作权限 . 在Android上,此请求需要外部存储权限 访问应用程序的私人目录以外的文件 . 在iOS和网络上,这总是返回"被授予",因为不需要特殊权限.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[PermissionRequestOptions](https://npmcn.com/package/%40capgo/capacitor-file/#readme-permissionrequestoptions)` | \- 许可请求的可选配置 |

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

* * *

### 接口

#### 文件系统

代表一个文件系统

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`name`** | `string` | 文件系统的名称 |
| **`root`** | `[DirectoryEntry](https://npmcn.com/package/%40capgo/capacitor-file/#readme-directoryentry)` | 文件系统的根目录 |

#### 目录条目

代表目录条目

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`isFile`** | `false` | 如果这是文件, 则为真 |
| **`isDirectory`** | `true` | 如果此目录为真 |

#### 请求文件系统选项

请求文件系统的选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`type`** | `[FileSystemType](https://npmcn.com/package/%40capgo/capacitor-file/#readme-filesystemtype)` | 要请求的文件系统类型 |
| **`size`** | `number` | 请求的字节大小( 可能不会在所有平台上执行) |

#### 条目

代表一个文件或目录条目

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`isFile`** | `boolean` | 如果这是文件, 则为真 |
| **`isDirectory`** | `boolean` | 如果此目录为真 |
| **`name`** | `string` | 文件或目录的名称 |
| **`fullPath`** | `string` | 相对于文件系统根的完整路径 |
| **`nativeURL`** | `string` | 原生档案 : URI 资源 |

#### 选项

解决 URL 到条目的选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`url`** | `string` | 要解决的 URL (file:// 或 cdvfile://) |

#### 文件条目

代表文件条目

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`isFile`** | `true` | 如果这是文件, 则为真 |
| **`isDirectory`** | `false` | 如果此目录为真 |

#### 获取文件选项

获取文件的选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`path`** | `string` | 文件的路径 |
| **`directory`** | `[Directory](https://npmcn.com/package/%40capgo/capacitor-file/#readme-directory)` | 基准目录 |
| **`options`** | `[GetOptions](https://npmcn.com/package/%40capgo/capacitor-file/#readme-getoptions)` | 创建文件的选项 |

#### 获取选项

创建或获取文件/目录的选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`create`** | `boolean` | 如果不存在, 则创建文件/ 目录 |
| **`exclusive`** | `boolean` | 如果真实和创建是真实的, 如果文件/ 目录已经存在, 丢出错误 |

#### 获取切换选项

获取目录的选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`path`** | `string` | 目录的路径 |
| **`directory`** | `[Directory](https://npmcn.com/package/%40capgo/capacitor-file/#readme-directory)` | 基准目录 |
| **`options`** | `[GetOptions](https://npmcn.com/package/%40capgo/capacitor-file/#readme-getoptions)` | 创建目录的选项 |

#### 读取结果

读取文件的结果

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`data`** | `string` | 文件内容为字符串(文本)或基数64(二进制) |

#### 读取文件选项

读取文件的选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`path`** | `string` | 文件的路径 |
| **`directory`** | `[Directory](https://npmcn.com/package/%40capgo/capacitor-file/#readme-directory)` | 基准目录 |
| **`encoding`** | `[Encoding](https://npmcn.com/package/%40capgo/capacitor-file/#readme-encoding)` | [编码](https://npmcn.com/package/%40capgo/capacitor-file/#readme-encoding) 文本文件(二进制/基准64的缩写) |
| **`offset`** | `number` | 开始读取的字节偏移( 默认 : 0) |
| **`length`** | `number` | 要读取的字节数( 默认: 已读到文件结尾) |

#### 写入文件

编写文件的结果

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`uri`** | `string` | 写入文件的 URI |

#### 写入文件选项

写入文件的选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`path`** | `string` | 文件的路径 |
| **`directory`** | `[Directory](https://npmcn.com/package/%40capgo/capacitor-file/#readme-directory)` | 基准目录 |
| **`data`** | `string` | 要写入的数据( 字符串用于文本, 基数64用于二进制) |
| **`encoding`** | `[Encoding](https://npmcn.com/package/%40capgo/capacitor-file/#readme-encoding)` | [编码](https://npmcn.com/package/%40capgo/capacitor-file/#readme-encoding) 用于文本文件 |
| **`append`** | `boolean` | 如果为真, 请将附件附加到已有文件, 而不是覆盖 |
| **`recursive`** | `boolean` | 如果中间目录不存在, 则创建此目录 |
| **`position`** | `number` | 开始写入的字节位置( 对于随机访问写入) 。 如果未指定, 则在“ 附录” 旗下从首字母写入或附加 |

#### 删除文件选项

删除文件或目录的选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`path`** | `string` | 文件或目录的路径 |
| **`directory`** | `[Directory](https://npmcn.com/package/%40capgo/capacitor-file/#readme-directory)` | 基准目录 |

#### Mkdir 选项

创建目录的选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`path`** | `string` | 目录的路径 |
| **`directory`** | `[Directory](https://npmcn.com/package/%40capgo/capacitor-file/#readme-directory)` | 基准目录 |
| **`recursive`** | `boolean` | 如果中间目录不存在, 则创建此目录 |

#### 删除标题选项

递归删除目录的选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`path`** | `string` | 目录的路径 |
| **`directory`** | `[Directory](https://npmcn.com/package/%40capgo/capacitor-file/#readme-directory)` | 基准目录 |
| **`recursive`** | `boolean` | 如果为真, 则连续删除内容 |

#### 读取结果

读取目录的结果

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`entries`** | `Entry[]` | 目录中的条目列表 |

#### 读取目录选项

读取目录的选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`path`** | `string` | 目录的路径 |
| **`directory`** | `[Directory](https://npmcn.com/package/%40capgo/capacitor-file/#readme-directory)` | 基准目录 |

#### 静态

获得文件/目录信息的结果

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`type`** | `'file' | 'directory'` | 类型 : “ 文件” 或“ 目录 ” |
| **`size`** | `number` | 以字节表示的大小 |
| **`ctime`** | `number` | 创作时间(如果有的话) |
| **`mtime`** | `number` | 上次修改时间 |
| **`uri`** | `string` | 乌干达共和国 |

#### 状态选项

获取文件信息的选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`path`** | `string` | 文件或目录的路径 |
| **`directory`** | `[Directory](https://npmcn.com/package/%40capgo/capacitor-file/#readme-directory)` | 基准目录 |

#### 元数据

代表文件或目录的元数据

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`modificationTime`** | `number` | 上次修改日期 |
| **`size`** | `number` | 以字节表示的大小(目录为0) |

#### 重命名选项

重命名/移动文件或目录的选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`from`** | `string` | 当前路径 |
| **`to`** | `string` | 新路径 |
| **`directory`** | `[Directory](https://npmcn.com/package/%40capgo/capacitor-file/#readme-directory)` | “ 从” 路径的基准目录 |
| **`toDirectory`** | `[Directory](https://npmcn.com/package/%40capgo/capacitor-file/#readme-directory)` | “ to” 路径的基础目录 |

#### 复制结果

复制操作结果

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`uri`** | `string` | 复制文件的 URI |

#### 复制选项

复制文件或目录的选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`from`** | `string` | 源路径 |
| **`to`** | `string` | 目标路径 |
| **`directory`** | `[Directory](https://npmcn.com/package/%40capgo/capacitor-file/#readme-directory)` | 源代码基础目录 |
| **`toDirectory`** | `[Directory](https://npmcn.com/package/%40capgo/capacitor-file/#readme-directory)` | 目的地基准目录 |

#### 现成

存在结果检查

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`exists`** | `boolean` | 如果文件或目录存在, 则为真 |
| **`type`** | `'file' | 'directory'` | 类型( 如果存在): “ 文件” 或“ 目录 ” |

#### 已存在选项

检查文件或目录是否存在的选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`path`** | `string` | 检查路径 |
| **`directory`** | `[Directory](https://npmcn.com/package/%40capgo/capacitor-file/#readme-directory)` | 基准目录 |

#### GetUriResult (英语)

获得URI的结果

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`uri`** | `string` | 本地的URI公司 |

#### 获取选项

获取文件 URI 选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`path`** | `string` | 文件的路径 |
| **`directory`** | `[Directory](https://npmcn.com/package/%40capgo/capacitor-file/#readme-directory)` | 基准目录 |

#### 截断选项

文件切换选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`path`** | `string` | 文件的路径 |
| **`directory`** | `[Directory](https://npmcn.com/package/%40capgo/capacitor-file/#readme-directory)` | 基准目录 |
| **`size`** | `number` | 缩写为( 默认为 0) |

#### 文件目录

插件曝光的已知文件系统目录

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`applicationDirectory`** | `string` | 应用程序安装目录( 只读) |
| **`applicationStorageDirectory`** | `string` | 应用程序存储目录根 |
| **`dataDirectory`** | `string` | 持续私有数据目录 |
| **`cacheDirectory`** | `string` | 缓存目录 |
| **`externalRootDirectory`** | `string` | 外部根目录 (Android) |
| **`externalApplicationStorageDirectory`** | `string` | 外部应用程序存储目录 (Android) |
| **`externalDataDirectory`** | `string` | 外部数据目录 (Android) |
| **`externalCacheDirectory`** | `string` | 外部缓存目录 (Android) |
| **`documentsDirectory`** | `string` | 文件目录( iOS) |
| **`syncedDataDirectory`** | `string` | 同步数据目录( iOS iCloud) |
| **`libraryDirectory`** | `string` | 图书馆目录(iOS) |
| **`tempDirectory`** | `string` | 临时目录 |

#### 插件听筒

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

#### 进展活动

文件操作进度事件

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`loaded`** | `number` | 迄今已装入的字节 |
| **`total`** | `number` | 总字节( 如果已知) |
| **`lengthComputable`** | `boolean` | 总数是否可计算 |

#### 文件发送状态

文件操作的权限状态

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`publicStorage`** | `[PermissionState](https://npmcn.com/package/%40capgo/capacitor-file/#readme-permissionstate)` | 读取公共/ 外部存储的权限状态 |

#### 权限请求选项

请求权限的选项

| Prop | 类型 | 说明 | 默认 |
| --- | --- | --- | --- |
| **`showSettingsAlert`** | `boolean` | 如果为真, 在拒绝许可时显示对打开设置的提醒 | `false` |
| **`title`** | `string` | 设置提醒对话框的标题 |  |
| **`message`** | `string` | 设置提醒对话框的消息 |  |
| **`openSettingsButtonTitle`** | `string` | 打开设置按钮的文本 |  |
| **`cancelButtonTitle`** | `string` | “取消”按钮的文本 |  |

### 类型异名

#### 权限状态

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

### 数字

#### 文件系统Type

| 成员 | 数值 |
| --- | --- |
| **`TEMPORARY`** | `0` |
| **`PERSISTENT`** | `1` |

#### 目录

| 成员 | 数值 | 说明 |
| --- | --- | --- |
| **`Documents`** | `'DOCUMENTS'` | 文件目录(iOS)/文件目录(Android) 持久性,用户可见,备份 |
| **`Data`** | `'DATA'` | 数据目录 持久性私有数据存储 |
| **`Library`** | `'LIBRARY'` | 图书馆目录(iOS)/文件目录(Android) 持续但用户看不见 |
| **`Cache`** | `'CACHE'` | 缓存目录 临时缓存, 可能由 OS 清除 |
| **`External`** | `'EXTERNAL'` | 外部存储( 只有Android) SD 卡或外部存储根 |
| **`ExternalStorage`** | `'EXTERNAL_STORAGE'` | 外部存储数据目录( 只有Android) |
| **`Application`** | `'APPLICATION'` | 应用程序捆绑/资产目录( 只读) |

#### 编码

| 成员 | 数值 |
| --- | --- |
| **`UTF8`** | `'utf8'` |
| **`ASCII`** | `'ascii'` |
| **`UTF16`** | `'utf16'` |

## 用法实例

### 正在读取文件

```typescript
import { CapacitorFile, Directory, Encoding } from '@capgo/capacitor-file';

// Read as text
const result = await CapacitorFile.readFile({
  path: 'my-file.txt',
  directory: Directory.Documents,
  encoding: Encoding.UTF8,
});
console.log(result.data);

// Read as base64 (binary)
const binaryResult = await CapacitorFile.readFile({
  path: 'image.png',
  directory: Directory.Documents,
});
console.log(binaryResult.data); // base64 string

// Read partial file (offset and length) - great for large files!
const partialResult = await CapacitorFile.readFile({
  path: 'large-file.bin',
  directory: Directory.Documents,
  offset: 1024,    // Start at byte 1024
  length: 512,     // Read 512 bytes
});
console.log(partialResult.data); // base64 encoded chunk
```

### 写入文件

```typescript
import { CapacitorFile, Directory, Encoding } from '@capgo/capacitor-file';

// Write text
await CapacitorFile.writeFile({
  path: 'my-file.txt',
  directory: Directory.Documents,
  data: 'Hello, World!',
  encoding: Encoding.UTF8,
  recursive: true, // Create parent directories if needed
});

// Write binary (base64)
await CapacitorFile.writeFile({
  path: 'image.png',
  directory: Directory.Documents,
  data: 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==',
});

// Write at specific position (random access) - great for patching files!
await CapacitorFile.writeFile({
  path: 'data.bin',
  directory: Directory.Documents,
  data: 'PATCHED',
  encoding: Encoding.UTF8,
  position: 100,  // Write starting at byte 100
});
```

### 创建和阅读目录

```typescript
import { CapacitorFile, Directory } from '@capgo/capacitor-file';

// Create a directory
await CapacitorFile.mkdir({
  path: 'my-folder/sub-folder',
  directory: Directory.Documents,
  recursive: true,
});

// Read directory contents
const result = await CapacitorFile.readdir({
  path: 'my-folder',
  directory: Directory.Documents,
});

for (const entry of result.entries) {
  console.log(`${entry.name} - ${entry.isFile ? 'file' : 'directory'}`);
}
```

### 复制和移动文件

```typescript
import { CapacitorFile, Directory } from '@capgo/capacitor-file';

// Copy a file
await CapacitorFile.copy({
  from: 'original.txt',
  to: 'backup/original-copy.txt',
  directory: Directory.Documents,
  toDirectory: Directory.Documents,
});

// Move/rename a file
await CapacitorFile.rename({
  from: 'old-name.txt',
  to: 'new-name.txt',
  directory: Directory.Documents,
});
```

### 检查文件存在

```typescript
import { CapacitorFile, Directory } from '@capgo/capacitor-file';

const result = await CapacitorFile.exists({
  path: 'my-file.txt',
  directory: Directory.Documents,
});

if (result.exists) {
  console.log(`Found ${result.type}`);
}
```

### 获取文件信息

```typescript
import { CapacitorFile, Directory } from '@capgo/capacitor-file';

const stat = await CapacitorFile.stat({
  path: 'my-file.txt',
  directory: Directory.Documents,
});

console.log(`Size: ${stat.size} bytes`);
console.log(`Modified: ${new Date(stat.mtime)}`);
console.log(`Type: ${stat.type}`);
```

## 从 cordova-plugin- file 迁移

此插件提供类似的功能至 `cordova-plugin-file` 还有更现代的API. 简而言之:

| Cordova 文件插件 | 此插件 |
| --- | --- |
| `window.resolveLocalFileSystemURL()` | `CapacitorFile.resolveLocalFileSystemURL()` |
| `directoryEntry.getFile()` | `CapacitorFile.getFile()` |
| `directoryEntry.getDirectory()` | `CapacitorFile.getDirectory()` |
| `fileReader.readAsText()` | `CapacitorFile.readFile({ encoding: Encoding.UTF8 })` |
| `fileReader.readAsDataURL()` | `CapacitorFile.readAsDataURL()` |
| `fileWriter.write()` | `CapacitorFile.writeFile()` |
| `entry.remove()` | `CapacitorFile.deleteFile()` |
| `entry.moveTo()` | `CapacitorFile.move()` |
| `entry.copyTo()` | `CapacitorFile.copy()` |
| `directoryEntry.removeRecursively()` | `CapacitorFile.rmdir({ recursive: true })` |
| `cordova.file.dataDirectory` | `Directory.Data` |
| `cordova.file.documentsDirectory` | `Directory.Documents` |
| `cordova.file.cacheDirectory` | `Directory.Cache` |

## 许可证

MPL - 2.0 导弹

## 常见问题

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

文件系统操作的电容插件, 兼容 Cordova 文件插件 API

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

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

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

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

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

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

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

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

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

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

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

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