# File

# saveFile

Supported from Base Library 1.3.9, iOS SDK 2.1.23, and Android SDK 2.1.38 onwards

saveFile(Object object)

Save a file to the local storage.

Note

saveFile moves the temporary file, so after a successful call, the passed tempFilePath will no longer be available.

Parameters

Object object

Property Type Default Value Required Description
tempFilePath string Yes Temporary path of the file to be saved
success function No Callback function for successful API call
fail function No Callback function for failed API call
complete function No Callback function when the API call ends (executed whether the call succeeds or fails)

object.success callback function

Parameters

Object res

Property Type Description
savedFilePath number Path where the file is stored after saving

Sample Code

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

Note

The size limit for local file storage is 10M.

# removeSavedFile

Supported from Base Library 1.3.9, iOS SDK 2.1.23, and Android SDK 2.1.38 onwards

removeSavedFile(Object object)

Delete a locally cached file.

Parameters

Object object

Property Type Default Value Required Description
filePath string Yes Path of the file to be deleted
success function No Callback function for successful API call
fail function No Callback function for failed API call
complete function No Callback function when the API call ends (executed whether the call succeeds or fails)

Sample Code

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

# openDocument

Supported from Base Library 1.3.9, iOS SDK 2.1.23, and Android SDK 2.37.7 onwards

openDocument(Object object)

Open a document in a new page.

Parameters

Object object

Property Type Default Value Required Description
filePath string Yes File path, which can be obtained via downloadFile
fileType string No File type, specifying the file type to open
success function No Callback function for successful API call
fail function No Callback function for failed API call
complete function No Callback function when the API call ends (executed whether the call succeeds or fails)

Valid values for object.fileType

Value Description
doc doc format
docx docx format
xls xls format
xlsx xlsx format
ppt ppt format
pptx pptx format
pdf pdf format

Sample Code

ft.downloadFile({
  // Example URL, not an actual file
  url: 'http://example.com/somefile.pdf',
  success(res) {
    const filePath = res.tempFilePath
    ft.openDocument({
      filePath,
      success(res) {
        console.log('Document opened successfully')
      }
    })
  }
})

# getSavedFileList

Supported from Base Library 1.3.9, iOS SDK 2.1.23, and Android SDK 2.1.38 onwards

getSavedFileList(Object object)

Get the list of locally cached files saved under this Mini-Program's directory.

Parameters

Object object

Property Type Default Value Required Description
success function No Callback function for successful API call
fail function No Callback function for failed API call
complete function No Callback function when the API call ends (executed whether the call succeeds or fails)

object.success callback function

Parameters

Object res

Property Type Description
fileList Array. Array of files, each item being a FileItem

Structure of res.fileList

Property Type Description
filePath string Local path
size number Size of the local file in bytes
createTime number Timestamp when the file was saved, in seconds from 1970/01/01 08:00:00 to the current time

Sample Code

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

# getSavedFileInfo

Supported from Base Library 1.3.9, iOS SDK 2.1.23, and Android SDK 2.1.38 onwards

getSavedFileInfo(Object object)

Get information about a local file. This API can only be used to retrieve information about files that have been saved locally. To get information about temporary files, use the getFileInfo() API.

Parameters

Object object

Property Type Default Value Required Description
filePath string Yes File path
success function No Callback function for successful API call
fail function No Callback function for failed API call
complete function No Callback function when the API call ends (executed whether the call succeeds or fails)

object.success callback function

Parameters

Object res

Property Type Description
size number Size of the local file in bytes
createTime number Timestamp when the file was saved, in seconds from 1970/01/01 08:00:00 to the current time

Sample Code

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

# getFileInfo

Supported from Base Library 1.3.9, iOS SDK 2.1.23, and Android SDK 2.1.38 onwards

getFileInfo(Object object)

Get file information.

Parameters

Object object

Property Type Default Value Required Description
filePath string Yes Local file path
digestAlgorithm string 'md5' No Algorithm to compute the file digest
success function No Callback function for successful API call
fail function No Callback function for failed API call
complete function No Callback function when the API call ends (executed whether the call succeeds or fails)

Valid values for object.digestAlgorithm

Value Description
md5 md5 algorithm
sha1 sha1 algorithm

object.success callback function

Parameters

Object res

