文件

saveFile

基础库 1.3.9 起，iOS SDK 2.1.23 起，Android SDK 2.1.38 起支持

saveFile(Object object)

保存文件到本地。

注意

saveFile 会把临时文件移动，因此调用成功后传入的 tempFilePath 将不可用。

参数

Object object

属性	类型	默认值	必填	说明
tempFilePath	string		是	需要保存的文件的临时路径
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.success 回调函数

参数

Object res

属性	类型	说明
savedFilePath	number	存储后的文件路径

示例代码

ft.chooseImage({
  success(res) {
    const tempFilePaths = res.tempFilePaths
    ft.saveFile({
      tempFilePath: tempFilePaths[0],
      success(res) {
        const savedFilePath = res.savedFilePath
      }
    })
  }
})

注意

本地文件存储的大小限制为10M

removeSavedFile

基础库 1.3.9 起，iOS SDK 2.1.23 起，Android SDK 2.1.38 起支持

removeSavedFile(Object object)

删除本地缓存文件。

参数

Object object

属性	类型	默认值	必填	说明
tempFilePath	string		是	需要删除的文件的路径
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

示例代码

ft.getSavedFileList({
  success(res) {
    if (res.fileList.length > 0) {
      ft.removeSavedFile({
        filePath: res.fileList[0].filePath,
        complete(res) {
          console.log(res)
        }
      })
    }
  }
})

openDocument

基础库 1.3.9 起，iOS SDK 2.1.23 起，Android SDK 2.37.7 起支持

openDocument(Object object)

新开页面打开文档。

参数

Object object

属性	类型	默认值	必填	说明
filePath	string		是	文件路径，可通过 downloadFile 获得
fileType	string		否	文件类型，指定文件类型打开文件
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.fileType 的合法值

值	说明
doc	doc 格式
docx	docx 格式
xls	xls 格式
xlsx	xlsx 格式
ppt	ppt 格式
pptx	pptx 格式
pdf	pdf 格式

示例代码

ft.downloadFile({
  // 示例 url，并非真实存在
  url: 'http://example.com/somefile.pdf',
  success(res) {
    const filePath = res.tempFilePath
    ft.openDocument({
      filePath,
      success(res) {
        console.log('打开文档成功')
      }
    })
  }
})

getSavedFileList

基础库 1.3.9 起，iOS SDK 2.1.23 起，Android SDK 2.1.38 起支持

getSavedFileList(Object object)

获取该小程序目录下已保存的本地缓存文件列表。

参数

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 到当前时间的秒数

示例代码

ft.getSavedFileList({
  success(res) {
    console.log(res.fileList)
  }
})

getSavedFileInfo

基础库 1.3.9 起，iOS SDK 2.1.23 起，Android SDK 2.1.38 起支持

getSavedFileInfo(Object object)

获取本地文件的文件信息。此接口只能用于获取已保存到本地的文件，若需要获取临时文件信息，请使用 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 到当前时间的秒数

示例代码

ft.getSavedFileList({
  success(res) {
    console.log(res.fileList)
  }
})

getFileInfo

基础库 1.3.9 起，iOS SDK 2.1.23 起，Android SDK 2.1.38 起支持

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 计算得出的的文件摘要

示例代码

ft.getFileInfo({
  success(res) {
    console.log(res.size)
    console.log(res.digest)
  }
})

saveFileToDisk

保存文件系统的文件到用户磁盘，仅在 PC 端支持

参数

Object object

属性	类型	默认值	必填	说明
filePath	string		是	待保存文件路径
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

示例代码

ft.saveFileToDisk({
  filePath: `${ft.env.USER_DATA_PATH}/hello.txt`,
  success(res) {
    console.log(res)
  },
  fail(res) {
    console.error(res)
  }
})

getFileSystemManager

基础库 2.10.6 开始支持

getFileSystemManager()

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

返回值

FileSystemManager

文件管理器

FileSystemManager.access

FileSystemManager.access(Object object)

判断文件/目录是否存在

参数

Object object

属性	类型	默认值	必填	说明
path	string		是	要判断是否存在的文件/目录路径 (本地路径)
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.fail 回调函数

参数

Object res

属性	类型	说明
errMsg	string	错误信息

示例代码

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

FileSystemManager.accessSync

FileSystemManager.accessSync(string path)

FileSystemManager.access的同步版本

参数

string path

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

示例代码

const fs = ft.getFileSystemManager()
// 同步接口
try {
  fs.accessSync(`${ft.env.USER_DATA_PATH}/test.txt`)
} catch(e) {
  console.error(e)
}

