FinClip为企业提供小程序生态圈技术产品,开发者可在FinClip小程序开发帮助中心找到相关FinClip小程序指引

# 基础

# 系统

# 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 系统当前主题,取值为lightdark,全局配置"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。
© 2022 FinClip with ❤