文件管理器

在应用平台中是按分区来存储文件的，目前支持以下分区

1. Cache，一般用于存储缓存文件，下载后的数据存在于该分区中，该分区中的文件可能因存储空间不够被系统删除
2. Files，一般用于存储永久文件，该分区中的文件由应用自己管理
3. Temp，表示从外部映射过来的临时文件，出于安全性考虑，临时文件是只读的，并且只能通过调用特定的 API 获取，比如 qg.pickImage 方法。另外临时文件的访问是临时的，应用重启后无法访问到临时文件，需要通过特定 API 重新获取。 另外应用资源也作为一个特殊的只读分区进行处理。

URL 说明

URI 用于标识应用资源和文件，通过 URI 来访问应用资源和文件。

internal URI 表示的是应用私有文件，即在指定 internal URI 时，无需指定应用标识，同一个 internal URI 对于不同的应用会指向不同的文件。

qg.getFileSystemManager()

获取全局唯一的文件管理器

返回值 FileSystemManager

文件管理器

方法

FileSystemManager.saveFile(Object object)

保存临时文件到本地。此接口会移动临时文件，因此调用成功后，tempFilePath 将不可用。

参数

Object object

object.success(Object res) 回调函数

FileSystemManager.saveFileSync(String tempFilePath, String filePath)

FileSystemManager.saveFile 的同步版本

参数

String tempFilePath

临时存储文件路径 (本地路径)

String filePath

要存储的文件路径 (本地路径)

返回值

String savedFilePath

存储后的文件路径 (本地路径)

FileSystemManager.mkdir(Object object)

创建目录

参数

Object object

FileSystemManager.mkdirSync(String dirPath, Boolean recursive)

FileSystemManager.mkdir 的同步版本

参数

String dirPath

创建的目录路径 (本地路径)

Boolean recursive

是否在递归创建该目录的上级目录后再创建该目录。如果对应的上级目录已经存在，则不创建该上级目录。如 dirPath 为 a/b/c/d 且 recursive 为 true，将创建 a 目录，再在 a 目录下创建 b 目录，以此类推直至创建 a/b/c 目录下的 d 目录。

示例代码

const fs = qg.getFileSystemManager();
fs.mkdir({
  dirPath: `${qg.env.USER_DATA_PATH}/example`,
  recursive: false,
  success(res) {
    console.log(res);
  },
  fail(res) {
    console.error(res);
  }
});

// 同步接口
try {
  fs.mkdirSync(`${qg.env.USER_DATA_PATH}/example`, false);
} catch (e) {
  console.error(e);
}

FileSystemManager.readFile(Object object)

读取本地文件内容。单个文件大小上限为 100M。

参数

Object object

encoding（指定读取文件的字符编码）

object.success(Object res) 回调函数

FileSystemManager.readFileSync(String filePath, String encoding, Number position, Number length)

FileSystemManager.readFile 的同步版本

参数

String filePath

要读取的文件的路径 (本地路径)

String encoding

指定读取文件的字符编码，如果不传 encoding，则以 ArrayBuffer 格式读取文件的二进制内容

encoding 的合法值

Number position

从文件指定位置开始读，如果不指定，则从文件头开始读。读取的范围应该是左闭右开区间 [position, position+length)。有效范围：[0, fileLength - 1]。单位：byte

Number length

指定文件的长度，如果不指定，则读到文件末尾。有效范围：[1, fileLength]。单位：byte

返回值

String|ArrayBuffer data

文件内容

示例代码

const fs = qg.getFileSystemManager();
fs.readFile({
  filePath: `${qg.env.USER_DATA_PATH}/hello.txt`,
  encoding: "utf8",
  position: 0,
  success(res) {
    console.log(res.data);
  },
  fail(res) {
    console.error(res);
  }
});

// 同步接口
try {
  const res = fs.readFileSync(`${qg.env.USER_DATA_PATH}/hello.txt`, "utf8", 0);
  console.log(res);
} catch (e) {
  console.error(e);
}

FileSystemManager.readdir(Object object)

读取目录内文件列表

参数

Object object

object.success(Object res ) 回调函数

注意事项 readdir 接口无法访问文件系统根路径。

FileSystemManager.readdirSync(String dirPath)

FileSystemManager.readdir 的同步版本

参数

String dirPath

要读取的目录路径 (本地路径)

返回值

Arrayfiles

指定目录下的文件名数组。