FileSystemManager.appendFile

FileSystemManager.appendFile(Object object)

在文件结尾追加内容

参数

Object object

属性	类型	默认值	必填	说明
filePath	string		是	要追加内容的文件路径 (本地路径)
data	string/ArrayBuffer		是	要追加的文本或二进制数据
encoding	string	utf-8	否	指定写入文件的字符编码
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.encoding 的合法值

值	说明
base64
binary
utf-8
utf8

object.fail 回调函数

参数

Object res

属性	类型	说明
errMsg	string	错误信息

示例代码

const fs = ft.getFileSystemManager()

fs.appendFile({
  filePath: `${ft.env.USER_DATA_PATH}/test.txt`,
  data: 'this is text',
  encoding: 'utf-8',
  success(res) {
    console.log(res)
  },
  fail(res) {
    console.error(res)
  }
})

FileSystemManager.appendFileSync

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

FileSystemManager.appendFile的同步版本

参数

string filePath

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

string|ArrayBuffer data

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

string encoding

指定写入文件的字符编码

示例代码

// 同步接口
const fs = ft.getFileSystemManager()

try {
  fs.appendFileSync(`${ft.env.USER_DATA_PATH}/test.txt`, 'this is text', 'utf8')
} catch(e) {
  console.error(e)
}

FileSystemManager.close

FileSystemManager.close(Object object)

关闭文件

参数

Object object

属性	类型	默认值	必填	说明
fd	string		是	需要被关闭的文件描述符。fd 通过 FileSystemManager.open 或 FileSystemManager.openSync 接口获得
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.fail 回调函数

参数

Object res

属性	类型	说明
errMsg	string	错误信息

示例代码

const fs = ft.getFileSystemManager()
// 打开文件
fs.open({
  filePath: `${ft.env.USER_DATA_PATH}/test.txt`,
  flag: 'a+',
  success(res) {
    // 关闭文件
    fs.close({
      fd: res.fd
    })
  }
})

FileSystemManager.closeSync

FileSystemManager.closeSync(Object object)

同步关闭文件

参数

Object object

属性	类型	默认值	必填	说明
fd	string		是	需要被关闭的文件描述符。fd 通过 FileSystemManager.open 或 FileSystemManager.openSync 接口获得

示例代码

const fs = ft.getFileSystemManager()

const fd = fs.openSync({
  filePath: `${ft.env.USER_DATA_PATH}/test.txt`,
  flag: 'a+'
})

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

FileSystemManager.copyFile

FileSystemManager.copyFile(Object object)

复制文件

参数

Object object

属性	类型	默认值	必填	说明
srcPath	string		是	源文件路径，支持本地路径
destPath	string		是	目标文件路径，支持本地路径
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.fail 回调函数

参数

Object res

属性	类型	说明
errMsg	string	错误信息

示例代码

const fs = ft.getFileSystemManager()

fs.copyFile({
  srcPath: `${ft.env.USER_DATA_PATH}/test-txt`,
  destPath: `${ft.env.USER_DATA_PATH}/new-test.txt`
  success(res) {
    console.log(res)
  },
  fail(res) {
    console.error(res)
  }
})

FileSystemManager.copyFileSync

FileSystemManager.copyFileSync(string srcPath, string destPath)

FileSystemManager.copyFile的同步版本

参数

string srcPath

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

string destPath

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

示例代码

const fs = ft.getFileSystemManager()

// 同步接口
try {
  fs.copyFileSync(
    `${ft.env.USER_DATA_PATH}/test.txt`,
    `${ft.env.USER_DATA_PATH}/new-test.txt`
  )
} catch(e) {
  console.error(e)
}

FileSystemManager.fstat

FileSystemManager.fstat(Object object)

获取文件的状态信息

参数

Object object

属性	类型	默认值	必填	说明
fd	string		是	需要被关闭的文件描述符。fd 通过 FileSystemManager.open 或 FileSystemManager.openSync 接口获得
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.success 回调函数

参数

Object res

属性	类型	说明
stats	object	包含了文件的状态信息

object.fail 回调函数

参数

Object res

属性	类型	说明
errMsg	string	错误信息

示例代码

const fs = ft.getFileSystemManager()
// 打开文件
fs.open({
  filePath: `${ft.env.USER_DATA_PATH}/test.txt`,
  flag: 'a+',
  success(res) {
    // 获取文件的状态信息
    fs.fstat({
      fd: res.fd,
      success(res) {
        console.log(res.stats)
      }
    })
  }
})