Property Type Description
size number Size of the local file in bytes
digest string File digest calculated using the provided digestAlgorithm

Sample Code

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

# saveFileToDisk

Save the file system's file to the user's disk, supported only on PC.

Parameters

Object object

Property Type Default Value Required Description
filePath string Yes Path of the file to be saved
success function No Callback function for successful API call
fail function No Callback function for failed API call
complete function No Callback function for when the API call ends (executed whether successful or failed)

Example Code

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

# getFileSystemManager

Supported starting from Base Library version 2.10.6

getFileSystemManager()

Get the globally unique file manager.

Return Value

FileSystemManager

File Manager

# FileSystemManager.access

FileSystemManager.access(Object object)

Check if a file/directory exists.

Parameters

Object object

Property Type Default Value Required Description
path string Yes Path of the file/directory to check (local path)
success function No Callback function for successful API call
fail function No Callback function for failed API call
complete function No Callback function for when the API call ends (executed whether successful or failed)

object.fail Callback Function

Parameters

Object res

Property Type Description
errMsg string Error message

Example Code

const fs = ft.getFileSystemManager()
// Check if file/directory exists
fs.access({
  path: `${ft.env.USER_DATA_PATH}/test.txt`,
  success(res) {
    // File exists
    console.log(res)
  },
  fail(res) {
    // File does not exist or other error
    console.error(res)
  }
})

# FileSystemManager.accessSync

FileSystemManager.accessSync(string path)

Synchronous version of FileSystemManager.access.

Parameters

string path

Path of the file/directory to check (local path).

Example Code

const fs = ft.getFileSystemManager()
// Synchronous interface
try {
  fs.accessSync(`${ft.env.USER_DATA_PATH}/test.txt`)
} catch(e) {
  console.error(e)
}

# FileSystemManager.appendFile

FileSystemManager.appendFile(Object object)

Append content to the end of a file.

Parameters

Object object

Property Type Default Value Required Description
filePath string Yes Path of the file to append content to (local path)
data string/ArrayBuffer Yes Text or binary data to append
encoding string utf-8 No Specifies the character encoding for writing to the file
success function No Callback function for successful API call
fail function No Callback function for failed API call
complete function No Callback function for when the API call ends (executed whether successful or failed)

Valid values for object.encoding

Value Description
base64
binary
utf-8
utf8

object.fail Callback Function

Parameters

Object res

Property Type Description
errMsg string Error message

Example Code

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)

Synchronous version of FileSystemManager.appendFile.

Parameters

string filePath

Path of the file to append content to (local path).

string|ArrayBuffer data

Text or binary data to append.

string encoding

Specifies the character encoding for writing to the file.

Example Code

// Synchronous interface
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)

Close a file.

Parameters

Object object

Property Type Default Value Required Description
fd string Yes File descriptor that needs to be closed. fd is obtained through the FileSystemManager.open or FileSystemManager.openSync interface.
success function No Callback function for successful API call
fail function No Callback function for failed API call
complete function No Callback function for when the API call ends (executed whether successful or failed)

object.fail Callback Function

Parameters

Object res

Property Type Description
errMsg string Error message

Example Code

const fs = ft.getFileSystemManager()
// Open file
fs.open({
  filePath: `${ft.env.USER_DATA_PATH}/test.txt`,
  flag: 'a+',
  success(res) {
    // Close file
    fs.close({
      fd: res.fd
    })
  }
})

# FileSystemManager.closeSync

FileSystemManager.closeSync(Object object)

Synchronously close a file.

Parameters

Object object

Attribute Type Default Value Required Description
fd string Yes The file descriptor that needs to be closed. The fd is obtained through the FileSystemManager.open or FileSystemManager.openSync interface.

Sample Code

const fs = ft.getFileSystemManager()

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

// Close the file
fs.closeSync({ fd: fd })

# FileSystemManager.copyFile

FileSystemManager.copyFile(Object object)

Copy a file

Parameters

Object object

Attribute Type Default Value Required Description
srcPath string Yes Source file path, supports local paths
destPath string Yes Destination file path, supports local paths
success function No Callback function for successful interface call
fail function No Callback function for failed interface call
complete function No Callback function for when the interface call ends (executed whether the call succeeds or fails)

object.fail callback function

Parameters

Object res

Attribute Type Description
errMsg string Error message

