基础

env

ft.env

环境变量

属性

string USER_DATA_PATH

文件系统中的用户目录路径 (本地路径)

base64ToArrayBuffer

ArrayBuffer ft.base64ToArrayBuffer(string base64)

将 Base64 字符串转成 ArrayBuffer 对象

参数

string base64

要转化成 ArrayBuffer 对象的 Base64 字符串

返回值

ArrayBuffer

ArrayBuffer 对象

示例代码

const base64 = 'CxYh'
const arrayBuffer = ft.base64ToArrayBuffer(base64)

arrayBufferToBase64

string ft.arrayBufferToBase64(ArrayBuffer arrayBuffer)

将 ArrayBuffer 对象转成 Base64 字符串

参数

ArrayBuffer arrayBuffer

要转换成 Base64 字符串的 ArrayBuffer 对象

返回值

string

Base64 字符串

示例代码

const arrayBuffer = new Uint8Array([11, 22, 33])
const base64 = ft.arrayBufferToBase64(arrayBuffer)

系统

getSystemInfoSync

基础库1.3.9开始支持，iOS版本2.1.23，Android版本2.1.38

getSystemInfoSync(Object object)

getSystemInfoSync 同步版本。

getSystemInfoAsync

ft.getSystemInfoAsync(Object object)

异步获取系统信息

参数

Object object

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

object.success 回调函数

参数

Object res

属性	类型	说明	最低版本
brand	string	设备品牌	1.5.0
model	string	设备型号。新机型刚推出一段时间会显示unknown，会尽快进行适配。
pixelRatio	number	设备像素比
screenWidth	number	屏幕宽度，单位px	1.1.0
screenHeight	number	屏幕高度，单位px	1.1.0
windowWidth	number	可使用窗口宽度，单位px
windowHeight	number	可使用窗口高度，单位px
statusBarHeight	number	状态栏的高度，单位px	1.9.0
language	string	APP 设置的语言
version	string	版本号
system	string	操作系统及版本
platform	string	客户端平台
fontSizeSetting	number	用户字体大小（单位px）	1.5.0
SDKVersion	string	客户端基础库版本	1.1.0
benchmarkLevel	number	设备性能等级（仅 Android）。取值为：-2 或 0（该设备无法运行小游戏），-1（性能未知），>=1（设备性能值，该值越高，设备性能越好，目前最高不到50）	1.8.0
albumAuthorized	boolean	允许使用相册的开关（仅 iOS 有效）	2.6.0
cameraAuthorized	boolean	允许使用摄像头的开关	2.6.0
locationAuthorized	boolean	允许使用定位的开关	2.6.0
microphoneAuthorized	boolean	允许使用麦克风的开关	2.6.0
notificationAuthorized	boolean	允许通知的开关	2.6.0
notificationAlertAuthorized	boolean	允许通知带有提醒的开关（仅 iOS 有效）	2.6.0
notificationBadgeAuthorized	boolean	允许通知带有标记的开关（仅 iOS 有效）	2.6.0
notificationSoundAuthorized	boolean	允许通知带有声音的开关（仅 iOS 有效）	2.6.0
bluetoothEnabled	boolean	蓝牙的系统开关	2.6.0
locationEnabled	boolean	地理位置的系统开关	2.6.0
wifiEnabled	boolean	Wi-Fi 的系统开关	2.6.0
safeArea	Object	在竖屏正方向下的安全区域	2.7.0
locationReducedAccuracy	boolean	true 表示模糊定位，false 表示精确定位，仅 iOS 支持
theme	string	系统当前主题，取值为light或dark，全局配置"darkmode":true时才能获取，否则为 undefined （不支持小游戏）	2.11.0
host	Object	当前小程序运行的宿主环境	2.12.3
enableDebug	boolean	是否已打开调试。可通过右上角菜单或 ft.setEnableDebug 打开调试。	2.15.0
deviceOrientation	string	设备方向

safeArea 的结构

属性	类型	说明
left	number	安全区域左上角横坐标
right	number	安全区域右下角横坐标
top	number	安全区域左上角纵坐标
bottom	number	安全区域右下角纵坐标
width	number	安全区域的宽度，单位逻辑像素
height	number	安全区域的高度，单位逻辑像素

theme 的合法值

值	说明	最低版本
dark	深色主题
light	浅色主题

host 的结构

属性	类型	说明
appId	string	宿主 app 对应的 appId

deviceOrientation 的合法值

值	说明	最低版本
portrait	竖屏
landscape	横屏

示例代码

在开发者工具中预览效果

