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

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

🚀 快速开始

$3

`typescript
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!'
});
`

$3

`typescript
// 按需导入高级功能模块
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






$3

`typescript
requestPermissions() => Promise
`

Returns: Promise<PermissionResult>

--------------------




$3

`typescript
checkPermissions() => Promise
`

Returns: Promise<PermissionResult>

--------------------




$3

`typescript
openSystemFilePicker(options: SystemFilePickerOptions) => Promise
`

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

Returns: Promise<SystemFilePickerResult>

--------------------




$3

`typescript
openSystemFileManager(path?: string | undefined) => Promise
`

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

--------------------




$3

`typescript
openFileWithSystemApp(filePath: string, mimeType?: string | undefined) => Promise
`

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

--------------------




$3

`typescript
listDirectory(options: ListDirectoryOptions) => Promise
`

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

Returns: Promise<ListDirectoryResult>

--------------------




$3

`typescript
createDirectory(options: CreateDirectoryOptions) => Promise
`

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

--------------------




$3

`typescript
deleteDirectory(options: FileOperationOptions) => Promise
`

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

--------------------




$3

`typescript
createFile(options: CreateFileOptions) => Promise
`

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

--------------------




$3

`typescript
readFile(options: ReadFileOptions) => Promise
`

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

Returns: Promise<ReadFileResult>

--------------------




$3

`typescript
writeFile(options: WriteFileOptions) => Promise
`

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

--------------------




$3

`typescript
deleteFile(options: FileOperationOptions) => Promise
`

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

--------------------




$3

`typescript
moveFile(options: MoveFileOptions) => Promise
`

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

--------------------




$3

`typescript
copyFile(options: CopyFileOptions) => Promise
`

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

--------------------




$3

`typescript
renameFile(options: RenameFileOptions) => Promise
`

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

--------------------




$3

`typescript
getFileInfo(options: FileOperationOptions) => Promise
`

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

Returns: Promise<FileInfo>

--------------------




$3

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

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

Returns: Promise<{ exists: boolean; }>

--------------------




$3

`typescript
searchFiles(options: SearchFilesOptions) => Promise
`

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

Returns: Promise<SearchFilesResult>

--------------------




$3

`typescript
searchContent(options: SearchContentOptions) => Promise
`

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

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

Returns: Promise<SearchContentResult>

--------------------




$3

`typescript
readFileRange(options: ReadFileRangeOptions) => Promise
`

读取文件指定行范围

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

Returns: Promise<ReadFileRangeResult>

--------------------




$3

`typescript
insertContent(options: InsertContentOptions) => Promise
`

在指定行插入内容

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

--------------------




$3

`typescript
replaceInFile(options: ReplaceInFileOptions) => Promise
`

查找并替换文件内容

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

Returns: Promise<ReplaceInFileResult>

--------------------




$3

`typescript
applyDiff(options: ApplyDiffOptions) => Promise
`

应用 diff 补丁

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

Returns: Promise<ApplyDiffResult>

--------------------




$3

`typescript
getFileHash(options: GetFileHashOptions) => Promise
`

获取文件哈希值

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

Returns: Promise<GetFileHashResult>

--------------------




$3

`typescript
getLineCount(options: FileOperationOptions) => Promise
`

获取文件行数

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

Returns: Promise<GetLineCountResult>

--------------------




$3

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

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

Returns: Promise<{ value: string; }>

--------------------




$3


#### 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 | 文件行数 |