capacitor-advanced-file-manager

v2.1.2

Published

10 days ago

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

0High
0Medium
0Low

q1600822305

capacitor plugin native file-manager file-system android ios web file-operations directory mt-manager file-browser cross-platform

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 处理大文件
});

📖 详细使用指南：

API

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

capacitor-advanced-file-manager

🏗️ 架构特性

📦 可用模块

Install

🚀 快速开始

基础使用

模块化使用

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

PermissionResult

SystemFilePickerResult

SelectedFileInfo

SystemFilePickerOptions

ListDirectoryResult

FileInfo

ListDirectoryOptions

CreateDirectoryOptions

FileOperationOptions

CreateFileOptions

ReadFileResult

ReadFileOptions

WriteFileOptions

MoveFileOptions

CopyFileOptions

RenameFileOptions

SearchFilesResult

SearchFilesOptions

SearchContentResult

ContentSearchFileResult

ContentMatch

SearchContentOptions

ReadFileRangeResult

ReadFileRangeOptions

InsertContentOptions

ReplaceInFileResult

ReplaceInFileOptions

ApplyDiffResult

ApplyDiffOptions

GetFileHashResult

GetFileHashOptions

GetLineCountResult