版本：v5

@capacitor/filesystem

Filesystem API 提供了一套类似 NodeJS 的 API，用于在设备上进行文件操作。

安装

npm install @capacitor/filesystem@latest-5
npx cap sync

iOS

若要使文件出现在“文件”应用中，必须在 Info.plist 中将以下键设置为 YES：

UIFileSharingEnabled (Application supports iTunes file sharing)
LSSupportsOpeningDocumentsInPlace (Supports opening documents in place)

请参阅配置 iOS 获取帮助。

Android

如果使用 Directory.Documents 或 Directory.ExternalStorage，在 Android 10 及更早版本中，此 API 需要在 AndroidManifest.xml 中添加以下权限：

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

有关设置 Android 权限的更多信息，请参阅 Android 指南中的设置权限。

请注意，Directory.ExternalStorage 仅在 Android 9 或更早版本上可用，而 Directory.Documents 在 Android 11 及更新版本上仅允许访问您的应用创建的文件/文件夹。

处理大文件时，可能需要向 AndroidManifest.xml 中的 <application> 标签添加 android:largeHeap="true"。

理解目录与文件

iOS 和 Android 对文件有额外的分层管理，例如有专门备份到云端的特殊目录，或用于存储文档的目录。Filesystem API 提供了一种简单的方法，将每个操作限定在设备上的特定特殊目录内。

此外，Filesystem API 支持使用完整的 file:// 路径，或在 Android 上读取 content:// 文件。只需不指定 directory 参数即可使用完整文件路径。

示例

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

const writeSecretFile = async () => {
  await Filesystem.writeFile({
    path: 'secrets/text.txt',
    data: 'This is a test',
    directory: Directory.Documents,
    encoding: Encoding.UTF8,
  });
};

const readSecretFile = async () => {
  const contents = await Filesystem.readFile({
    path: 'secrets/text.txt',
    directory: Directory.Documents,
    encoding: Encoding.UTF8,
  });

  console.log('secrets:', contents);
};

const deleteSecretFile = async () => {
  await Filesystem.deleteFile({
    path: 'secrets/text.txt',
    directory: Directory.Documents,
  });
};

const readFilePath = async () => {
  // 这是一个读取完整文件路径文件的示例。当需要从返回文件 URI（例如相机插件）的插件中读取二进制数据（base64 编码）时，可以使用此方法。
  const contents = await Filesystem.readFile({
    path: 'file:///var/mobile/Containers/Data/Application/22A433FD-D82D-4989-8BE6-9FC49DEA20BB/Documents/text.txt',
  });

  console.log('data:', contents);
};

API

readFile(...)
writeFile(...)
appendFile(...)
deleteFile(...)
mkdir(...)
rmdir(...)
readdir(...)
getUri(...)
stat(...)
rename(...)
copy(...)
checkPermissions()
requestPermissions()
downloadFile(...)
addListener('progress', ...)
removeAllListeners()
接口
类型别名
枚举

readFile(...)

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

从磁盘读取文件

参数	类型
`options`	`ReadFileOptions`

返回值:

Promise<ReadFileResult>

起始版本: 1.0.0

writeFile(...)

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

将文件写入设备的指定位置

参数	类型
`options`	`WriteFileOptions`

返回值:

Promise<WriteFileResult>

起始版本: 1.0.0

appendFile(...)

appendFile(options: AppendFileOptions) => Promise<void>

在设备的指定位置向文件追加内容

参数	类型
`options`	`AppendFileOptions`

起始版本: 1.0.0

deleteFile(...)

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

从磁盘删除文件

参数	类型
`options`	`DeleteFileOptions`

起始版本: 1.0.0

mkdir(...)

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

创建目录。

参数	类型
`options`	`MkdirOptions`

起始版本: 1.0.0

rmdir(...)

rmdir(options: RmdirOptions) => Promise<void>

删除目录

参数	类型
`options`	`RmdirOptions`

起始版本: 1.0.0

readdir(...)

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

返回目录中的文件列表（非递归）

参数	类型
`options`	`ReaddirOptions`

返回值:

Promise<ReaddirResult>

