跳到主要内容
版本：v8

@capacitor/filesystem

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

安装​

npm install @capacitor/filesystem
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>
        <key>NSPrivacyAccessedAPIType</key>
        <string>NSPrivacyAccessedAPICategoryFileTimestamp</string>
        <key>NSPrivacyAccessedAPITypeReasons</key>
        <array>
          <string>C617.1</string>
        </array>
      </dict>
    </array>
  </dict>
</plist>

从downloadFile迁移到文件传输插件​

自版本7.1.0起，文件系统插件中的downloadFile功能已被弃用，推荐使用新的@capacitor/file-transfer插件。

安装文件传输插件​

npm install @capacitor/file-transfer
npx cap sync

迁移示例​

之前（使用文件系统插件）：

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

await Filesystem.downloadFile({
  url: 'https://example.com/file.pdf',
  path: 'downloaded-file.pdf',
  directory: Directory.Documents,
  progress: true,
});

// 进度事件
Filesystem.addListener('progress', (progress) => {
  console.log(`已下载 ${progress.bytes} / ${progress.contentLength}`);
});

之后（使用文件传输插件）：

import { FileTransfer } from '@capacitor/file-transfer';
import { Filesystem, Directory } from '@capacitor/filesystem';

// 首先使用Filesystem获取完整文件路径
const fileInfo = await Filesystem.getUri({
  directory: Directory.Documents,
  path: 'downloaded-file.pdf',
});

// 然后使用文件传输插件下载
await FileTransfer.downloadFile({
  url: 'https://example.com/file.pdf',
  path: fileInfo.uri,
  progress: true,
});

// 进度事件
FileTransfer.addListener('progress', (progress) => {
  console.log(`已下载 ${progress.bytes} / ${progress.contentLength}`);
});

文件传输插件提供了更高的可靠性、更好的错误处理（带有特定的错误代码），并且还添加了上传功能。

iOS​

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

  • UIFileSharingEnabled（应用程序支持iTunes文件共享）
  • LSSupportsOpeningDocumentsInPlace（支持在位置打开文档）

阅读配置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在文件之间有额外的分离层，例如备份到云的特殊目录，或用于存储文档的目录。文件系统API提供了一种简单的方法，将每个操作限定到设备上的特定特殊目录。

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

示例​

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