Sample Code

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)

The synchronous version of FileSystemManager.copyFile

Parameters

string srcPath

Source file path, supports local paths

string destPath

Destination file path, supports local paths

Sample Code


const fs = ft.getFileSystemManager()

// Synchronous interface
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)

Get the status information of a file

Parameters

Object object

Attribute Type Default Value Required Description
fd string Yes The file descriptor that needs to be closed. The fd is obtained through the FileSystemManager.open or FileSystemManager.openSync interface.
success function No Callback function for successful interface call
fail function No Callback function for failed interface call
complete function No Callback function for when the interface call ends (executed whether the call succeeds or fails)

object.success callback function

Parameters

Object res

Attribute Type Description
stats object Contains the status information of the file

object.fail callback function

Parameters

Object res

Attribute Type Description
errMsg string Error message

Sample Code

const fs = ft.getFileSystemManager()
// Open the file
fs.open({
  filePath: `${ft.env.USER_DATA_PATH}/test.txt`,
  flag: 'a+',
  success(res) {
    // Get the status information of the file
    fs.fstat({
      fd: res.fd,
      success(res) {
        console.log(res.stats)
      }
    })
  }
})

# FileSystemManager.fstatSync

FileSystemManager.fstatSync(Object object)

Synchronously get the status information of a file

Parameters

Object object

Attribute Type Default Value Required Description
fd string Yes The file descriptor that needs to be closed. The fd is obtained through the FileSystemManager.open or FileSystemManager.openSync interface.

Return Value

Object object

An object containing the status information of the file

Sample Code

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)

Truncate the contents of a file

Parameters

Object object

Attribute Type Default Value Required Description
fd string Yes The file descriptor that needs to be closed. The fd is obtained through the FileSystemManager.open or FileSystemManager.openSync interface.
length number Yes Truncation position, default 0. If length is less than the file length (in bytes), only the first length bytes will remain in the file, and the rest will be deleted; if length is greater than the file length, it will be extended, and the extended part will be filled with null bytes ('\0')
success function No Callback function for successful interface call
fail function No Callback function for failed interface call
complete function No Callback function for when the interface call ends (executed whether the call succeeds or fails)

object.fail callback function

Parameters

Object res

Attribute Type Description
errMsg string Error message

Sample Code

const fs = ft.getFileSystemManager()
// Open the file
fs.open({
  filePath: `${ft.env.USER_DATA_PATH}/test.txt`,
  flag: 'a+',
  success(res) {
    // Truncate the contents of the file
    fs.ftruncate({
      fd: res.fd,
      length: 10, // Truncate the file starting from the 10th byte
      success(res) {
        console.log(res)
      }
    })
  }
})

# FileSystemManager.ftruncateSync

FileSystemManager.ftruncateSync(Object object)

Synchronously truncate the contents of a file

Parameters

Object object

Attribute Type Default Value Required Description
fd string Yes The file descriptor that needs to be closed. The fd is obtained through the FileSystemManager.open or FileSystemManager.openSync interface.
length number Yes Truncation position, default 0. If length is less than the file length (in bytes), only the first length bytes will remain in the file, and the rest will be deleted; if length is greater than the file length, it will be extended, and the extended part will be filled with null bytes ('\0')

Return Value

undefined

Sample Code

const fs = ft.getFileSystemManager()

const fd = fs.openSync({
  filePath: `${ft.env.USER_DATA_PATH}/test.txt`,
  flag: 'a+'
})
fs.ftruncateSync({
  fd: fd,
  length: 10 // Truncate the file starting from the 10th byte
})

# FileSystemManager.getFileInfo

FileSystemManager.getFileInfo(Object object)

Get information about the local temporary file or local cache file in this Mini-Program.

Parameters

Object object

Property Type Default Value Required Description
filePath string Yes The file path (local path) to which content will be appended
digestAlgorithm string 'md5' No Algorithm for calculating file digest
success function No Callback function for successful API call
fail function No Callback function for failed API call
complete function No Callback function for when the API call ends (executed whether the call succeeds or fails)

Valid values for object.digestAlgorithm

Value Description
md5 md5 algorithm
sha1 sha1 algorithm

Callback function object.success

Parameters

Object res

Property Type Description
size number File size, in bytes

Callback function object.fail

Parameters

Object res

