For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt, and this page is available as Markdown at /apps-plugin/docs/js-api/file-system/getFileSystemManager.md.

getFileSystemManager

获取文件系统管理器。

扫码预览

扫码预览 getFileSystemManager

支持版本

前端库版本不低于 0.0.31。

支持平台

平台支持情况
Android支持
iOS支持
PC不支持
HarmonyOS不支持

支持场景

场景支持情况
页面支持
卡片不支持

接入准备

前置条件

  • 无额外前置条件,直接调用 getFileSystemManager 获取管理器实例后再调用其方法

使用说明

  • readFile、readFileSync 省略 encoding 时默认返回 Base64 字符串,writeFile、appendFile 省略 encoding 时默认按 UTF-8 写入;需要明确编码时请显式传入 encoding。

调用方式

同步 API

getFileSystemManager(): FileSystemManager

入参

无。

调用示例

import { getFileSystemManager } from '@doubao-dev/framework/api';

const fs = getFileSystemManager();
const { data } = await fs.readFile({
  filePath: '/tmp/profile.json',
  encoding: 'utf-8'
});

console.log(data);

返回值

名称类型必返说明
access(params: AccessParams) => Promise<void>是判断文件或目录是否存在(异步)。存在时 Promise 兑现,不存在时 Promise 拒绝。
accessSync(params: AccessParams) => void是判断文件或目录是否存在(同步)。不存在时抛出异常。
appendFile(params: AppendFileParams) => Promise<void>是在文件末尾追加内容(异步)。文件不存在则创建,不会覆盖已有内容。
appendFileSync(params: AppendFileParams) => void是在文件末尾追加内容(同步)。文件不存在则创建,不会覆盖已有内容。
copyFile(params: CopyFileParams) => Promise<void>是复制文件(异步)。仅支持文件,目标已存在同名文件时覆盖。
copyFileSync(params: CopyFileParams) => void是复制文件(同步)。仅支持文件,目标已存在同名文件时覆盖。
getFileInfo(params: GetFileInfoParams) => Promise<GetFileInfoResult>是获取文件信息(异步);返回 GetFileInfoResult,含字节大小和可选的摘要。
getSavedFileList() => Promise<GetSavedFileListResult>是获取已保存的本地文件列表(异步);返回 GetSavedFileListResult,每项含路径、字节大小和毫秒级保存时间。
mkdir(params: MkdirParams) => Promise<void>是创建目录(异步)。recursive 为 true 时一并创建缺失的上级目录。
mkdirSync(params: MkdirParams) => void是创建目录(同步)。recursive 为 true 时一并创建缺失的上级目录。
readdir(params: ReaddirParams) => Promise<ReaddirResult>是读取目录内容(异步);返回 ReaddirResult,files 为目录下的文件与子目录名称(非完整路径,非递归)。
readdirSync(params: ReaddirParams) => ReaddirResult是读取目录内容(同步);返回 ReaddirResult,files 为目录下的文件与子目录名称(非完整路径,非递归)。
readFile(params: ReadFileParams) => Promise<ReadFileResult>是读取文件内容(异步);返回 ReadFileResult,其中 data 按 encoding 为 UTF-8 或 Base64 字符串。
readFileSync(params: ReadFileParams) => ReadFileResult是读取文件内容(同步);返回 ReadFileResult,其中 data 按 encoding 为 UTF-8 或 Base64 字符串。
removeSavedFile(params: RemoveSavedFileParams) => Promise<void>是删除通过 saveFile 保存的本地文件(异步)。
rename(params: RenameParams) => Promise<void>是重命名或移动文件(异步)。目标已存在同名文件时覆盖。
renameSync(params: RenameParams) => void是重命名或移动文件(同步)。目标已存在同名文件时覆盖。
rmdir(params: RmdirParams) => Promise<void>是删除目录(异步)。recursive 为 false 时仅能删除空目录,为 true 时递归删除全部内容。
rmdirSync(params: RmdirParams) => void是删除目录(同步)。recursive 为 false 时仅能删除空目录,为 true 时递归删除全部内容。
saveFile(params: SaveFileParams) => Promise<SaveFileResult>是将临时文件保存到本地持久化存储(异步);返回 SaveFileResult,含实际保存路径。
saveFileSync(params: SaveFileParams) => SaveFileResult是将临时文件保存到本地持久化存储(同步);返回 SaveFileResult,含实际保存路径。
stat(params: StatParams) => Promise<StatResult>是获取文件或目录状态(异步);返回 StatResult,含字节大小、毫秒级修改时间和是否为目录。
statSync(params: StatParams) => StatResult是获取文件或目录状态(同步);返回 StatResult,含字节大小、毫秒级修改时间和是否为目录。
truncate(params: TruncateParams) => Promise<void>是截断文件到指定长度(异步)。短于原长度时截断,长于原长度时以 \0 填充。
truncateSync(params: TruncateParams) => void是截断文件到指定长度(同步)。短于原长度时截断,长于原长度时以 \0 填充。
unlink(params: UnlinkParams) => Promise<void>是删除文件(异步)。只能删除文件,删除目录请使用 rmdir。
unlinkSync(params: UnlinkParams) => void是删除文件(同步)。只能删除文件,删除目录请使用 rmdir。
unzip(params: UnzipParams) => Promise<void>是解压 zip 文件到指定目录(异步)。目标目录须已存在。
writeFile(params: WriteFileParams) => Promise<void>是写入文件内容(异步)。文件和父目录不存在则创建,文件已存在则覆盖。
writeFileSync(params: WriteFileParams) => void是写入文件内容(同步)。文件和父目录不存在则创建,文件已存在则覆盖。

错误处理

同步调用失败时抛出错误。错误对象和通用错误码见 通用错误处理。

失败示例

{
  "errNo": 203,
  "errMsg": "file does not exist"
}

错误码

errNoerrMsg平台触发条件处理建议
203file does not existAndroid、iOSreadFile、stat、getFileInfo、copyFile、rename、truncate、unlink、rmdir、removeSavedFile、unzip 等操作的目标文件或目录不存在确认路径存在或先创建后重试。
213invalid file pathAndroid、iOS传入的路径不是合法的沙箱内 appletfile 路径,或试图越过沙箱根目录访问使用应用沙箱内的合法本地路径后重试。
208total size limit exceededAndroid、iOSreadFile、writeFile、appendFile、copyFile 时单次读写超过单文件大小上限,或写入后超出沙箱存储配额减小单次读写数据量或清理已保存文件后重试。
1901001target is a directoryAndroid、iOS对目录执行了仅适用于文件的操作(如 readFile、writeFile、appendFile、copyFile、truncate、getFileInfo、unzip 的源文件),或 rmdir 删除非空目录时未开启 recursive改为对文件操作,或删除目录时开启 recursive。
1901002target is not a directoryAndroid、iOS对文件执行了仅适用于目录的操作(如 readdir),或 mkdir 目标已存在同名文件、unzip 的 targetPath 不是目录确认目标为目录后重试。

通用错误码

errNoerrMsg说明平台
102internal error内部错误Android、iOS
103feature not support当前环境不支持该能力Android
104invalid parameter参数不合法Android、iOS