【愚公系列】《微信小程序与云开发从入门到实践》039-小程序文件系统

🚀前言

随着小程序的广泛应用，如何高效管理和存储数据成为开发者面临的重要课题。小程序文件系统作为一种轻量级的存储解决方案，提供了灵活的文件存储和管理能力，使得开发者能够更加便捷地处理用户数据和应用资源。

在本篇文章中，我们将深入探讨小程序文件系统的基本概念、主要功能以及实际应用场景。我们将详细介绍文件的读写操作、文件的上传与下载、以及如何有效管理文件存储空间等内容。此外，我们还会分享一些最佳实践与常见问题的解决方案，帮助开发者更好地利用文件系统提升小程序的性能和用户体验。

🚀一、小程序文件系统

🔎1.以 wx 开头的文件系统接口

🦋1.1 小程序与文件系统相关的常用方法

小程序提供了一些便捷的方法，帮助开发者操作文件系统。这些方法一般以 wx 开头，提供快速使用的接口。

常用方法与参数说明

🦋1.2 详细方法解析

☀️1.2.1 wx.saveFileToDisk

• 功能：将小程序文件系统中的文件保存到用户的磁盘中。此方法仅支持在 PC 端使用，用于将文件从小程序的文件系统保存到本地磁盘。
• 参数：
  • filePath：待保存的文件路径。
  • success：成功时的回调函数。
  • fail：失败时的回调函数。
  • complete：完成时的回调函数。

☀️1.2.2 wx.saveFile

• 功能：将临时文件（比如通过文件上传下载等方式获取的文件）保存到本地文件系统中。保存后，临时文件的路径将不可用，且返回保存后的文件路径。
• 参数：
  • tempFilePath：临时文件路径。
  • success：成功时的回调函数，返回保存后的文件路径。
  • fail：失败时的回调函数。
  • complete：完成时的回调函数。

☀️1.2.3 wx.removeSavedFile

• 功能：删除本地文件。
• 参数：
  • filePath：要删除的文件的本地路径。
  • success：成功时的回调函数。
  • fail：失败时的回调函数。
  • complete：完成时的回调函数。

☀️1.2.4 wx.openDocument

• 功能：用于打开本地的文档文件，支持的文件类型有 doc、docx、xls、xlsx、ppt、pptx、pdf 等。
• 参数：
  • filePath：文件的本地路径。
  • fileType：文件的类型，支持 doc、docx、xls、xlsx、ppt、pptx、pdf 等类型。
  • success：成功时的回调函数。
  • fail：失败时的回调函数。
  • complete：完成时的回调函数。

☀️1.2.5 wx.getSavedFileList

• 功能：获取当前小程序已经存储到本地的缓存文件列表，返回一个 fileList 数组，每个元素包含文件的路径、大小（单位：字节）和创建时间等信息。
• 参数：
  • success：成功时的回调函数，返回一个 fileList 数组。
  • fail：失败时的回调函数。
  • complete：完成时的回调函数。

☀️1.2.6 wx.getSavedFileInfo

• 功能：获取本地文件的文件信息，返回文件的大小和创建时间。
• 参数：
  • filePath：文件的本地路径。
  • success：成功时的回调函数，返回文件的 size 和 createTime 信息。
  • fail：失败时的回调函数。
  • complete：完成时的回调函数。

☀️1.2.7 wx.getFileInfo

• 功能：获取本地文件的详细信息，返回文件的大小和 digest 摘要信息，digest 是通过摘要算法（如 MD5）计算出来的。
• 参数：
  • filePath：文件的本地路径。
  • digestAlgorithm：摘要算法（默认值为 md5）。
  • success：成功时的回调函数，返回文件的 size 和 digest 摘要信息。
  • fail：失败时的回调函数。
  • complete：完成时的回调函数。

☀️1.2.8 wx.getFileSystemManager

• 功能：获取全局的文件管理器对象，该对象封装了更多丰富的文件管理方法，可以用于更底层的文件系统操作。
• 返回值：返回一个 FileSystemManager 对象，提供更丰富的文件管理操作，如读取文件、写入文件等。

🦋1.3 文件系统管理器 FileSystemManager 方法

wx.getFileSystemManager 返回的 FileSystemManager 对象，封装了比普通文件方法更丰富的文件操作接口。这些方法可以帮助你处理文件的读取、写入、删除等操作，适用于更复杂的文件系统管理需求。

🔎2.FileSystemManager 文件管理器

通过 wx.getFileSystemManager() 可以获取到一个全局唯一的文件管理器实例，通过该实例可以进行文件操作，如判断文件是否存在、创建文件、读取文件、重命名文件、删除文件等。

🦋2.1 判断文件或目录是否存在

• 异步: access
  • 参数：path（文件或目录路径），success（成功回调），fail（失败回调），complete（完成回调）
  • 功能：判断指定文件或目录是否存在。如果存在，调用 success 回调；如果不存在，调用 fail 回调。
• 同步: accessSync
  • 参数：path（文件或目录路径）
  • 功能：同步地判断文件或目录是否存在，如果不存在会抛出异常。

🦋2.2 读取文件内容

• 异步: readFile
  • 参数：filePath（文件路径），encoding（编码方式），position（开始读取的位置），length（读取的字节数），success（成功回调），fail（失败回调），complete（完成回调）
  • 功能：异步读取文件内容，读取成功后返回数据。
• 同步: readFileSync
  • 参数：filePath（文件路径），encoding（编码方式）
  • 功能：同步读取文件内容，返回文件内容。

🦋2.3 追加文件内容

• 异步: appendFile
  • 参数：filePath（文件路径），data（要追加的内容），encoding（编码方式），success（成功回调），fail（失败回调），complete（完成回调）
  • 功能：异步追加内容到文件末尾。