Property Type Description
errMsg string Error message

Example code

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)

Get the list of locally cached files saved under this Mini-Program.

Parameters

Object object

Property Type Default Value Required Description
success function No Callback function for successful API call
fail function No Callback function for failed API call
complete function No Callback function for when the API call ends (executed whether the call succeeds or fails)

Callback function object.success

Parameters

Object res

Property Type Description
fileList Array. Array of files, where each object contains filePath, size, and createTime

Callback function object.fail

Parameters

Object res

Property Type Description
errMsg string Error message

Example code

const fs = ft.getFileSystemManager()

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

# FileSystemManager.mkdir

FileSystemManager.mkdir(Object object)

Create a directory.

Parameters

Object object

Property Type Default Value Required Description
dirPath string Yes Path of the directory to create (local path)
recursive boolean false No Whether to recursively create parent directories before creating this directory. If the corresponding parent directory already exists, it will not be created again. For example, if dirPath is a/b/c/d and recursive is true, the a directory will be created first, then the b directory inside a, and so on until the d directory inside a/b/c.
success function No Callback function for successful API call
fail function No Callback function for failed API call
complete function No Callback function for when the API call ends (executed whether the call succeeds or fails)

Callback function object.fail

Parameters

Object res

Property Type Description
errMsg string Error message

Example code

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)

The synchronous version of FileSystemManager.mkdirSync.

Parameters

string dirPath

Path of the directory to create (local path)

boolean recursive

Whether to recursively create parent directories before creating this directory. If the corresponding parent directory already exists, it will not be created again. For example, if dirPath is a/b/c/d and recursive is true, the a directory will be created first, then the b directory inside a, and so on until the d directory inside a/b/c.

Example code


const fs = ft.getFileSystemManager()

// Synchronous interface
try {
  fs.mkdirSync(`${ft.env.USER_DATA_PATH}/a/b`, false)
} catch(e) {
  console.error(e)
}

# FileSystemManager.open

FileSystemManager.open(Object object)

Open a file and return a file descriptor.

Parameters

Object object

Property Type Default Value Required Description
filePath string Yes File path (local path)
flag string r No File system flag, default value: 'r'
success function No Callback function for successful API call
fail function No Callback function for failed API call
complete function No Callback function for when the API call ends (executed whether the call succeeds or fails)

Valid values for object.flag

Value Description
a Open file for appending. Create the file if it does not exist
ax Similar to 'a', but fails if the path exists
a+ Open file for reading and appending. Create the file if it does not exist
ax+ Similar to 'a+', but fails if the path exists
as Open file for appending (in synchronous mode). Create the file if it does not exist
as+ Open file for reading and appending (in synchronous mode). Create the file if it does not exist
r Open file for reading. An exception occurs if the file does not exist
r+ Open file for reading and writing. An exception occurs if the file does not exist
w Open file for writing. Create the file if it does not exist, truncate the file if it exists
wx Similar to 'w', but fails if the path exists
w+ Open file for reading and writing. Create the file if it does not exist, truncate the file if it exists
wx+ Similar to 'w+', but fails if the path exists

Callback function object.success

Parameters

Object res

Property Type Description
fd string File descriptor

Callback function object.fail

Parameters

Object res

Property Type Description
errMsg string Error message

Example code

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)

Synchronously open a file, returning a file descriptor.

Parameters

Object object

Property Type Default Value Required Description
filePath string Yes File path (local path)
flag string r No File system flag, default value: 'r'

Valid values for object.flag

Value Description
a Open the file for appending. If the file does not exist, create it.
ax Similar to 'a', but fails if the path exists.
a+ Open the file for reading and appending. If the file does not exist, create it.
ax+ Similar to 'a+', but fails if the path exists.
as Open the file for appending (in synchronous mode). If the file does not exist, create it.
as+ Open the file for reading and appending (in synchronous mode). If the file does not exist, create it.
r Open the file for reading. An exception occurs if the file does not exist.
r+ Open the file for reading and writing. An exception occurs if the file does not exist.
w Open the file for writing. Create the file if it does not exist; truncate the file if it exists.
wx Similar to 'w', but fails if the path exists.
w+ Open the file for reading and writing. Create the file if it does not exist; truncate the file if it exists.
wx+ Similar to 'w+', but fails if the path exists.

Return Value

string