FileSystemManager.fstatSync

FileSystemManager.fstatSync(Object object)

同步获取文件的状态信息

参数

Object object

属性	类型	默认值	必填	说明
fd	string		是	需要被关闭的文件描述符。fd 通过 FileSystemManager.open 或 FileSystemManager.openSync 接口获得

返回值

Object object

包含了文件的状态信息的对象

示例代码

const fs = ft.getFileSystemManager()

const fd = fs.openSync({
  filePath: `${ft.env.USER_DATA_PATH}/test.txt`,
  flag: 'a+'
})

const stats = fs.fstatSync({fd: fd})
console.log(stats)

FileSystemManager.ftruncate

FileSystemManager.ftruncate(Object object)

对文件内容进行截断操作

参数

Object object

属性	类型	默认值	必填	说明
fd	string		是	需要被关闭的文件描述符。fd 通过 FileSystemManager.open 或 FileSystemManager.openSync 接口获得
length	number		是	截断位置，默认0。如果 length 小于文件长度（单位：字节），则只有前面 length 个字节会保留在文件中，其余内容会被删除；如果 length 大于文件长度，则会对其进行扩展，并且扩展部分将填充空字节（'\0'）
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.fail 回调函数

参数

Object res

属性	类型	说明
errMsg	string	错误信息

示例代码

const fs = ft.getFileSystemManager()
// 打开文件
fs.open({
  filePath: `${ft.env.USER_DATA_PATH}/test.txt`,
  flag: 'a+',
  success(res) {
    // 对文件内容进行截断操作
    fs.ftruncate({
      fd: res.fd,
      length: 10, // 从第 10 个字节开始截断文件
      success(res) {
        console.log(res)
      }
    })
  }
})

FileSystemManager.ftruncateSync

FileSystemManager.ftruncateSync(Object object)

同步对文件内容进行截断操作

参数

Object object

属性	类型	默认值	必填	说明
fd	string		是	需要被关闭的文件描述符。fd 通过 FileSystemManager.open 或 FileSystemManager.openSync 接口获得
length	number		是	截断位置，默认0。如果 length 小于文件长度（单位：字节），则只有前面 length 个字节会保留在文件中，其余内容会被删除；如果 length 大于文件长度，则会对其进行扩展，并且扩展部分将填充空字节（'\0'）

返回值

undefined

示例代码

const fs = ft.getFileSystemManager()

const fd = fs.openSync({
  filePath: `${ft.env.USER_DATA_PATH}/test.txt`,
  flag: 'a+'
})
fs.ftruncateSync({
  fd: fd,
  length: 10 // 从第 10 个字节开始截断文件
})

FileSystemManager.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	文件大小，以字节为单位

object.fail 回调函数

参数

Object res

属性	类型	说明
errMsg	string	错误信息

示例代码

const fs = ft.getFileSystemManager()

fs.getFileInfo({
  filePath: `${ft.env.USER_DATA_PATH}/test.txt`,
  success(res) {
    console.log(res)
  },
  fail(res) {
    console.error(res)
  }
})

FileSystemManager.getSavedFileList

FileSystemManager.getSavedFileList(Object object)

获取该小程序下已保存的本地缓存文件列表

参数

Object object

属性	类型	默认值	必填	说明
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.success 回调函数

参数

Object res

属性	类型	说明
fileList	Array.<Object>	文件数组，object 包含 filePath、size、createTime

object.fail 回调函数

参数

Object res

属性	类型	说明
errMsg	string	错误信息

示例代码

const fs = ft.getFileSystemManager()

fs.getSavedFileList({
  success(res) {
    console.log(res)
  },
  fail(res) {
    console.error(res)
  }
})

FileSystemManager.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	错误信息

示例代码

const fs = ft.getFileSystemManager()

fs.mkdir({
  dirPath: `${ft.env.USER_DATA_PATH}/a/b/c`,
  recursive: false
  success(res) {
    console.log(res)
  },
  fail(res) {
    console.error(res)
  }
})

FileSystemManager.mkdirSync

FileSystemManager.mkdirSync(string dirPath, boolean recursive)

FileSystemManager.mkdirSync的同步版本

参数

string dirPath

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

boolean recursive

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

示例代码

const fs = ft.getFileSystemManager()

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

FileSystemManager.open

FileSystemManager.open(Object object)

打开文件，返回文件描述符

参数

Object object

属性	类型	默认值	必填	说明
filePath	string		是	文件路径 (本地路径)
flag	string	r	否	文件系统标志，默认值: 'r'
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.flag 的合法值

