tencent cloud

文件
最后更新时间:2025-02-24 17:10:37
文件
最后更新时间: 2025-02-24 17:10:37

saveFile

该 API 使用方法为 wx.saveFile(Object object)
说明:
该 API 小程序支持,小游戏不支持。
注意:
本地文件存储的大小限制为 10M。
功能说明:保存文件到本地。
注意:
saveFile 会把临时文件移动,因此调用成功后传入的 tempFilePath 将不可用。
参数及说明:Object object
属性
类型
默认值
必填
说明
tempFilePath
string
-
需要保存的文件的临时路径
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
object.success 回调函数参数:Object res
属性
类型
说明
savedFilePath
string
存储后的文件路径
示例代码:
wx.chooseImage({
success(res) {
const tempFilePaths = res.tempFilePaths
wx.saveFile({
tempFilePath: tempFilePaths[0],
success(res) {
const savedFilePath = res.savedFilePath
}
})
}
})

removeSavedFile

该 API 使用方法为 wx.removeSavedFile(Object object)
说明:
该 API 小程序支持,小游戏不支持。
功能说明:删除本地缓存文件。
参数及说明:Object object
属性
类型
默认值
必填
说明
filePath
string
-
需要删除的文件路径
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
示例代码:
wx.getSavedFileList({
success(res) {
if (res.fileList.length > 0) {
wx.removeSavedFile({
filePath: res.fileList[0].filePath,
complete(res) {
console.log(res)
}
})
}
}
})

openDocument

该 API 使用方法为 wx.openDocument(Object object)
说明:
该 API 小程序支持,小游戏不支持。
功能说明:新开页面打开文档。
参数及说明:Object object
属性
类型
默认值
必填
说明
filePath
string
-
文件路径(本地路径),可通过 downloadFile 获得
fileType
string
-
文件类型,指定文件类型打开文件
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
object.fileType 的合法值
说明
pdf
pdf 格式
示例代码:
wx.downloadFile({
// 示例 url,并非真实存在
url: 'https://example.com/somefile.pdf',
success(res) {
const filePath = res.tempFilePath
wx.openDocument({
filePath,
success(res) {
console.log('打开文档成功')
}
})
}
})

getSavedFileList

该 API 使用方法为 wx.getSavedFileList(Object object)
说明:
该 API 小程序支持,小游戏不支持。
功能说明:获取该小程序下已保存的本地缓存文件列表。
参数及说明:Object object
属性
类型
默认值
必填
说明
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
object.success 回调函数参数:Object res
属性
类型
说明
fileList
Array.<Object>
文件数组,每一项是一个 FileItem
res.fileList 的结构
属性
类型
说明
filePath
string
本地路径
size
number
本地文件大小,以字节为单位
createTime
number
文件保存时的时间戳,从1970/01/01 08:00:00 到当前时间的秒数
示例代码:
wx.getSavedFileList({
success(res) {
console.log(res.fileList)
}
})

getSavedFilelnfo

该 API 使用方法为 wx.getSavedFileInfo(Object object)
说明:
该 API 小程序支持,小游戏不支持。
功能说明:获取本地文件的文件信息。此接口只能用于获取已保存到本地的文件,若需要获取临时文件信息,请使用 wx.getFileInfo() 接口。
参数及说明:Object object
属性
类型
默认值
必填
说明
filePath
string
-
文件路径
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
object.success 回调函数参数:Object res
属性
类型
说明
size
number
文件大小,单位 B
createTime
number
文件保存时的时间戳,从1970/01/01 08:00:00 到该时刻的秒数
示例代码:
wx.getSavedFileList({
success(res) {
console.log(res.fileList)
}
})

getFileInfo

该 API 使用方法为 wx.getFileInfo(Object object)
说明:
该 API 小程序支持,小游戏不支持。
功能说明:获取文件信息。
参数及说明:Object object
属性
类型
默认值
必填
说明
filePath
string
-
本地文件路径
digestAlgorithm
string
'md5'
计算文件摘要的算法
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
object.digestAlgorithm 的合法值
说明
md5
md5 算法
sha1
sha1 算法
object.success 回调函数参数:Object res
属性
类型
说明
size
number
文件大小,以字节为单位
digest
string
按照传入的 digestAlgorithm 计算得出的文件摘要
示例代码:
wx.getFileInfo({
success(res) {
console.log(res.size)
console.log(res.digest)
}
})

getFileSystemManager

该 API 使用方法为 FileSystemManager wx.getFileSystemManager()
功能说明:获取全局唯一的文件管理器。
返回值: FileSystemManager 文件管理器。

FileSystemManager

文件管理器,可通过 wx.getFileSystemManager 获取。


.access

该方法使用方式为 FileSystemManager.access(Object object)
功能说明:判断文件/目录是否存在。
参数及说明:Object object
属性
类型
默认值
必填
说明
path
string
-
要判断是否存在的文件/目录路径
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
object.fail 回调函数参数:Object res
属性
类型
说明
errMsg
string
错误信息
res.errMsg 的合法值
说明
fail no such file or directory ${path}
文件/目录不存在
bad file descriptor
无效的文件描述符
permission denied
权限错误,文件是只读或只写
permission denied, cannot access file path
目标路径无访问权限(usr目录)
not a directory
dirPath 指定路径不是目录,常见于指定的写入路径的上级路径为一个文件的情况
Invalid argument
无效参数,可以检查length或offset是否越界
directory not empty
目录不为空
the maximum size of the file storage limit is exceeded
存储空间不足,或文件大小超出上限(上限100M)
base64 encode error
字符编码转换失败(例如 base64 格式错误)
data to write is empty
写入数据为空
illegal operation on a directory
不可对目录进行此操作(例如,指定的 filePath 是一个已经存在的目录)
file already exists ${dirPath}
已有同名文件或目录
value of length is out of range
传入的 length 不合法
value of offset is out of range
传入的 offset 不合法
value of position is out of range
position值越界
示例代码:
const fs = wx.getFileSystemManager()
// 判断文件/目录是否存在
fs.access({
path: `${wx.env.USER_DATA_PATH}/hello.txt`,
success(res) {
// 文件存在
console.log(res)
},
fail(res) {
// 文件不存在或其他错误
console.error(res)
}
})

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


.accessSync

