capacitor-advanced-file-manager

Advanced file manager plugin for Capacitor with comprehensive file system operations including browse, create, edit, delete, move, copy, and search files and directories.

🏗️ 架构特性

• 核心功能：完整的文件系统操作 API
• 模块化扩展：按需导入高级功能模块
• 跨平台支持：Android、iOS、Web 统一 API
• 类型安全：完整的 TypeScript 类型定义

📦 可用模块

| 模块 | 功能 | 状态 | |------|------|------| | 核心 | 基础文件操作 | ✅ 已完成 | | /search | 高级文件搜索 | ✅ 已完成 | | /batch | 批量文件操作 | ✅ 已完成 | | /utils | 文件工具集 | 🚧 开发中 | | /web-enhanced | Web端增强功能 | ✅ 已完成 | | /preview | 文件预览 | 📋 计划中 | | /share | 文件分享 | 📋 计划中 |

Install

npm install capacitor-advanced-file-manager
npx cap sync

🚀 快速开始

基础使用

import { AdvancedFileManager } from 'capacitor-advanced-file-manager';

// 列出目录内容
const files = await AdvancedFileManager.listDirectory({
  path: '/storage/emulated/0',
  showHidden: false
});

// 创建文件
await AdvancedFileManager.createFile({
  path: '/storage/emulated/0/test.txt',
  content: 'Hello World!'
});

模块化使用

// 按需导入高级功能模块
import { FileSearch } from 'capacitor-advanced-file-manager/search';
import { BatchOperations } from 'capacitor-advanced-file-manager/batch';
import { WebEnhancedFileManager } from 'capacitor-advanced-file-manager/web-enhanced';

// 文件搜索
const results = await FileSearch.search({
  directory: '/storage/emulated/0',
  query: '*.jpg',
  recursive: true
});

// 批量操作
await BatchOperations.batchDelete([
  '/path/to/file1.txt',
  '/path/to/file2.txt'
]);

// Web端增强功能 - 突破浏览器文件限制
await WebEnhancedFileManager.initializeWebFS({
  useOPFS: true,              // 使用 Origin Private File System
  enableIndexedDBCache: true, // 启用 IndexedDB 缓存
  useWebWorkers: true         // 使用 Web Workers 处理大文件
});

📖 详细使用指南：

• 模块化使用指南
• Web端突破限制完全指南 🌐

API

• requestPermissions()
• checkPermissions()
• openSystemFilePicker(...)
• openSystemFileManager(...)
• openFileWithSystemApp(...)
• listDirectory(...)
• createDirectory(...)
• deleteDirectory(...)
• createFile(...)
• readFile(...)
• writeFile(...)
• deleteFile(...)
• moveFile(...)
• copyFile(...)
• renameFile(...)
• getFileInfo(...)
• exists(...)
• searchFiles(...)
• searchContent(...)
• readFileRange(...)
• insertContent(...)
• replaceInFile(...)
• applyDiff(...)
• getFileHash(...)
• getLineCount(...)
• echo(...)
• Interfaces

requestPermissions()

requestPermissions() => Promise<PermissionResult>

Returns: Promise<PermissionResult>

checkPermissions()

checkPermissions() => Promise<PermissionResult>

Returns: Promise<PermissionResult>

openSystemFilePicker(...)

openSystemFilePicker(options: SystemFilePickerOptions) => Promise<SystemFilePickerResult>

| Param | Type | | ------------- | --------------------------------------------------------------------------- | | options | SystemFilePickerOptions |

Returns: Promise<SystemFilePickerResult>

openSystemFileManager(...)

openSystemFileManager(path?: string | undefined) => Promise<void>

| Param | Type | | ---------- | ------------------- | | path | string |

openFileWithSystemApp(...)

openFileWithSystemApp(filePath: string, mimeType?: string | undefined) => Promise<void>

| Param | Type | | -------------- | ------------------- | | filePath | string | | mimeType | string |

listDirectory(...)

listDirectory(options: ListDirectoryOptions) => Promise<ListDirectoryResult>

| Param | Type | | ------------- | --------------------------------------------------------------------- | | options | ListDirectoryOptions |