值	说明
a	打开文件用于追加。 如果文件不存在，则创建该文件
ax	类似于 'a'，但如果路径存在，则失败
a+	打开文件用于读取和追加。 如果文件不存在，则创建该文件
ax+	类似于 'a+'，但如果路径存在，则失败
as	打开文件用于追加（在同步模式中）。 如果文件不存在，则创建该文件
as+	打开文件用于读取和追加（在同步模式中）。 如果文件不存在，则创建该文件
r	打开文件用于读取。 如果文件不存在，则会发生异常
r+	打开文件用于读取和写入。 如果文件不存在，则会发生异常
w	打开文件用于写入。 如果文件不存在则创建文件，如果文件存在则截断文件
wx	类似于 'w'，但如果路径存在，则失败
w+	打开文件用于读取和写入。 如果文件不存在则创建文件，如果文件存在则截断文件
wx+	类似于 'w+'，但如果路径存在，则失败

object.success 回调函数

参数

Object res

属性	类型	说明
fd	string	文件描述符

object.fail 回调函数

参数

Object res

属性	类型	说明
errMsg	string	错误信息

示例代码

const fs = ft.getFileSystemManager()

fs.open({
  filePath: `${ft.env.USER_DATA_PATH}/test.txt`,
  flag: 'a+',
  success(res) {
    console.log(res.fd)
  }
})

FileSystemManager.openSync

FileSystemManager.openSync(Object object)

同步打开文件，返回文件描述符

参数

Object object

属性	类型	默认值	必填	说明
filePath	string		是	文件路径 (本地路径)
flag	string	r	否	文件系统标志，默认值: 'r'

object.flag 的合法值

值	说明
a	打开文件用于追加。 如果文件不存在，则创建该文件
ax	类似于 'a'，但如果路径存在，则失败
a+	打开文件用于读取和追加。 如果文件不存在，则创建该文件
ax+	类似于 'a+'，但如果路径存在，则失败
as	打开文件用于追加（在同步模式中）。 如果文件不存在，则创建该文件
as+	打开文件用于读取和追加（在同步模式中）。 如果文件不存在，则创建该文件
r	打开文件用于读取。 如果文件不存在，则会发生异常
r+	打开文件用于读取和写入。 如果文件不存在，则会发生异常
w	打开文件用于写入。 如果文件不存在则创建文件，如果文件存在则截断文件
wx	类似于 'w'，但如果路径存在，则失败
w+	打开文件用于读取和写入。 如果文件不存在则创建文件，如果文件存在则截断文件
wx+	类似于 'w+'，但如果路径存在，则失败

返回值

string

文件描述符

示例代码

const fs = ft.getFileSystemManager()

const fd = fs.openSync({
  filePath: `${ft.env.USER_DATA_PATH}/test.txt`,
  flag: 'a+'
})
console.log(fd)

FileSystemManager.read

FileSystemManager.read(Object object)

读文件

参数

Object object

属性	类型	默认值	必填	说明
fd	string		是	文件描述符。fd 通过 FileSystemManager.open 或 FileSystemManager.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

object.fail 回调函数

参数

Object res

属性	类型	说明
errMsg	string	错误信息

示例代码

const fs = ft.getFileSystemManager()

const ab = new ArrayBuffer(1024)
// 打开文件
fs.open({
  filePath: `${ft.env.USER_DATA_PATH}/test.txt`,
  flag: 'a+',
  success(res) {
    // 读取文件到 ArrayBuffer 中
    fs.read({
      fd: res.fd,
      arrayBuffer: ab,
      length: 10,
      success(res) {
        console.log(res)
      }
    })
  }
})

FileSystemManager.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	错误信息

示例代码

const fs = ft.getFileSystemManager()

fs.readdir({
  dirPath: `${ft.env.USER_DATA_PATH}/a`,
  success(res) {
    console.log(res.files)
  },
  fail(res) {
    console.error(res)
  }
})

FileSystemManager.readdirSync

FileSystemManager.readdirSync(string dirPath)

FileSystemManager.readdirSync的同步版本

参数

string dirPath

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

返回值

Array.<string> files

指定目录下的文件名数组

示例代码

const fs = ft.getFileSystemManager()

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

FileSystemManager.readFile

FileSystemManager.readFile(Object object)

读取本地文件内容。

基础库 3.6.2 起，SDK 2.47.9 起，readFile 新增了 buffer 类型读取优化，文件尺寸最大限制为 100M。

参数

Object object

