跳转至正文
@capgo/capacitor-file 文件与存储 开源

文件 Capacitor 插件

功能完备的文件系统插件,用于读写及管理文件与目录

安装

bun add @capgo/capacitor-file bunx cap sync
npm、pnpm 或 yarn
  • npm install @capgo/capacitor-file
  • pnpm add @capgo/capacitor-file
  • yarn add @capgo/capacitor-file

指南

如何在 Capacitor 中使用 File

使用 @capgo/capacitor-file

Capacitor File 插件提供与 Cordova File 插件类似的文件系统操作。

安装

bun add @capgo/capacitor-file
bunx cap sync

bunx cap sync 将插件的原生 code 复制到你的原生项目中。每次升级插件后都要重新运行。

导入

import { CapacitorFile } from '@capgo/capacitor-file';

API 概览

方法 描述
requestFileSystem 请求文件系统。
resolveLocalFileSystemURL 将文件 URL 解析为条目。
getFile 获取文件条目。
getDirectory 获取目录项。
readFile 以文本或 base64 格式读取文件。
readAsDataURL 以 data URL 格式读取文件(带 MIME 类型前缀的 base64)。
writeFile 将数据写入文件。
appendFile 向文件追加数据。
deleteFile 删除文件。
mkdir 创建目录。
rmdir 删除目录。
readdir 读取目录内容。
stat 获取文件或目录的元数据。
getMetadata 获取文件或目录的元数据。stat() 的别名。
rename 重命名或移动文件或目录。
move 移动文件或目录。rename() 的别名。
copy 复制文件或目录。
exists 检查文件或目录是否存在。
getUri 获取文件的 URI。
truncate 将文件截断到指定大小。
getDirectories 获取所有已知的文件系统目录。
getFreeDiskSpace 获取以字节为单位的可用磁盘空间。
checkPermissions 检查文件操作的当前权限状态。在 Android 上,这会检查外部存储权限。在 iOS 和 Web 上,由于无需特殊权限,始终返回 'granted'。
requestPermissions 请求文件操作的权限。在 Android 上,这会请求访问应用私有目录之外文件所需的外部存储权限。在 iOS 和 Web 上,由于无需特殊权限,始终返回 'granted'。

示例

requestFileSystem()

请求文件系统。

import { CapacitorFile, FileSystemType } from '@capgo/capacitor-file';

const result = await CapacitorFile.requestFileSystem({ type: FileSystemType.TEMPORARY });
console.log(result);

resolveLocalFileSystemURL()

将文件 URL 解析为条目。

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.resolveLocalFileSystemURL({ url: 'https://example.com' });
console.log(result);

getFile()

获取文件条目。

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.getFile({ path: 'path/to/file' });
console.log(result);

getDirectory()

获取目录项。

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.getDirectory({ path: 'path/to/file' });
console.log(result);

readFile()

以文本或 base64 格式读取文件。

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.readFile({ path: 'path/to/file' });
console.log(result);

readAsDataURL()

以 data URL 格式读取文件(带 MIME 类型前缀的 base64)。

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.readAsDataURL({ path: 'path/to/file' });
console.log(result);

上表列出了 24 个核心方法。监听器、版本辅助函数以及每个方法的完整契约,详见 GitHub 仓库.

监听事件

addListener 会返回一个句柄。调用 handle.remove() 在屏幕卸载时,或者调用 CapacitorFile.removeAllListeners() 以清除所有监听器。

完整参考文档

继续了解如何使用 @capgo/capacitor-file

如果你正在使用 使用 @capgo/capacitor-file 要规划存储和文件处理,请将其与 @capgo/capacitor-file 关于 @capgo/capacitor-file 中的实现细节, 快速入门 有关“入门指南”中的实现细节, @capgo/capacitor-data-storage-sqlite 关于 @capgo/capacitor-data-storage-sqlite 中的实现细节, 使用 @capgo/capacitor-data-storage-sqlite 关于使用 @capgo/capacitor-data-storage-sqlite 的原生能力,以及 @capgo/capacitor-uploader 了解 @capgo/capacitor-uploader. 的实现细节

常见问题

File 插件常见问题

如何在 Capacitor 应用中安装 File 插件?

运行 "bun add @capgo/capacitor-file"(或 "npm install @capgo/capacitor-file"),然后运行 "bunx cap sync",让 iOS 和 Android 项目获取到原生 code。再在应用 code 中从 "@capgo/capacitor-file" 导入。

@capgo/capacitor-file 支持 React、Vue 和 Angular 吗?

支持。File 是一个 Capacitor 包,因此可与任何运行在 Capacitor 中的 Web 框架配合使用,包括 Ionic、React、Vue、Angular、Svelte 和纯 JavaScript。

@capgo/capacitor-file 支持哪个 Capacitor 版本?

Capgo 插件遵循 Capacitor 的主版本号:请使用与 Capacitor 主版本号一致的插件主版本(例如插件 v8 对应 Capacitor 8)。GitHub README 中的兼容性表列出了仍在维护的版本。

@capgo/capacitor-file 是免费开源的吗?

是的。code 的源码已在 GitHub 公开,地址为 https://github.com/Cap-go/capacitor-file/,该包也可从 npm 免费安装。欢迎提交 Bug 报告和 Pull Request。

使用 File 的 code 可以在不经过 App Store 审核的情况下更新吗?

安装或升级插件会改动原生 code,因此需要重新做一次商店构建。之后,调用该插件的 JavaScript、HTML 和 CSS 改动就能通过 Capgo live updates 立即发布。

无需等待应用审核,即可发布 File 更新

只要插件已包含在你的商店版本中,Capgo live updates 就能在几分钟内把 JavaScript、HTML 和 CSS 的改动推送给用户。

开始使用 Capgo