版本：v4

@capacitor/filesystem

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

安装

npm install @capacitor/filesystem
npx cap sync

iOS

要让文件显示在 Files 应用中，必须在 Info.plist 中将以下键设置为 YES：

UIFileSharingEnabled（应用支持 iTunes 文件共享）
LSSupportsOpeningDocumentsInPlace（支持就地打开文档）

参阅配置 iOS 获取帮助。

Android

如果使用 Directory.Documents 或 Directory.ExternalStorage，则需要在 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 的插件（如 Camera）读取二进制数据（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

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`	文件或目录名称
`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

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`

类型别名

RenameOptions


  CopyOptions

PermissionState

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

枚举

成员	值	说明	自版本
`Documents`	`'DOCUMENTS'`	Documents 目录。iOS 上为应用的文档目录，用于存储用户生成的内容。Android 上为公共 Documents 文件夹，可被其他应用访问。在 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'`	External 目录。iOS 上使用 Documents 目录。Android 上为主共享/外部存储设备上的应用专用持久文件目录，这些文件对用户不可见，卸载应用时会被删除。	1.0.0
`ExternalStorage`	`'EXTERNAL_STORAGE'`	External Storage 目录。iOS 上使用 Documents 目录。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，仅 Android 支持此编码。	1.0.0
`UTF16`	`'utf16'`	十六位 UCS 转换格式，字节序由可选的字节序标识符决定，仅 Android 支持此编码。	1.0.0

安装​

iOS​

Android​

理解目录与文件​

示例​

API​

readFile(...)​

writeFile(...)​

appendFile(...)​

deleteFile(...)​

mkdir(...)​

rmdir(...)​

readdir(...)​

getUri(...)​

stat(...)​

rename(...)​

copy(...)​

checkPermissions()​

requestPermissions()​

接口​

ReadFileResult​

ReadFileOptions​

WriteFileResult​

WriteFileOptions​

AppendFileOptions​

DeleteFileOptions​

MkdirOptions​

RmdirOptions​

ReaddirResult​

FileInfo​

ReaddirOptions​

GetUriResult​

GetUriOptions​

StatResult​

StatOptions​

CopyOptions​

CopyResult​

PermissionStatus​

类型别名​

RenameOptions​

PermissionState​

枚举​

Directory​

Encoding​

Contents

安装

iOS

Android

理解目录与文件

示例

API

readFile(...)

writeFile(...)

appendFile(...)

deleteFile(...)

mkdir(...)

rmdir(...)

readdir(...)

getUri(...)

stat(...)

rename(...)

copy(...)

checkPermissions()

requestPermissions()

接口

ReadFileResult

ReadFileOptions

WriteFileResult

WriteFileOptions

AppendFileOptions

DeleteFileOptions

MkdirOptions

RmdirOptions

ReaddirResult

FileInfo

ReaddirOptions

GetUriResult

GetUriOptions

StatResult

StatOptions

CopyOptions

CopyResult

PermissionStatus

类型别名

RenameOptions

PermissionState

枚举

Directory

Encoding