属性	类型	默认值	必填	说明
filePath	string		是	要读取的文件的路径 (本地路径)，SDK 2.47.9 起，异步读取的文件尺寸限制为 100M 内。
encoding	string	utf-8	否	指定读取文件的字符编码，如果不传 encoding，则以 ArrayBuffer 格式读取文件的二进制内容
position	number		否	从文件指定位置开始读，如果不指定，则从文件头开始读。读取的范围应该是左闭右开区间 [position, position+length)。有效范围：[0, fileLength - 1]。单位：byte
length	number		否	指定文件的长度，如果不指定，则读到文件末尾。有效范围：[1, fileLength]。单位：byte
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.encoding 的合法值

值	说明
base64
binary
utf-8
utf8

object.success 回调函数

参数

Object res

属性	类型	说明
data	string/ArrayBuffer	文件内容

object.fail 回调函数

参数

Object res

属性	类型	说明
errMsg	string	错误信息

示例代码

const fs = ft.getFileSystemManager()

fs.readFile({
  filePath: `${ft.env.USER_DATA_PATH}/test.txt`,
  encoding: 'utf8',
  position: 0,
  success(res) {
    console.log(res.data)
  },
  fail(res) {
    console.error(res)
  }
})

FileSystemManager.readFileSync

FileSystemManager.readFileSync(string filePath, string encoding, number position, number length)

FileSystemManager.readFileSync 的同步版本

SDK 2.47.9 起，同步读取文件尺寸最大限制为 30M。异步读取最大限制为 100M。

参数

string filePath

要读取的文件的路径 (本地路径)，SDK 2.47.9 起，同步读取的文件尺寸限制为 30M 内。

string encoding

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

encoding 的合法值

值	说明
base64
binary
utf-8
utf8

number position

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

number length

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

返回值

string|ArrayBuffer data

文件内容

示例代码

const fs = ft.getFileSystemManager()

// 同步接口
try {
  fs.copyFileSync(
    `${ft.env.USER_DATA_PATH}/test.txt`,
    `${ft.env.USER_DATA_PATH}/new-test.txt`
  )
} catch(e) {
  console.error(e)
}

FileSystemManager.readSync

FileSystemManager.readSync(Object object)

读文件

参数

Object object

属性	类型	默认值	必填	说明
fd	string		是	文件描述符。fd 通过 FileSystemManager.open 或 FileSystemManager.openSync 接口获得
arrayBuffer	ArrayBuffer		是	数据写入的缓冲区，必须是 ArrayBuffer 实例
offset	number	0	否	缓冲区中的写入偏移量，默认 0
length	number	0	否	要从文件中读取的字节数，默认 0
position	number		否	文件读取的起始位置，如不传或传 null，则会从当前文件指针的位置读取。如果 position 是正整数，则文件指针位置会保持不变并从 position 读取文件。

返回值

Object res

属性	类型	说明
bytesRead	number	实际读取的字节数
arrayBuffer	ArrayBuffer	被写入的缓存区的对象，即接口入参的 arrayBuffer

示例代码

const fs = ft.getFileSystemManager()

const ab = new ArrayBuffer(1024)
const fd = fs.openSync({
  filePath: `${ft.env.USER_DATA_PATH}/hello.txt`,
  flag: 'a+'
})
const res = fs.readSync({
  fd: fd,
  arrayBuffer: ab,
  length: 10
})
console.log(res)

FileSystemManager.readZipEntry

FileSystemManager.readZipEntry(Object object)

读取压缩包内的文件

参数

Object object

属性	类型	默认值	必填	说明
filePath	string		是	需要读取的 zip 文件路径 (本地路径)
encoding	string		否	统一指定读取文件的字符编码，只在 entries 值为 "all" 时有效。如果 entries 值为 "all" 且不传 encoding，则以 ArrayBuffer 格式读取文件的二进制内容
entries	Array or string		是	要读取的压缩包内的文件列表（当传入 "all" 时表示读取压缩包内所有文件）
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

返回值

Object res

属性	类型	说明
entries	Object	文件读取结果。res.entries 是一个对象，key 是文件路径，value 是一个对象 FileItem ，表示该文件的读取结果。每个 FileItem 包含 data （文件内容） 和 errMsg （错误信息） 属性。
错误

示例代码

const fs = ft.getFileSystemManager()
// 读取 zip 内某个或多个文件
fs.readZipEntry({
  filePath: 'path/to/zip.zip',
  entries: [{
    path: 'zip/file/1.txt', // zip内文件路径
    encoding: 'utf-8'
  }, {
    path: 'zip/file/2.txt', // zip内文件路径
  }],
  success(res) {
    console.log(res.entries)
  },
  fail(res) {
    console.log(res.errMsg)
  }
})