注意事项 readdir 接口无法访问文件系统根路径。

示例代码

const fs = qg.getFileSystemManager();
fs.readdir({
  dirPath: `${qg.env.USER_DATA_PATH}/example`,
  success(res) {
    console.log(res.files);
  },
  fail(res) {
    console.error(res);
  }
});

// 同步接口
try {
  const res = fs.readdirSync(`${qg.env.USER_DATA_PATH}/example`);
  console.log(res);
} catch (e) {
  console.error(e);
}

FileSystemManager.readZipEntry(Object object)

读取压缩包内的文件

参数

Object object

encoding（统一指定读取文件的字符编码）

entries（要读取的压缩包内的文件列表）

object.success(Object res) 回调函数

entries （文件读取结果）

path（文件路径）

示例代码

const fs = qg.getFileSystemManager();
// 读取zip内某个或多个文件
fs.readZipEntry({
  filePath: "scheme://from/to.zip",
  entries: [
    {
      path: "some_folder/my_file.txt", // zip内文件路径
      encoding: "utf-8", // 指定读取文件的字符编码，如果不传 encoding，则以 ArrayBuffer 格式读取文件的二进制内容
      position: 0, // 从文件指定位置开始读，如果不指定，则从文件头开始读。读取的范围应该是左闭右开区间 [position, position+length)。有效范围：[0, fileLength - 1]。单位：byte
      length: 10000 // 指定文件的长度，如果不指定，则读到文件末尾。有效范围：[1, fileLength]。单位：byte
    },
    {
      path: "other_folder/orther_file.txt" // zip内文件路径
    }
  ],
  success(res) {
    console.log(res.entries);
  },
  fail(res) {
    console.log(res.errMsg);
  }
});

// 读取zip内所有文件。允许指定统一的encoding。position、length则不再允许指定，分别默认为0和文件长度
fs.readZipEntry({
  filePath: "scheme://from/to.zip",
  entries: "all",
  encoding: "utf-8", // 统一指定读取文件的字符编码，如果不传 encoding，则以 ArrayBuffer 格式读取文件的二进制内容
  success(res) {
    console.log(res.entries);
  },
  fail(res) {
    console.log(res.errMsg);
  }
});

FileSystemManager.readCompressedFile(Object object)

读取指定压缩类型的本地文件内容

参数

Object object

compressionAlgorithm（文件压缩类型）

object.success(Object res) 回调函数

FileSystemManager.readCompressedFileSync(Object object)

同步读取指定压缩类型的本地文件内容

参数

Object object

compressionAlgorithm（文件压缩类型）

返回值

ArrayBuffer

文件读取结果

示例代码

const fs = qg.getFileSystemManager();

// 异步接口
fs.readCompressedFile({
  filePath: "${qg.env.USER_DATA_PATH}/hello.br",
  compressionAlgorithm: "br",
  success(res) {
    console.log(res.data);
  },
  fail(res) {
    console.log("readCompressedFile fail", res);
  }
});

// 同步接口
try {
  const data = fs.readCompressedFileSync({
    filePath: "${qg.env.USER_DATA_PATH}/hello.br",
    compressionAlgorithm: "br"
  });
  console.log(data);
} catch (err) {
  console.log(err);
}

FileSystemManager.copyFile(Object object)

复制文件

参数

Object object

FileSystemManager.copyFileSync(String srcPath, String destPath)

FileSystemManager.copyFile 的同步版本

参数

String srcPath

源文件路径，支持本地路径

String destPath

目标文件路径，支持本地路径

示例代码

const fs = qg.getFileSystemManager();
fs.copyFile({
  srcPath: `${qg.env.USER_DATA_PATH}/hello.txt`,
  destPath: `${qg.env.USER_DATA_PATH}/hello_copy.txt`,
  success(res) {
    console.log(res);
  },
  fail(res) {
    console.error(res);
  }
});

// 同步接口
try {
  fs.copyFileSync(
    `${qg.env.USER_DATA_PATH}/hello.txt`,
    `${qg.env.USER_DATA_PATH}/hello_copy.txt`
  );
} catch (e) {
  console.error(e);
}

FileSystemManager.getFileInfo(Object object)

获取该快游戏下的本地临时文件或本地缓存文件信息

参数

Object object

object.success(Object res) 回调函数

FileSystemManager.getSavedFileList(Object object)

获取该快游戏下已保存的本地缓存文件列表