ft.getSystemInfoAsync({
  success (res) {
    console.log(res.model)
    console.log(res.pixelRatio)
    console.log(res.windowWidth)
    console.log(res.windowHeight)
    console.log(res.language)
    console.log(res.version)
    console.log(res.platform)
  }
})

getSystemInfo

基础库1.3.9开始支持，iOS版本2.1.23，Android版本2.1.38

getSystemInfo(Object object)

获取系统信息。

参数

Object object

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

object.success 回调函数 ​ 参数

Object res

属性	类型	说明
SDKVersion	string	小程序基础库版本号
runtimeSDKVersion	string	小程序SDK版本号
brand	string	设备品牌
model	string	设备型号
pixelRatio	number	设备像素比
screenWidth	number	屏幕宽度，单位px
screenHeight	number	屏幕高度，单位px
windowWidth	number	可使用窗口宽度，单位px
windowHeight	number	可使用窗口高度，单位px
statusBarHeight	number	状态栏的高度，单位px
language	string	宿主应用设置的语言
version	string	宿主应用的版本号
system	string	操作系统及版本
platform	string	客户端平台
inFinChat	boolean	是否在finchat小程序环境
deviceId	string	设备标识

示例代码

 ft.getSystemInfo({
  success(res) {
    console.log(res.model)
    console.log(res.pixelRatio)
    console.log(res.windowWidth)
    console.log(res.windowHeight)
    console.log(res.language)
    console.log(res.version)
    console.log(res.platform)
  }
})

更新

getUpdateManager

基础库1.5.30开始支持，iOS版本2.5.6，Android版本2.8.76

获取全局唯一的版本更新管理器，用于管理小程序更新。 返回值UpdateManager

UpdateManager方法

UpdateManager.applyUpdate() 强制小程序重启并使用新版本。在小程序新版本下载完成后（即收到 onUpdateReady 回调）调用。​

UpdateManager.onCheckForUpdate(function callback) 监听向后台请求检查更新结果事件。运行时在小程序冷启动时自动检查更新，不需由开发者主动触发。

UpdateManager.onUpdateReady(function callback) 监听小程序有版本更新事件。客户端主动触发下载（无需开发者触发），下载成功后回调 UpdateManager.onUpdateFailed(function callback) 监听小程序更新失败事件。小程序有新版本，客户端主动触发下载（无需开发者触发），下载失败（可能是网络原因等）后回调。

示例代码

const updateManager = ft.getUpdateManager()

updateManager.onCheckForUpdate(function (res) {
  // 请求完新版本信息的回调
  console.log(res.hasUpdate)
})

updateManager.onUpdateReady(function () {
  ft.showModal({
    title: '更新提示',
    content: '新版本已经准备好，是否重启应用？',
    success: function (res) {
      if (res.confirm) {
        // 新的版本已经下载好，调用 applyUpdate 应用新版本并重启
        updateManager.applyUpdate()
      }
    }
  })
})

updateManager.onUpdateFailed(function () {
  // 新版本下载失败
})

小程序

getLaunchOptionsSync

Object ft.getLaunchOptionsSync() 获取小程序启动时的参数。与 App.onLaunch 的回调参数一致。

返回值

Object

启动参数

属性	类型	说明
path	string	启动小程序的路径 (代码包路径)
scene	number	启动小程序的场景值
query	Object	启动小程序的 query 参数
shareTicket	string	shareTicket，详见获取更多转发信息
referrerInfo	Object	来源信息

referrerInfo 的结构

属性	类型	说明
appId	string	来源小程序、公众号或 App 的 appId
extraData	Object	来源小程序传过来的数据，scene=1037或1038时支持

forwardMaterials 的结构

属性	类型	说明
type	string	文件的mimetype类型
name	string	文件名
path	string	文件路径（如果是webview则是url）
size	number	文件大小

返回有效 referrerInfo 的场景

场景值	场景	appId含义
1020	公众号 profile 页相关小程序列表	来源公众号
1035	公众号自定义菜单	来源公众号
1036	App 分享消息卡片	来源App
1037	小程序打开小程序	来源小程序
1038	从另一个小程序返回	来源小程序
1043	公众号模板消息	来源公众号
1069	移动应用	来源App

getEnterOptionsSync

Object ft.getEnterOptionsSync()

获取本次小程序启动时的参数。如果当前是冷启动，则返回值与 App.onLaunch 的回调参数一致；如果当前是热启动，则返回值与 App.onShow 一致。

返回值

Object

启动参数

属性	类型	说明
path	string	启动小程序的路径 (代码包路径)
scene	number	启动小程序的场景值
query	Object	启动小程序的 query 参数
shareTicket	string	shareTicket，详见获取更多转发信息
referrerInfo	Object	来源信息

referrerInfo 的结构