起始版本: 1.0.0

--------------------### getUri(...)

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

获取指定路径和目录的完整文件 URI（统一资源标识符）。

参数	类型
`options`	`GetUriOptions`

返回：

Promise<GetUriResult>

自： 1.0.0

stat(...)

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

获取文件的元数据信息。

参数	类型
`options`	`StatOptions`

返回：

Promise<StatResult>

自： 1.0.0

rename(...)

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

重命名一个文件或目录。

参数	类型
`options`	`CopyOptions`

自： 1.0.0

copy(...)

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

复制一个文件或目录。

参数	类型
`options`	`CopyOptions`

返回：

Promise<CopyResult>

自： 1.0.0

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

检查读写权限。仅在 Android 平台上，且使用 Directory.Documents 或 Directory.ExternalStorage 目录时需要调用此方法。

返回：

Promise<PermissionStatus>

自： 1.0.0

requestPermissions()

requestPermissions() => Promise<PermissionStatus>

请求读写权限。仅在 Android 平台上，且使用 Directory.Documents 或 Directory.ExternalStorage 目录时需要调用此方法。

返回：

Promise<PermissionStatus>

自： 1.0.0

downloadFile(...)

downloadFile(options: DownloadFileOptions) => Promise<DownloadFileResult>

向服务器发起 HTTP 请求并将文件下载到指定位置。

参数	类型
`options`	`DownloadFileOptions`

返回：

Promise<DownloadFileResult>

自： 5.1.0

addListener('progress', ...)

addListener(eventName: 'progress', listenerFunc: ProgressListener) => Promise<PluginListenerHandle> & PluginListenerHandle

为文件下载进度事件添加监听器。

参数	类型
`eventName`	`'progress'`
`listenerFunc`	`ProgressListener`

返回：

Promise<PluginListenerHandle> & PluginListenerHandle

自： 5.1.0

removeAllListeners()

removeAllListeners() => Promise<void>

移除此插件的所有监听器。

自： 5.2.0

接口

ReadFileResult

属性	类型	描述	自
`data`	`string \| Blob`	文件中包含的数据表示形式。注意：`Blob` 仅在 Web 端可用。在原生平台上，数据以字符串形式返回。	1.0.0

ReadFileOptions

属性	类型	描述	自
`path`	`string`	要读取的文件路径	1.0.0
`directory`	`Directory`	读取文件的来源 `Directory`	1.0.0
`encoding`	`Encoding`	读取文件时使用的编码。如果未提供，数据将被作为二进制读取并以 base64 编码的字符串返回。传递 Encoding.UTF8 可以将数据作为字符串读取。	1.0.0

WriteFileResult

属性	类型	描述	自
`uri`	`string`	文件被写入后的 URI 地址	1.0.0

属性	类型	描述	默认值	始于
`path`	`string`	要写入的文件路径		1.0.0
`data`	`string \| Blob`	要写入的数据。注意：Blob 数据仅在 Web 端支持		1.0.0
`directory`	`Directory`	存储文件的 `Directory`		1.0.0
`encoding`	`Encoding`	文件的写入编码。如果未提供，数据将以 base64 编码写入。传入 Encoding.UTF8 可将数据作为字符串写入		1.0.0
`recursive`	`boolean`	是否创建所有缺失的父目录	`false`	1.0.0

AppendFileOptions

属性	类型	描述	始于
`path`	`string`	要追加的文件路径	1.0.0
`data`	`string`	要写入的数据	1.0.0
`directory`	`Directory`	存储文件的 `Directory`	1.0.0
`encoding`	`Encoding`	文件的写入编码。如果未提供，数据将以 base64 编码写入。传入 Encoding.UTF8 可将数据作为字符串写入	1.0.0

DeleteFileOptions

属性	类型	描述	始于
`path`	`string`	要删除的文件路径	1.0.0
`directory`	`Directory`	从中删除文件的 `Directory`	1.0.0

MkdirOptions

属性	类型	描述	默认值	始于
`path`	`string`	新目录的路径		1.0.0
`directory`	`Directory`	在其中创建新目录的 `Directory`		1.0.0
`recursive`	`boolean`	是否同时创建所有缺失的父目录	`false`	1.0.0