File descriptor

Example code

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)

Read a file.

Parameters

Object object

Property Type Default Value Required Description
fd string Yes File descriptor. fd is obtained via the FileSystemManager.open or FileSystemManager.openSync interface.
arrayBuffer ArrayBuffer Yes Buffer to write data into, must be an instance of ArrayBuffer.
offset number 0 No Write offset in the buffer, default is 0.
length number 0 No Number of bytes to read from the file, default is 0.
position number No Starting position for file reading. If not provided or null is passed, reading starts from the current file pointer position. If position is a positive integer, the file pointer remains unchanged and reads from the position.
success function No Callback function for successful API call.
fail function No Callback function for failed API call.
complete function No Callback function for when the API call ends (executed whether the call succeeds or fails).

object.success callback function

Parameters

Object res

Property Type Description
bytesRead number Actual number of bytes read.
arrayBuffer ArrayBuffer The buffer object written to, i.e., the arrayBuffer parameter passed to the API.

object.fail callback function

Parameters

Object res

Property Type Description
errMsg string Error message.

Example code

const fs = ft.getFileSystemManager()

const ab = new ArrayBuffer(1024)
// Open the file
fs.open({
  filePath: `${ft.env.USER_DATA_PATH}/test.txt`,
  flag: 'a+',
  success(res) {
    // Read the file into the ArrayBuffer
    fs.read({
      fd: res.fd,
      arrayBuffer: ab,
      length: 10,
      success(res) {
        console.log(res)
      }
    })
  }
})

# FileSystemManager.readdir

FileSystemManager.readdir(Object object)

Read the list of files in a directory.

Parameters

Object object

Property Type Default Value Required Description
dirPath string Yes Path of the directory to read (local path).
success function No Callback function for successful API call.
fail function No Callback function for failed API call.
complete function No Callback function for when the API call ends (executed whether the call succeeds or fails).

object.success callback function

Parameters

Object res

Property Type Description
files Array. Array of filenames in the specified directory.

object.fail callback function

Parameters

Object res

Property Type Description
errMsg string Error message.

Example code

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)

The synchronous version of FileSystemManager.readdirSync.

Parameters

string dirPath

Path of the directory to read (local path).

Return Value

Array. files

Array of filenames in the specified directory.

Example code


const fs = ft.getFileSystemManager()

// Synchronous interface
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)

Read the content of a local file.

Parameters

Object object

Property Type Default Value Required Description
filePath string Yes Path of the file to read (local path).
encoding string binary No Specify the character encoding for reading the file. If encoding is not provided, the file's binary content will be read in ArrayBuffer format.
position number No Start reading from the specified position in the file. If not specified, reading starts from the beginning of the file. The range to read should be the left-closed right-open interval [position, position+length). Valid range: [0, fileLength - 1]. Unit: byte.
length number No Specify the length of the file to read. If not specified, reading continues until the end of the file. Valid range: [1, fileLength]. Unit: byte.
success function No Callback function for successful API call.
fail function No Callback function for failed API call.
complete function No Callback function for when the API call ends (executed whether the call succeeds or fails).

Valid values for object.encoding

Value Description
base64
binary
utf-8
utf8

object.success callback function

Parameters

Object res

Property Type Description
data string/ArrayBuffer File content.

object.fail callback function

Parameters

Object res

Property Type Description
errMsg string Error message.

Example code

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)

The synchronous version of FileSystemManager.readFileSync.

Parameters

string filePath

Path of the file to read (local path).

string encoding

Specify the character encoding for reading the file. If encoding is not provided, the file's binary content will be read in ArrayBuffer format.

Valid values for encoding

Value Description
base64
binary
utf-8
utf8

number position

Start reading from the specified position in the file. If not specified, reading starts from the beginning of the file. The range to read should be the left-closed right-open interval [position, position+length). Valid range: [0, fileLength - 1]. Unit: byte.

number length

Specify the length of the file to read. If not specified, reading continues until the end of the file. Valid range: [1, fileLength]. Unit: byte. Return Value

string|ArrayBuffer data

File content

Sample Code


const fs = ft.getFileSystemManager()

// Synchronous interface
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)

Read file

Parameters

Object object

