@mptool/file

Mr.Hope2025/10/30大约 4 分钟

文件 API

提示

请注意，框架会自动帮你添加 USER_DATA_PATH 作为前缀，因此你无需关注它。

ls(path: string): string[]
以数组形式列出目录下所有内容
readFile(path: string, encoding?: string): string | ArrayBuffer | undefined
读取指定路径的文件内容并返回。当文件不存在时，返回 undefined。
encoding 为文件的编码格式，可选，当文件为文本文件时默认 "utf-8"，为二进制文件时默认为 'buffer'
readJSON(path: string, encoding = 'utf-8'): any | undefined
读取可序列化文件数据并返回解析结果。
当 JSON 文件不存在或解析失败时，返回 undefined
- path: 读取的文件路径，不应含有 .json 后缀
- encoding: 文件的编码格式，可选，默认 utf-8

mkdir(path: string, recursive = false): void
创建目录。第二个参数 recursive可选，代表是否递归父目录。
rm(path: string, type?: "dir" | "file"): void
删除指定路径。
第二个参数 type 是可选的，可填入 "dir" 或 "file"，填入可提升删除性能
writeFile(path: string, data: any, encoding?: string): void
写入文件
- path: 待写入的文件路径，若文件或其父文件夹不存在会自动创建
- data: 待写入的数据，可接受任意可序列化的数据或 Buffer
- encoding: 文件编码选项，可选，默认 utf-8 (数据) 或 binary (Buffer)
writeJSON(path: string, data: any, encoding = 'utf-8'): void
写入可序列化数据为 JSON
- path: 写入文件的路径，若父文件夹不存在会自动创建
- data: 写入文件的数据，可接受任意可序列化的数据
- encoding: 文件编码选项，默认 utf-8
saveFile(tempFilePath: string, path: string): void
将缓存文件保存到本地文件存储。
- tempFilePath: 缓存文件路径
- path: 保存文件路径
saveOnlineFile(onlinePath: string, localPath: string): Promise<void>
将在线文件保存到本地指定位置
- onlinePath: 在线文件路径
- localPath: 本地文件路径
提示
保存目录会自动创建。
unzip(zipFilePath: string, targetPath: string): Promise<void>
解压文件
- zipFilePath: 待解压的压缩文件路径
- targetPath: 解压到的目录
提示
解压目录会自动创建。

put 和 take 可以存入任何数据，但存入的数据只能取出一次，且仅在当次小程序启动中有效。

提示

为了保证性能，以及由于小程序对 Function 进行了特殊处理，我们不会对存入的数据进行深拷贝。

put<T = unknown>(key: string, data: T): void: 存数据。
take<T = unknown>(key: string): T | undefined: 取数据
提示
当数据已经被取过一次后，后续返回 undefined。

get 和 set 设置的数据可持久化，且可以设置过期时间。

注意

请注意由于微信小程序底层上的问题，自动清除只发生在下一次读取并发现已经失效时，如果你没有后续读取对应的存储，它们会一直保存 (即使已经过期)。

所以如果你使用了大量临时的键值去存入数据，你可能需要定期通过 check 手动检查并清除过期数据。

set(key: string, value: any, expire?: number | 'once' | 'keep' = 'once'): void
同步设置数据。
- key: 设置的键名
- value: 存入的值
- expire: 过期时间，可选，默认为 'once'
  - 'once': 默认，表示仅本次启动有效
  - 'keep': 表示保持上一次有效时间
  - 数字: 已毫秒为单位的有效时间
  - 0: 永久有效
提示
请注意，如果传入 'keep' 时，存储中不存在同名键值，则该值也不会被写入。
setAsync(key: string, value: any, expire?: number | 'once' | 'keep' = 'once'): Promise<void>
set 的异步版本，在设置大量数据时可考虑使用，返回一个 Promise。
get<T = unknown>(key: string): T | undefined
同步读取数据并返回。
当数据已经过期时，返回 undefined。
- key: 设置的键名
getAsync<T = unknown>(key: string): Promise<T | undefined>
get 的异步版本，在读取大量数据避免阻塞线程时可考虑使用，返回一个 Promise。
- key: 设置的键名
remove(key: string): void
同步删除数据。
- key: 删除的键名
removeAsync(key: string): Promise<void>
异步删除数据，返回一个 Promise。
- key: 删除的键名
check(): void
同步检查并清理过期数据。
checkAsync(): Promise<void>
异步检查并清理过期数据，返回一个 Promise。