该方法使用方式为 FileSystemManager.accessSync(string path)
功能说明:FileSystemManager.access 的同步版本。
参数及说明:string path,要判断是否存在的文件/目录路径。
示例代码:
const fs = wx.getFileSystemManager()
// 判断文件/目录是否存在
fs.access({
path: `${wx.env.USER_DATA_PATH}/hello.txt`,
success(res) {
// 文件存在
console.log(res)
},
fail(res) {
// 文件不存在或其他错误
console.error(res)
}
})

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


.appendFile

该方法使用方式为 FileSystemManager.appendFile(Object object)
功能说明:在文件结尾追加内容。
参数及说明:Object object
属性
类型
默认值
必填
说明
filePath
string
-
要追加内容的文件路径
data
string/ArrayBuffer
-
要追加的文本或二进制数据
encoding
string
utf-8
指定写入文件的字符编码
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
object.encoding 的合法值
说明
ascii
-
base64
-
binary
-
hex
-
ucs2/ucs-2/utf16le/utf-16le
以小端序读取
utf-8/utf8
-
latin1
-
object.fail 回调函数参数:Object res
属性
类型
说明
errMsg
string
错误信息
res.errMsg 的合法值
说明
fail no such file or directory, open ${filePath}
指定的 filePath 文件不存在
fail illegal operation on a directory, open "${filePath}"
指定的 filePath 是一个已经存在的目录
fail permission denied, open ${dirPath}
指定的 filePath 路径没有写权限
fail sdcard not mounted
android sdcard 挂载失败
示例代码:
const fs = wx.getFileSystemManager()

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

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


.appendFileSync

该方法使用方式为 FileSystemManager.appendFileSync(string filePath, string|ArrayBuffer data, string encoding)
功能说明:FileSystemManager.appendFile 的同步版本。
参数及说明
string filePath:要追加内容的文件路径。
string|ArrayBuffer data:要追加的文本或二进制数据。
string encoding:指定写入文件的字符编码。
encoding 的合法值
说明
ascii
-
base64
-
binary
-
hex
-
ucs2/ucs-2/utf16le/utf-16le
以小端序读取
utf-8/utf8
-
latin1
-
示例代码:
const fs = wx.getFileSystemManager()

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

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


.close

该方法使用方式为 FileSystemManager.close(Object object)
说明:
该 API 小程序支持,小游戏暂不支持。
功能说明:关闭文件。
参数及说明:Object object
属性
类型
默认值
必填
说明
fd
string
-
需要被关闭的文件描述符。fd 通过 FileSystemManager.openFileSystemManager.openSync 接口获得
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
示例代码
const fs = wx.getFileSystemManager()
// 打开文件
fs.open({
filePath: `${wx.env.USER_DATA_PATH}/hello.txt`,
flag: 'a+',
success(res) {
// 关闭文件
fs.close({
fd: res.fd
})
}
})


.closeSync

该方法使用方式为 undefined FileSystemManager.closeSync(Object object)
说明:
该 API 小程序支持,小游戏暂不支持。
功能说明:同步关闭文件。
参数及说明:Object object
属性
类型
默认值
必填
说明
fd
string
-
需要被关闭的文件描述符。fd 通过 FileSystemManager.openFileSystemManager.openSync 接口获得
返回值:undefined。
示例代码
const fs = wx.getFileSystemManager()
const fd = fs.openSync({
filePath: `${wx.env.USER_DATA_PATH}/hello.txt`,
flag: 'a+'
})

// 关闭文件
fs.closeSync({fd: fd})


.copyFile

该方法使用方式为 FileSystemManager.copyFile(Object object)
功能说明:复制文件。
参数及说明:Object object
属性
类型
默认值
必填
说明
srcPath
string
-
源文件路径,只可以是普通文件
destPath
string
-
目标文件路径,支持本地路径
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
object.fail 回调函数参数:Object res
属性
类型
说明
errMsg
string
错误信息
res.errMsg 的合法值
说明
fail permission denied, copyFile ${srcPath} -> ${destPath}
指定目标文件路径没有写权限
fail no such file or directory, copyFile ${srcPath} -> ${destPath}
源文件不存在,或目标文件路径的上层目录不存在
示例代码:
const fs = wx.getFileSystemManager()
fs.copyFile({
srcPath: `${wx.env.USER_DATA_PATH}/hello.txt`,
destPath: `${wx.env.USER_DATA_PATH}/hello_copy.txt`
success(res) {
console.log(res)
},
fail(res) {
console.error(res)
}
})

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


.copyFileSync

该方法使用方式为 FileSystemManager.copyFileSync(string srcPath, string destPath)
功能说明:FileSystemManager.copyFile 的同步版本。
参数及说明:
string srcPath:源文件路径,只可以是普通文件。
string destPath:目标文件路径。
示例代码:
const fs = wx.getFileSystemManager()
fs.copyFile({
srcPath: `${wx.env.USER_DATA_PATH}/hello.txt`,
destPath: `${wx.env.USER_DATA_PATH}/hello_copy.txt`
success(res) {
console.log(res)
},
fail(res) {
console.error(res)
}
})

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


.getFileInfo

该方法使用方式为 FileSystemManager.getFileInfo(Object object)
功能说明:获取该小程序下的 本地临时文件 或 本地缓存文件 信息。
参数及说明:Object object
属性
类型
默认值
必填
说明
filePath
string
-
要读取的文件路径
digestAlgorithm
string
md5
计算文件摘要的算法
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
object.digestAlgorithm 的合法值
说明
md5
md5 算法
sha1
sha1 算法
object.success 回调函数参数:Object res
属性
类型
说明
size
number
文件大小,以字节为单位
digest
string
按照传入的 digestAlgorithm 计算得出的的文件摘要
object.fail 回调函数参数:Object res
属性
类型
说明
errMsg
string
错误信息
res.errMsg 的合法值
说明
fail file not exist
指定的 filePath 找不到文件
no such file or directory ${path}
文件/目录不存在,或者目标文件路径的上层目录不存在
Input/output error
输入输出流不可用
permission denied
权限错误,文件是只读或只写
Path permission denied
传入的路径没有权限
not a directory
dirPath 指定路径不是目录,常见于指定的写入路径的上级路径为一个文件的情况
Invalid argument
无效参数,可以检查length或offset是否越界
excced max concurrent fd limit
fd数量已达上限


.fstat

