版本：v6

@capacitor/filesystem

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

安装

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

Apple 隐私清单要求

Apple 要求应用开发者现在必须指定 API 使用批准理由以增强用户隐私。到 2024 年 5 月 1 日，在向 App Store Connect 提交应用时必须包含这些理由。

在您的应用中使用此特定插件时，您必须在 /ios/App 中创建一个 PrivacyInfo.xcprivacy 文件，或使用 VS Code 扩展生成它，并指定使用理由。

有关详细步骤，请参阅 Capacitor 文档。

对于此插件，必需的字典键是 NSPrivacyAccessedAPICategoryFileTimestamp，推荐的理由是 C617.1。

示例 PrivacyInfo.xcprivacy

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>NSPrivacyAccessedAPITypes</key>
    <array>
      <!-- 如果 PrivacyInfo 文件已存在，将此 dict 条目添加到数组中 -->
      <dict>
        <key>NSPrivacyAccessedAPIType</key>
        <string>NSPrivacyAccessedAPICategoryFileTimestamp</string>
        <key>NSPrivacyAccessedAPITypeReasons</key>
        <array>
          <string>C617.1</string>
        </array>
      </dict>
    </array>
  </dict>
</plist>

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 指南中关于设置权限的更多信息。

注意，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 的插件（如 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()
downloadFile(...)
addListener('progress', ...)
removeAllListeners()
Interfaces
Type Aliases
Enums

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>

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

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

返回：

Promise<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

WriteFileOptions

属性	类型	描述	默认值	始于
`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`	文件或目录的名称。
`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

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`	`'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

DownloadFileOptions

属性	类型	描述	默认值	始于
`path`	`string`	下载文件应移动到的路径。		5.1.0
`directory`	`Directory`	写入文件的目录。如果使用此选项，filePath 可以是相对路径而不是绝对路径。默认为 `DATA` 目录。		5.1.0
`progress`	`boolean`	可选的监听器函数，用于接收下载进度事件。如果使用此选项，应在每个接收到的数据块上调度 progress 事件。在 Android/iOS 上，数据块每 100ms 被节流以避免性能下降。		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'`	文档目录。在 iOS 上是应用的 documents 目录。使用此目录存储用户生成的内容。在 Android 上是公共 Documents 文件夹，因此其他应用可以访问。在 Android 10 上不可访问，除非应用通过在 `AndroidManifest.xml` 的 `application` 标签中添加 `android:requestLegacyExternalStorage="true"` 来启用传统外部存储。在 Android 11 或更新版本上，应用只能访问其自己创建的文件/文件夹。	1.0.0
`Data`	`'DATA'`	数据目录。在 iOS 上使用 Documents 目录。在 Android 上是持有应用程序文件的目录。卸载应用时文件将被删除。	1.0.0
`Library`	`'LIBRARY'`	库目录。在 iOS 上使用 Library 目录。在 Android 上是持有应用程序文件的目录。卸载应用时文件将被删除。	1.1.0
`Cache`	`'CACHE'`	缓存目录。可能在内存不足时被删除，因此使用此目录编写应用特定的文件，且应用可以轻松重新创建。	1.0.0
`External`	`'EXTERNAL'`	外部目录。在 iOS 上使用 Documents 目录。在 Android 上，是主共享/外部存储设备上的目录，应用程序可以在其中放置其拥有的持久文件。这些文件对应用来说是内部的，通常不对用户可见。卸载应用时文件将被删除。	1.0.0
`ExternalStorage`	`'EXTERNAL_STORAGE'`	外部存储目录。在 iOS 上使用 Documents 目录。在 Android 上是主共享/外部存储目录。在 Android 10 上不可访问，除非应用启用了传统外部存储。在 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

安装​

Apple 隐私清单要求​

示例 PrivacyInfo.xcprivacy​

iOS​

Android​

理解目录和文件​

示例​

API​

readFile(...)​

writeFile(...)​

appendFile(...)​

deleteFile(...)​

mkdir(...)​

rmdir(...)​

readdir(...)​

getUri(...)​

stat(...)​

rename(...)​

copy(...)​

checkPermissions()​

requestPermissions()​

downloadFile(...)​

addListener('progress', ...)​

removeAllListeners()​

接口​

ReadFileResult​

ReadFileOptions​

WriteFileResult​

WriteFileOptions​

AppendFileOptions​

DeleteFileOptions​

MkdirOptions​

RmdirOptions​

ReaddirResult​

FileInfo​

ReaddirOptions​

GetUriResult​

GetUriOptions​

StatResult​

StatOptions​

CopyOptions​

CopyResult​

PermissionStatus​

DownloadFileResult​

DownloadFileOptions​

PluginListenerHandle​

ProgressStatus​

类型别名​

RenameOptions​

PermissionState​

ProgressListener​

枚举​

Directory​

Encoding​

Contents

安装

Apple 隐私清单要求

示例 PrivacyInfo.xcprivacy

iOS

Android

理解目录和文件

示例

API

readFile(...)

writeFile(...)

appendFile(...)

deleteFile(...)

mkdir(...)

rmdir(...)

readdir(...)

getUri(...)

stat(...)

rename(...)

copy(...)

checkPermissions()

requestPermissions()

downloadFile(...)

addListener('progress', ...)

removeAllListeners()

接口

ReadFileResult

ReadFileOptions

WriteFileResult

WriteFileOptions

AppendFileOptions

DeleteFileOptions

MkdirOptions

RmdirOptions

ReaddirResult

FileInfo

ReaddirOptions

GetUriResult

GetUriOptions

StatResult

StatOptions

CopyOptions

CopyResult

PermissionStatus

DownloadFileResult

DownloadFileOptions

PluginListenerHandle

ProgressStatus

类型别名

RenameOptions

PermissionState

ProgressListener

枚举

Directory

Encoding