Returns: Promise<ListDirectoryResult>

createDirectory(...)

createDirectory(options: CreateDirectoryOptions) => Promise<void>

| Param | Type | | ------------- | ------------------------------------------------------------------------- | | options | CreateDirectoryOptions |

deleteDirectory(...)

deleteDirectory(options: FileOperationOptions) => Promise<void>

| Param | Type | | ------------- | --------------------------------------------------------------------- | | options | FileOperationOptions |

createFile(...)

createFile(options: CreateFileOptions) => Promise<void>

| Param | Type | | ------------- | --------------------------------------------------------------- | | options | CreateFileOptions |

readFile(...)

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

| Param | Type | | ------------- | ----------------------------------------------------------- | | options | ReadFileOptions |

Returns: Promise<ReadFileResult>

writeFile(...)

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

| Param | Type | | ------------- | ------------------------------------------------------------- | | options | WriteFileOptions |

deleteFile(...)

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

| Param | Type | | ------------- | --------------------------------------------------------------------- | | options | FileOperationOptions |

moveFile(...)

moveFile(options: MoveFileOptions) => Promise<void>

| Param | Type | | ------------- | ----------------------------------------------------------- | | options | MoveFileOptions |

copyFile(...)

copyFile(options: CopyFileOptions) => Promise<void>

| Param | Type | | ------------- | ----------------------------------------------------------- | | options | CopyFileOptions |

renameFile(...)

renameFile(options: RenameFileOptions) => Promise<void>

| Param | Type | | ------------- | --------------------------------------------------------------- | | options | RenameFileOptions |

getFileInfo(...)

getFileInfo(options: FileOperationOptions) => Promise<FileInfo>

| Param | Type | | ------------- | --------------------------------------------------------------------- | | options | FileOperationOptions |

Returns: Promise<FileInfo>

exists(...)

exists(options: FileOperationOptions) => Promise<{ exists: boolean; }>

| Param | Type | | ------------- | --------------------------------------------------------------------- | | options | FileOperationOptions |

Returns: Promise<{ exists: boolean; }>

searchFiles(...)

searchFiles(options: SearchFilesOptions) => Promise<SearchFilesResult>

| Param | Type | | ------------- | ----------------------------------------------------------------- | | options | SearchFilesOptions |

Returns: Promise<SearchFilesResult>

searchContent(...)

searchContent(options: SearchContentOptions) => Promise<SearchContentResult>

原生层内容搜索（避免 OOM） 在原生层执行搜索，只返回匹配结果，不返回完整文件内容

| Param | Type | | ------------- | --------------------------------------------------------------------- | | options | SearchContentOptions |

Returns: Promise<SearchContentResult>

readFileRange(...)

readFileRange(options: ReadFileRangeOptions) => Promise<ReadFileRangeResult>

读取文件指定行范围

| Param | Type | | ------------- | --------------------------------------------------------------------- | | options | ReadFileRangeOptions |

Returns: Promise<ReadFileRangeResult>

insertContent(...)

insertContent(options: InsertContentOptions) => Promise<void>

在指定行插入内容

| Param | Type | | ------------- | --------------------------------------------------------------------- | | options | InsertContentOptions |

replaceInFile(...)

replaceInFile(options: ReplaceInFileOptions) => Promise<ReplaceInFileResult>

查找并替换文件内容

| Param | Type | | ------------- | --------------------------------------------------------------------- | | options | ReplaceInFileOptions |

Returns: Promise<ReplaceInFileResult>

applyDiff(...)

applyDiff(options: ApplyDiffOptions) => Promise<ApplyDiffResult>

应用 diff 补丁

| Param | Type | | ------------- | ------------------------------------------------------------- | | options | ApplyDiffOptions |

Returns: Promise<ApplyDiffResult>

getFileHash(...)

getFileHash(options: GetFileHashOptions) => Promise<GetFileHashResult>

获取文件哈希值

| Param | Type | | ------------- | ----------------------------------------------------------------- | | options | GetFileHashOptions |

Returns: Promise<GetFileHashResult>