// 读取 zip 内所有文件，允许指定统一的 encoding
fs.readZipEntry({
  filePath: 'path/to/zip.zip',
  entries: 'all',
  encoding: 'utf-8',
  success(res) {
    console.log(res.entries)
  },
  fail(res) {
    console.log(res.errMsg)
  }
})

FileSystemManager.removeSavedFile

FileSystemManager.removeSavedFile(Object object)

删除该小程序下已保存的本地缓存文件

参数

Object object

属性	类型	默认值	必填	说明
filePath	string		是	需要删除的文件路径 (本地路径)
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.fail 回调函数

参数

Object res

属性	类型	说明
errMsg	string	错误信息

示例代码

const fs = ft.getFileSystemManager()

fs.removeSavedFile({
  filePath: `${ft.env.USER_DATA_PATH}/test.txt`,
  success(res) {
    console.log(res)
  },
  fail(res) {
    console.error(res)
  }
})

FileSystemManager.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	错误信息

示例代码

const fs = ft.getFileSystemManager()

fs.rename({
  oldPath: `${ft.env.USER_DATA_PATH}/hello.txt`,
  newPath: `${ft.env.USER_DATA_PATH}/new-hello.txt`,
  success(res) {
    console.log(res)
  },
  fail(res) {
    console.error(res)
  }
})

FileSystemManager.renameSync

FileSystemManager.renameSync(string oldPath, string newPath)

FileSystemManager.rename的同步版本

参数

string oldPath

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

string newPath

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

示例代码

const fs = ft.getFileSystemManager()

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

FileSystemManager.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	错误信息

示例代码

const fs = ft.getFileSystemManager()

fs.rmdir({
  dirPath: `${ft.env.USER_DATA_PATH}/a`,
  recursive: false,
  success(res) {
    console.log(res)
  },
  fail(res) {
    console.error(res)
  }
})

FileSystemManager.rmdirSync

FileSystemManager.rmdirSync(string dirPath, boolean recursive)

FileSystemManager.rmdir的同步版本

参数

string dirPath

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

boolean recursive

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

示例代码

const fs = ft.getFileSystemManager()

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

FileSystemManager.saveFile

FileSystemManager.saveFile(Object object)

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

参数

Object object

属性	类型	默认值	必填	说明
tempFilePath	string		是	临时存储文件路径 (本地路径)
filePath	string		否	要存储的文件路径 (本地路径)
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.success 回调函数

参数

Object res

属性	类型	说明
savedFilePath	string	存储后的文件路径 (本地路径)

object.fail 回调函数

参数

Object res

属性	类型	说明
errMsg	string	错误信息

示例代码

const fs = ft.getFileSystemManager()

fs.saveFile({
  tempFilePath: `finfile:://temp/sample.text`,
  success(res) {
    console.log(res)
  },
  fail(res) {
    console.error(res)
  }
})

FileSystemManager.saveFileSync

FileSystemManager.saveFileSync(string tempFilePath, string filePath)

FileSystemManager.saveFile的同步版本

参数

string tempFilePath

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

string filePath

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

示例代码

const fs = ft.getFileSystemManager()

// 同步接口
try {
  fs.saveFileSync( `finfile://temp/sample.txt`)
} catch(e) {
  console.error(e)
}

FileSystemManager.stat

FileSystemManager.stat(Object object)

获取文件信息对象

参数

Object object

属性	类型	默认值	必填	说明
path	string		是	文件/目录路径 (本地路径)
recursive	boolean	false	否	是否递归获取目录下的每个文件的信息
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.success 回调函数

参数

Object res

属性	类型	说明
stats	object/Array.<object>	当 recursive 为 false 时，res.stats 是一个对象。当 recursive 为 true 且 path 是一个目录的路径时，res.stats 是一个 Array，数组的每一项是一个对象，每个对象包含 path 和 stats。

object.fail 回调函数

参数

Object res

属性	类型	说明
errMsg	string	错误信息

示例代码

const fs = ft.getFileSystemManager()

fs.stat({
  path: `${ft.env.USER_DATA_PATH}/test`,
  success: res => {
    console.log(res.stats)
  }
})

fs.stat({
  path: `${ft.env.USER_DATA_PATH}/test`,
  recursive: true,
  success: res => {
    Object.keys(res.stats).forEach(path => {
      let stats = res.stats[path]
      console.log(path, stats)
    })
  }
})