RmdirOptions

属性	类型	描述	默认值	始于
`path`	`string`	要移除的目录路径		1.0.0
`directory`	`Directory`	从中移除目录的 `Directory`		1.0.0
`recursive`	`boolean`	是否递归移除目录内的所有内容	`false`	1.0.0

ReaddirResult

属性	类型	描述	始于
`files`	`FileInfo[]`	目录内的文件和目录列表	1.0.0

FileInfo

属性	类型	描述	始于
`name`	`string`	文件或目录的名称	4.0.0
`type`	`'file' \| 'directory'`	文件的类型	4.0.0
`size`	`number`	文件的大小（字节）	4.0.0
`ctime`	`number`	创建时间（毫秒）。在 Android 7 及更早的设备上不可用	4.0.0
`mtime`	`number`	最后修改时间（毫秒）	4.0.0
`uri`	`string`	文件的 URI	4.0.0

属性	类型	描述	始于版本
`path`	`string`	要读取的目录路径	1.0.0
`directory`	`Directory`	用于列出文件的 `Directory`	1.0.0

GetUriResult

属性	类型	描述	始于版本
`uri`	`string`	文件的 URI	1.0.0

GetUriOptions

属性	类型	描述	始于版本
`path`	`string`	要获取其 URI 的文件路径	1.0.0
`directory`	`Directory`	文件所在的 `Directory`	1.0.0

StatResult

属性	类型	描述	始于版本
`type`	`'file' \| 'directory'`	文件类型。	1.0.0
`size`	`number`	文件大小，单位为字节。	1.0.0
`ctime`	`number`	创建时间，单位为毫秒。在 Android 7 及更早版本上不可用。	1.0.0
`mtime`	`number`	最后修改时间，单位为毫秒。	1.0.0
`uri`	`string`	文件的 URI	1.0.0

StatOptions

属性	类型	描述	始于版本
`path`	`string`	要获取信息的文件路径	1.0.0
`directory`	`Directory`	文件所在的 `Directory`	1.0.0

CopyOptions

属性	类型	描述	始于版本
`from`	`string`	现有的文件或目录	1.0.0
`to`	`string`	目标文件或目录	1.0.0
`directory`	`Directory`	包含现有文件或目录的 `Directory`	1.0.0
`toDirectory`	`Directory`	包含目标文件或目录的 `Directory`。如果未提供，将使用 'directory' 参数作为目标位置	1.0.0

CopyResult

属性	类型	描述	始于版本
`uri`	`string`	文件被复制到的目标 URI	4.0.0

PermissionStatus

属性	类型
`publicStorage`	`PermissionState`

DownloadFileResult

属性	类型	描述	始于版本
`path`	`string`	文件被下载到的路径。	5.1.0
`blob`	`Blob`	已下载文件的 Blob 数据。此属性仅 Web 端可用。	5.1.0

属性	类型	说明	默认值	引入版本
`path`	`string`	下载文件应移动到的路径。		5.1.0
`directory`	`Directory`	写入文件的目录。如果使用此选项，filePath 可以是相对路径而非绝对路径。默认使用 `DATA` 目录。		5.1.0
`progress`	`boolean`	可选的监听函数，用于接收下载进度事件。如果使用此选项，应在每次收到数据块时分派进度事件。在 Android/iOS 上，数据块会节流至每 100 毫秒一次，以避免性能下降。		5.1.0
`recursive`	`boolean`	是否创建所有缺失的父目录。	`false`	5.1.2

PluginListenerHandle

属性	类型
`remove`	`() => Promise<void>`

ProgressStatus

属性	类型	说明	引入版本
`url`	`string`	正在下载的文件的 URL。	5.1.0
`bytes`	`number`	目前已下载的字节数。	5.1.0
`contentLength`	`number`	此文件需要下载的总字节数。	5.1.0

类型别名

RenameOptions

CopyOptions

PermissionState

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

ProgressListener

接收进度事件的监听函数。

(progress: ProgressStatus): void

