# File

# saveFile

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

saveFile(Object object)

Saves 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 for when the API call ends (executed on both success and failure)

object.success callback function

Parameters

Object res

Property Type Description
savedFilePath number Path where the file is stored

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 10MB.

# removeSavedFile

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

removeSavedFile(Object object)

Deletes 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 for when the API call ends (executed on both success and failure)

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)

Opens a document in a new page.

Parameters

Object object

Property Type Default Value Required Description
filePath string Yes File path, can be obtained via downloadFile
fileType string No File type, specify the file type to open 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 on both success and failure)

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

Retrieves the list of locally cached files saved under the Mini-Program 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 for when the API call ends (executed on both success and failure)

object.success callback function

Parameters

Object res

Property Type Description
fileList Array. Array of files, each item is 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)

Retrieves information about a local file. This API can only be used to retrieve information about files that have been saved locally. To retrieve 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 for when the API call ends (executed on both success and failure)

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)

Retrieves file information.

Parameters

Object object

Property Type Default Value Required Description
filePath string Yes Local file path
digestAlgorithm string 'md5' No Algorithm used to calculate 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 for when the API call ends (executed on both success and failure)

Legal 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

Saves a file system 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 on both success and failure)

Sample Code

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

# openBrowser

Supported from Base Library 3.11.3, iOS SDK 2.51.11, and Android SDK 2.51.11 onwards

openBrowser(Object object)

Open a URL using the system browser.

Parameters

Object object

Property Type Default Value Required Description
url string Yes The URL address to be opened

# getFileSystemManager

Supported from Base Library 2.10.6 onwards

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 The file/directory path (local path) to check for existence
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()
// 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

The file/directory path (local path) to check for existence.

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 The file path (local path) where content will be appended
data string/ArrayBuffer Yes The 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 when API call ends (executed on both success and failure)

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

The file path (local path) where content will be appended.

string|ArrayBuffer data

The 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 The 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 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()
// 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

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

Example code

const fs = ft.getFileSystemManager()

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

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

# FileSystemManager.copyFile

FileSystemManager.copyFile(Object object)

Copy file

Parameters

Object object

Property Type Default Value Required Description
srcPath string Yes Source file path, supports local path
destPath string Yes Target file path, supports 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.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)

Synchronous version of FileSystemManager.copyFile

Parameters

string srcPath

Source file path, supports local path

string destPath

Target file path, supports local path

Example 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 file status information

Parameters

Object object

Property Type Default Value Required Description
fd string Yes File descriptor that needs to be closed. fd is obtained via 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 the call succeeds or fails)

object.success callback function

Parameters

Object res

Property Type Description
stats object Contains the file status information

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) {
    // Get file status information
    fs.fstat({
      fd: res.fd,
      success(res) {
        console.log(res.stats)
      }
    })
  }
})

# FileSystemManager.fstatSync

FileSystemManager.fstatSync(Object object)

Synchronously get file status information

Parameters

Object object

Property Type Default Value Required Description
fd string Yes File descriptor that needs to be closed. fd is obtained via the FileSystemManager.open or FileSystemManager.openSync interface

Return Value

Object object

An object containing the file status information

Example 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 file content

Parameters

Object object

Property Type Default Value Required Description
fd string Yes File descriptor that needs to be closed. fd is obtained via 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 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()
// Open file
fs.open({
  filePath: `${ft.env.USER_DATA_PATH}/test.txt`,
  flag: 'a+',
  success(res) {
    // Truncate file content
    fs.ftruncate({
      fd: res.fd,
      length: 10, // Truncate file starting from the 10th byte
      success(res) {
        console.log(res)
      }
    })
  }
})

# FileSystemManager.ftruncateSync

FileSystemManager.ftruncateSync(Object object)

Synchronously truncate file content

Parameters

Object object

Property Type Default Value Required Description
fd string Yes File descriptor that needs to be closed. fd is obtained via 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