参数

Object object

object.success(Object res) 回调函数

fileList（文件数组）

FileSystemManager.unzip(Object object)

解压文件

参数

Object object

示例代码

const fs = qg.getFileSystemManager();
fs.unzip({
  zipFilePath: `${qg.env.USER_DATA_PATH}/example.zip`,
  targetPath: "${qg.env.USER_DATA_PATH}/example",
  success(res) {
    console.log(res);
  },
  fail(res) {
    console.error(res);
  }
});

FileSystemManager.access(Object object)

判断文件/目录是否存在

参数

Object object

FileSystemManager.accessSync(String path)

FileSystemManager.access 的同步版本

参数

String path

要判断是否存在的文件/目录路径 (本地路径)

示例代码

const fs = qg.getFileSystemManager();
// 判断文件/目录是否存在
fs.access({
  path: `${qg.env.USER_DATA_PATH}/hello.txt`,
  success(res) {
    // 文件存在
    console.log(res);
  },
  fail(res) {
    // 文件不存在或其他错误
    console.error(res);
  }
});

// 同步接口
try {
  fs.accessSync(`${qg.env.USER_DATA_PATH}/hello.txt`);
} catch (e) {
  console.error(e);
}

FileSystemManager.removeSavedFile(Object object)

删除该快游戏下已保存的本地缓存文件

参数

Object object

FileSystemManager.rmdir(Object object)

删除目录

参数

Object object

FileSystemManager.rmdirSync(String dirPath, Boolean recursive)

FileSystemManager.rmdir 的同步版本

参数

String dirPath

要删除的目录路径 (本地路径)

Boolean recursive

是否递归删除目录。如果为 true，则删除该目录和该目录下的所有子目录以及文件。

示例代码

const fs = qg.getFileSystemManager();
fs.rmdir({
  dirPath: `${qg.env.USER_DATA_PATH}/example`,
  recursive: false,
  success(res) {
    console.log(res);
  },
  fail(res) {
    console.error(res);
  }
});

// 同步接口
try {
  const res = fs.rmdirSync(`${qg.env.USER_DATA_PATH}/example`, false);
  console.log(res);
} catch (e) {
  console.error(e);
}

FileSystemManager.unlink(Object object)

删除文件

参数

Object object

FileSystemManager.unlinkSync(String filePath)

FileSystemManager.unlink 的同步版本

参数

String filePath

要删除的文件路径 (本地路径)

示例代码

const fs = qg.getFileSystemManager();
fs.unlink({
  filePath: `${qg.env.USER_DATA_PATH}/hello.txt`,
  success(res) {
    console.log(res);
  },
  fail(res) {
    console.error(res);
  }
});

// 同步接口
try {
  const res = fs.unlinkSync(`${qg.env.USER_DATA_PATH}/hello.txt`);
  console.log(res);
} catch (e) {
  console.error(e);
}

FileSystemManager.writeFile(Object object)

写文件

参数

Object object

encoding（指定写入文件的字符编码）

FileSystemManager.writeFileSync(String filePath, String|ArrayBuffer data, String encoding)

FileSystemManager.writeFile 的同步版本

参数

String filePath

要写入的文件路径 (本地路径)

String|ArrayBuffer data

要写入的文本或二进制数据

String encoding

指定写入文件的字符编码

encoding 的合法值

示例代码

const fs = qg.getFileSystemManager();
fs.writeFile({
  filePath: `${qg.env.USER_DATA_PATH}/hello.txt`,
  data: "some text or arrayBuffer",
  encoding: "utf8",
  success(res) {
    console.log(res);
  },
  fail(res) {
    console.error(res);
  }
});

// 同步接口
try {
  const res = fs.writeFileSync(
    `${qg.env.USER_DATA_PATH}/hello.txt`,
    "some text or arrayBuffer",
    "utf8"
  );
  console.log(res);
} catch (e) {
  console.error(e);
}

FileSystemManager.appendFile(Object object)

在文件结尾追加内容

参数

Object object

encoding（指定写入文件的字符编码）

FileSystemManager.appendFileSync(String filePath, String|ArrayBuffer data, String encoding)

FileSystemManager.appendFile 的同步版本

参数

String filePath

要追加内容的文件路径 (本地路径)

String|ArrayBuffer data

要追加的文本或二进制数据

String encoding

指定写入文件的字符编码

encoding 的合法值

示例代码

