# 基础
# 系统
# getSystemInfoSync
基础库1.3.9开始支持，iOS版本2.1.23，Android版本2.1.38
getSystemInfoSync()
getSystemInfo 的同步版本。
# 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 |
| 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) 监听向后台请求检查更新结果事件。SDK在小程序冷启动时自动检查更新，不需由开发者主动触发。
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 () {
// 新版本下载失败
})
# 小程序
# onShow
ft.onShow(function callback)
监听小游戏切前台事件。
参数
function callback
小游戏切前台事件的回调函数
参数
Object res
| 属性 | 类型 | 说明 |
|---|---|---|
| path | string | 小游戏切前台的路径 (代码包路径) |
| query | Object | 小程序切前台的 query 参数 |
| referrerInfo | Object | 来源信息。从另一个小程序、公众号或 App 进入小程序时返回。否则返回 {}。(参见后文注意) |
referrerInfo 的结构
| 属性 | 类型 | 说明 |
|---|---|---|
| appId | string | 小程序的 appId |
| extraData | Object | 来源小程序传过来的数据 |
注意
部分版本在无referrerInfo的时候会返回 undefined，建议使用 options.referrerInfo && options.referrerInfo.appId 进行判断。
# onHide
ft.onHide(function callback)
监听小游戏切后台事件。
参数
function callback
小游戏切后台事件的回调函数
# offShow
ft.offShow(function callback)
取消监听小游戏切前台事件
参数
function callback
小游戏切前台事件的回调函数
# offHide
ft.offHide(function callback)
取消监听小游戏切后台事件
参数
function callback
小游戏切后台事件的回调函数
# getLaunchOptionsSync
Object ft.getLaunchOptionsSync() 获取小游戏启动时的参数。
返回值
Object
启动参数
| 属性 | 类型 | 说明 |
|---|---|---|
| query | Object | 启动小游戏的 query 参数 |
| referrerInfo | Object | 来源信息 |
referrerInfo 的结构
| 属性 | 类型 | 说明 |
|---|---|---|
| appId | string | 来源小程序、公众号或 App 的 appId |
| extraData | Object | 来源小程序传过来的数据 |
# getEnterOptionsSync
Object ft.getEnterOptionsSync()
获取本次小游戏启动时的参数。 返回值
Object
启动参数
| 属性 | 类型 | 说明 |
|---|---|---|
| query | Object | 启动小游戏的 query 参数 |
| referrerInfo | Object | 来源信息 |
referrerInfo 的结构
| 属性 | 类型 | 说明 |
|---|---|---|
| appId | string | 小程序的 appId |
| extraData | Object | 来源小程序传过来的数据 |
注意
部分版本在无 referrerInfo 的时候会返回 undefined，建议使用 options.referrerInfo && options.referrerInfo.appId 进行判断。
# 应用级事件
# onError
ft.onError(function callback)
监听小游戏错误事件，如脚本错误或 API 调用报错等。
参数
function callback
小游戏错误事件的回调函数
参数
string error
错误信息，包含堆栈
# onAudioInterruptionBegin
ft.onAudioInterruptionBegin(function callback)
监听音频因为受到系统占用而被中断开始事件。包括但不仅限于以下场景会触发此事件：闹钟、电话等。
此事件触发后，小程序内所有音频会暂停。
参数
function callback
音频因为受到系统占用而被中断开始事件的监听函数
# onAudioInterruptionEnd
ft.onAudioInterruptionEnd(function callback)
监听音频中断结束事件
在收到 onAudioInterruptionEnd 事件之后，小游戏内所有音频会暂停，收到此事件之后才可再次播放成功
参数
function callback
音频中断结束事件的监听函数
# offError
ft.offError(function callback)
取消监听小游戏错误事件。
参数
function callback
onError 传入的回调函数
# offAudioInterruptionBegin
ft.offAudioInterruptionBegin(function callback)
取消监听音频因为受到系统占用而被中断开始的事件
参数
function callback
onAudioInterruptionBegin 传入的回调函数
# offAudioInterruptionEnd
ft.offAudioInterruptionEnd(function callback)
取消监听音频中断结束事件
参数
function callback
onAudioInterruptionEnd 传入的回调函数
# 调试
# 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。