属性	类型	说明
appId	string	来源小程序、公众号或 App 的 appId
extraData	Object	来源小程序传过来的数据，scene=1037或1038时支持

返回有效 referrerInfo 的场景

场景值	场景	appId含义
1020	公众号 profile 页相关小程序列表	来源公众号
1035	公众号自定义菜单	来源公众号
1036	App 分享消息卡片	来源App
1037	小程序打开小程序	来源小程序
1038	从另一个小程序返回	来源小程序
1043	公众号模板消息	来源公众号

注意

部分版本在无 referrerInfo 的时候会返回 undefined，建议使用 options.referrerInfo && options.referrerInfo.appId 进行判断。

onPageNotFound

ft.onPageNotFound(function callback)

监听小程序要打开的页面不存在事件。该事件与 App.onPageNotFound 的回调时机一致。

参数

function callback

小程序要打开的页面不存在事件的回调函数

参数

Object res

属性	类型	说明
path	string	不存在页面的路径 (代码包路径)
query	Object	打开不存在页面的 query 参数
isEntryPage	boolean	是否本次启动的首个页面（例如从分享等入口进来，首个页面是开发者配置的分享页面）

注意

• 开发者可以在回调中进行页面重定向，但必须在回调中同步处理，异步处理（例如 setTimeout 异步执行）无效。
• 若开发者没有调用 ft.onPageNotFound 绑定监听，也没有声明 App.onPageNotFound，当跳转页面不存在时，将推入原生的页面不存在提示页面。
• 如果回调中又重定向到另一个不存在的页面，将推入原生的页面不存在提示页面，并且不再第二次回调。

onError

ft.onError(function callback)

监听小程序错误事件。如脚本错误或 API 调用报错等。该事件与 App.onError 的回调时机与参数一致。

参数

function callback

小程序错误事件的回调函数

参数

string error

错误信息，包含堆栈

onAppShow

ft.onAppShow(function callback)

监听小程序切前台事件。该事件与 App.onShow 的回调参数一致。

参数

function callback

小程序切前台事件的回调函数

参数

Object res

属性	类型	说明
path	string	小程序切前台的路径 (代码包路径)
scene	number	小程序切前台的场景值
query	Object	小程序切前台的 query 参数
shareTicket	string	shareTicket，详见获取更多转发信息
referrerInfo	Object	来源信息。从另一个小程序、公众号或 App 进入小程序时返回。否则返回 {}。(参见后文注意)
forwardMaterials	Array.<Object>	打开的文件信息数组，只有从聊天素材场景打开（scene为1173）才会携带该参数

referrerInfo 的结构

属性	类型	说明
appId	string	来源小程序、公众号或 App 的 appId
extraData	Object	来源小程序传过来的数据，scene=1037或1038时支持

forwardMaterials 的结构

属性	类型	说明
type	string	文件的mimetype类型
name	string	文件名
path	string	文件路径（如果是webview则是url）
size	number	文件大小

返回有效 referrerInfo 的场景

场景值	场景	appId含义
1020	公众号 profile 页相关小程序列表	来源公众号
1035	公众号自定义菜单	来源公众号
1036	App 分享消息卡片	来源App
1037	小程序打开小程序	来源小程序
1038	从另一个小程序返回	来源小程序
1043	公众号模板消息	来源公众号

注意

部分版本在无referrerInfo的时候会返回 undefined，建议使用 options.referrerInfo && options.referrerInfo.appId 进行判断。

onAppHide

ft.onAppHide(function callback)

监听小程序切后台事件。该事件与 App.onHide 的回调时机一致。

参数

function callback

小程序切后台事件的回调函数

offPageNotFound

ft.offPageNotFound(function callback)

取消监听小程序要打开的页面不存在事件

参数

function callback

小程序要打开的页面不存在事件的回调函数

offError

ft.offError(function callback)

取消监听小程序错误事件。

参数

function callback

小程序错误事件的回调函数

offAppShow

ft.offAppShow(function callback)

取消监听小程序切前台事件

参数

function callback

小程序切前台事件的回调函数

offAppHide

ft.offAppHide(function callback)

取消监听小程序切后台事件

参数

function callback

小程序切后台事件的回调函数

调试

setEnableDebug

ft.setEnableDebug(Object object)

设置是否打开调试开关。此开关对正式版也能生效。

参数

Object object

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

示例代码

// 打开调试
ft.setEnableDebug({
  enableDebug: true
})

// 关闭调试
ft.setEnableDebug({
  enableDebug: false
})

Tips

• 在正式版打开调试还有一种方法，就是先在开发版或体验版打开调试，再切到正式版就能看到vConsole。