const fs = qg.getFileSystemManager();

fs.appendFile({
  filePath: `${qg.env.USER_DATA_PATH}/hello.txt`,
  data: "some text",
  encoding: "utf8",
  success(res) {
    console.log(res);
  },
  fail(res) {
    console.error(res);
  }
});

// 同步接口
try {
  fs.appendFileSync(`${qg.env.USER_DATA_PATH}/hello.txt`, "some text", "utf8");
} catch (e) {
  console.error(e);
}

FileSystemManager.rename(Object object)

重命名文件。可以把文件从 oldPath 移动到 newPath

参数

Object object

FileSystemManager.renameSync(String oldPath, String newPath)

FileSystemManager.rename 的同步版本

参数

String oldPath

源文件路径，支持本地路径

String newPath

新文件路径，支持本地路径

示例代码

const fs = qg.getFileSystemManager();
fs.rename({
  oldPath: `${qg.env.USER_DATA_PATH}/hello.txt`,
  newPath: `${qg.env.USER_DATA_PATH}/hello_new.txt`,
  success(res) {
    console.log(res);
  },
  fail(res) {
    console.error(res);
  }
});

// 同步接口
try {
  const res = fs.renameSync(
    `${qg.env.USER_DATA_PATH}/hello.txt`,
    `${qg.env.USER_DATA_PATH}/hello_new.txt`
  );
  console.log(res);
} catch (e) {
  console.error(e);
}

FileSystemManager.stat(Object object)

获取文件 Stats 对象

参数

Object object

object.success(Object res) 回调函数

示例代码

recursive 为 false 时

// 异步版本
let fs = qg.getFileSystemManager();
fs.stat({
  path: `${qg.env.USER_DATA_PATH}/testDir`,
  success: res => {
    console.log(res.stats.isDirectory());
  }
});
// 同步版本
fs.statSync(`${qg.env.USER_DATA_PATH}/testDir`, false);

recursive 为 true 时

let fs = qg.getFileSystemManager();
// 异步版本
fs.stat({
  path: `${qg.env.USER_DATA_PATH}/testDir`,
  recursive: true,
  success: res => {
    Object.keys(res.stats).forEach(path => {
      let stats = res.stats[path];
      console.log(path, stats.isDirectory());
    });
  }
});
// 同步版本
fs.statSync(`${qg.env.USER_DATA_PATH}/testDir`, true);

FileSystemManager.statSync(String path, Boolean recursive)

FileSystemManager.stat 的同步版本

参数

String path

文件/目录路径 (本地路径)

Boolean recursive

是否递归获取目录下的每个文件的 Stats 信息

返回值

Stats|Arraystats

当 recursive 为 false 时，res.stats 是一个 Stats 对象。当 recursive 为 true 且 path 是一个目录的路径时，res.stats 是一个 Array，数组的每一项是一个对象，每个对象包含 path 和 stats。

示例代码

recursive 为 false 时

// 异步版本
let fs = qg.getFileSystemManager();
fs.stat({
  path: `${qg.env.USER_DATA_PATH}/testDir`,
  success: res => {
    console.log(res.stats.isDirectory());
  }
});
// 同步版本
fs.statSync(`${qg.env.USER_DATA_PATH}/testDir`, false);

recursive 为 true 时

let fs = qg.getFileSystemManager();
// 异步版本
fs.stat({
  path: `${qg.env.USER_DATA_PATH}/testDir`,
  recursive: true,
  success: res => {
    Object.keys(res.stats).forEach(path => {
      let stats = res.stats[path];
      console.log(path, stats.isDirectory());
    });
  }
});
// 同步版本
fs.statSync(`${qg.env.USER_DATA_PATH}/testDir`, true);

Stats

描述文件状态的对象

属性

Number mode

文件的类型和存取的权限，对应 POSIX stat.st_mode

Number size

文件大小，单位：B，对应 POSIX stat.st_size

Number lastAccessedTime

文件最近一次被存取或被执行的时间，UNIX 时间戳，对应 POSIX stat.st_atime

Number lastModifiedTime

文件最后一次被修改的时间，UNIX 时间戳，对应 POSIX stat.st_mtime

方法

Stats.isDirectory()

判断当前文件是否一个目录

返回值 Boolean

表示当前文件是否一个目录

Stats.isFile()

判断当前文件是否一个普通文件

返回值 Boolean

表示当前文件是否一个普通文件