Advanced file manager plugin for Capacitor with comprehensive file system operations including browse, create, edit, delete, move, copy, and search files and directories.
npm install capacitor-advanced-file-manager/search | 高级文件搜索 | ✅ 已完成 |
/batch | 批量文件操作 | ✅ 已完成 |
/utils | 文件工具集 | 🚧 开发中 |
/web-enhanced | Web端增强功能 | ✅ 已完成 |
/preview | 文件预览 | 📋 计划中 |
/share | 文件分享 | 📋 计划中 |
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 | 文件行数 |