版本：v4

@capacitor/filesystem

Filesystem API 提供了类似 NodeJS 的 API，用于在设备上处理文件。

安装

npm install @capacitor/filesystem
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，此 API 需要在 AndroidManifest.xml 中添加以下权限：

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

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

请注意，Directory.Documents 和 Directory.ExternalStorage 仅在 Android 9 或更旧版本上可用。

理解目录与文件

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()
接口
类型别名
枚举

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

接口

ReadFileResult

属性	类型	描述	自
`data`	`string`	文件中包含的数据的字符串表示形式	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

WriteFileOptions

属性	类型	描述	默认值	自
`path`	`string`	要写入的文件路径		1.0.0
`data`	`string`	要写入的数据		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

属性	类型	描述	始于版本
`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`	文件或目录的名称
`type`	`'directory' \| 'file'`	文件类型	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

ReaddirOptions

属性	类型	描述	始于版本
`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`	`'directory' \| 'file'`	文件类型	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

属性	类型	描述	自版本
`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`

类型别名

重命名选项 (RenameOptions)

CopyOptions

权限状态 (PermissionState)

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

枚举

目录 (Directory)

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

编码 (Encoding)

成员	值	描述	自版本
`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(...)​

getUri(...)​

rename(...)​

copy(...)​

checkPermissions()​

requestPermissions()​

接口​

ReadFileResult​

ReadFileOptions​

WriteFileResult​

WriteFileOptions​

AppendFileOptions​

MkdirOptions​

RmdirOptions​

ReaddirResult​

FileInfo​

ReaddirOptions​

GetUriResult​

GetUriOptions​

StatResult​

StatOptions​

复制结果 (CopyResult)​

权限状态 (PermissionStatus)​

类型别名​

重命名选项 (RenameOptions)​

权限状态 (PermissionState)​

枚举​

目录 (Directory)​

编码 (Encoding)​

Contents

安装

iOS

Android

理解目录与文件

示例

API

readFile(...)

writeFile(...)

appendFile(...)

deleteFile(...)

mkdir(...)

rmdir(...)

readdir(...)

getUri(...)

rename(...)

copy(...)

checkPermissions()

requestPermissions()

接口

ReadFileResult

ReadFileOptions

WriteFileResult

WriteFileOptions

AppendFileOptions

MkdirOptions

RmdirOptions

ReaddirResult

FileInfo

ReaddirOptions

GetUriResult

GetUriOptions

StatResult

StatOptions

复制结果 (CopyResult)

权限状态 (PermissionStatus)

类型别名

重命名选项 (RenameOptions)

权限状态 (PermissionState)

枚举

目录 (Directory)

编码 (Encoding)