文件

saveFile

基础库 1.3.9 开始支持，iOS 版本 2.1.23，Android 版本 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 版本 2.1.23，Android 版本 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 版本 2.1.23，Android 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 版本 2.1.23，Android 版本 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 版本 2.1.23，Android 版本 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 版本 2.1.23，Android 版本 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		是	要追加内容的文件路径 (本地路径)
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

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)

读取本地文件内容

参数

Object object

属性	类型	默认值	必填	说明
filePath	string		是	要读取的文件的路径 (本地路径)
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的同步版本

参数

string filePath

要读取的文件的路径 (本地路径)

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.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)