Property Type Default Value Required Description
fd string Yes File descriptor. fd is obtained through the FileSystemManager.open or FileSystemManager.openSync interface
arrayBuffer ArrayBuffer Yes Buffer to write data into, must be an instance of ArrayBuffer
offset number 0 No Write offset in the buffer, default is 0
length number 0 No Number of bytes to read from the file, default is 0
position number No Starting position for file reading. If not passed or null is passed, it will read from the current file pointer position. If position is a positive integer, the file pointer position remains unchanged and reads from position.

Return Value

Object res

Property Type Description
bytesRead number Actual number of bytes read
arrayBuffer ArrayBuffer The object written to the buffer, i.e., the arrayBuffer parameter of the interface

Sample Code

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)

Read files inside a zip archive

Parameters

Object object

Property Type Default Value Required Description
filePath string Yes Path to the zip file to be read (local path)
encoding string No Uniformly specify the character encoding for reading files, only valid when entries value is "all". If entries value is "all" and encoding is not passed, the file's binary content will be read in ArrayBuffer format
entries Array or string Yes List of files within the zip archive to be read (passing "all" indicates reading all files within the zip archive)
success function No Callback function for successful interface invocation
fail function No Callback function for failed interface invocation
complete function No Callback function for interface invocation completion (executed whether the call succeeds or fails)

Return Value

Object res

Property Type Description
entries Object File reading results. res.entries is an object where the key is the file path, and the value is an object FileItem representing the reading result of that file. Each FileItem contains data (file content) and errMsg (error message) properties.
Error

Sample Code

const fs = ft.getFileSystemManager()
// Read one or multiple files within the zip
fs.readZipEntry({
  filePath: 'path/to/zip.zip',
  entries: [{
    path: 'zip/file/1.txt', // File path within the zip
    encoding: 'utf-8'
  }, {
    path: 'zip/file/2.txt', // File path within the zip
  }],
  success(res) {
    console.log(res.entries)
  },
  fail(res) {
    console.log(res.errMsg)
  }
})

// Read all files within the zip, allowing specifying a unified 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)

Delete locally cached files saved under this Mini-Program

Parameters

Object object

Property Type Default Value Required Description
filePath string Yes Path of the file to be deleted (local path)
success function No Callback function for successful interface invocation
fail function No Callback function for failed interface invocation
complete function No Callback function for interface invocation completion (executed whether the call succeeds or fails)

object.fail callback function

Parameters

Object res

Property Type Description
errMsg string Error message

Sample Code

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)

Rename a file. Can move a file from oldPath to newPath

Parameters

Object object

Property Type Default Value Required Description
oldPath string Yes Source file path, supports local path
newPath string Yes New file path, supports local path
success function No Callback function for successful interface invocation
fail function No Callback function for failed interface invocation
complete function No Callback function for interface invocation completion (executed whether the call succeeds or fails)

object.fail callback function

Parameters

Object res

Property Type Description
errMsg string Error message

Sample Code

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)

Synchronous version of FileSystemManager.rename

Parameters

string oldPath

Source file path, supports local path

string newPath

New file path, supports local path

Sample Code


const fs = ft.getFileSystemManager()

// Synchronous interface
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)

Delete a directory.

Parameters

Object object

Property Type Default Value Required Description
dirPath string Yes Path of the directory to delete (local path)
recursive boolean false No Whether to recursively delete the directory. If true, deletes the directory and all its subdirectories and files
success function No Callback function for successful API call
fail function No Callback function for failed API call
complete function No Callback function when API call ends (executed on both success and failure)

object.fail callback function

Parameters

Object res

Property Type Description
errMsg string Error message

Example code

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)

Synchronous version of FileSystemManager.rmdir

Parameters

string dirPath

Path of the directory to delete (local path)

boolean recursive

Whether to recursively delete the directory. If true, deletes the directory and all its subdirectories and files

Example code


const fs = ft.getFileSystemManager()

// Synchronous interface
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)

Save a temporary file to local storage. This API moves the temporary file, so after a successful call, tempFilePath will no longer be available.

Parameters

Object object

Property Type Default Value Required Description
tempFilePath string Yes Temporary file storage path (local path)
filePath string No Target file storage path (local path)
success function No Callback function for successful API call
fail function No Callback function for failed API call
complete function No Callback function when API call ends (executed on both success and failure)

object.success callback function

Parameters

Object res

Property Type Description
savedFilePath string Path of the stored file (local path)

