qg.getFileSystemManager
基础信息说明
功能概述：获取全局唯一的文件管理器，读写、复制、删除、遍历与统计文件/目录
| 项目 | 说明 |
| 版本要求 | 无 |
| 前提条件 | 具有文件访问权限，路径有效 |
| 使用限制 | 无 |
| 相关教程 | 无 |
参数说明
无
返回值说明
同步方法：调用后立即返回同一个 FileSystemManager 实例。
| 属性名 | 类型 | 说明 |
| fsm | FileSystemManager | 文件管理器对象 |
方法与回调说明
本节包含说明方法用途、参数与字段映射、同步/异步行为、成功/失败回调及返回值形态
access
功能概述：判断文件/目录是否存在
参数说明
| 属性名 | 类型 | 必填 | 说明 |
| path | String | 是 | 要判断是否存在的文件/目录路径 |
| success | Function | 否 | 接口调用成功的回调函数 |
| fail | Function | 否 | 接口调用失败的回调函数，fail({ errMsg }) |
| complete | Function | 否 | 接口调用结束的回调函数 |
回调失败
| 属性名 | 类型 | 说明 |
| errMsg | String | 错误信息（底层原文） |
错误码
| 错误信息 | 说明 |
| no such file or directory | 文件/目录不存在 |
accessSync
功能概述：判断文件/目录是否存在的同步方法
参数说明
| 属性名 | 类型 | 必填 | 说明 |
| tempFilePath | String | 是 | 临时存储文件路径 |
| filePath | String | 否 | 要存储的文件路径 |
| success | Function | 否 | 接口调用成功的回调函数 |
| fail | Function | 否 | 接口调用失败的回调函数 |
| complete | Function | 否 | 接口调用结束的回调函数 |
回调成功
| 属性名 | 类型 | 说明 |
| savedFilePath | String | 存储后的文件路径 |
回调失败
错误码
| 错误信息 | 说明 |
| tempFilePath file not exist | 指定的临时文件不存在 |
| permission denied | 目标文件路径没有写权限 |
| no such file or directory | 上级目录不存在 |
saveFileSync
功能概述：保存临时文件的同步方法
参数说明
| 属性名 | 类型 | 必填 | 说明 |
| tempFilePath | String | 是 | 临时存储文件路径 |
| filePath | String | 是 | 要存储的文件路径 |
copyFile
功能概述：复制文件
参数说明
| 属性名 | 类型 | 必填 | 说明 |
| srcPath | String | 是 | 源文件路径，仅限普通文件 |
| destPath | String | 是 | 目标文件路径 |
| success | Function | 否 | 接口调用成功的回调函数 |
| fail | Function | 否 | 接口调用失败的回调函数，fail({ errMsg }) |
| complete | Function | 否 | 接口调用结束的回调函数 |
回调失败
错误码
| 错误信息 | 说明 |
| no such file or directory | 源文件不存在，或目标文件路径的上层目录不存在 |
| permission denied | 指定目标文件路径没有写权限 |
copyFileSync
功能概述：复制文件的同步方法
参数说明
| 属性名 | 类型 | 必填 | 说明 |
| srcPath | String | 是 | 源文件路径，仅限普通文件 |
| destPath | String | 是 | 目标文件路径 |
getSavedFileList
功能概述：获取本应用保存的文件列表
参数说明
| 属性名 | 类型 | 必填 | 说明 |
| success | Function | 否 | 成功回调 |
| fail | Function | 否 | 失败回调 |
| complete | Function | 否 | 结束回调 |
回调失败
错误码
| 错误信息 | 说明 |
| no such file or directory | 用户数据目录不存在 |
| permission denied | 指定的路径没有读权限 |
removeSavedFile
功能概述：删除本应用保存的本地缓存文件
参数说明
| 属性名 | 类型 | 必填 | 说明 |
| filePath | String | 是 | 需要删除的文件路径 |
| success | Function | 否 | 接口调用成功的回调函数 |
| fail | Function | 否 | 接口调用失败的回调函数，指定目录不存在调用 |
| complete | Function | 否 | 接口调用结束的回调函数 |
回调失败
错误码
| 错误信息 | 说明 |
| file not exist | 指定的路径 |
unlink
功能概述：删除文件
参数说明
| 属性名 | 类型 | 必填 | 说明 |
| filePath | String | 是 | 要删除的文件路径 |
| success | Function | 否 | 接口调用成功的回调函数 |
| fail | Function | 否 | 接口调用失败的回调函数 |
| complete | Function | 否 | 接口调用结束的回调函数 |
回调失败
错误码
| 错误信息 | 说明 |
| permission denied | 指定的路径没有读权限 |
| no such file or directory | 文件不存在 |
| operation not permitted | 传入的 filePath 是一个目录 |
unlinkSync
功能概述：删除文件的同步方法
参数说明
| 属性名 | 类型 | 必填 | 说明 |
| filePath | String | 是 | 要删除的文件路径 |
readdir
功能概述：读取目录列表
参数说明
| 属性名 | 类型 | 必填 | 说明 |
| dirPath | String | 是 | 要读取的目录路径 |
| success | Function | 否 | 成功回调 |
| fail | Function | 否 | 失败回调 |
| complete | Function | 否 | 结束回调 |
回调成功
| 属性名 | 类型 | 说明 |
| files | Array[String] | 指定目录下的文件名数组。 |
回调失败
错误码
| 错误信息 | 说明 |
| no such file or directory | 目录不存在 |
| not a directory | dirPath 不是目录 |
| permission denied | 指定的路径没有读权限 |
readdirSync
功能概述：读取目录列表的同步方法
参数说明
| 属性名 | 类型 | 必填 | 说明 |
| dirPath | String | 是 | 要读取的目录路径 |
返回值
| 属性名 | 类型 | 必填 | 说明 |
| files | Array | 指定目录下的文件名数组 | 要读取的目录路径 |
readFile
功能概述：读取本地文件内容
参数说明
| 属性名 | 类型 | 必填 | 说明 |
| filePath | String | 是 | 要读取的文件路径 |
| encoding | String | 否 | 指定读取编码，默认为 binary |
| success | Function | 否 | 成功回调 ({ data })，文本或二进制 |
| fail | Function | 否 | 失败回调 ({ errMsg }) |
| complete | Function | 否 | 结束回调 |
回调成功
| 属性名 | 类型 | 说明 |
| data | String/ArrayBuffer | 读取到的文本或二进制数据 |
回调失败
错误码
| 错误信息 | 说明 |
| no such file or directory | 上级目录不存在或文件不存在 |
| permission denied | 指定目标文件路径没有读权限 |
readFileSync
功能概述：读取本地文件内容的同步方法
参数说明
| 属性名 | 类型 | 必填 | 说明 |
| filePath | String | 是 | 要读取的文件路径 |
| encoding | String | 否 | 指定读取文件的字符编码，默认为 binary |
返回值
| 属性名 | 类型 | 必填 | 说明 |
| data | String/ArrayBuffer | 读取到的文本或二进制数据 | 要读取的目录路径 |
writeFile
功能概述：写文件，文本通过 text 写入；二进制通过 buffer 写入
| 方法名 | 入参 | 说明 |
| writeFile | filePath(必填), data(必填), encoding(可选, 默认'utf8'), append(可选),success(可选), fail(可选), complete(可选) | 文本通过 text 写入；二进制通过 buffer 写入 |
参数说明
| 属性名 | 类型 | 必填 | 说明 |
| filePath | String | 是 | 要写入的文件路径 |
| data | String/ArrayBuffer | 是 | 要写入的文本或二进制数据 |
| encoding | String | 否 | 指定写入编码，默认 utf8；二进制忽略编码 |
| append | Boolean | 否 | 是否追加写入（默认覆盖） |
| success | Function | 否 | 接口调用成功的回调函数 |
| fail | Function | 否 | 接口调用失败的回调函数 |
| complete | Function | 否 | 接口调用结束的回调函数 |
回调失败
错误码
| 错误信息 | 说明 |
| no such file or directory | 指定的 filePath 文件不存在，或是一个目录 |
| permission denied | 指定目标文件路径没有写权限 |
writeFileSync
功能概述：写文件的同步方法
参数说明
| 属性名 | 类型 | 必填 | 说明 |
| filePath | String | 是 | 要写入的文件路径 |
| data | String/ArrayBuffer | 是 | 要写入的文本或二进制数据 |
| encoding | String | 否 | 指定写入文件的字符编码，默认 utf8 |
| append | Boolean | 否 | 是否追加（默认覆盖） |
appendFile
功能概述：在文件末尾追加内容
参数说明
| 属性名 | 类型 | 必填 | 说明 |
| filePath | String | 是 | 要追加内容的文件路径 |
| data | String/ArrayBuffer | 是 | 要追加的文本或二进制数据 |
| encoding | String | 否 | 指定写入文件的字符编码，当前支持：utf8、binary |
| success | Function | 否 | 接口调用成功的回调函数 |
| fail | Function | 否 | 接口调用失败的回调函数 |
| complete | Function | 否 | 接口调用结束的回调函数 |
回调失败
错误码
| 错误信息 | 说明 |
| no such file or directory | 指定的 filePath 文件不存在，或 filePath 是目录 |
| permission denied | 指定目标文件路径没有写权限 |
appendFileSync
功能概述：在文件末尾追加内容的同步方法
参数说明
| 属性名 | 类型 | 必填 | 说明 |
| filePath | String | 是 | 要追加内容的文件路径 |
| data | String/ArrayBuffer | 是 | 要追加的文本或二进制数据 |
| encoding | String | 否 | 指定写入文件的字符编码，当前支持：utf8、binary |
mkdir
功能概述：创建目录
参数说明
| 属性名 | 类型 | 必填 | 说明 |
| dirPath | String | 是 | 创建的目录路径 |
| success | Function | 否 | 接口调用成功的回调函数 |
| fail | Function | 否 | 接口调用失败的回调函数，fail({ errMsg }) |
| complete | Function | 否 | 接口调用结束的回调函数 |
回调失败
错误码
| 错误信息 | 说明 |
| no such file or directory | 上级目录不存在 |
| permission denied | 指定目标文件路径没有写权限 |
| file already exists | 有同名文件或目录 |
mkdirSync
功能概述：创建目录的同步方法
参数说明
| 属性名 | 类型 | 必填 | 说明 |
| dirPath | String | 是 | 创建的目录路径 |
| recursive | Boolean | 否 | 是否在递归创建该目录的上级目录后再创建该目录。如果对应的上级目录已经存在，则不创建该上级目录。如 dirPath 为 a/b/c/d 且 recursive 为 true，将创建 a 目录，再在 a 目录下创建 b 目录，以此类推直至创建 a/b/c 目录下的 d 目录 |
rmdir
功能概述：删除目录
参数说明
| 属性名 | 类型 | 必填 | 说明 |
| dirPath | String | 是 | 要删除的目录路径 |
| recursive | Boolean | 否 | 是否递归删除该目录及其内容，如果为 true，则删除该目录和该目录下的所有子目录以及文件 |
| success | Function | 否 | 接口调用成功的回调函数 |
| fail | Function | 否 | 接口调用失败的回调函数 |
| complete | Function | 否 | 接口调用结束的回调函数 |
回调失败
错误码
| 错误信息 | 说明 |
| no such file or directory | 目录不存在 |
| directory not empty | 目录不为空 |
| permission denied | 指定的 dirPath 路径没有写权限 |
rmdirSync
功能概述：删除目录的同步方法
参数说明
| 属性名 | 类型 | 必填 | 说明 |
| dirPath | String | 是 | 要删除的目录路径 |
| recursive | Boolean | 否 | 是否递归删除该目录及其内容 |
rename
功能概述：重命名或移动文件
参数说明
| 属性名 | 类型 | 必填 | 说明 |
| oldPath | String | 是 | 源文件路径（普通文件或目录） |
| newPath | String | 是 | 新文件路径 |
| success | Function | 否 | 接口调用成功的回调函数 |
| fail | Function | 否 | 接口调用失败的回调函数 |
| complete | Function | 否 | 接口调用结束的回调函数 |
回调失败
错误码
| 错误信息 | 说明 |
| no such file or directory | 源文件不存在，或目标文件路径的上层目录不存在 |
| permission denied | 没有写权限 |
renameSync
功能概述：重命名或移动文件的同步方法
参数说明
| 属性名 | 类型 | 必填 | 说明 |
| oldPath | String | 是 | 源文件路径（普通文件或目录） |
| newPath | String | 是 | 新文件路径 |
getFileInfo
功能概述：读取临时/缓存文件信息（大小）
参数说明
| 属性名 | 类型 | 必填 | 说明 |
| filePath | String | 是 | 要读取的文件路径 |
| success | Function | 否 | 成功回调 ，以字节为单位，键值类型：Number |
| fail | Function | 否 | 失败回调 |
| complete | Function | 否 | 结束回调 |
回调失败
错误码
| 错误信息 | 说明 |
| file not exist | 指定的路径找不到文件 |
stat
功能概述：获取文件Stats 对象
参数说明
| 属性名 | 类型 | 必填 | 说明 |
| path | String | 是 | 文件/目录路径 |
| success | Function | 否 | 成功回调 |
| fail | Function | 否 | 失败回调 |
| complete | Function | 否 | 结束回调 |
回调成功
| 属性名 | 类型 | 说明 |
| stat | Stats | 一个 Stats 对象 |
回调失败
错误码
| 错误信息 | 说明 |
| permission denied | 指定的路径没有读权限 |
| no such file or directory | 文件或目录不存在 |
statSync
功能概述：获取文件Stats对象的同步方法
参数说明
| 属性名 | 类型 | 必填 | 说明 |
| path | String | 是 | 文件/目录路径 |
| recursive | Boolean | 否 | 是否递归获取目录下文件的统计信息 |
返回值
当 recursive 为 false 时，res.stats 是一个 Stats 对象。当 recursive 为 true 且 path 是一个目录的路径时，res.stats 是一个 Object，key 以 path 为根路径的相对路径，value 是该路径对应的 Stats 对象。
unzip
功能概述：解压 zip 到目标目录
参数说明
| 属性名 | 类型 | 必填 | 说明 |
| zipFilePath | String | 是 | 源文件路径，只可以是 zip 压缩文件 |
| targetPath | String | 是 | 目标目录路径 |
| success | Function | 否 | 成功回调 |
| fail | Function | 否 | 失败回调 |
| complete | Function | 否 | 结束回调 |
回调失败
错误码
| 错误信息 | 说明 |
| permission denied | 指定目标文件路径没有写权限 |
| no such file or directory | 源文件不存在，或目标文件路径的上层目录不存在 |
示例代码
// 获取文件管理器
const fsm = qg.getFileSystemManager()
// 保存临时文件到持久路径
fsm.saveFile({
tempFilePath: '/tmp/audio.mp3',
filePath: '/data/local/audio.mp3',
success(res) {
console.log('saved:', res.savedFilePath)
},
fail(err) {
console.error('read failed:', err)
}
})
注意事项
- 选项中的路径通过 uri 传递给底层模块，请确保路径可访问与权限允许。
- stat（递归）返回以 uri 为键的映射，值为 Stats；注意遍历处理。
- 解压仅支持 zip 文件，目标路径需有效且可写。
