docs📝: 新增微信小程序-文件系统文档；

usage-frame/wechat-mini-program/基础能力.md

@@ -78,4 +78,306 @@ wx.clearStorage({
 })
 
 wx.clearStorageSync()
-```
+```
+
+## 文件系统
+
+定义：
+- 文件系统是小程序提供的一套以*小程序和用户维度*隔离的存储以及一套相应的管理接口
+
+文件分类：
+- 代码包文件：指的是项目源代码目录中的文件，由于代码包大小的限制，适用于放置首次加载时需要的文件，访问代码包文件只能以绝对路径方式引入，从项目根目录开始，比如（`/images/xxx.png`或`images/xxx.png`）
+- 本地文件：指的是小程序被用户添加到手机后，会有一块独立的文件存储区域，以用户和小程序的维度隔离。通过调用接口本地产生，或是网络下载保存到本地的文件，文件路径均为`{{wxfile/http://path}`的格式，其中http是开发者工具上的，wxfile是客户端上的。本地文件分为：
+  - 本地临时文件：临时产生，随时会被回收的文件，不能直接写入内容，仅在当前生命周期内保证是有效的，若想保证以后优先，可使用`saveFile`、`copyFile`等接口将其转成下面两者文件形式。运行时最多存储4GB，运行结束后超过2GB的部分会按文件维度从时间远近被清理。所有小程序占用不能超过6GB，超过则按小程序维度进行清理。在下载临时文件时，可先使用`access`检查该文件是否存在，减少重复下载。
+  - 本地缓存文件：通过接口方式`saveFile()`将本地临时文件缓存后的文件，不能自定义存放的目录和名称，和本地用户文件一起最多可存放200MB，仅在代码包清理时才被清理
+  - 本地用户文件：比本地缓存文件功能更完整，通过接口方式（特定API）将本地临时文件缓存后的文件，能自定义存放的子目录和名称，有完全的读写权限，可通过`wx.env.USER_DATA_PATH`获取存放目录根路径，和本地缓存文件一起最多可存放200MB，仅在代码包清理时才被清理
+
+
+使用：通过`fs = wx.getFileSystemManager()`获取全局唯一的文件系统管理器，所有的文件操作都可以通过对象fs进行调用
+
+api使用：
+
+<!-- tabs:start -->
+<!-- tab:常用api -->
+```js
+const fs = wx.getFileSystemManager()
+// 注意，下列的接口，若后缀带Sync，则为同步接口，否则是异步的
+
+// 保存文件到系统磁盘（PC）
+wx.saveFileToDisk({
+  filePath: '',
+  success/fail/complete() {}
+})
+
+// 新开页面打开文档
+wx.openDocument({
+  filePath: '',
+  // 是否显示右上角菜单
+  showMenu: boolean,
+  // doc,docx,xls,xlsx,ppt,pptx,pdf
+  fileType: '',
+  success/fail/complete(){}
+})
+
+// 判断文件/目录是否存在
+fs.access({
+  // 是否存在的本地文件/目录路径
+  path: '',
+  success/fail/complete(res) {}
+})
+// 文件存在时，会返回undefined，否则会报错，应该使用try-catch或其他错误处理函数包裹
+try {
+  fs.accessSync(path)
+} catch (e) {
+  console.log(e)
+}
+
+// 创建目录
+fs.mkdir({
+  dirPath: '',
+  // 是否递归该目录的上级目录后在创建目录，上级目录不存在时，会创建上级目录
+  recursive: true,
+  success/fail/complete() {}
+})
+
+try {
+  fs.mkdir(dirPath, recursive)
+} catch (e) {
+  console.log(e)
+}
+
+// 删除目录
+fs.rmdir({
+  dirPath: '',
+  recursive: true,
+  success/fail/complete() {}
+})
+
+const res = fs.rmdirSync(dirpath, recursive)
+
+// 打开、关闭文件
+fs.open({
+  filePath: '',
+  // 文件系统标志，有r(默认，打开文件读取，不存在，则会发生异常)、r+（打开文件读取和写入，不存在，则会发生异常）、w（打开文件写入，不存在则创建）、w+（打开文件读取和写入，不存在则创建）、a（打开文件追加，不存在则创建）、a+(打开文件用于读取和追加，不存在则创建)、as/as+(效果同a/a+，同步模式，不存在则创建)
+  flag: 'a+',
+  // 参数res的属性有fd：文件描述符
+  success (res) {
+    fs.close({
+      // 需要被关闭的文件描述符，通过open/openSync函数获取
+      fd: res.fd,
+      success/fail/complete() {}
+    })
+  },
+  fail/complete() {}
+})
+
+const fd = fs.openSync({
+  filePath: '',
+  flag: 'a+'
+})
+
+fs.closeSync({
+  fd: fd
+})
+
+// 读取文件
+fs.read({
+  fd: '',
+  // 数据写入的缓冲区
+  arrayBuffer: arrayBuffer,
+  // 缓冲区写入的偏移量
+  offset: number,
+  // 从文件中读取的字节数
+  length: number,
+  // 从文件中读取的起始位置
+  position: number,
+  success (res) {
+    const { bytesRead, arrayBuffer } = res
+  },
+  fail/complete() {}
+})
+
+res = fs.readSync({
+  fd: '',
+  arrayBuffer: arrayBuffer,
+  offset/length/position
+})
+
+// 读取本地文件内容
+fs.readFile({
+  filePath: '',
+  encoding: '',
+  position/length,
+  success (res) {
+    console.log(res.data)
+  },
+  fail/complete() {}
+})
+
+try {
+  const res = fs.readFileSync(filePath, encoding, position, length)
+} catch (e) {
+  console.log(e)
+}
+
+// 读取目录内文件列表
+fs.readdir({
+  dirPath: '',
+  success (res) {
+    console.log(res.files)
+  },
+  fail/complete() {}
+})
+
+try {
+  const res = fs.readdirSync(dirpath)
+} catch (e) {
+  console.log(e)
+}
+
+// 写入文件
+fs.write({
+  fd: '',
+  data: string/arrayBuffer,
+  offset/length/position,
+  encoding: '',
+  success (res) {
+    const { bytesWritten } = res
+  },
+  fail/complete () {}
+})
+
+const res = fs.writeSync({
+  fd: '',
+  data,
+  offset/length/position,
+  encoding
+})
+
+// 写入本地文件
+fs.writeFile({
+  filePath: '',
+  data: string/arrayBuffer,
+  encoding: '',
+  success/fail/complete () {}
+})
+
+const res = fs.writeFileSync(filePath, data, encoding)
+
+// 复制文件
+fs.copyFile({
+  srcPath: '',
+  // 目标文件路径
+  destPath: '',
+  success/fail/complete() {}
+})
+
+try {
+  fs.copyFileSync(srcPath, destPath)
+} catch (e) {
+  console.log(e)
+}
+
+// 删除保存的本地缓存文件
+fs.removeSavedFile({
+  filePath: '',
+  success/fail/complete() {}
+})
+
+// 重命名文件，文件移动
+fs.rename({
+  oldPath: '',
+  newPath: '',
+  success/fail/complete() {}
+})
+
+try {
+  const res = fs.renameSync(oldPath, newPath)
+} catch (e) {}
+
+// 在文件结尾追加内容
+fs.appendFile({
+  filePath: '',
+  // 要追加的文本、二进制数据
+  data: string/arrayBuffer,
+  // 指定写入文件的字符编码，值有uft8（默认）、ascii、base64、ucs2、uth16le
+  encoding: string,
+  success/fail/complete() {}
+})
+
+try {
+  fs.appendFileSync(path, data, encoding)
+} catch (e) {
+  console.log(e)
+}
+
+// 保存文件
+fs.saveFile({
+  tempFilePath: '',
+  filePath: '',
+  success (res) {
+    const { savedFilePath } = res
+  },
+  fail/complete () {}
+})
+
+const savedFilePath = FS.saveFileSync(tempFilePath, filePath)
+
+// 删除文件
+fs.unlink({
+  filePath: '',
+  success/fail/complete() {}
+})
+
+const res = fs.unlinkSync(filePath)
+
+// 解压文件
+fs.unzip({
+  zipFilePath: '',
+  targetPath: '',
+  success/fail/complete () {}
+})
+
+// 获取已保存的本地缓存文件列表
+fs.getSavedFileList({
+  success (res) {
+    const { fileList } = res
+    const { filePath, size, createTime } = for(fileList)
+  }
+})
+```
+
+<!-- tab:不常用 -->
+```js
+// 获取文件状态信息
+fs.fstat({
+  // 文件描述符，同上
+  fd: '',
+  success/fail/complete() {}
+})
+
+// stats表示文件状态的对象
+const stats = fs.fstatSync({fd: fd})
+const {
+  // 文件类型和存取的权限
+ mode: '',
+ size: number,
+  //  最近一次操作的unix时间
+  lastAccessedTime: number,
+  lastModifiedTime: number
+  // 判断当前文件是否是目录
+  isDirectory(),
+  // 当前文件是否是普通文件
+  isFile()
+} = stats
+
+// 获取小程序下的本地临时文件、本地缓存文件的信息
+fs.getFileInfo({
+  filePath: '',
+  success (res) {
+    console.log(res.size)
+  },
+  fail/complete() {}
+})
+```
+<!-- tabs:end -->