该方法使用方式为 FileSystemManager.fstat(Object object)
说明:
该 API 小程序支持,小游戏暂不支持。
功能说明:获取文件的状态信息。
参数及说明:Object object
属性
类型
默认值
必填
说明
fd
string
-
文件描述符。fd 通过 FileSystemManager.openFileSystemManager.openSync 接口获得
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
object.success 回调函数参数:Object res
属性
类型
说明
stats
Stats
Stats 对象,包含了文件的状态信息
示例代码:
const fs = wx.getFileSystemManager()
// 打开文件
fs.open({
filePath: `${wx.env.USER_DATA_PATH}/hello.txt`,
flag: 'a+',
success(res) {
// 获取文件的状态信息
fs.fstat({
fd: res.fd,
success(res) {
console.log(res.stats)
}
})
}
})


.fstatSync

该方法使用方式为 Stats FileSystemManager.fstatSync(Object object)
说明:
该 API 小程序支持,小游戏暂不支持。
功能说明:同步获取文件的状态信息。
参数及说明:Object object
属性
类型
默认值
必填
说明
fd
string
-
文件描述符。fd 通过 FileSystemManager.openFileSystemManager.openSync 接口获得
返回值:Stats,Stats 对象,包含了文件的状态信息。
示例代码:
const fs = wx.getFileSystemManager()
const fd = fs.openSync({
filePath: `${wx.env.USER_DATA_PATH}/hello.txt`,
flag: 'a+'
})
const stats = fs.fstatSync({fd: fd})
console.log(stats)


.ftruncate

该方法使用方式为 FileSystemManager.ftruncate(Object object)
说明:
该 API 小程序支持,小游戏暂不支持。
功能说明:对文件内容进行截断操作。
参数及说明:Object object
属性
类型
默认值
必填
说明
fd
string
-
文件描述符。fd 通过 FileSystemManager.openFileSystemManager.openSync 接口获得
length
number
-
截断位置,默认0。如果 length 小于文件长度(单位:字节),则只有前面 length 个字节会保留在文件中,其余内容会被删除;如果 length 大于文件长度,则会对其进行扩展,并且扩展部分将填充空字节('\\0')
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
示例代码:
const fs = wx.getFileSystemManager()
// 打开文件
fs.open({
filePath: `${wx.env.USER_DATA_PATH}/hello.txt`,
flag: 'a+',
success(res) {
// 对文件内容进行截断操作
fs.ftruncate({
fd: res.fd,
length: 10, // 从第10个字节开始截断文件
success(res) {
console.log(res)
}
})
}
})


.ftruncateSync

该方法使用方式为 undefined FileSystemManager.ftruncateSync(Object object)
说明:
该 API 小程序支持,小游戏暂不支持。
功能说明:对文件内容进行截断操作。
参数及说明:Object object
属性
类型
默认值
必填
说明
fd
string
-
文件描述符。fd 通过 FileSystemManager.openFileSystemManager.openSync 接口获得
length
number
-
截断位置,默认0。如果 length 小于文件长度(单位:字节),则只有前面 length 个字节会保留在文件中,其余内容会被删除;如果 length 大于文件长度,则会对其进行扩展,并且扩展部分将填充空字节('\\0')
返回值:undefined
示例代码:
const fs = wx.getFileSystemManager()
const fd = fs.openSync({
filePath: `${wx.env.USER_DATA_PATH}/hello.txt`,
flag: 'a+'
})
fs.ftruncateSync({
fd: fd,
length: 10 // 从第10个字节开始截断文件
})


.getSavedFileList

该方法使用方式为 FileSystemManager.getSavedFileList(Object object)
功能说明:获取该小程序下已保存的本地缓存文件列表。
参数及说明:Object object
属性
类型
默认值
必填
说明
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
object.success 回调函数参数:Object res
属性
类型
说明
fileList
Array.<Object>
文件数组
res.fileList 的结构
属性
类型
说明
filePath
string
本地路径
size
number
本地文件大小,以字节为单位
createTime
number
文件保存时的时间戳,从1970/01/01 08:00:00 到当前时间的秒数


.mkdir

该方法使用方式为 FileSystemManager.mkdir(Object object)
功能说明:创建目录。
参数及说明:Object object
属性
类型
默认值
必填
说明
dirPath
string
-
创建的目录路径
recursive
boolean
false
是否在递归创建该目录的上级目录后再创建该目录。如果对应的上级目录已经存在,则不创建该上级目录。如 dirPath 为 a/b/c/d 且 recursive 为 true,将创建 a 目录,再在 a 目录下创建 b 目录,以此类推直至创建 a/b/c 目录下的 d 目录。
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
object.fail 回调函数参数:Object res
属性
类型
说明
errMsg
string
错误信息
res.errMsg 的合法值
说明
fail no such file or directory ${dirPath}
上级目录不存在
fail permission denied, open ${dirPath}
指定的 filePath 路径没有写权限
fail file already exists ${dirPath}
有同名文件或目录
示例代码:
const fs = wx.getFileSystemManager()
fs.mkdir({
dirPath: `${wx.env.USER_DATA_PATH}/example`,
recursive: false,
success(res) {
console.log(res)
},
fail(res) {
console.error(res)
}
})

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


.mkdirSync

该方法使用方式为 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 = wx.getFileSystemManager()
fs.mkdir({
dirPath: `${wx.env.USER_DATA_PATH}/example`,
recursive: false,
success(res) {
console.log(res)
},
fail(res) {
console.error(res)
}
})

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


.open

该方法使用方式为 FileSystemManager.open(Object object)
说明:
该 API 小程序支持,小游戏暂不支持。
功能说明:打开文件,返回文件描述符。
参数及说明:Object object
属性
类型
默认值
必填
说明
filePath
string
-
文件路径(本地路径)
flag
string
r
文件系统标志,默认值:r
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
flag 合法值
合法值
说明
a
打开文件用于追加。 如果文件不存在,则创建该文件
ax
类似于 'a',但如果路径存在,则失败
a+
打开文件用于读取和追加。 如果文件不存在,则创建该文件
ax+
类似于 'a+',但如果路径存在,则失败
as
打开文件用于追加(在同步模式中)。 如果文件不存在,则创建该文件
as+
打开文件用于读取和追加(在同步模式中)。 如果文件不存在,则创建该文件
r
打开文件用于读取。 如果文件不存在,则会发生异常
r+
打开文件用于读取和写入。 如果文件不存在,则会发生异常
w
打开文件用于写入。 如果文件不存在则创建文件,如果文件存在则截断文件
wx
类似于 'w',但如果路径存在,则失败
w+
打开文件用于读取和写入。 如果文件不存在则创建文件,如果文件存在则截断文件
wx+
类似于 'w+',但如果路径存在,则失败
object.success 回调函数参数:Object res
属性
类型
说明
fd
string
文件描述符
示例代码:
const fs = wx.getFileSystemManager()
fs.open({
filePath: `${wx.env.USER_DATA_PATH}/hello.txt`,
flag: 'a+',
success(res) {
console.log(res.fd)
}
})