FileSystemManager.statSync

FileSystemManager.statSync(string path, boolean recursive)

FileSystemManager.stat的同步版本

参数

string path

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

string recursive

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

返回值

object|Array.<object>

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

示例代码

const fs = ft.getFileSystemManager()

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

FileSystemManager.truncate

FileSystemManager.truncate(Object object)

对文件内容进行截断操作

参数

Object object

属性	类型	默认值	必填	说明
filePath	string		是	要截断的文件路径 (本地路径)
length	number	0	是	截断位置，默认0。如果 length 小于文件长度（字节），则只有前面 length 个字节会保留在文件中，其余内容会被删除；如果 length 大于文件长度，则会对其进行扩展，并且扩展部分将填充空字节（'\0'）
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.fail 回调函数

参数

Object res

属性	类型	说明
errMsg	string	错误信息

示例代码

const fs = ft.getFileSystemManager()

fs.truncate({
  filePath: `${ft.env.USER_DATA_PATH}/test.txt`,
  length: 10,
  success(res) {
    console.log(res)
  }
})

FileSystemManager.truncateSync

FileSystemManager.truncateSync(Object object)

FileSystemManager.truncate的同步版本

参数

属性	类型	默认值	必填	说明
filePath	string		是	要截断的文件路径 (本地路径)
length	number	0	是	截断位置，默认0。如果 length 小于文件长度（字节），则只有前面 length 个字节会保留在文件中，其余内容会被删除；如果 length 大于文件长度，则会对其进行扩展，并且扩展部分将填充空字节（'\0'）

示例代码

const fs = ft.getFileSystemManager()

// 同步接口
try {
  fs.truncateSync({
    filePath: `${ft.env.USER_DATA_PATH}/test.txt`,
    length: 10,
  })
} catch(e) {
  console.error(e)
}

FileSystemManager.unlink

FileSystemManager.unlink(Object object)

删除文件

参数

Object object

属性	类型	默认值	必填	说明
filePath	string		是	要删除的文件路径 (本地路径)
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.fail 回调函数

参数

Object res

属性	类型	说明
errMsg	string	错误信息

示例代码

const fs = ft.getFileSystemManager()

fs.unlink({
  filePath: `${ft.env.USER_DATA_PATH}/test.txt`,
  success(res) {
    console.log(res)
  },
  fail(res) {
    console.error(res)
  }
})

FileSystemManager.unlinkSync

FileSystemManager.unlinkSync(string filePath)

FileSystemManager.unlink的同步版本

参数

string filePath

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

示例代码

const fs = ft.getFileSystemManager()

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

FileSystemManager.unzip

FileSystemManager.unzip(Object object)

解压文件

参数

Object object

属性	类型	默认值	必填	说明
zipFilePath	string		是	源文件路径，支持本地路径, 只可以是 zip 压缩文件
targetPath	string/ArrayBuffer		是	目标目录路径, 支持本地路径
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.fail 回调函数

参数

Object res

属性	类型	说明
errMsg	string	错误信息

示例代码

const fs = ft.getFileSystemManager()

fs.unzip({
  zipFilePath: `${ft.env.USER_DATA_PATH}/sample.zip`,
  targetPath: `${ft.env.USER_DATA_PATH}/sample`,
  success(res) {
    console.log(res)
  },
  fail(res) {
    console.error(res)
  }
})

FileSystemManager.write

FileSystemManager.write(Object object)

写入文件

参数

Object object

属性	类型	默认值	必填	说明
fd	string		是	文件描述符。fd 通过 FileSystemManager.open 或 FileSystemManager.openSync 接口获得
data	string/ArrayBuffer		是	写入的内容，类型为 String 或 ArrayBuffer
offset	number	0	否	只在 data 类型是 ArrayBuffer 时有效，决定 arrayBuffer 中要被写入的部位，即 arrayBuffer 中的索引，默认0
length	number		否	只在 data 类型是 ArrayBuffer 时有效，指定要写入的字节数，默认为 arrayBuffer 从0开始偏移 offset 个字节后剩余的字节数
encoding	string	utf-8	否	只在 data 类型是 String 时有效，指定写入文件的字符编码，默认为 utf8
position	number		否	指定文件开头的偏移量，即数据要被写入的位置。当 position 不传或者传入非 Number 类型的值时，数据会被写入当前指针所在位置。
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.encoding 的合法值

值	说明
base64
binary
utf-8
utf8

object.success 回调函数

参数

Object res

属性	类型	说明
bytesWritten	number	实际被写入到文件中的字节数（注意，被写入的字节数不一定与被写入的字符串字符数相同）