getLineCount(...)

getLineCount(options: FileOperationOptions) => Promise<GetLineCountResult>

获取文件行数

| Param | Type | | ------------- | --------------------------------------------------------------------- | | options | FileOperationOptions |

Returns: Promise<GetLineCountResult>

echo(...)

echo(options: { value: string; }) => Promise<{ value: string; }>

| Param | Type | | ------------- | ------------------------------- | | options | { value: string; } |

Returns: Promise<{ value: string; }>

Interfaces

PermissionResult

| Prop | Type | | ------------- | -------------------- | | granted | boolean | | message | string |

SystemFilePickerResult

| Prop | Type | Description | | ----------------- | ------------------------------- | ----------- | | files | SelectedFileInfo[] | 选择的文件信息列表 | | directories | SelectedFileInfo[] | 选择的目录信息列表 | | cancelled | boolean | 是否被用户取消 |

SelectedFileInfo

| Prop | Type | Description | | -------------- | ---------------------------------- | ----------------- | | name | string | 文件名 | | path | string | 文件路径（可能是真实路径或URI） | | uri | string | 原始URI（移动端） | | size | number | 文件大小 | | type | 'file' | 'directory' | 文件类型 | | mimeType | string | MIME类型 | | mtime | number | 修改时间 | | ctime | number | 创建时间 |

SystemFilePickerOptions

| Prop | Type | Description | | -------------------- | -------------------------------------------- | ----------- | | type | 'file' | 'directory' | 'both' | 选择类型 | | multiple | boolean | 是否允许多选 | | accept | string[] | 文件类型过滤 | | startDirectory | string | 起始目录 | | title | string | 标题 |

ListDirectoryResult

| Prop | Type | | ---------------- | ----------------------- | | files | FileInfo[] | | totalCount | number |

FileInfo

| Prop | Type | | ----------------- | ---------------------------------- | | name | string | | path | string | | size | number | | type | 'file' | 'directory' | | mtime | number | | ctime | number | | permissions | string | | isHidden | boolean |

ListDirectoryOptions

| Prop | Type | | ---------------- | -------------------------------------------------- | | path | string | | showHidden | boolean | | sortBy | 'name' | 'size' | 'mtime' | 'type' | | sortOrder | 'asc' | 'desc' |

CreateDirectoryOptions

| Prop | Type | | --------------- | -------------------- | | path | string | | recursive | boolean |

FileOperationOptions

| Prop | Type | | ---------- | ------------------- | | path | string |

CreateFileOptions

| Prop | Type | | -------------- | ------------------------------- | | path | string | | content | string | | encoding | 'utf8' | 'base64' |

ReadFileResult

| Prop | Type | | -------------- | ------------------- | | content | string | | encoding | string |

ReadFileOptions

| Prop | Type | | -------------- | ------------------------------- | | path | string | | encoding | 'utf8' | 'base64' |

WriteFileOptions

| Prop | Type | | -------------- | ------------------------------- | | path | string | | content | string | | encoding | 'utf8' | 'base64' | | append | boolean |

MoveFileOptions

| Prop | Type | | --------------------- | ------------------- | | sourcePath | string | | destinationPath | string |

CopyFileOptions

| Prop | Type | | --------------------- | -------------------- | | sourcePath | string | | destinationPath | string | | overwrite | boolean |

RenameFileOptions

| Prop | Type | | ------------- | ------------------- | | path | string | | newName | string |

SearchFilesResult

| Prop | Type | | ---------------- | ----------------------- | | files | FileInfo[] | | totalFound | number |

SearchFilesOptions

| Prop | Type | | ---------------- | ------------------------------------------ | | directory | string | | query | string | | searchType | 'name' | 'content' | 'both' | | fileTypes | string[] | | maxResults | number | | recursive | boolean |

SearchContentResult

内容搜索结果

| Prop | Type | Description | | ------------------ | -------------------------------------- | ----------------- | | results | ContentSearchFileResult[] | 搜索结果列表 | | totalFiles | number | 总匹配文件数 | | totalMatches | number | 总匹配数 | | duration | number | 搜索耗时（毫秒） | | skippedFiles | number | 被跳过的文件数（因文件过大等原因） |