.openSync

该方法使用方式为 string FileSystemManager.openSync(Object object)
说明:
该 API 小程序支持,小游戏暂不支持。
功能说明:同步打开文件,返回文件描述符。
参数及说明:Object object
属性
类型
默认值
必填
说明
filePath
string
-
文件路径(本地路径)
flag
string
r
文件系统标志,默认值:r
flag 合法值
合法值
说明
a
打开文件用于追加。 如果文件不存在,则创建该文件
ax
类似于 'a',但如果路径存在,则失败
a+
打开文件用于读取和追加。 如果文件不存在,则创建该文件
ax+
类似于 'a+',但如果路径存在,则失败
as
打开文件用于追加(在同步模式中)。 如果文件不存在,则创建该文件
as+
打开文件用于读取和追加(在同步模式中)。 如果文件不存在,则创建该文件
r
打开文件用于读取。 如果文件不存在,则会发生异常
r+
打开文件用于读取和写入。 如果文件不存在,则会发生异常
w
打开文件用于写入。 如果文件不存在则创建文件,如果文件存在则截断文件
wx
类似于 'w',但如果路径存在,则失败
w+
打开文件用于读取和写入。 如果文件不存在则创建文件,如果文件存在则截断文件
wx+
类似于 'w+',但如果路径存在,则失败
返回值:string,文件描述符。
示例代码:
const fs = wx.getFileSystemManager() const fd = fs.openSync({ filePath: `${wx.env.USER_DATA_PATH}/hello.txt`, flag: 'a+' }) console.log(fd)


.read

该方法使用方式为 FileSystemManager.read(Object object)
说明:
该 API 小程序支持,小游戏暂不支持。
功能说明:读文件。
参数及说明:Object object
属性
类型
默认值
必填
说明
fd
string
-
文件描述符。fd 通过 FileSystemManager.openFileSystemManager.openSync 接口获得
arrayBuffer
ArrayBuffer
-
数据写入的缓冲区,必须是 ArrayBuffer 实例
offset
number
0
缓冲区中的写入偏移量,默认0
length
number
0
要从文件中读取的字节数,默认0
position
number
-
文件读取的起始位置,如不传或传 null,则会从当前文件指针的位置读取。如果 position 是正整数,则文件指针位置会保持不变并从 position 读取文件。
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
object.success 回调函数参数:Object res
属性
类型
说明
bytesRead
number
实际读取的字节数
arrayBuffer
ArrayBuffer
被写入的缓存区的对象,即接口入参的 arrayBuffer
示例代码:
const fs = wx.getFileSystemManager()
const ab = new ArrayBuffer(1024)
// 打开文件
fs.open({
filePath: `${wx.env.USER_DATA_PATH}/hello.txt`,
flag: 'a+',
success(res) {
// 读取文件到 ArrayBuffer 中
fs.read({
fd: res.fd,
arrayBuffer: ab,
length: 10,
success(res) {
console.log(res)
}
})
}
})


.readSync

该方法使用方式为 ReadResult FileSystemManager.readSync(Object object)
说明:
该 API 小程序支持,小游戏暂不支持。
功能说明:读文件。
参数及说明:Object object
属性
类型
默认值
必填
说明
fd
string
-
文件描述符。fd 通过 FileSystemManager.openFileSystemManager.openSync 接口获得
arrayBuffer
ArrayBuffer
-
数据写入的缓冲区,必须是 ArrayBuffer 实例
offset
number
0
缓冲区中的写入偏移量,默认0
length
number
0
要从文件中读取的字节数,默认0
position
number
-
文件读取的起始位置,如不传或传 null,则会从当前文件指针的位置读取。如果 position 是正整数,则文件指针位置会保持不变并从 position 读取文件
返回值:ReadResult,文件读取结果。
示例代码:
const fs = wx.getFileSystemManager()
const ab = new ArrayBuffer(1024)
const fd = fs.openSync({
filePath: `${wx.env.USER_DATA_PATH}/hello.txt`,
flag: 'a+'
})
const res = fs.readSync({
fd: fd,
arrayBuffer: ab,
length: 10
})
console.log(res)


.readCompressedFile

该方法使用方式为 FileSystemManager.readCompressedFile(Object object)
说明:
该 API 小程序支持,小游戏暂不支持。
功能说明:读取指定压缩类型的本地文件内容。
参数及说明:Object object
属性
类型
默认值
必填
说明
filePath
string
-
要读取的文件的路径 (本地用户文件或代码包文件)
compressionAlgorithm
string
-
文件压缩类型,目前仅支持 br
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
object.compressionAlgorithm 的合法值如下:
合法值
说明
br
brotli压缩文件
object.success 回调函数参数:Object res
属性
类型
说明
data
ArrayBuffer
文件内容
示例代码:
const fs = wx.getFileSystemManager()

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

// 同步接口
const data = fs.readCompressedFileSync({
filePath: '${wx.env.USER_DATA_PATH}/hello.br',
compressionAlgorithm: 'br',
})
console.log(data)


.readCompressedFileSync

该方法使用方式为 ArrayBuffer FileSystemManager.readCompressedFileSync(Object object)
说明:
该 API 小程序支持,小游戏暂不支持。
功能说明:同步读取指定压缩类型的本地文件内容。
参数及说明:Object object
属性
类型
默认值
必填
说明
filePath
string
-
要读取的文件的路径 (本地用户文件或代码包文件)
compressionAlgorithm
string
-
文件压缩类型,目前仅支持 br
object.compressionAlgorithm 的合法值如下:
合法值
说明
br
brotli压缩文件
返回值:ArrayBuffer,文件读取结果。
示例代码:
const fs = wx.getFileSystemManager()

// 异步接口
fs.readCompressedFile({
filePath: '${wx.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: '${wx.env.USER_DATA_PATH}/hello.br',
compressionAlgorithm: 'br',
})
console.log(data)
} catch (err) {
console.log(err)
}


.readdir