object.fail 回调函数

参数

Object res

属性	类型	说明
errMsg	string	错误信息

示例代码

const fs = ft.getFileSystemManager()

fs.open({
  filePath: `${ft.env.USER_DATA_PATH}/test.txt`,
  flag: 'a+',
  success(res) {
    // 写入文件
    fs.write({
      fd: res.fd,
      data: 'this is text',
      success(res) {
        console.log(res.bytesWritten)
      }
    })
  }
})

FileSystemManager.writeFile

FileSystemManager.writeFile(Object object)

写入文件

参数

Object object

属性	类型	默认值	必填	说明
filePath	string		是	要写入的文件路径 (本地路径)
data	string/ArrayBuffer		是	要写入的文本或二进制数据
encoding	string	utf-8	否	指定写入文件的字符编码
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.encoding 的合法值

值	说明
base64
binary
utf-8
utf8

object.fail 回调函数

参数

Object res

属性	类型	说明
errMsg	string	错误信息

示例代码

const fs = ft.getFileSystemManager()

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

FileSystemManager.writeFileSync

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

FileSystemManager.writeFile的同步版本

参数

string filePath

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

string|ArrayBuffer data

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

string encoding

指定写入文件的字符编码

object.encoding 的合法值

值	说明
base64
binary
utf-8
utf8

示例代码

const fs = ft.getFileSystemManager()

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

FileSystemManager.writeSync

FileSystemManager.writeSync(Object object)

同步写入文件

参数

Object object

属性	类型	默认值	必填	说明
fd	string		是	文件描述符。fd 通过 FileSystemManager.open 或 FileSystemManager.openSync 接口获得
data	string/ArrayBuffer		是	写入的内容，类型为 String 或 ArrayBuffer
offset	number	0	否	只在 data 类型是 ArrayBuffer 时有效，决定 arrayBuffer 中要被写入的部位，即 arrayBuffer 中的索引，默认0
length	number		否	只在 data 类型是 ArrayBuffer 时有效，指定要写入的字节数，默认为 arrayBuffer 从0开始偏移 offset 个字节后剩余的字节数
encoding	string	utf-8	否	只在 data 类型是 String 时有效，指定写入文件的字符编码，默认为 utf8
position	number		否	指定文件开头的偏移量，即数据要被写入的位置。当 position 不传或者传入非 Number 类型的值时，数据会被写入当前指针所在位置。

object.encoding 的合法值

值	说明
base64
binary
utf-8
utf8

返回值

Object res

属性	类型	说明
bytesWritten	number	实际被写入到文件中的字节数（注意，被写入的字节数不一定与被写入的字符串字符数相同）

示例代码

const fs = ft.getFileSystemManager()

const fd = fs.openSync({
  filePath: `${ft.env.USER_DATA_PATH}/test.txt`,
  flag: 'a+'
})

const res = fs.writeSync({
  fd: fd,
  data: 'this is text'
})
console.log(res)

FileSystemManager.readCompressedFile

基础库 3.3.7 起支持，SDK 版本 2.45.1 起支持，使用 readCompressedFile 需添加扩展 SDK iOS 仅支持异步 API，不支持同步 readCompressedFileSync

FileSystemManager.readCompressedFile(Object object)

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

参数

Object object

属性	类型	默认值	必填	说明
filePath	string		是	文件路径
compressionAlgorithm	string	string	否	文件压缩类型，仅支持 'br'
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

返回值

Object res

属性	类型	说明
data	ArrayBuffer	文件内容

示例代码

const fs = ft.getFileSystemManager()

fs.readCompressedFile({
  filePath: `path/to/file.br`,
  compressionAlgorithm: 'br',
  success(res) {
    console.log(res.data)
  }
})

FileSystemManager.readCompressedFileSync

基础库 3.3.7 起支持，SDK 版本 2.45.1 起支持，使用 readCompressedFileSync 需添加扩展 SDK iOS 仅支持异步 API，不支持同步 readCompressedFileSync

FileSystemManager.readCompressedFileSync(Object object)

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

参数

Object object

属性	类型	默认值	必填	说明
filePath	string		是	文件路径
compressionAlgorithm	string	string	否	文件压缩类型，仅支持 'br'

返回值

Object data

属性	类型	说明
data	ArrayBuffer	文件内容

示例代码

const fs = ft.getFileSystemManager()

const data = fs.readCompressedFileSync({
  filePath: `path/to/file.br`,
  compressionAlgorithm: 'br'
})

console.log(data)