Example 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 file starting from the 10th byte
})

# FileSystemManager.getFileInfo

FileSystemManager.getFileInfo(Object object) Get information about local temporary files or local cache files under this Mini-Program.

Parameters

Object object

Property Type Default Value Required Description
filePath string Yes 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 for object.success

Parameters

Object res

Property Type Description
size number File size in bytes

Callback function for 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 a 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 for object.success

Parameters

Object res

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

Callback function for 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 won't create that parent directory. For example, if dirPath is a/b/c/d and recursive is true, it will first create the a directory, then create the b directory inside a, and so on until creating 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 for 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)

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 won't create that parent directory. For example, if dirPath is a/b/c/d and recursive is true, it will first create the a directory, then create the b directory inside a, and so on until creating 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 for object.success

Parameters

Object res

Property Type Description
fd string File descriptor

Callback function for 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. If the file does not exist, an exception will occur.
r+ Open the file for reading and writing. If the file does not exist, an exception will occur.
w Open the file for writing. If the file does not exist, create it; if the file exists, truncate it.
wx Similar to 'w', but fails if the path exists.
w+ Open the file for reading and writing. If the file does not exist, create it; if the file exists, truncate it.
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 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 0.
length number 0 No Number of bytes to read from the file, default 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 reading starts from position.
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

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

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 file
fs.open({
  filePath: `${ft.env.USER_DATA_PATH}/test.txt`,
  flag: 'a+',
  success(res) {
    // Read file into 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 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

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.

Starting from Base Library 3.6.2 and SDK 2.47.9, readFile has been optimized for buffer-type reading, with a maximum file size limit of 100MB.

Parameters

Object object

Property Type Default Value Required Description
filePath string Yes Path of the file to read (local path). Starting from SDK 2.47.9, the asynchronous read file size limit is within 100MB.
encoding string binary No Specify the character encoding for reading the file. If encoding is not provided, the file's binary content is 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. If not specified, read until the end of the file. Valid range: [1, fileLength]. Unit: byte.
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).

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.

Starting from SDK 2.47.9, the maximum file size limit for synchronous reading is 30MB. The maximum limit for asynchronous reading is 100MB.

Parameters

string filePath

Path of the file to read (local path). Starting from SDK 2.47.9, the synchronous read file size limit is within 30MB.

string encoding

Specify the character encoding for reading the file. If encoding is not provided, the file's binary content is 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. If not specified, read 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 Data write buffer, 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 that needs 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 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)

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 inside zip
    encoding: 'utf-8'
  }, {
    path: 'zip/file/2.txt', // File path inside zip
  }],
  success(res) {
    console.log(res.entries)
  },
  fail(res) {
    console.log(res.errMsg)
  }
})

// Read all files within the zip, allowing specification of a uniform 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 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

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

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 for when the API call ends (executed on both success and failure)

object.fail callback function

Parameters

Object res

Property Type Description
errMsg string Error message

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

Sample 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 the 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 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 for when the API call ends (executed on both success and failure)

object.success callback function

Parameters

Object res

Property Type Description
savedFilePath string Stored file path (local path)

object.fail callback function

Parameters

Object res

Property Type Description
errMsg string Error message

Sample 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

File storage path (local path)

Sample 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 for when the 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

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

Sample 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 Path to 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 Path to 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 Path to 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

Path to 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 portion 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 in 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 should 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 written string)

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 file path to write to (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 on both success and failure)

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 file path to write to (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; using readCompressedFile requires adding the Extension SDK iOS only supports asynchronous API, does not support synchronous readCompressedFileSync

FileSystemManager.readCompressedFile(Object object)

Reads the content of a local file with 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 supports 'br'
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 on both success and failure)

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; using readCompressedFileSync requires adding the Extension SDK iOS only supports asynchronous API, does not support synchronous readCompressedFileSync

FileSystemManager.readCompressedFileSync(Object object)

Reads the content of a local file with 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 supports 'br'

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