成员	值	说明	引入版本
`Documents`	`'DOCUMENTS'`	Documents 目录。在 iOS 上，这是应用程序的文档目录，用于存储用户生成的内容。在 Android 上，这是公共文档文件夹，因此其他应用可以访问。在 Android 10 上，除非应用在 `AndroidManifest.xml` 的 `application` 标签中添加 `android:requestLegacyExternalStorage="true"` 以启用旧版外部存储，否则无法访问。在 Android 11 或更高版本上，应用只能访问其自己创建的文件/文件夹。	1.0.0
`Data`	`'DATA'`	Data 目录。在 iOS 上，使用 Documents 目录。在 Android 上，这是存放应用文件的目录。卸载应用时会删除文件。	1.0.0
`Library`	`'LIBRARY'`	Library 目录。在 iOS 上，使用 Library 目录。在 Android 上，这是存放应用文件的目录。卸载应用时会删除文件。	1.1.0
`Cache`	`'CACHE'`	Cache 目录。在内存不足时可能被删除，因此请使用此目录写入应用可以轻松重新创建的应用特定文件。	1.0.0
`External`	`'EXTERNAL'`	外部目录。在 iOS 上，使用 Documents 目录。在 Android 上，这是主共享/外部存储设备上的目录，应用可以在其中放置其拥有的持久文件。这些文件是应用内部的，通常不作为媒体对用户可见。卸载应用时会删除文件。	1.0.0
`ExternalStorage`	`'EXTERNAL_STORAGE'`	外部存储目录。在 iOS 上，使用 Documents 目录。在 Android 上，这是主共享/外部存储目录。在 Android 10 上，除非应用在 `AndroidManifest.xml` 的 `application` 标签中添加 `android:requestLegacyExternalStorage="true"` 以启用旧版外部存储，否则无法访问。在 Android 11 或更高版本上无法访问。	1.0.0

成员	值	描述	开始版本
`UTF8`	`'utf8'`	八位 UCS 转换格式	1.0.0
`ASCII`	`'ascii'`	七位 ASCII，又称 ISO646-US，即 Unicode 字符集中的基本拉丁字符块。此编码仅在 Android 上受支持。	1.0.0
`UTF16`	`'utf16'`	十六位 UCS 转换格式，字节顺序由可选的字节顺序标记标识。此编码仅在 Android 上受支持。	1.0.0

安装​

iOS​

Android​

理解目录与文件​

示例​

API​

readFile(...)​

writeFile(...)​

appendFile(...)​

deleteFile(...)​

mkdir(...)​

rmdir(...)​

readdir(...)​

stat(...)​

rename(...)​

copy(...)​

checkPermissions()​

requestPermissions()​

downloadFile(...)​

addListener('progress', ...)​

removeAllListeners()​

接口​

ReadFileResult​

ReadFileOptions​

WriteFileResult​

AppendFileOptions​

DeleteFileOptions​

MkdirOptions​

RmdirOptions​

ReaddirResult​

FileInfo​

GetUriResult​

GetUriOptions​

StatResult​

StatOptions​

CopyOptions​

CopyResult​

PermissionStatus​

DownloadFileResult​

PluginListenerHandle​

ProgressStatus​

类型别名​

RenameOptions​

PermissionState​

ProgressListener​

枚举​

Directory​

Contents

安装

iOS

Android

理解目录与文件

示例

API

readFile(...)

writeFile(...)

appendFile(...)

deleteFile(...)

mkdir(...)

rmdir(...)

readdir(...)

stat(...)

rename(...)

copy(...)

checkPermissions()

requestPermissions()

downloadFile(...)

addListener('progress', ...)

removeAllListeners()

接口

ReadFileResult

ReadFileOptions

WriteFileResult

AppendFileOptions

DeleteFileOptions

MkdirOptions

RmdirOptions

ReaddirResult

FileInfo

GetUriResult

GetUriOptions

StatResult

StatOptions

CopyOptions

CopyResult

PermissionStatus

DownloadFileResult

PluginListenerHandle

ProgressStatus

类型别名

RenameOptions

PermissionState

ProgressListener

枚举

Directory