快速入门

安装

你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo skills 添加到你的 AI 工具中：

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

然后使用以下 prompt：

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-file` plugin in my project.

如果你更想手动设置，请运行以下命令安装插件，并按照下方各平台的说明操作：

npm install @capgo/capacitor-file
npx cap sync

导入

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

快速入门

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

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

示例：resolveLocalFileSystemURL

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

const result = await CapacitorFile.resolveLocalFileSystemURL({
  url: 'file:///data/user/0/com.example.app/files/report.pdf',
});
console.log(result);

示例：getFile

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

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

常见坑点

• 权限: 调用 checkPermissions() 然后 requestPermissions() 在需要时。
• 监听器: 在页面卸载时移除句柄。
• 唯一可信来源：信任 src/definitions.ts 在 GitHub 仓库中。

API 概览

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);

writeFile

将数据写入文件。

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

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

appendFile

向文件追加数据。

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

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

deleteFile

删除文件。

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

await CapacitorFile.deleteFile({ path: 'path/to/file' });

mkdir

创建目录。

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

await CapacitorFile.mkdir({ path: 'path/to/file' });

rmdir

删除目录。

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

await CapacitorFile.rmdir({ path: 'path/to/file' });

readdir

读取目录内容。

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

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

stat

获取文件或目录的元数据。

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

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

getMetadata

获取文件或目录的元数据。 stat() 的别名。

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

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

rename

重命名或移动文件或目录。

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

await CapacitorFile.rename({
  from: 'from',
  to: 'to',
});

move

移动文件或目录。 rename() 的别名。

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

await CapacitorFile.move({
  from: 'from',
  to: 'to',
});

copy

复制文件或目录。

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

const result = await CapacitorFile.copy({
  from: 'from',
  to: 'to',
});
console.log(result);

exists

检查文件或目录是否存在。

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

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

getUri

获取文件的 URI。

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

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

truncate

将文件截断至指定大小。

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

await CapacitorFile.truncate({ path: 'path/to/file' });

getDirectories

获取所有已知的文件系统目录。

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

const result = await CapacitorFile.getDirectories();
console.log(result);

getFreeDiskSpace

获取以字节为单位的剩余磁盘空间。

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

const result = await CapacitorFile.getFreeDiskSpace();
console.log(result);

checkPermissions

检查当前文件操作的权限状态。 在 Android 上，这会检查外部存储权限。 在 iOS 和 Web 上，由于无需特殊权限，将始终返回 ‘granted’。

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

const result = await CapacitorFile.checkPermissions();
console.log(result);

requestPermissions

请求文件操作权限。 在 Android 上，这将请求访问应用私有目录以外文件所需的外部存储权限。 在 iOS 和 Web 上，由于不需要特殊权限，将始终返回 ‘granted’。

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

const result = await CapacitorFile.requestPermissions();
console.log(result);

类型参考

RequestFileSystemOptions

请求文件系统的配置选项。

export interface RequestFileSystemOptions {
  /** The type of file system to request */
  type: FileSystemType;
  /** Requested size in bytes (may not be enforced on all platforms) */
  size?: number;
}

FileSystem

表示一个文件系统。

export interface FileSystem {
  /** The name of the file system */
  name: string;
  /** The root directory of the file system */
  root: DirectoryEntry;
}

ResolveURLOptions

将 URL 解析为条目的选项。

export interface ResolveURLOptions {
  /** The URL to resolve (file:// or cdvfile://) */
  url: string;
}

Entry

表示文件或目录条目。

export interface Entry {
  /** True if this is a file */
  isFile: boolean;
  /** True if this is a directory */
  isDirectory: boolean;
  /** The name of the file or directory */
  name: string;
  /** The full path relative to the filesystem root */
  fullPath: string;
  /** The native file:// URI */
  nativeURL: string;
}

GetFileOptions

获取文件的相关选项。

export interface GetFileOptions {
  /** Path to the file */
  path: string;
  /** Base directory */
  directory?: Directory;
  /** Options for creating the file */
  options?: GetOptions;
}

FileEntry

表示文件条目。

export interface FileEntry extends Entry {
  isFile: true;
  isDirectory: false;
}

GetDirectoryOptions

获取目录的选项。

export interface GetDirectoryOptions {
  /** Path to the directory */
  path: string;
  /** Base directory */
  directory?: Directory;
  /** Options for creating the directory */
  options?: GetOptions;
}

DirectoryEntry

表示一个目录条目。

export interface DirectoryEntry extends Entry {
  isFile: false;
  isDirectory: true;
}

ReadFileOptions

读取文件的选项。

export interface ReadFileOptions {
  /** Path to the file */
  path: string;
  /** Base directory */
  directory?: Directory;
  /** Encoding for text files (omit for binary/base64) */
  encoding?: Encoding;
  /** Byte offset to start reading from (default: 0) */
  offset?: number;
  /** Number of bytes to read (default: read to end of file) */
  length?: number;
}

ReadFileResult

读取文件的结果。

export interface ReadFileResult {
  /** File contents as string (text) or base64 (binary) */
  data: string;
}

WriteFileOptions

写入文件的选项。

export interface WriteFileOptions {
  /** Path to the file */
  path: string;
  /** Base directory */
  directory?: Directory;
  /** Data to write (string for text, base64 for binary) */
  data: string;
  /** Encoding for text files */
  encoding?: Encoding;
  /** If true, append to existing file instead of overwriting */
  append?: boolean;
  /** Create intermediate directories if they don't exist */
  recursive?: boolean;
  /** Byte position to start writing at (for random access writes). If not specified, writes from beginning or appends based on 'append' flag */
  position?: number;
}

WriteFileResult

文件写入结果。

export interface WriteFileResult {
  /** The URI of the written file */
  uri: string;
}

单一事实来源

本页面由插件的 src/definitions.ts生成。当上游的公共 API 发生变化时，请重新运行 sync。

从入门指南继续

如果你正在使用 快速入门 要规划存储和文件处理，请将其与 使用 @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-file 实现细节请参阅 @capgo/capacitor-file，以及 @capgo/capacitor-uploader 了解 @capgo/capacitor-uploader. 的实现细节