object.fail callback function

Parameters

Object res

Property Type Description
errMsg string Error message

Example code

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)

Synchronous version of FileSystemManager.saveFile

Parameters

string tempFilePath

Temporary file storage path (local path)

string filePath

Target file storage path (local path)

Example code


const fs = ft.getFileSystemManager()

// Synchronous interface
try {
  fs.saveFileSync( `finfile://temp/sample.txt`)
} catch(e) {
  console.error(e)
}

# FileSystemManager.stat

FileSystemManager.stat(Object object)

Get file information object.

Parameters

Object object

Property Type Default Value Required Description
path string Yes File/directory path (local path)
recursive boolean false No Whether to recursively get information for each file in the directory
success function No Callback function for successful API call
fail function No Callback function for failed API call
complete function No Callback function when API call ends (executed on both success and failure)

object.success callback function

Parameters

Object res

Property Type Description
stats object/Array.<object> When recursive is false, res.stats is an object. When recursive is true and path is a directory path, res.stats is an Array where each item is an object containing path and stats.

object.fail callback function

Parameters

Object res

Property Type Description
errMsg string Error message

Example code

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)

Synchronous version of FileSystemManager.stat

Parameters

string path

File/directory path (local path)

string recursive

Whether to recursively get Stats information for each file in the directory

Return Value

object|Array.<object>

When recursive is false, res.stats is an object. When recursive is true and path is a directory path, res.stats is an Array where each item is an object containing path and stats.

Example code


const fs = ft.getFileSystemManager()

// Synchronous interface
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)

Truncate the contents of a file

Parameters

Object object

Property Type Default Value Required Description
filePath string Yes The path of the file to be truncated (local path)
length number 0 Yes Truncation position, default is 0. If length is less than the file length (in bytes), only the first length bytes will remain in the file, and the rest will be deleted; if length is greater than the file length, it will be extended, and the extended part will be filled with null bytes ('\0')
success function No Callback function for successful API call
fail function No Callback function for failed API call
complete function No Callback function for when the API call ends (executed whether the call succeeds or fails)

object.fail callback function

Parameters

Object res

Property Type Description
errMsg string Error message

Example code

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)

Synchronous version of FileSystemManager.truncate

Parameters

Property Type Default Value Required Description
filePath string Yes The path of the file to be truncated (local path)
length number 0 Yes Truncation position, default is 0. If length is less than the file length (in bytes), only the first length bytes will remain in the file, and the rest will be deleted; if length is greater than the file length, it will be extended, and the extended part will be filled with null bytes ('\0')

Example code


const fs = ft.getFileSystemManager()

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

FileSystemManager.unlink(Object object)

Delete a file

Parameters

Object object

Property Type Default Value Required Description
filePath string Yes The path of the file to be deleted (local path)
success function No Callback function for successful API call
fail function No Callback function for failed API call
complete function No Callback function for when the API call ends (executed whether the call succeeds or fails)

object.fail callback function

Parameters

Object res

Property Type Description
errMsg string Error message

Example code

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)

Synchronous version of FileSystemManager.unlink

Parameters

string filePath

The path of the file to be deleted (local path)

Example code


const fs = ft.getFileSystemManager()

// Synchronous interface
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)

Unzip a file

Parameters

Object object

Property Type Default Value Required Description
zipFilePath string Yes Source file path, supports local paths, must be a zip compressed file
targetPath string/ArrayBuffer Yes Target directory path, supports local paths
success function No Callback function for successful API call
fail function No Callback function for failed API call
complete function No Callback function for when the API call ends (executed whether the call succeeds or fails)

object.fail callback function

Parameters

Object res

Property Type Description
errMsg string Error message

Example code

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)

Write to a file

Parameters

Object object

Property Type Default Value Required Description
fd string Yes File descriptor. fd is obtained through the FileSystemManager.open or FileSystemManager.openSync interface
data string/ArrayBuffer Yes Content to write, type can be String or ArrayBuffer
offset number 0 No Only valid when data type is ArrayBuffer, determines the part of the arrayBuffer to be written, i.e., the index in the arrayBuffer, default is 0
length number No Only valid when data type is ArrayBuffer, specifies the number of bytes to write, default is the remaining bytes of the arrayBuffer starting from offset 0
encoding string utf-8 No Only valid when data type is String, specifies the character encoding for writing to the file, default is utf8
position number No Specifies the offset from the beginning of the file, i.e., the position where the data will be written. When position is not passed or a non-Number type value is passed, the data will be written at the current pointer position.
success function No Callback function for successful API call
fail function No Callback function for failed API call
complete function No Callback function for when the API call ends (executed whether the call succeeds or fails)

