跳至主要内容
版本: v8

@capacitor/filesystem

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>
      
      <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 (应用程序支持 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 及更高版本上访问您的应用程序在 Android 上创建的文件/文件夹。

处理大型文件可能需要您在 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 () => {
  // Here's an example of reading a file with a full file path. Use this to
  // read binary data (base64 encoded) from plugins that return File URIs, such as
  // the Camera.
  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(...)​

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

从磁盘读取文件

参数类型
optionsReadFileOptions

返回值: Promise<ReadFileResult>

自 1.0.0

writeFile(...)​

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

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

参数类型
optionsWriteFileOptions

返回值: Promise<WriteFileResult>

自 1.0.0

appendFile(...)​

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

追加到设备上指定位置的磁盘上的文件

参数类型
optionsAppendFileOptions

自 1.0.0

deleteFile(...)​

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

从磁盘删除文件

参数类型
optionsDeleteFileOptions

自 1.0.0

mkdir(...)​

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

创建目录。

参数类型
optionsMkdirOptions

自 1.0.0

rmdir(...)​

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

删除目录

参数类型
optionsRmdirOptions

自 1.0.0

readdir(...)​

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

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

参数类型
optionsReaddirOptions

返回值: Promise<ReaddirResult>

自 1.0.0

getUri(...)​

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

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

参数类型
optionsGetUriOptions

返回值: Promise<GetUriResult>

自 1.0.0

stat(...)​

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

返回有关文件的信息

参数类型
optionsStatOptions

返回值: Promise<StatResult>

自 1.0.0

rename(...)​

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

重命名文件或目录

参数类型
optionsCopyOptions

自 1.0.0

copy(...)​

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

复制文件或目录

参数类型
optionsCopyOptions

返回值: 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 请求并将文件下载到指定的目标。

参数类型
optionsDownloadFileOptions

返回值: Promise<DownloadFileResult>

自 5.1.0

addListener('progress', ...)​

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

向文件下载进度事件添加侦听器。

参数类型
eventName'progress'
listenerFuncProgressListener

返回值: Promise<PluginListenerHandle>

自 5.1.0

removeAllListeners()​

removeAllListeners() => Promise<void>

删除此插件的所有侦听器。

自 5.2.0

接口​

ReadFileResult​

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

ReadFileOptions​

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

WriteFileResult​

属性类型描述自
uristring文件写入到的 URI1.0.0

WriteFileOptions​

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

AppendFileOptions​

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

DeleteFileOptions​

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

MkdirOptions​

属性类型描述默认自
pathstring新目录的路径1.0.0
directoryDirectory要创建新目录的 Directory1.0.0
recursiveboolean是否也创建任何缺少的父目录。false1.0.0

RmdirOptions​

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

ReaddirResult​

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

FileInfo​

属性类型描述自
名称string文件或目录的名称。
类型'file' | 'directory'文件的类型。4.0.0
大小号码文件的大小（以字节为单位）。4.0.0
创建时间号码创建时间（以毫秒为单位）。在 Android 7 及更早版本的设备上不可用。4.0.0
修改时间号码上次修改时间（以毫秒为单位）。4.0.0
uristring文件的 URI。4.0.0

ReaddirOptions​

属性类型描述自
pathstring要读取的目录的路径1.0.0
directoryDirectory要从中列出文件的 目录1.0.0

GetUriResult​

属性类型描述自
uristring文件的 URI1.0.0

GetUriOptions​

属性类型描述自
pathstring要获取 URI 的文件的路径1.0.0
directoryDirectory包含该文件的 目录1.0.0

StatResult​

属性类型描述自
类型'file' | 'directory'文件的类型。1.0.0
大小号码文件的大小（以字节为单位）。1.0.0
创建时间号码创建时间（以毫秒为单位）。在 Android 7 及更早版本的设备上不可用。1.0.0
修改时间号码上次修改时间（以毫秒为单位）。1.0.0
uristring文件的 URI1.0.0

StatOptions​

属性类型描述自
pathstring要获取数据的文件的路径1.0.0
directoryDirectory包含该文件的 目录1.0.0

CopyOptions​

属性类型描述自
来自string现有的文件或目录1.0.0
至string目标文件或目录1.0.0
directoryDirectory包含现有文件或目录的 目录1.0.0
toDirectoryDirectory包含目标文件或目录的 目录。如果未提供，将使用“directory”参数作为目标1.0.0

CopyResult​

属性类型描述自
uristring文件被复制到的 URI4.0.0

PermissionStatus​

属性类型
publicStoragePermissionState

DownloadFileResult​

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

DownloadFileOptions​

属性类型描述默认自
pathstring下载的文件应移动到的路径。5.1.0
directoryDirectory要写入文件的目录。如果使用此选项，filePath 可以是相对路径而不是绝对路径。默认情况下是 DATA 目录。5.1.0
进度boolean一个可选的监听器函数，用于接收下载进度事件。如果使用此选项，则应在接收每个块时调度进度事件。块在 Android/iOS 上每 100 毫秒节流一次，以避免减速。5.1.0
recursiveboolean是否创建任何缺少的父目录。false5.1.2

PluginListenerHandle​

属性类型
移除() => Promise<void>

ProgressStatus​

属性类型描述自
URLstring正在下载的文件的 URL。5.1.0
字节号码到目前为止下载的字节数。5.1.0
contentLength号码此文件要下载的总字节数。5.1.0

类型别名​

RenameOptions​

CopyOptions

PermissionState​

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

ProgressListener​

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

(progress: ProgressStatus): void

枚举​

Directory​

成员价值描述自
文件'DOCUMENTS'文档目录。在 iOS 上，它是应用程序的文档目录。使用此目录存储用户生成的内容。在 Android 上，它是公共文档文件夹，因此可以从其他应用程序访问。除非应用程序通过在 AndroidManifest.xml 中的 application 标签中添加 android:requestLegacyExternalStorage="true" 来启用传统外部存储，否则它在 Android 10 上不可访问。在 Android 11 或更高版本上，应用程序只能访问应用程序创建的文件/文件夹。1.0.0
数据'DATA'数据目录。在 iOS 上，它将使用文档目录。在 Android 上，它是包含应用程序文件的目录。卸载应用程序时将删除文件。1.0.0
库'LIBRARY'库目录。在 iOS 上，它将使用库目录。在 Android 上，它是包含应用程序文件的目录。卸载应用程序时将删除文件。1.1.0
缓存'CACHE'缓存目录。在内存不足的情况下可以删除，因此使用此目录写入应用程序特定的文件。你的应用程序可以轻松地重新创建。1.0.0
外部'EXTERNAL'外部目录。在 iOS 上，它将使用文档目录。在 Android 上，它是主要共享/外部存储设备上的目录，应用程序可以在其中放置它拥有的持久文件。这些文件对应用程序是内部的，通常对用户不可见为媒体。卸载应用程序时将删除文件。1.0.0
外部存储'EXTERNAL_STORAGE'外部存储目录。在 iOS 上，它将使用文档目录。在 Android 上，它是主要共享/外部存储目录。除非应用程序通过在 AndroidManifest.xml 中的 application 标签中添加 android:requestLegacyExternalStorage="true" 来启用传统外部存储，否则它在 Android 10 上不可访问。在 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

内容

编辑此页面