• 同步: appendFileSync
  • 参数：filePath（文件路径），data（要追加的内容），encoding（编码方式）
  • 功能：同步地追加内容到文件末尾。

🦋2.4 打开文件

• 异步: open
  • 参数：filePath（文件路径），flag（操作符），success（成功回调），fail（失败回调），complete（完成回调）
  • 功能：异步打开文件，返回文件标识符，后续的文件操作需要使用该标识符。
• 同步: openSync
  • 参数：filePath（文件路径），flag（操作符）
  • 功能：同步打开文件，返回文件标识符。

🦋2.5 关闭文件

• 异步: close
  • 参数：fd（文件标识符），success（成功回调），fail（失败回调），complete（完成回调）
  • 功能：异步关闭文件。
• 同步: closeSync
  • 参数：fd（文件标识符）
  • 功能：同步关闭文件。

🦋2.6 文件重命名

• 异步: rename
  • 参数：oldPath（源路径），newPath（目标路径），success（成功回调），fail（失败回调），complete（完成回调）
  • 功能：异步重命名文件（也可以用于移动文件）。
• 同步: renameSync
  • 参数：oldPath（源路径），newPath（目标路径）
  • 功能：同步重命名文件。

🦋2.7 删除文件或目录

• 异步: unlink
  • 参数：filePath（文件路径），success（成功回调），fail（失败回调），complete（完成回调）
  • 功能：异步删除文件。
• 同步: unlinkSync
  • 参数：filePath（文件路径）
  • 功能：同步删除文件。

🦋2.8 创建目录

• 异步: mkdir
  • 参数：dirPath（目录路径），recursive（是否递归创建），success（成功回调），fail（失败回调），complete（完成回调）
  • 功能：异步创建目录，支持递归创建。
• 同步: mkdirSync
  • 参数：dirPath（目录路径），recursive（是否递归创建）
  • 功能：同步创建目录，支持递归创建。

🦋2.9 删除目录

• 异步: rmdir
  • 参数：dirPath（目录路径），recursive（是否递归删除），success（成功回调），fail（失败回调），complete（完成回调）
  • 功能：异步删除目录，支持递归删除。
• 同步: rmdirSync
  • 参数：dirPath（目录路径），recursive（是否递归删除）
  • 功能：同步删除目录，支持递归删除。

🦋2.10 复制文件

• 异步: copyFile
  • 参数：srcPath（源文件路径），destPath（目标文件路径），success（成功回调），fail（失败回调），complete（完成回调）
  • 功能：异步复制文件。
• 同步: copyFileSync
  • 参数：srcPath（源文件路径），destPath（目标文件路径）
  • 功能：同步复制文件。

🦋2.11 获取文件状态

• 异步: fstat
  • 参数：fd（文件描述符），success（成功回调），fail（失败回调），complete（完成回调）
  • 功能：异步获取文件状态，返回一个 Stats 对象。
• 同步: fstatSync
  • 参数：fd（文件描述符）
  • 功能：同步获取文件状态，返回一个 Stats 对象。

🦋2.12 获取文件信息

• 异步: getFileInfo
  • 参数：filePath（文件路径），success（成功回调），fail（失败回调），complete（完成回调）
  • 功能：异步获取文件的尺寸信息。
• 同步: getFileInfoSync
  • 参数：filePath（文件路径）
  • 功能：同步获取文件的尺寸信息。

🦋2.13 解压文件

• 异步: unzip
  • 参数：zipFilePath（压缩文件路径），targetPath（解压目标路径），success（成功回调），fail（失败回调），complete（完成回调）
  • 功能：异步解压文件（支持 .zip 格式）。
• 同步: unzipSync
  • 参数：zipFilePath（压缩文件路径），targetPath（解压目标路径）
  • 功能：同步解压文件（支持 .zip 格式）。

🔎3.文件标识符与打开文件方式

🦋3.1 文件标识符与操作方法

在文件操作中，有些方法可以直接通过文件路径操作文件，然而有些方法需要使用文件标识符（fd）来操作文件。对于需要使用文件标识符的操作，在执行之前必须先通过 open() 方法打开文件，获取文件标识符。

🦋3.2 打开文件 (open) 方法

通过 wx.getFileSystemManager().open() 方法打开文件时，可以设置 flag 参数，指定文件的打开方式。flag 参数用于限制文件的使用方式，不同的值有不同的含义，具体如下：

表 9-13：flag 参数的值及含义

🦋3.3 使用文件标识符

• 使用文件标识符 fd 时，首先需要通过 open() 方法打开文件并获取标识符。之后，调用需要文件标识符的操作方法，如 fstat(), read(), write() 等。
• 在操作完成后，必须通过 close() 方法关闭文件，释放资源。

🦋3.4 Stats 对象介绍

stat() 方法用于获取文件或目录的状态信息，返回一个 Stats 对象，该对象封装了文件的详细信息。

表 9-14：Stats 对象的属性

表 9-15：Stats 对象的方法

通过 Stats 对象可以获取到文件或目录的更多细节，如文件大小、权限以及最后修改时间等。

🦋3.4 readZipEntry 方法介绍

readZipEntry 方法用于读取压缩包中的文件，可以通过 entries 参数来指定读取的文件列表。

entries 参数

• 如果 entries 设置为字符串 "a"，则表示读取压缩包内的所有文件。
• 如果 entries 设置为一个对象数组，则可以更精确地控制要读取的文件内容。

表 9-16：entries 数组时可配置的属性

这些配置项允许开发者精准地控制要从压缩包中读取的文件内容，可以通过设置路径、编码方式以及读取位置来进行灵活的操作。