const writeSecretFile = async () => {
  await Filesystem.writeFile({
    path: 'secrets/text.txt',
    data: '这是一个测试',
    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('秘密:', 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('数据:', contents);
};

API​

有关现有错误代码的列表，请参阅错误。

checkPermissions()​

checkPermissions() => Promise<PermissionStatus>

检查读/写权限。 仅在Android上使用Directory.Documents或 Directory.ExternalStorage时需要。

返回: 

Promise<PermissionStatus>

Since: 1.0.0

requestPermissions()​

requestPermissions() => Promise<PermissionStatus>

请求读/写权限。 仅在Android上使用Directory.Documents或 Directory.ExternalStorage时需要。

返回: 

Promise<PermissionStatus>

Since: 1.0.0

readFile(...)​

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

从磁盘读取文件

参数类型
options
ReadFileOptions

返回: 

Promise<ReadFileResult>

Since: 1.0.0

readFileInChunks(...)​

readFileInChunks(options: ReadFileInChunksOptions, callback: ReadFileInChunksCallback) => Promise<CallbackID>

从磁盘分块读取文件。 仅原生（在Web上不可用）。 使用回调接收每个读取的块。 如果返回空块，则表示文件已完全读取。

参数类型
options
ReadFileInChunksOptions
callback
ReadFileInChunksCallback

返回: Promise<string>

Since: 7.1.0

writeFile(...)​

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

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

参数类型
options
WriteFileOptions

返回: 

Promise<WriteFileResult>

Since: 1.0.0

appendFile(...)​

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

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

参数类型
options
AppendFileOptions

Since: 1.0.0

deleteFile(...)​

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

从磁盘删除文件

参数类型
options
DeleteFileOptions

Since: 1.0.0

mkdir(...)​

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

创建目录。

参数类型
options
MkdirOptions

Since: 1.0.0

rmdir(...)​

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

删除目录

参数类型
options
RmdirOptions

Since: 1.0.0

readdir(...)​

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

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

参数类型
options
ReaddirOptions

返回: 

Promise<ReaddirResult>

Since: 1.0.0

getUri(...)​

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

返回路径和目录的完整文件URI

参数类型
options
GetUriOptions

返回: 

Promise<GetUriResult>

Since: 1.0.0

stat(...)​

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

返回文件的数据信息

参数类型
options
StatOptions

返回: 

Promise<FileInfo>

Since: 1.0.0

rename(...)​

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

重命名文件或目录

参数类型
options
CopyOptions

Since: 1.0.0

copy(...)​

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

复制文件或目录

参数类型
options
CopyOptions

返回: 

Promise<CopyResult>

Since: 1.0.0

downloadFile(...)​

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

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

此方法自版本7.1.0起已弃用。 我们建议改用@capacitor/file-transfer插件，与此插件结合使用。

参数类型
options
DownloadFileOptions

返回: 

Promise<DownloadFileResult>

Since: 5.1.0

addListener('progress', ...)​

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

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

此方法自版本7.1.0起已弃用。 我们建议改用@capacitor/file-transfer插件，与此插件结合使用。

参数类型
eventName'progress'
listenerFunc
ProgressListener

返回: 

Promise<PluginListenerHandle>

Since: 5.1.0

removeAllListeners()​

removeAllListeners() => Promise<void>

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

此方法自版本7.1.0起已弃用。 我们建议改用@capacitor/file-transfer插件，与此插件结合使用。

Since: 5.2.0

Interfaces​

PermissionStatus​

属性类型
publicStorage
PermissionState

ReadFileResult​

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

ReadFileOptions​

属性类型描述Since
pathstring要读取的文件路径1.0.0
directory
Directory
从中读取文件的Directory1.0.0
encoding
Encoding
读取文件的编码方式，如果未提供，数据将作为二进制读取并返回base64编码。传递Encoding.UTF8以字符串形式读取数据1.0.0

ReadFileInChunksOptions​

属性类型描述Since
chunkSizenumber块大小（字节）。7.1.0

WriteFileResult​

属性类型描述Since
uristring文件写入的uri1.0.0

WriteFileOptions​

属性类型描述默认值Since
pathstring要写入的文件路径1.0.0
datastring | Blob要写入的数据 注意：Blob数据仅在Web上受支持。1.0.0
directory
Directory
存储文件的Directory1.0.0
encoding
Encoding
写入文件的编码方式。如果未提供，数据将作为base64编码写入。传递Encoding.UTF8以字符串形式写入数据1.0.0
recursiveboolean是否创建任何缺失的父目录。false1.0.0

AppendFileOptions​

属性类型描述Since
pathstring要追加的文件路径1.0.0
datastring要写入的数据1.0.0
directory
Directory
存储文件的Directory1.0.0
encoding
Encoding
写入文件的编码方式。如果未提供，数据将作为base64编码写入。传递Encoding.UTF8以字符串形式写入数据1.0.0

DeleteFileOptions​

属性类型描述Since
pathstring要删除的文件路径1.0.0
directory
Directory
从中删除文件的Directory1.0.0

MkdirOptions​

属性类型描述默认值Since
pathstring新目录的路径1.0.0
directory
Directory
创建新目录的Directory1.0.0
recursiveboolean是否同时创建任何缺失的父目录。false1.0.0

RmdirOptions​

属性类型描述默认值Since
pathstring要删除的目录路径1.0.0
directory
Directory
从中删除目录的Directory1.0.0
recursiveboolean是否递归删除目录内容false1.0.0

ReaddirResult​

属性类型描述Since
filesFileInfo[]目录内的文件和目录列表1.0.0

FileInfo​

属性类型描述Since
namestring文件或目录的名称。7.1.0
type'file' | 'directory'文件类型。4.0.0
sizenumber文件大小（字节）。4.0.0
ctimenumber创建时间（毫秒）。在Android 7及更早设备上不可用。7.1.0
mtimenumber最后修改时间（毫秒）。7.1.0
uristring文件的uri。4.0.0

ReaddirOptions​

属性类型描述Since
pathstring要读取的目录路径1.0.0
directory
Directory
从中列出文件的Directory1.0.0

GetUriResult​

属性类型描述Since
uristring文件的uri1.0.0

GetUriOptions​

属性类型描述Since
pathstring要获取URI的文件路径1.0.0
directory
Directory
文件所在的Directory1.0.0

StatOptions​

属性类型描述Since
pathstring要获取数据的文件路径1.0.0
directory
Directory
文件所在的Directory1.0.0

CopyOptions​

属性类型描述Since
fromstring现有文件或目录1.0.0
tostring目标文件或目录1.0.0
directory
Directory
包含现有文件或目录的Directory1.0.0
toDirectory
Directory
包含目标文件或目录的Directory。如果未提供，将使用'directory'参数作为目标1.0.0

CopyResult​

属性类型描述Since
uristring文件复制到的uri4.0.0

DownloadFileResult​

属性类型描述Since
pathstring文件下载到的路径。5.1.0
blobBlob下载文件的blob数据。这仅在Web上可用。5.1.0

DownloadFileOptions​

属性类型描述默认值Since
pathstring下载文件应移动到的路径。5.1.0
directory
Directory
写入文件的目录。如果使用此选项，filePath可以是相对路径而不是绝对路径。默认为DATA目录。5.1.0
progressboolean可选监听器函数以接收下载进度事件。如果使用此选项，应在每个接收到的块上分派进度事件。在Android/iOS上，块被限制为每100ms一次以避免减速。5.1.0
recursiveboolean是否创建任何缺失的父目录。false5.1.2

PluginListenerHandle​

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

ProgressStatus​

属性类型描述Since
urlstring正在下载的文件的URL。5.1.0
bytesnumber到目前为止下载的字节数。5.1.0
contentLengthnumber此文件要下载的总字节数。5.1.0

Type Aliases​

PermissionState​

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

ReadFileInChunksCallback​

用于接收从文件读取的块的回调，或在出现错误时接收错误。


  (chunkRead: ReadFileResult | null, err?: any): void

CallbackID​

string

StatResult​


  FileInfo

RenameOptions​


  CopyOptions

ProgressListener​

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


  (progress: ProgressStatus): void

Enums​

Directory​

成员值描述Since
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
ExternalCache'EXTERNAL_CACHE'外部缓存目录。在iOS上将使用文档目录。在Android上是主共享/外部缓存。7.1.0
LibraryNoCloud'LIBRARY_NO_CLOUD'无云备份的库目录。在iOS上使用。在Android上是保存应用文件的目录。7.1.0
Temporary'TEMPORARY'iOS的临时目录。在Android上是保存应用缓存的目录。7.1.0

Encoding​

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

错误​

自版本7.1.0起，插件在原生Android和iOS上返回带有特定代码的特定错误。Web不遵循此错误标准。

下表列出了所有插件错误：

错误代码平台消息
OS-PLUG-FILE-0004iOSCordova / Capacitor桥未初始化。
OS-PLUG-FILE-0005Android, iOS方法输入参数无效。
OS-PLUG-FILE-0006Android, iOS提供的路径无效。
OS-PLUG-FILE-0007Android无法执行文件操作，用户拒绝了权限请求。
OS-PLUG-FILE-0008Android, iOS操作失败，因为文件不存在。
OS-PLUG-FILE-0009Android不支持提供的输入操作。
OS-PLUG-FILE-0010Android, iOS目录已存在，无法覆盖。
OS-PLUG-FILE-0011Android, iOS缺少父目录 - 可能传递了recursive=false或父目录创建失败。
OS-PLUG-FILE-0012Android, iOS无法删除包含子项的目录；收到recursive=false但目录有内容。
OS-PLUG-FILE-0013Android, iOS操作失败并出现错误。

Contents

编辑此页