开始

安装

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

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

然后使用以下提示：

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

如果您更喜欢手动设置，请通过运行以下命令安装插件并按照以下平台特定的说明进行操作：

bun add @capgo/capacitor-file
bunx cap sync

导入

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

API概述

requestFileSystem

请求一个文件系统。

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

await CapacitorFile.requestFileSystem({} as RequestFileSystemOptions);

resolveLocalFileSystemURL

将一个文件 URL 解析为一个入口。

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

await CapacitorFile.resolveLocalFileSystemURL({} as ResolveURLOptions);

getFile

获取一个文件入口。

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

await CapacitorFile.getFile({} as GetFileOptions);

getDirectory

获取一个目录入口。

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

await CapacitorFile.getDirectory({} as GetDirectoryOptions);

readFile

读取文件为文本或base64。

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

await CapacitorFile.readFile({} as ReadFileOptions);

readAsDataURL

读取文件为数据URL（base64加 MIME类型前缀）。

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

await CapacitorFile.readAsDataURL({} as ReadFileOptions);

writeFile

将数据写入文件。

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

await CapacitorFile.writeFile({} as WriteFileOptions);

appendFile

追加数据到文件。

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

await CapacitorFile.appendFile({} as WriteFileOptions);

deleteFile

删除文件。

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

await CapacitorFile.deleteFile({} as DeleteFileOptions);

mkdir

创建目录。

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

await CapacitorFile.mkdir({} as MkdirOptions);

rmdir

删除目录。

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

await CapacitorFile.rmdir({} as DeleteDirectoryOptions);

readdir

读取目录内容。

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

await CapacitorFile.readdir({} as ReaddirOptions);

stat

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

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

await CapacitorFile.stat({} as StatOptions);

getMetadata

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

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

await CapacitorFile.getMetadata({} as StatOptions);

rename

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

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

await CapacitorFile.rename({} as RenameOptions);

move

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

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

await CapacitorFile.move({} as RenameOptions);

copy

复制文件或目录。

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

await CapacitorFile.copy({} as CopyOptions);

exists

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

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

await CapacitorFile.exists({} as ExistsOptions);

getUri

获取文件的 URI。

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

await CapacitorFile.getUri({} as GetUriOptions);

truncate

将文件截断到指定大小。

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

await CapacitorFile.truncate({} as TruncateOptions);

getDirectories

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

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

await CapacitorFile.getDirectories();

getFreeDiskSpace

获取磁盘可用空间（以字节为单位）。

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

await CapacitorFile.getFreeDiskSpace();

checkPermissions

检查文件操作的当前权限状态。 在 Android 上，这检查外部存储权限。 在 iOS 和 web 上，这始终返回 ‘已授权’，因为不需要特殊权限。

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

await CapacitorFile.checkPermissions();

requestPermissions

请求文件操作的权限。 在 Android 上，这请求外部存储权限，以便访问应用私有目录外的文件。 在 iOS 和 web 上，这始终返回 ‘已授权’，因为不需要特殊权限。

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

await CapacitorFile.requestPermissions();

类型参考

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 上游发生变化时，请重新同步。

从 Getting Started 开始

如果您正在使用 Getting Started 来规划存储和文件处理，连接它到 使用 @capgo/capacitor-file 为 Using @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 的实现细节