该方法使用方式为 FileSystemManager.readdir(Object object)
功能说明:读取目录内文件列表。
参数及说明:Object object
属性
类型
默认值
必填
说明
dirPath
string
-
要读取的目录路径
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
object.success 回调函数参数:Object res
属性
类型
说明
files
Array.<string>
指定目录下的文件名数组。
object.fail 回调函数参数:Object res
属性
类型
说明
errMsg
string
错误信息
res.errMsg 的合法值
说明
fail no such file or directory ${dirPath}
目录不存在
fail not a directory ${dirPath}
dirPath 不是目录
fail permission denied, open ${dirPath}
指定的 filePath 路径没有读权限
示例代码:
注意:
readdir接口无法访问文件系统根路径(wxfile://)。
const fs = wx.getFileSystemManager()
fs.readdir({
dirPath: `${wx.env.USER_DATA_PATH}/example`,
success(res) {
console.log(res.files)
},
fail(res) {
console.error(res)
}
})

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


.readdirSync

该方法使用方式为 Array.<string> FileSystemManager.readdirSync(string dirPath)
功能说明:FileSystemManager.readdir 的同步版本。
参数及说明:string dirPath,要读取的目录路径。
返回值:Array.<string>  files,指定目录下的文件名数组。
示例代码:
const fs = wx.getFileSystemManager()
fs.readdir({
dirPath: `${wx.env.USER_DATA_PATH}/example`,
success(res) {
console.log(res.files)
},
fail(res) {
console.error(res)
}
})

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


.readFile

该方法使用方式为 FileSystemManager.readFile(Object object)
功能说明:读取本地文件内容。单个文件大小上限为100M。
参数及说明:Object object
属性
类型
默认值
必填
说明
filePath
string
-
要读取的文件的路径
encoding
string
-
指定读取文件的字符编码,如果不传 encoding,则以 ArrayBuffer 格式读取文件的二进制内容
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
object.encoding 的合法值
说明
ascii
-
base64
-
binary
-
hex
-
ucs2/ucs-2/utf16le/utf-16le
以小端序读取
utf-8/utf8
-
latin1
-
object.success 回调函数参数:Object res
属性
类型
说明
data
string/ArrayBuffer
文件内容
object.fail 回调函数参数:Object res
属性
类型
说明
errMsg
string
错误信息
res.errMsg 的合法值
说明
fail no such file or directory, open ${filePath}
指定的 filePath 所在目录不存在
fail permission denied, open ${dirPath}
指定的 filePath 路径没有读权限
示例代码:
const fs = wx.getFileSystemManager()
fs.readFile({
filePath: `${wx.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(`${wx.env.USER_DATA_PATH}/hello.txt`, 'utf8', 0)
console.log(res)
} catch(e) {
console.error(e)
}


.readFileSync

该方法使用方式为 string|ArrayBuffer FileSystemManager.readFileSync(string filePath, string encoding)
说明:
该 API 小程序支持,小游戏暂不支持。
功能说明:FileSystemManager.readFile 的同步版本。
参数及说明:
string filePath:要读取的文件的路径。
string encoding:指定读取文件的字符编码,如果不传 encoding,则以 ArrayBuffer 格式读取文件的二进制内容。
encoding 的合法值
说明
ascii
-
base64
-
binary
-
hex
-
ucs2/ucs-2/utf16le/utf-16le
以小端序读取
utf-8/utf8
-
latin1
-
返回值:string|ArrayBuffer data,文件内容。
示例代码:
const fs = wx.getFileSystemManager()
fs.readFile({
filePath: `${wx.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(`${wx.env.USER_DATA_PATH}/hello.txt`, 'utf8', 0)
console.log(res)
} catch(e) {
console.error(e)
}


.readZipEntry

该方法使用方式为 FileSystemManager.readZipEntry(Object object)
功能说明:读取压缩包内的文件。
参数及说明:Object object
属性
类型
默认值
必填
说明
filePath
string
-
要读取的压缩包的路径 (本地路径)
encoding
string
-
统一指定读取文件的字符编码,只在 entries 值为"all"时有效。如果 entries 值为"all"且不传 encoding,则以 ArrayBuffer 格式读取文件的二进制内容
entries
Array.<Object>/'all'
-
要读取的压缩包内的文件列表(当传入"all" 时表示读取压缩包内所有文件)
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)

encoding 合法值

说明
ascii
-
base64
-
binary
-
hex
-
ucs2/ucs-2/utf16le/utf-16le
以小端序读取
utf-8/utf8
-
latin1
-

entries 结构属性
结构属性
类型
默认值
必填
说明
path
string
-
压缩包内文件路径
encoding
string
-
指定读取文件的字符编码,如果不传 encoding,则以 ArrayBuffer 格式读取文件的二进制内容, 合法取值同 encoding
position
number
-
从文件指定位置开始读,如果不指定,则从文件头开始读。读取的范围应该是左闭右开区间 [position, position+length)。有效范围:[0, fileLength - 1]。单位:byte
length
number
-
指定文件的长度,如果不指定,则读到文件末尾。有效范围:[1, fileLength]。单位:byte
object.success 回调函数参数:Object res
属性
类型
说明
entries
Object
文件读取结果。res.entries 是一个对象,key是文件路径,value是一个对象 FileItem ,表示该文件的读取结果。每个 FileItem 包含 data (文件内容) 和 errMsg (错误信息) 属性
entries 结构属性
结构属性
类型
说明
path
string
文件路径
path 结构属性
结构属性
类型
说明
data
string/ArrayBuffer
文件内容
errMsg
string
错误信息
示例代码:
const fs = wx.getFileSystemManager()
// 读取zip内某个或多个文件
fs.readZipEntry({
filePath: 'wxfile://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)
// res.entries === {
// 'some_folder/my_file.txt': {
// errMsg: 'readZipEntry:ok',
// data: 'xxxxxx'
// },
// 'other_folder/orther_file.txt': {
// data: (ArrayBuffer)
// }
// }
},
fail(res) {
console.log(res.errMsg)
},
})

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


.removeSavedFile

该方法使用方式为 FileSystemManager.removeSavedFile(Object object)
功能说明:删除该小程序下已保存的本地缓存文件。
参数及说明:Object object
属性
类型
默认值
必填
说明
filePath
string
-
需要删除的文件路径
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
object.fail 回调函数参数:Object res
属性
类型
说明
errMsg
string
错误信息
res.errMsg 的合法值
说明
fail file not exist
指定的 tempFilePath 找不到文件


.rename

该方法使用方式为 FileSystemManager.rename(Object object)
功能说明:重命名文件。可以把文件从 oldPath 移动到 newPath。
参数及说明:Object object
属性
类型
默认值
必填
说明
oldPath
string
-
源文件路径,可以是普通文件或目录,支持本地路径
newPath
string
-
新文件路径,支持本地路径
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
object.fail 回调函数参数:Object res
属性
类型
说明
errMsg
string
错误信息
res.errMsg 的合法值
说明
fail permission denied, rename ${oldPath} -> ${newPath}
指定源文件或目标文件没有写权限
fail no such file or directory, rename ${oldPath} -> ${newPath}
源文件不存在,或目标文件路径的上层目录不存在
示例代码:
const fs = wx.getFileSystemManager()
fs.rename({
oldPath: `${wx.env.USER_DATA_PATH}/hello.txt`,
newPath: `${wx.env.USER_DATA_PATH}/hello_new.txt`,
success(res) {
console.log(res)
},
fail(res) {
console.error(res)
}
})

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


.renameSync

该方法使用方式为 FileSystemManager.renameSync(string oldPath, string newPath)
功能说明:FileSystemManager.rename 的同步版本。
参数及说明
string oldPath:源文件路径,可以是普通文件或目录,支持本地路径。
string newPath:新文件路径,支持本地路径。
示例代码:
const fs = wx.getFileSystemManager()
fs.rename({
oldPath: `${wx.env.USER_DATA_PATH}/hello.txt`,
newPath: `${wx.env.USER_DATA_PATH}/hello_new.txt`,
success(res) {
console.log(res)
},
fail(res) {
console.error(res)
}
})

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


.rmdir

该方法使用方式为 FileSystemManager.rmdir(Object object)
功能说明:删除目录。
参数及说明:Object object
属性
类型
默认值
必填
说明
dirPath
string
-
要删除的目录路径
recursive
boolean
false
是否递归删除目录。如果为 true,则删除该目录和该目录下的所有子目录以及文件。
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
object.fail 回调函数参数:Object res
属性
类型
说明
errMsg
string
错误信息
res.errMsg 的合法值
说明
fail no such file or directory ${dirPath}
目录不存在
fail directory not empty
目录不为空
fail permission denied, open ${dirPath}
指定的 dirPath 路径没有写权限
示例代码:
const fs = wx.getFileSystemManager()
fs.rmdir({
dirPath: `${wx.env.USER_DATA_PATH}/example`,
recursive: false,
success(res) {
console.log(res)
},
fail(res) {
console.error(res)
}
})

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


.rmdirSync

该方法使用方式为 FileSystemManager.rmdirSync(string dirPath, boolean recursive)
功能说明:FileSystemManager.rmdir 的同步版本。
参数及说明:
string dirPath:要删除的目录路径。
boolean recursive:是否递归删除目录。如果为 true,则删除该目录和该目录下的所有子目录以及文件。
示例代码:
const fs = wx.getFileSystemManager()
fs.rmdir({
dirPath: `${wx.env.USER_DATA_PATH}/example`,
recursive: false,
success(res) {
console.log(res)
},
fail(res) {
console.error(res)
}
})

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


.saveFile

该方法使用方式为 FileSystemManager.saveFile(Object object)
功能说明:保存临时文件到本地。此接口会移动临时文件,因此调用成功后,tempFilePath 将不可用。
参数及说明:Object object
属性
类型
默认值
必填
说明
tempFilePath
string
-
临时存储文件路径
filePath
string
-
要存储的文件路径
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
object.success 回调函数参数:Object res
属性
类型
说明
savedFilePath
number
存储后的文件路径
object.fail 回调函数参数:Object res
属性
类型
说明
errMsg
string
错误信息
res.errMsg 的合法值
说明
fail tempFilePath file not exist
指定的 tempFilePath 找不到文件
fail permission denied, open "${filePath}"
指定的 filePath 路径没有写权限
fail no such file or directory "${dirPath}"
上级目录不存在


.saveFileSync

该方法使用方式为 number FileSystemManager.saveFileSync(string tempFilePath, string filePath)
功能说明:FileSystemManager.saveFile 的同步版本。
参数及说明:
string tempFilePath:临时存储文件路径。
string filePath:要存储的文件路径。
返回值:number savedFilePath,存储后的文件路径。


.stat

该方法使用方式为 FileSystemManager.stat(Object object)
功能说明:获取文件 Stats 对象。
参数及说明:Object object
属性
类型
默认值
必填
说明
path
string
-
文件/目录路径
recursive
boolean
false
是否递归获取目录下的每个文件的 Stats 信息
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
object.success 回调函数参数:Object res
属性
类型
说明
stats
Stats/Object
当 recursive 为 false 时,res.stats 是一个 Stats 对象。当 recursive 为 true 且 path 是一个目录的路径时,res.stats 是一个 Object,key 以 path 为根路径的相对路径,value 是该路径对应的 Stats 对象。
object.fail 回调函数参数:Object res
属性
类型
说明
errMsg
string
错误信息
res.errMsg 的合法值
说明
fail permission denied, open ${path}
指定的 path 路径没有读权限
fail no such file or directory ${path}
文件不存在
示例代码:
recursive 为 false 时
// 异步版本
let fs = wx.getFileSystemManager()
fs.stat({
path: `${wx.env.USER_DATA_PATH}/testDir`,
success: res => {
console.log(res.stats.isDirectory())
}
})
// 同步版本
fs.statSync(`${wx.env.USER_DATA_PATH}/testDir`, false)
recursive 为 true 时
let fs = wx.getFileSystemManager()
// 异步版本
fs.stat({
path: `${wx.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(`${wx.env.USER_DATA_PATH}/testDir`, true)


.statSync

该方法使用方式为 Stats|Object FileSystemManager.statSync(string path, boolean recursive)
功能说明:FileSystemManager.stat 的同步版本。
参数及说明:
string path:文件/目录路径。
boolean recursive:是否递归获取目录下的每个文件的 Stats 信息。
返回值:Stats|Object stats,当 recursive 为 false 时,res.stats 是一个 Stats 对象。当 recursive 为 true 且 path 是一个目录的路径时,res.stats 是一个 Object,key 以 path 为根路径的相对路径,value 是该路径对应的 Stats 对象。
示例代码:
recursive 为 false 时
// 异步版本
let fs = wx.getFileSystemManager()
fs.stat({
path: `${wx.env.USER_DATA_PATH}/testDir`,
success: res => {
console.log(res.stats.isDirectory())
}
})
// 同步版本
fs.statSync(`${wx.env.USER_DATA_PATH}/testDir`, false)
recursive 为 true 时
let fs = wx.getFileSystemManager()
// 异步版本
fs.stat({
path: `${wx.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(`${wx.env.USER_DATA_PATH}/testDir`, true)


.truncate

该方法使用方式为 FileSystemManager.truncate(Object object)
说明:
该 API 小程序支持,小游戏暂不支持。
功能说明:对文件内容进行截断操作。
参数及说明:Object object
属性
类型
默认值
必填
说明
filePath
string
-
要截断的文件路径 (本地路径)
length
number
0
截断位置,默认0。如果 length 小于文件长度(字节),则只有前面 length 个字节会保留在文件中,其余内容会被删除;如果 length 大于文件长度,则会对其进行扩展,并且扩展部分将填充空字节('\\0')
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
示例代码:
const fs = wx.getFileSystemManager()
fs.truncate({
filePath: `${wx.env.USER_DATA_PATH}/hello.txt`,
length: 10, // 从第10个字节开始截断
success(res) {
console.log(res)
}
})


.truncateSync

该方法使用方式为 undefined FileSystemManager.truncateSync(Object object)
说明:
该 API 小程序支持,小游戏暂不支持。
功能说明:对文件内容进行截断操作 (truncate 的同步版本)
参数及说明:Object object
属性
类型
默认值
必填
说明
filePath
string

要截断的文件路径 (本地路径)
length
number
0
截断位置,默认0。如果 length 小于文件长度(字节),则只有前面 length 个字节会保留在文件中,其余内容会被删除;如果 length 大于文件长度,则会对其进行扩展,并且扩展部分将填充空字节('\\0')
返回值:undefined。
示例代码:
const fs = wx.getFileSystemManager()
fs.truncateSync({
filePath: `${wx.env.USER_DATA_PATH}/hello.txt`,
length: 10, // 从第10个字节开始截断
})

该方法使用方式为 FileSystemManager.unlink(Object object)
功能说明:删除文件。
参数及说明:Object object
属性
类型
默认值
必填
说明
filePath
string
-
要删除的文件路径
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
object.fail 回调函数参数:Object res
属性
类型
说明
errMsg
string
错误信息
res.errMsg 的合法值
说明
fail permission denied, open ${path}
指定的 path 路径没有读权限
fail no such file or directory ${path}
文件不存在
fail operation not permitted, unlink ${filePath}
传入的 filePath 是一个目录
示例代码:
const fs = wx.getFileSystemManager()
fs.unlink({
filePath: `${wx.env.USER_DATA_PATH}/hello.txt`,
success(res) {
console.log(res)
},
fail(res) {
console.error(res)
}
})

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


.unlinkSync

该方法使用方式为 FileSystemManager.unlinkSync(string filePath)
功能说明:FileSystemManager.unlink 的同步版本。
参数及说明:string filePath,要删除的文件路径。
示例代码:
const fs = wx.getFileSystemManager()
fs.unlink({
filePath: `${wx.env.USER_DATA_PATH}/hello.txt`,
success(res) {
console.log(res)
},
fail(res) {
console.error(res)
}
})

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


.unzip

该方法使用方式为 FileSystemManager.unzip(Object object)
功能说明:解压文件。
参数及说明:Object object
属性
类型
默认值
必填
说明
zipFilePath
string
-
源文件路径,只可以是 zip 压缩文件
targetPath
string
-
目标目录路径
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
object.fail 回调函数参数:Object res
属性
类型
说明
errMsg
string
错误信息
res.errMsg 的合法值
说明
fail permission denied, unzip ${zipFilePath} -> ${destPath}
指定目标文件路径没有写权限
fail no such file or directory, unzip ${zipFilePath} -> ${destPath}
源文件不存在,或目标文件路径的上层目录不存在
示例代码:
const fs = wx.getFileSystemManager()
fs.unzip({
zipFilePath: `${wx.env.USER_DATA_PATH}/example.zip`,
targetPath: '${wx.env.USER_DATA_PATH}/example',
success(res) {
console.log(res)
},
fail(res) {
console.error(res)
}
})


.write

该方法使用方式为 FileSystemManager.write(Object object)
说明:
该 API 小程序支持,小游戏暂不支持。
功能说明:写入文件。
参数及说明:Object object
属性
类型
默认值
必填
说明
fd
string
-
文件描述符。fd 通过 FileSystemManager.openFileSystemManager.openSync 接口获得
data
string/ArrayBuffer
-
要写入的文本或二进制数据
offset
number
0
只在 data 类型是 ArrayBuffer 时有效,决定 arrayBuffe 中要被写入的部位,即 arrayBuffer 中的索引,默认0
length
number
-
只在 data 类型是 ArrayBuffer 时有效,指定要写入的字节数,默认为 arrayBuffer 从0开始偏移 offset 个字节后剩余的字节数
encoding
string
utf8
指定写入文件的字符编码
position
number
-
指定文件开头的偏移量,即数据要被写入的位置。当 position 不传或者传入非 Number 类型的值时,数据会被写入当前指针所在位置
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
encoding 合法值
说明
ascii
-
base64
-
binary
-
hex
-
ucs2/ucs-2/utf16le/utf-16le
以小端序读取
utf-8/utf8
-
latin1
-
object.success 回调函数参数:Object res
属性
类型
说明
bytesWritten
number
实际被写入到文件中的字节数(注意,被写入的字节数不一定与被写入的字符串字符数相同)
示例代码:
const fs = wx.getFileSystemManager()
// 打开文件
fs.open({
filePath: `${wx.env.USER_DATA_PATH}/hello.txt`,
flag: 'a+',
success(res) {
// 写入文件
fs.write({
fd: res.fd,
data: 'some text',
success(res) {
console.log(res.bytesWritten)
}
})
}
})


.writeSync

该方法使用方式为 FileSystemManager.writeFile(Object object)
说明:
该 API 小程序支持,小游戏暂不支持。
功能说明:同步写入文件。
参数及说明:Object object
属性
类型
默认值
必填
说明
fd
string
-
文件描述符。fd 通过 FileSystemManager.openFileSystemManager.openSync 接口获得
data
string/ArrayBuffer
-
要写入的文本或二进制数据
offset
number
0
只在 data 类型是 ArrayBuffer 时有效,决定 arrayBuffe 中要被写入的部位,即 arrayBuffer 中的索引,默认0
length
number
-
只在 data 类型是 ArrayBuffer 时有效,指定要写入的字节数,默认为 arrayBuffer 从0开始偏移 offset 个字节后剩余的字节数
encoding
string
utf8
指定写入文件的字符编码
position
number
-
指定文件开头的偏移量,即数据要被写入的位置。当 position 不传或者传入非 Number 类型的值时,数据会被写入当前指针所在位置
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
encoding 合法值
说明
ascii
-
base64
-
binary
-
hex
-
ucs2/ucs-2/utf16le/utf-16le
以小端序读取
utf-8/utf8
-
latin1
-
object.success 回调函数参数:Object res
属性
类型
说明
bytesWritten
number
实际被写入到文件中的字节数(注意,被写入的字节数不一定与被写入的字符串字符数相同)
示例代码:
const fs = wx.getFileSystemManager()
const fd = fs.openSync({
filePath: `${wx.env.USER_DATA_PATH}/hello.txt`,
flag: 'a+'
})
const res = fs.writeSync({
fd: fd,
data: 'some text'
})
console.log(res.bytesWritten)


.writeFile

该方法使用方式为 FileSystemManager.writeFile(Object object)
功能说明:写文件。
参数及说明:Object object
属性
类型
默认值
必填
说明
filePath
string
-
要写入的文件路径
data
string/ArrayBuffer
-
要写入的文本或二进制数据
encoding
string
utf8
指定写入文件的字符编码
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
object.encoding 的合法值
说明
ascii
-
base64
-
binary
-
hex
-
ucs2/ucs-2/utf16le/utf-16le
以小端序读取
utf-8/utf8
-
latin1
-
object.fail 回调函数参数:Object res
属性
类型
说明
errMsg
string
错误信息
res.errMsg 的合法值
说明
fail no such file or directory, open ${filePath}
指定的 filePath 所在目录不存在
fail permission denied, open ${dirPath}
指定的 filePath 路径没有写权限
示例代码:
const fs = wx.getFileSystemManager()
fs.writeFile({
filePath: `${wx.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(
`${wx.env.USER_DATA_PATH}/hello.txt`,
'some text or arrayBuffer',
'utf8'
)
console.log(res)
} catch(e) {
console.error(e)
}


.writeFileSync

该方法使用方式为 FileSystemManager.writeFileSync(string filePath, string|ArrayBuffer data, string encoding)
功能说明:FileSystemManager.writeFile 的同步版本。
参数及说明:
string filePath:要写入的文件路径。
string|ArrayBuffer data:要写入的文本或二进制数据。
string encoding:指定写入文件的字符编码。
encoding 的合法值
说明
ascii
-
base64 (注意,选择 base64 编码,data 只需要传 base64 内容本身,不要传 Data URI 前缀,否则会报 fail base64 encode error 错误。例如,传 aGVsbG8= 而不是传 data:image/png;base64,aGVsbG8= )
-
binary
-
hex
-
ucs2/ucs-2/utf16le/utf-16le
以小端序读取
utf-8/utf8
-
latin1
-
示例代码:
const fs = wx.getFileSystemManager()
fs.writeFile({
filePath: `${wx.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(
`${wx.env.USER_DATA_PATH}/hello.txt`,
'some text or arrayBuffer',
'utf8'
)
console.log(res)
} catch(e) {
console.error(e)
}


错误码

说明:
若无特殊说明,错误码均以下表为准。
错误码
错误信息
说明
1300001
operation not permitted
操作不被允许(例如,filePath 预期传入一个文件而实际传入一个目录)
1300002
no such file or directory ${path}
文件/目录不存在,或者目标文件路径的上层目录不存在
1300005
Input/output error
输入输出流不可用
1300009
bad file descriptor
无效的文件描述符
1300013
permission denied
权限错误,文件是只读或只写
1300014
Path permission denied
传入的路径没有权限
1300020
not a directory
dirPath 指定路径不是目录,常见于指定的写入路径的上级路径为一个文件的情况
1300021
Is a directory
指定路径是一个目录
1300022
Invalid argument
无效参数,可以检查length或offset是否越界
1300036
File name too long
文件名过长
1300066
directory not empty
目录不为空
1300201
system error
系统接口调用失败
1300202
the maximum size of the file storage limit is exceeded
存储空间不足,或文件大小超出上限(上限100M)
1300203
base64 encode error
字符编码转换失败(例如 base64 格式错误)
1300300
sdcard not mounted
android sdcard 挂载失败
1300301
unable to open as fileType
无法以fileType打开文件
1301000
permission denied, cannot access file path
目标路径无访问权限(usr目录)
1301002
data to write is empty
写入数据为空
1301003
illegal operation on a directory
不可对目录进行此操作(例如,指定的 filePath 是一个已经存在的目录)
1301004
illegal operation on a package directory
不可对代码包目录进行此操作
1301005
file already exists ${dirPath}
已有同名文件或目录
1301006
value of length is out of range
传入的 length 不合法
1301007
value of offset is out of range
传入的 offset 不合法
1301009
value of position is out of range
position值越界
1301100
store directory is empty
store目录为空
1301102
unzip open file fail
压缩文件打开失败
1301103
unzip entry fail
解压单个文件失败
1301104
unzip fail
解压失败
1301111
brotli decompress fail
brotli解压失败(例如,指定的 compressionAlgorithm 与文件实际压缩格式不符)
1301112
tempFilePath file not exist
指定的 tempFilePath 找不到文件
1302001
fail permission denied
指定的 fd 路径没有读权限/没有写权限
1302002
exceed max concurrent fd limit
fd数量已达上限
1302003
invalid flag
无效的flag
1302004
permission denied when open using flag
无法使用flag标志打开文件
1302005
array buffer does not exist
未传入arrayBuffer
1302100
array buffer is readonly
arrayBuffer只读


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。

方法集

.isDirectory

该方法使用方式为 boolean Stats.isDirectory()
功能说明:判断当前文件是否一个目录。
返回值:boolean,表示当前文件是否一个目录。


.isFile

该方法使用方式为 boolean Stats.isFile()
功能说明:判断当前文件是否一个普通文件。
返回值:boolean,表示当前文件是否一个普通文件。


ReadResult

功能说明:文件读取结果。 通过 FileSystemManager.readSync 接口返回。
属性:
number bytesRead,实际读取的字节数;
ArrayBuffer arrayBuffer,被写入的缓存区的对象,即接口入参的 arrayBuffer。


WriteResult

功能说明:文件写入结果。 通过 FileSystemManager.writeSync 接口返回。
属性:number bytesWritten,实际被写入到文件中的字节数(注意,被写入的字节数不一定与被写入的字符串字符数相同)。

本页内容是否解决了您的问题?
您也可以 联系销售 提交工单 以寻求帮助。

文档反馈