Valid values for object.encoding

Value Description
base64
binary
utf-8
utf8

object.success callback function

Parameters

Object res

Property Type Description
bytesWritten number The actual number of bytes written to the file (note that the number of bytes written may not be the same as the number of characters in the string being written)

object.fail callback function

Parameters

Object res

Property Type Description
errMsg string Error message

Example code

const fs = ft.getFileSystemManager()

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

# FileSystemManager.writeFile

FileSystemManager.writeFile(Object object)

Write to a file

Parameters

Object object

Property Type Default Value Required Description
filePath string Yes The path of the file to write (local path)
data string/ArrayBuffer Yes The text or binary data to write
encoding string utf-8 No Specifies the character encoding for writing to the file
success function No Callback function for successful API call
fail function No Callback function for failed API call
complete function No Callback function when the API call ends (executed whether the call succeeds or fails)

Valid values for object.encoding

Value Description
base64
binary
utf-8
utf8

object.fail callback function

Parameters

Object res

Property Type Description
errMsg string Error message

Example code

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)

Synchronous version of FileSystemManager.writeFile

Parameters

string filePath

The path of the file to write (local path)

string|ArrayBuffer data

The text or binary data to write

string encoding

Specifies the character encoding for writing to the file

Valid values for object.encoding

Value Description
base64
binary
utf-8
utf8

Example code


const fs = ft.getFileSystemManager()

// Synchronous interface
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)

Synchronously write to a file

Parameters

Object object

Property Type Default Value Required Description
fd string Yes File descriptor. fd is obtained through the FileSystemManager.open or FileSystemManager.openSync interface
data string/ArrayBuffer Yes Content to be written, type can be String or ArrayBuffer
offset number 0 No Only valid when data type is ArrayBuffer, determines the part of the arrayBuffer to be written, i.e., the index in arrayBuffer, default is 0
length number No Only valid when data type is ArrayBuffer, specifies the number of bytes to write, default is the remaining bytes of arrayBuffer starting from offset 0
encoding string utf-8 No Only valid when data type is String, specifies the character encoding for writing to the file, default is utf8
position number No Specifies the offset from the beginning of the file, i.e., the position where data will be written. When position is not passed or a non-Number type value is passed, data will be written at the current pointer position.

Valid values for object.encoding

Value Description
base64
binary
utf-8
utf8

Return Value

Object res

Property Type Description
bytesWritten number The actual number of bytes written to the file (note that the number of bytes written may not be the same as the number of characters in the written string)

Example code

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

Supported from Base Library 3.3.7, SDK version 2.45.1 onwards. To use readCompressedFile, add the Extension SDK. iOS only supports asynchronous API and does not support synchronous readCompressedFileSync.

FileSystemManager.readCompressedFile(Object object)

Reads the content of a local file with the specified compression type

Parameters

Object object

Property Type Default Value Required Description
filePath string Yes File path
compressionAlgorithm string string No File compression type, only 'br' supported
success function No Callback function for successful API call
fail function No Callback function for failed API call
complete function No Callback function when the API call ends (executed whether the call succeeds or fails)

Return Value

Object res

Property Type Description
data ArrayBuffer File content

Example code

const fs = ft.getFileSystemManager()

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

# FileSystemManager.readCompressedFileSync

Supported from Base Library 3.3.7, SDK version 2.45.1 onwards. To use readCompressedFileSync, add the Extension SDK. iOS only supports asynchronous API and does not support synchronous readCompressedFileSync.

FileSystemManager.readCompressedFileSync(Object object)

Reads the content of a local file with the specified compression type

Parameters

Object object

Property Type Default Value Required Description
filePath string Yes File path
compressionAlgorithm string string No File compression type, only 'br' supported

Return Value

Object data

Property Type Description
data ArrayBuffer File content

Example code

const fs = ft.getFileSystemManager()

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

console.log(data)
© FinClip with ❤ , Since 2017