ContentSearchFileResult

单个文件的内容搜索结果

| Prop | Type | Description | | --------------- | ---------------------------------------------- | ----------- | | path | string | 文件路径 | | name | string | 文件名 | | matchType | 'content' | 'both' | 'filename' | 匹配类型 | | matches | ContentMatch[] | 匹配列表 | | score | number | 相关性评分 |

ContentMatch

内容搜索匹配项

| Prop | Type | Description | | ----------------- | ------------------- | ------------------- | | lineNumber | number | 匹配的行号 (1-based) | | lineContent | string | 匹配的行内容 | | context | string | 匹配的上下文（带高亮标记位置） | | matchStart | number | 匹配开始位置（在 context 中） | | matchEnd | number | 匹配结束位置（在 context 中） |

SearchContentOptions

内容搜索选项

| Prop | Type | Description | | ----------------------- | --------------------- | -------------------------- | | directory | string | 搜索目录 | | keyword | string | 搜索关键词 | | caseSensitive | boolean | 是否区分大小写 | | fileExtensions | string[] | 文件扩展名过滤（如 ['.md', '.txt']） | | maxFiles | number | 最大搜索文件数 | | maxFileSize | number | 最大文件大小（字节），超过的文件将被跳过 | | maxMatchesPerFile | number | 每个文件最大匹配数 | | contextLength | number | 上下文长度（匹配前后的字符数） | | maxDepth | number | 最大递归深度 | | recursive | boolean | 是否递归搜索子目录 |

ReadFileRangeResult

| Prop | Type | Description | | ---------------- | ------------------- | ------------ | | content | string | 读取到的内容 | | totalLines | number | 文件总行数 | | startLine | number | 实际读取的起始行 | | endLine | number | 实际读取的结束行 | | rangeHash | string | 内容哈希（用于冲突检测） |

ReadFileRangeOptions

| Prop | Type | Description | | --------------- | ------------------------------- | ------------------ | | path | string | | | startLine | number | 起始行号 (1-based) | | endLine | number | 结束行号 (1-based, 包含) | | encoding | 'utf8' | 'base64' | 编码方式 |

InsertContentOptions

| Prop | Type | Description | | ------------- | ------------------- | ---------------------------- | | path | string | | | line | number | 插入位置的行号 (1-based)，内容将插入到该行之前 | | content | string | 要插入的内容 |

ReplaceInFileResult

| Prop | Type | Description | | ------------------ | -------------------- | ----------- | | replacements | number | 替换的次数 | | modified | boolean | 是否有修改 |

ReplaceInFileOptions

| Prop | Type | Description | | ------------------- | -------------------- | ------------- | | path | string | | | search | string | 要查找的字符串或正则表达式 | | replace | string | 替换为的内容 | | isRegex | boolean | 是否使用正则表达式 | | replaceAll | boolean | 是否替换所有匹配项 | | caseSensitive | boolean | 是否区分大小写 |

ApplyDiffResult

| Prop | Type | Description | | ------------------ | -------------------- | --------------- | | success | boolean | 是否成功应用 | | linesChanged | number | 修改的行数 | | linesAdded | number | 添加的行数 | | linesDeleted | number | 删除的行数 | | backupPath | string | 备份文件路径（如果创建了备份） |

ApplyDiffOptions

| Prop | Type | Description | | ------------------ | -------------------- | -------------------- | | path | string | | | diff | string | Unified diff 格式的补丁内容 | | createBackup | boolean | 是否创建备份 |

GetFileHashResult

| Prop | Type | Description | | --------------- | ------------------- | ----------- | | hash | string | 文件哈希值 | | algorithm | string | 使用的算法 |

GetFileHashOptions

| Prop | Type | Description | | --------------- | ------------------------------ | ----------- | | path | string | | | algorithm | 'md5' | 'sha256' | 哈希算法 |

GetLineCountResult

| Prop | Type | Description | | ----------- | ------------------- | ----------- | | lines | number | 文件行数 |